Cloud Storage uses a Google-managed service account
,
known as 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 Ownerrole ( roles/storage.legacyBucketOwner
) or
the Storage Adminrole ( 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 Note that if the destination bucket has object versioning
enabled, neither |
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 Writerand Storage Object Viewerroles to the service agent, follow these steps.
Find the service agent's email
-
Go to the
googleServiceAccounts.get
reference page .An interactive panel opens, titled Try this method.
-
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.
-
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
- In the Google Cloud console, go to the Cloud Storage Buckets
page.
-
Click the Bucket overflowmenu ( ) associated with the bucket to which you want to grant a principal a role.
-
Choose Edit access.
-
Click the + Add principalbutton.
-
In the New principalsfield, enter your service agent's account email.
-
Select
Storage Legacy Bucket Writer
from the Select a roledrop-down menu. -
Click Save.
-
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
Where:
-
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, use the same command, but
replace roles/storage.legacyBucketWriter
with roles/storage.objectViewer
:
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 .
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 .
Go
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 Go API reference documentation .
To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries .
Java
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 Java API reference documentation .
To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries .
Node.js
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 Node.js API reference documentation .
To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries .
PHP
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 PHP API reference documentation .
To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries .
Python
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 Python API reference documentation .
To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries .
Ruby
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 Ruby API reference documentation .
To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries .