Upload logs to IBM Cloud Storage

Before using this role, create a cloud object storage `service instance`_
and a `service credential`_.

You may create a bucket within the instance, or allow this role to
create the bucket (or buckets) for you.

**Role Variables**

.. zuul:rolevar:: zuul_site_upload_logs
   :default: true

   Controls when logs are uploaded. true, the default, means always
   upload logs. false means never upload logs. 'failure' means to only
   upload logs when the job has failed.

   .. note:: Intended to be set by admins via site-variables.

.. zuul:rolevar:: zuul_log_partition
   :default: false

   If set to true, then the first component of the log path will be
   removed from the object name and added to the bucket name, so
   that logs for different changes are distributed across a large
   number of buckets.

.. zuul:rolevar:: zuul_log_bucket

   If partitioning is not enabled, this is the name of the bucket
   which will be used.  If partitioning is enabled, then this will be
   used as the prefix for the bucket name which will be separated
   from the partition name by an underscore.  For example, "logs_42"
   would be the bucket name for partition 42.

.. zuul:rolevar:: zuul_log_bucket_public
   :default: true

   If the bucket is created, this indicates whether it should be
   created with global read ACLs.  If the bucket already exists, it
   will not be modified.

.. zuul:rolevar:: zuul_log_bucket_location

   If the bucket is created, this `storage location`_ will be used as
   the location constraint.

.. zuul:rolevar:: zuul_log_path
   :default: Generated by the role `set-zuul-log-path-fact`

   Prepend this path to the object names when uploading.

.. zuul:rolevar:: zuul_log_create_indexes
   :default: true

   Whether to create `index.html` files with directory indexes.

.. zuul:rolevar:: zuul_log_path_shard_build
   :default: false

   This var is consumed by set-zuul-log-path-fact which
   upload-logs-ibm calls into. If you set this you will get log
   paths prefixed with the first three characters of the build
   uuid. This will improve log file sharding.

   More details can be found at
   :zuul:rolevar:`set-zuul-log-path-fact.zuul_log_path_shard_build`.

.. zuul:rolevar:: zuul_log_api_key

   The API key that was created as part of the `service credential`_.
   This is required.

.. zuul:rolevar:: zuul_log_instance_id

   The instance id that appears in the `service credential`_.
   This is required.

.. zuul:rolevar:: zuul_log_endpoint_url

   The cloud storage `endpoint`_.
   This is required.


.. _service instance: https://cloud.ibm.com/docs/cloud-object-storage/iam/service-credentials.html

.. _service credential: https://cloud.ibm.com/docs/cloud-object-storage/iam?topic=cloud-object-storage-service-credentials

.. _endpoint: https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-endpoints#endpoints

.. _storage location: https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-classes#classes