Using user-managed service accounts

App Engine apps require a service account in order to access other Google Cloud services and execute tasks. By default, the App Engine default service account is used as the identity of your App Engine app. You may also specify a different user-managed service account to be used as the identity for a specific version of your App Engine app. This allows you to grant different privileges to each version, based on the specific tasks it performs, and avoid granting more privileges than necessary.

This guide covers how to specify a different user-managed service account when deploying a new version. If you don't need to create a distinct service account when deploying a specific version of your app, you can continue to use the default service account by not specifying a service account.

Creating a user-managed service account

To create a user-managed service account, see these instructions. When defining the Identity and Access Management (IAM) roles to grant your service account, you can refer to Roles that Grant Access to App Engine.

If you need to review IAM concepts before creating your service account, see IAM concepts overview and service accounts guides.

After you create your user-managed service account, you can update the app-level default service account for your application by using one of the following methods:

gcloud

Run the gcloud app update command.

    gcloud app update --service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

Replace:

  • SERVICE_ACCOUNT_NAME with the name of the service account that you created.
  • PROJECT_ID with ID of the Google Cloud project in which you want to assign the service account.

Each new version that you deploy after this update uses the new app-level default service account unless you explicitly assign a version-specific service account.

Console

  1. Go to the App Engine Application Settings tab in the console and click Edit Application Settings.

    Go to Application Settings

  2. Choose an app-level default service account from Select a Service account and click Save.

    You will be redirected to the Application Settings tab where you can view the email address of your updated app-level default service account. Example: SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com.

    Each new version that you deploy after this update uses the new app-level default service account unless you explicitly assign a version-specific service account.

Specifying a service account when deploying your app

gcloud

Run the gcloud app deploy command and specify your service account:

gcloud app deploy --service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

app.yaml

In your app.yaml file, specify your service account by adding the service_account element:

service_account: SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

Next steps

Follow best practices for working with service accounts.