Agent-based project-level permissions

Agent-based transfers require project-level IAM permissions for two distinct entities: a service agent and a transfer agent account.

Configure the permissions on this page only if your transfer involves a file system, HDFS, or S3-compatible storage. If your transfer is agentless, do not configure the roles on this page; proceed directly to Configure access to your source and destination.

Agent-based transfers use the following identities:

  • Service agent: A Google-managed service account used by Storage Transfer Service to coordinate tasks with transfer agents.
  • Transfer agent account: The Google Cloud user account or user-managed service account used to authenticate and run transfer agents on your client machines or instances.

For general information on granting IAM roles, see Granting, changing, and revoking access to resources.

Service agent permissions

Storage Transfer Service uses a service agent to coordinate agent-driven transfers.

To enable Storage Transfer Service to coordinate work between Google Cloud and your transfer agents, grant the following role to the service agent on the project running Storage Transfer Service:

  • Storage Transfer Service Agent (roles/storagetransfer.serviceAgent)

Obtain the service agent email address

Granting a role to the service agent requires the service agent's email address identifier. The service agent is created automatically when you first create a transfer job, run gcloud transfer setup commands, visit the Storage Transfer page in the Google Cloud console, or call googleServiceAccounts.get.

To obtain the service agent email address:

  1. Go to the googleServiceAccounts.get reference page. An interactive panel opens, titled Try this method.
  2. Under Request parameters, enter your project ID.
  3. Click Execute.

Copy the value of accountEmail. The email address uses the following format: project-PROJECT_NUMBER@storage-transfer-service.iam.gserviceaccount.com.

Grant the service agent role

To grant the Storage Transfer Service Agent role:

Google Cloud console

  1. In the Google Cloud console, go to the IAM page for the project running Storage Transfer Service.

    Go to IAM

  2. Click Grant access.

  3. In the New principals field, enter your service agent email address.

  4. In the Select a role drop-down list, search for and select Storage Transfer Service Agent (roles/storagetransfer.serviceAgent).

  5. Click Save.

gcloud

Run gcloud projects add-iam-policy-binding:

gcloud projects add-iam-policy-binding PROJECT_ID \
--member="serviceAccount:SERVICE_AGENT_EMAIL" \
--role="roles/storagetransfer.serviceAgent"

Replace the following:

Transfer agent account permissions

Transfer agents run on your client machines using the credentials of either a user account or a user-managed service account:

  • A user account uses the credentials of an authenticated user.
  • A user-managed service account uses service account keys or identity federation. To create a service account, see Create and manage service accounts.

To authorize transfer agents to connect to Storage Transfer Service, receive tasks, and log status, assign the following role on the Google Cloud project hosting your agent pool:

  • Storage Transfer Agent (roles/storagetransfer.transferAgent)

To grant this role:

Google Cloud console

  1. In the Google Cloud console, go to the IAM page.

    Go to IAM

  2. Ensure you have selected the project containing your agent pool.

  3. Click Grant access.

  4. In the New principals field, enter the email address of your user account or user-managed service account.

  5. In the Select a role drop-down list, search for and select Storage Transfer Agent (roles/storagetransfer.transferAgent).

  6. Click Save.

gcloud

Run gcloud projects add-iam-policy-binding:

gcloud projects add-iam-policy-binding AGENT_POOL_PROJECT_ID \
--member="serviceAccount_OR_user:TRANSFER_AGENT_ACCOUNT" \
--role="roles/storagetransfer.transferAgent"

Replace the following:

  • AGENT_POOL_PROJECT_ID: The project containing your agent pool.
  • serviceAccount_OR_user: Specify either serviceAccount if your transfer agent account is a service account, or user if your agents were installed with a user account.
  • TRANSFER_AGENT_ACCOUNT: The email address of the account running the transfer agents.

What's next

After configuring project permissions, proceed with the following setup steps in order:

  1. Create an agent pool.
  2. Install transfer agents in your pool.
  3. Configure access permissions for your storage systems:
  4. Review the complete Role and permission reference.