Configure access to a sink: Cloud Storage

Cloud Storage uses a service agent to move data to a Cloud Storage bucket. This service agent is created the first time that you call googleServiceAccounts.get.

The destination bucket does not need to belong to the same project as the service agent. The steps are the same regardless of which project the bucket is in.

User permissions

In order to grant the required permissions to the service agent, you must have the relevant permissions on the destination bucket:

  • storage.buckets.getIamPolicy
  • storage.buckets.setIamPolicy

The Storage Legacy Bucket Owner role (roles/storage.legacyBucketOwner) or the Storage Admin role (roles/storage.admin) provide the required permissions.

Auto-granting permissions in the Google Cloud console

If you're using the Google Cloud console to create your transfer and have the permissions listed in User permissions, the service agent will automatically be granted the required permissions on your destination bucket.

You can skip the steps on this page. If required, configure access to your source, then create a transfer.

Required permissions

The service agent must have the following permissions for the destination bucket:

Permission Description
storage.buckets.get Allows the service account to get the location of the bucket.
storage.objects.get Allows the service account to view objects and their metadata, excluding ACLs. Required if your transfer is configured to [overwrite objects](/storage-transfer/docs/reference/rest/v1/TransferOptions#OverwriteWhen) in the sink when different, or never. Not required if your transfer setting is to overwrite always.
storage.objects.create Allows the service account to add objects to the bucket.
storage.objects.delete

Allows the service account to delete objects in the bucket. Required if you set overwriteObjectsAlreadyExistingInSink or deleteObjectsUniqueInSink to true.

Note that if the destination bucket has object versioning enabled, neither overwriteObjectsAlreadyExistingInSink nor deleteObjectsUniqueInSink permanently delete any objects. Instead, relevant live object versions become noncurrent.
storage.objects.list Allows the service account to list objects in the bucket. Required if you set overwriteObjectsAlreadyExistingInSink to false or deleteObjectsUniqueInSink to true.

The following predefined role grants the required permissions:

  • Storage Legacy Bucket Writer (roles/storage.legacyBucketWriter)

In addition, for transfers configured to overwrite objects in the sink when different, or never, assign the following predefined role to the service agent:

  • Storage Object Viewer (roles/storage.objectViewer)

For a complete list of Cloud Storage roles and the permissions they contain, see IAM roles.

Grant the required permissions

To grant the Storage Legacy Bucket Writer and Storage Object Viewer roles to the service agent, follow these steps.

Find the service agent's email

  1. Go to the googleServiceAccounts.get reference page.

    An interactive panel opens, titled Try this method.

  2. In the panel, under Request parameters, enter your project ID. The project you specify here must be the project that you're using to manage Storage Transfer Service, which might be different from the destination bucket's project.

  3. Click Execute.

    Your service agent's email is returned as the value of accountEmail. Copy this value.

    The service agent's email uses the format project-PROJECT_NUMBER@storage-transfer-service.iam.gserviceaccount.com.

Add the service agent to a bucket-level policy

Console

  1. In the Google Cloud console, go to the Cloud Storage Buckets page.

    Go to Buckets

  2. Click the Bucket overflow menu () associated with the bucket to which you want to grant a principal a role.

  3. Choose Edit access.

  4. Click the + Add principal button.

  5. In the New principals field, enter your service agent's account email.

  6. Select Storage Legacy Bucket Writer from the Select a role drop-down menu.

  7. Click Save.

  8. Repeat to add the Storage Object Viewer role if your transfer is configured to overwrite objects in the sink when different, or never.

gcloud

Use the gcloud storage buckets add-iam-policy-binding command:

gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
--member=serviceAccount:YOUR_AGENT_EMAIL --role=roles/storage.legacyBucketWriter

Replace the following:

  • BUCKET_NAME is the name of the bucket that you're granting the principal access to. For example, my-bucket.
  • YOUR_AGENT_EMAIL is the agent account email that you copied in Find the service agent's email.

To grant the Storage Object Viewer role for transfers configured to overwrite objects in the sink when different or never:

gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
--member=serviceAccount:YOUR_AGENT_EMAIL --role=roles/storage.objectViewer

Code samples

C++

To learn how to install and use the client library for Cloud Storage, see Cloud Storage client libraries. For more information, see the Cloud Storage C++ API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries. 

namespace gcs = ::google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client