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 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.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
)
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 Storage Legacy Bucket Writer role to the service agent, follow the steps below.
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 overflow menu (
) associated with the bucket to which you want to grant a principal a role.Choose Edit access.
Click the + Add principal button.
In the New principals field, enter your service agent's account email.
Select
Storage Legacy Bucket Writer
from the Select a role drop-down menu.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.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.
Code samples
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 a local development environment.
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 a local development environment.
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 a local development environment.
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 a local development environment.
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 a local development environment.
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 a local development environment.
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 a local development environment.
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 a local development environment.
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
JSON
Have gcloud CLI installed and initialized, which lets you generate an access token for the
Authorization
header.Create a JSON file that contains the following information:
{ "bindings":[ { "role": "roles/storage.legacyBucketWriter", "members":[ "YOUR_AGENT_EMAIL" ] } ] }
Where:
YOUR_AGENT_EMAIL
is the agent account email you copied in Find the service agent's email.
Use
cURL
to call the JSON API with aPUT setIamPolicy
request:curl -X PUT --data-binary @JSON_FILE_NAME \ -H "Authorization: Bearer OAUTH2_TOKEN" \ -H "Content-Type: application/json" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/iam"
Where:
JSON_FILE_NAME
is the path for the file that you created in Step 2.OAUTH2_TOKEN
is the access token that you generated in Step 1.BUCKET_NAME
is the name of the bucket to which you want to give the principal access. For example,my-bucket
.
For more information on assigning IAM roles to Cloud Storage resources, see the Cloud Storage IAM documentation.