Configure access to a source: Cloud Storage

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

The source 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 source 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 source bucket.

You can skip the steps on this page and go directly to creating a transfer.

Required permissions

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

Permission Description
storage.buckets.get Allows the service agent to get the location of the bucket.
storage.objects.list Allows the service agent to list objects in the bucket.
storage.objects.get Allows the service agent to read objects in the bucket.
storage.objects.create

Allows the service agent to create objects in the bucket. Required if the transfer is to a file system.

Storage Transfer Service creates and populates two folders in the source bucket: cloud-ingest/ contains file system information, and storage-transfer/ contains transfer logs.
storage.objects.delete Allows the service agent to delete objects in the bucket. Required if you set deleteObjectsFromSourceAfterTransfer to true.
storage.objects.getIamPolicy Allows the service agent to read ACLs on source objects. Required if object ACL preservation (ACL_PRESERVE) is enabled.

The following predefined roles together grant the required permissions:

  • One of:
    • Storage Object Viewer (roles/storage.objectViewer) if the transfer is to another Cloud Storage bucket.
    • Storage Object Creator (roles/storage.objectCreator) if the transfer is to a file system.
  • Plus one of:
    • Storage Legacy Bucket Writer (roles/storage.legacyBucketWriter) if object delete permission is required.
    • Storage Legacy Bucket Reader (roles/storage.legacyBucketReader) if object delete permission is not required.
  • Additionally, if preserving object ACLs with ACL_PRESERVE:
    • Storage Legacy Object Owner (roles/storage.legacyObjectOwner)

Any Cloud Storage role marked as a legacy role can only be granted at the bucket level.

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

Grant the required permissions

To grant the required permissions to the service agent, follow the steps below.

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 you're using to manage Storage Transfer Service, which might be different from the source 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 Object Viewer or Storage Object Creator from the Select a role drop-down menu.

  7. Click Add another role.

  8. Select either Storage Legacy Bucket Writer or Storage Legacy Bucket Reader.

  9. Click Save.

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.objectViewer