Upload logs to Google Cloud Storage

Before using this role, create at least one bucket and set up
appropriate access controls or lifecycle events.  This role will not
automatically create buckets (though it will configure CORS policies).

This role requires the ``google-cloud-storage`` Python package to be
installed in the Ansible environment on the Zuul executor.  It uses
Google Cloud Application Default Credentials.

**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_container

   This role *will not* create buckets which do not already exist.  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.

   Note that you will want to set this to a value that uniquely
   identifies your Zuul installation.

.. 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-gcs 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_credentials_file

   This log upload role normally uses Google Cloud Application Default
   Credentials, however it can also operate in a mode where it uses a
   credential file written by gcp-authdaemon:
   https://opendev.org/zuul/gcp-authdaemon

   To use this mode of operation, supply a path to the credentials
   file previously written by gcp-authdaemon.

   Also supply :zuul:rolevar:`upload-logs-gcs.zuul_log_project`.

.. zuul:rolevar:: zuul_log_project

   When using
   :zuul:rolevar:`upload-logs-gcs.zuul_log_credentials_file`, the name
   of the Google Cloud project of the log container must also be
   supplied.