A Cloud Run service or revision has a service identity that is used as the authenticated account for accessing Google Cloud APIs from your Cloud Run instance container. To learn more about service identity, see the Introduction to service identity guide.
How service identity is used
In Cloud Run, the service identity is a service account that is both a resource and a principal.
- Service identity as a resource: In order to attach a service account as the service identity, the deployer account must have access on the service identity resource. Certain operations, like creating or updating a service or revision, require the deployer account to have permissions on the service identity resource.
- Service identity as a principal: In order to access Google Cloud APIs from a Cloud Run service or revision, you must grant the service identity the required roles or permissions for the operations you want your service or revision to perform.
The next section covers the required roles for granting the deployer account access on the service identity resource and granting access for the service account principal.
Required roles
You or your administrator must grant IAM roles and permissions for the deployer account and the service identity.
Click to view required roles for the deployer account
To get the permissions that you need to attach a service account as the
service identity on the service or revision, you or your administrator
must grant your deployer account the
Service Account User
role (roles/iam.serviceAccountUser
) on the service account
that is used as the service identity.
This predefined role contains the iam.serviceAccounts.actAs
permission, which is required to attach a service account on the
service or revision. You might also be able to get this permission
by configuring custom roles
or using other predefined roles.
For instructions on how to grant the deployer account this role on the service identity, see deployment permissions. If the service account is in a different project from the Cloud Run service or revision, you or your administrator must also configure an IAM role for the Cloud Run service agent and set up an org policy. See use service accounts in other projects for more details.
Click to view required roles for the service identity
To allow the service identity to access Google Cloud APIs from Cloud Run, you or your administrator must grant the service identity the permissions or roles that are required by operations you want to perform. To accessing specific Cloud Client Libraries, refer to the Google Cloud documentation for the Google Cloud service.
If a Cloud Run service or revision does not access other Google Cloud services, you don't need to grant the service identity any roles or permissions, and you can use the default service account that was assigned to the project.
Get recommendations to create dedicated service accounts
When you create a new service account from the Google Cloud console, the optional step "Grant this service account access to the project" is for any additional access required. For example, one Cloud Run service might invoke another private Cloud Run service, or it might access a Cloud SQL database, both which require specific IAM roles. Refer to the documentation on managing access for more information.
The Recommender service also automatically supplies recommendations to create a dedicated service accounts with the minimal required set of permissions.
Configure service identity
If you haven't already created a service account, you can either create a user-managed service account in IAM, or in Cloud Run.
To configure service identity, use either the Google Cloud console, the gcloud CLI, the API (YAML) when you create a new service or deploy a new revision, or Terraform:
Console
In the Google Cloud console, go to Cloud Run:
Click Deploy container and select Service to configure a new service. If you are configuring an existing service, click the service, then click Edit and deploy new revision.
If you are configuring a new service, fill out the initial service settings page, then click Container(s), volumes, networking, security to expand the service configuration page.
Click the Security tab.
- Click the Service account dropdown and select an existing service account, or click Create a new service account if applicable.
Click Create or Deploy.
gcloud
If you haven't already created a service account, you can either create a user-managed service account in IAM.
You can update an existing service to have a new service account by using the following command:
gcloud run services update SERVICE --service-account SERVICE_ACCOUNT
Replace:
- SERVICE with the name of your service.
- SERVICE_ACCOUNT with the service account associated with the
new identity: this value is the email address for the service account, for
example,
example@myproject.iam.gserviceaccount.com
.
You can also set a service account during deployment using the command:
gcloud run deploy --image IMAGE_URL --service-account SERVICE_ACCOUNT
Replace:
- IMAGE_URL with a reference to the container image, for
example,
us-docker.pkg.dev/cloudrun/container/hello:latest
. If you use Artifact Registry, the repository REPO_NAME must already be created. The URL has the shapeLOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
. - SERVICE_ACCOUNT with the service account associated with the
new identity: this value is the email address for the service account, for
example,
example@myservice.iam.gserviceaccount.com
.
YAML
If you haven't already created a service account, you can either create a user-managed service account in IAM.
If you are creating a new service, skip this step. If you are updating an existing service, download its YAML configuration:
gcloud run services describe SERVICE --format export > service.yaml
Update the
serviceAccountName:
attribute:apiVersion: serving.knative.dev/v1 kind: Service metadata: name: SERVICE spec: template: spec: serviceAccountName: SERVICE_ACCOUNT
Replace
- SERVICE with the name of your Cloud Run service.
- SERVICE_ACCOUNT with the service account associated with
the new identity: this value is the email address for the service account,
for example,
SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
.
Create or update the service using the following command:
gcloud run services replace service.yaml
Terraform
To learn how to apply or remove a Terraform configuration, see Basic Terraform commands.
To create a service account, add the following resource to your to your existing main.tf
file:
Create or update a Cloud Run service and include your service account:
Use service accounts in other projects
If you configure a service account from a different Google Cloud project than the Cloud Run resource, do the following:
You or your administrator must grant the Service Account User role (
roles/iam.serviceAccountUser
) on the service account that you use as the service identity.Console
Go to the Service accounts page of the Google Cloud console:
Select the service account email address you are using as the service identity.
Click the Permissions tab.
Click the
Grant access button.Enter the deployer account email address that matches the principal you're granting the Admin or Developer role to.
In the Select a role drop-down, select the Service Accounts > Service Account User role.
Click Save.
gcloud
Use the
gcloud iam service-accounts add-iam-policy-binding
command, replacing the highlighted variables with the appropriate values:gcloud iam service-accounts add-iam-policy-binding \ SERVICE_ACCOUNT_NAME@SERVICE_ACCOUNT_PROJECT_ID.iam.gserviceaccount.com \ --member="PRINCIPAL" \ --role="roles/iam.serviceAccountUser"
Replace:
SERVICE_ACCOUNT_NAME
: The name of the service account that you are attaching the Cloud Run resource to.SERVICE_ACCOUNT_PROJECT_ID
: The project ID where the service account is located.PRINCIPAL with the deployer account you are adding the binding for, using the format
user|group|serviceAccount:email
ordomain:domain
. For example:user:test-user@gmail.com
group:admins@example.com
serviceAccount:test123@example.domain.com
domain:example.domain.com
You or your administrator must grant the Cloud Run resource's service agent the Service Account Token Creator role (
roles/iam.serviceAccountTokenCreator
) on the service account you use as the service identity. The service agent follows the format ofservice-PROJECT_NUMBER@serverless-robot-prod.iam.gserviceaccount.com
.Console
Go to the Service accounts page of the Google Cloud console:
Select the service account email address you are using as the service identity.
Click the Permissions tab.
Click the
Grant access button.Enter the service agent email address. For example:
service-PROJECT_NUMBER@serverless-robot-prod.iam.gserviceaccount.com
.In the Select a role drop-down, select the Service Accounts > Service Account Token Creator role.
Click Save.
gcloud
Use the
gcloud iam service-accounts add-iam-policy-binding
command:gcloud iam service-accounts add-iam-policy-binding \ SERVICE_ACCOUNT_NAME@SERVICE_ACCOUNT_PROJECT_ID.iam.gserviceaccount.com \ --member="serviceAccount:service-CLOUD_RUN_RESOURCE_PROJECT_NUMBER@serverless-robot-prod.iam.gserviceaccount.com" \ --role="roles/iam.serviceAccountTokenCreator"
Replace the following values:
SERVICE_ACCOUNT_NAME
: The name of the service account that you are attaching the Cloud Run resource to.SERVICE_ACCOUNT_PROJECT_ID
: The project ID where the service account is located.CLOUD_RUN_RESOURCE_PROJECT_NUMBER
: The project number where the Cloud Run is located.
The command prints the updated allow policy for the user-managed service account.
The project containing this service account requires the org-policy
iam.disableCrossProjectServiceAccountUsage
to be set to false or unenforced at the folder level or inherited from project-level settings. By default, this is set totrue
.Console
Go to the Organization policies page in the Google Cloud console:
From the project picker, select the organization and project for which you want to disable cross-project service account usage for.
Select the disable cross-project service account usage policy.
Click Manage policy.
Under Policy source, select Override parent's policy.
Click Add a rule.
Under Enforcement, select Off.
To enforce the policy, click Set policy.
gcloud
In the project that has the service account, ensure that the
iam.disableCrossProjectServiceAccountUsage
organization policy constraint is not enforced. This constraint is enforced by default.To disable this organization policy constraint, run:
gcloud resource-manager org-policies disable-enforce iam.disableCrossProjectServiceAccountUsage --project=SERVICE_ACCOUNT_PROJECT_ID
Replace SERVICE_ACCOUNT_PROJECT_ID with the project ID that contains the service account.
You can apply role memberships directly to the service account resource or inherit from higher levels in the resource hierarchy.
What's next
- For more information about service accounts, see the IAM service account and user-managed service account guides.
- If your Cloud Run service or job accesses Google APIs or Google Cloud services, you must configure your service account as the service identity. Learn more.