Configure secrets for worker pools

Preview — Cloud Run worker pools

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

Your worker pool might require API keys, passwords, certificates, or other sensitive information for its dependencies. For Cloud Run, Google recommends storing this sensitive information in a secret you create in Secret Manager.

Make a secret available to your containers in one of the following ways:

• When you mount each secret as a volume, Cloud Run makes the secret available to the container as files. When reading a volume, Cloud Run always fetches the secret value from the Secret Manager to use the value with the latest version. This method also works well with secret rotation.
• Pass a secret using environment variables. Environment variables are resolved at instance startup time, so if you use this method, Google recommends that you pin the secret to a particular version instead of using latest as the version.

For more information, see Secret Manager best practices.

How secrets are checked at deployment and runtime

During worker pool deployment, Cloud Run checks all the secrets you use. The check ensures that the service account that runs the container has permission to access these secrets.

During runtime, when instances start up:

• If the secret is an environment variable, Cloud Run retrieves the value of the secret prior to starting the instance. If the secret retrieval process fails, the instance doesn't start.
• If you mount the secret as a volume, Cloud Run doesn't perform any checks during instance startup. However, during runtime, if a secret is inaccessible, attempts to read the mounted volume fail.

Volume ownership

The ownership of a Cloud Run secret volume differs by the execution environment and deployment type.

When you mount a secret volume using the second generation execution environment, which is always the case for worker pool, root owns the volume.

Before you begin

1. Enable the Secret Manager API.

   Roles required to enable APIs

   To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

   Enable the API

2. Use an existing secret or, create a secret in Secret Manager, as described in Create a secret.

Required roles

To get the permissions that you need to configure secrets, ask your administrator to grant you the following IAM roles:

• Cloud Run Admin (roles/run.admin) on the Cloud Run worker pool
• Service Account User (roles/iam.serviceAccountUser) on the service identity

To allow Cloud Run to access the secret, the service identity must have the following role:

• Secret Manager Secret Accessor (roles/secretmanager.secretAccessor)

For instructions on how to add the service identity principal to the Secret Manager Secret Accessor role, see Manage access to secrets.

For a list of IAM roles and permissions that are associated with Cloud Run, see Cloud Run IAM roles and Cloud Run IAM permissions. If your Cloud Run worker pool interfaces with Google Cloud APIs, such as Cloud Client Libraries, see the service identity configuration guide. For more information about granting roles, see deployment permissions and manage access.

Make a secret accessible to Cloud Run

Any configuration change leads to the creation of a new revision. Subsequent revisions will also automatically get this configuration setting unless you make explicit updates to change it.

You can make a secret accessible to your worker pool using the Google Cloud console, or the Google Cloud CLI when you deploy a new worker pool or update an existing worker pool, and deploy a revision. Click the tab of your choice:

Console

1. In the Google Cloud console, go to Cloud Run:

   Go to Cloud Run

2. Select Worker pools from the menu, and click Deploy container to configure a new worker pool. Fill out the initial worker pool settings page, then click Container(s), Volumes, Networking, Security to expand the configuration page.

3. If you are configuring an existing worker pool, click the worker pool, and click Edit and deploy new revision.

4. Follow the steps to mount the secret as a volume, or expose the secret as an environment variable.

   • To expose the secret as an environment variable:

     1. Click the Container(s) tab.
     2. In the Variables and Secrets tab, click Reference a secret.
     3. In the Name 1 field, enter the name of the environment variable.
     4. From the Secret list, select the secret you want to use.
     5. From the Version 1 list, select the version of the secret to reference.
     6. Click Done.
     7. Click Create or Deploy.

   • To mount secret as a volume:

     1. Click the Volumes tab and select Add volume.
     2. In the Volume type list, select Secret.
     3. In the Volume name field, enter a name or accept the default name.
     4. From the Secret list, select the secret you want to use.
     5. In the Path 1 field, enter the name of the file to mount.
     6. In the Version 1 list, select the version of the secret to reference. By default, the latest version is selected. You can select a specific version if you want.
     7. Click Done.
     8. Navigate to the Container(s) tab to mount your secret to the container.
     9. In the Volume mounts tab, and click Mount volume.
     10. From the Name 1 list, select your volume name.
     11. In the Mount path 1 field, enter the mount path for this secret. This is the directory where all versions of your secret are placed.
     12. Click Done.
     13. Click Create or Deploy.

gcloud

• To expose the secret as an environment variable when you deploy a worker pool, run the following command:

  gcloud beta run worker-pools deploy WORKER_POOL \
  --image IMAGE_URL \
  --update-secrets=ENV_VAR_NAME=SECRET_NAME:VERSION

  Replace the following:

  • WORKER_POOL: the name of your worker pool.
  • IMAGE_URL: a reference to the container image that contains the worker pool, such as us-docker.pkg.dev/cloudrun/container/worker-pool:latest.
  • ENV_VAR_NAME: the name of the environment variable you want to use with the secret.
  • SECRET_NAME: the secret name in the same project—for example, mysecret.
  • VERSION: the secret version. Use latest for latest version, or a number—for example, 2.

• To update multiple secrets at the same time, separate the configuration options for each secret with a comma. The following command updates one secret mounted as a volume and another secret exposed as an environment variable. To update existing secrets, run the following command:

  gcloud beta run worker-pools deploy WORKER_POOL \
  --image IMAGE_URL \
  --update-secrets=PATH=SECRET_NAME:VERSION,ENV_VAR_NAME=SECRET_NAME:VERSION

• To clear existing secrets and make a new secret accessible to the worker pool, use the --set-secrets flag:

  gcloud beta run worker-pools update WORKER_POOL \
  --set-secrets="ENV_VAR_NAME=SECRET_NAME:VERSION"

Reference secrets from other projects

To reference a secret from another project, verify that your project's worker pool account has access to the secret.

Console

1. In the Google Cloud console, go to Cloud Run:

   Go to Cloud Run

2. Select Worker pools from the menu, and click Deploy container to configure a new worker pool. Fill out the initial worker pool settings page, then click Container(s), Volumes, Networking, Security to expand the configuration page.

3. If you are configuring an existing worker pool, click the worker pool, and click Edit and deploy new revision.

4. Follow the steps to mount the secret as a volume, or expose the secret as an environment variable.

   • To expose the secret as an environment variable:

     1. Click the Container(s) tab.
     2. In the Variables and Secrets tab, click Reference a secret.
     3. In the Name 1 field, enter the name of the environment variable.
     4. From the Secret list, click Enter secret manually.

     5. Enter the secret's resource ID in the following format:

        projects/PROJECT_NUMBER/secrets/SECRET_NAME
        

        Replace the following:

        • PROJECT_NUMBER with your Google Cloud project number. For detailed instructions on how to find your project number, see Creating and managing projects.

        • SECRET_NAME: The name of the secret in Secret Manager.

     6. From the Version 1 list, select the version of the secret to reference.

     7. Click Done.

     8. Click Create or Deploy.

   • To mount secret as a volume:

     1. Click the Volumes tab and select Add volume.
     2. In the Volume type list, select Secret.
     3. In the Volume name field, enter a name or accept the default name.
     4. From the Secret list, click Enter secret manually.

     5. Enter the secret's resource ID in the following format:

        projects/PROJECT_NUMBER/secrets/SECRET_NAME
        

        Replace the following:

        • PROJECT_NUMBER with your Google Cloud project number. For detailed instructions on how to find your project number, see Creating and managing projects.

        • SECRET_NAME: The name of the secret in Secret Manager.

     6. In the Path 1 field, enter the name of the file to mount.

     7. In the Version 1 list, select the version of the secret to reference. By default, the latest version is selected. You can select a specific version if you want.

     8. Click Done.

     9. Navigate to the Container(s) tab to mount your secret to the container.

     10. In the Volume mounts tab, and click Mount volume.

     11. From the Name 1 list, select your volume name.

     12. In the Mount path 1 field, enter the mount path for this secret. This is the directory where all versions of your secret are placed.

     13. Click Done.

     14. Click Create or Deploy.

gcloud

To reference a secret as an environment variable, run the following commad:

gcloud beta run worker-pools deploy WORKER_POOL \
--image IMAGE_URL \
--update-secrets=ENV_VAR_NAME=projects/PROJECT_NUMBER/secrets/SECRET_NAME:VERSION

Replace the following:

• WORKER_POOL: the name of your worker pool.
• IMAGE_URL: a reference to the container image that contains the worker pool, such as us-docker.pkg.dev/cloudrun/container/worker-pool:latest.
• PROJECT_NUMBER with the project number for the project the secret was created in.
• SECRET_NAME: the secret name—for example, mysecret.
• VERSION with the secret version. Use latest for latest version, or a number—for example, 2.

View secrets settings

To view the current secrets settings for your Cloud Run worker pool:

Console

1. In the Google Cloud console, go to the Cloud Run worker pools page:

   Go to Cloud Run worker pools

2. Click the worker pool you are interested in to open the Worker pools details page.

3. Click Edit and deploy new revision.

4. Locate the secrets setting in the configuration details.

gcloud

1. Use the following command:

   gcloud beta run worker-pools describe WORKER_POOL

2. Locate the secrets setting in the returned configuration.

Remove secrets from a worker pool

You can remove secrets from a worker pool using either the Google Cloud console or the gcloud CLI:

Console

1. In the Google Cloud console, go to Cloud Run:

   Go to Cloud Run

2. Select your worker pool from the list, and click Edit and deploy new revision.

3. Click the Container(s) tab.

4. To delete secrets mounted as a volume, select the Volume mounts tab, and hold the pointer over the secret you want to remove, then click Delete.

5. To delete secrets exposed as an environment variable, select the Variables and secrets tab, and hold the pointer over the secret you want to remove, then click Delete.

6. Click Deploy.

gcloud

You can remove all secrets from a worker pool or specify one or more secrets to remove:

• To remove all secrets, run the following command:

  gcloud beta run worker-pools deploy WORKER_POOL --image IMAGE_URL \
  --clear-secrets

Replace the following:

• WORKER_POOL: the name of your worker pool.

• IMAGE_URL: a reference to the container image that contains the worker pool, such as us-docker.pkg.dev/cloudrun/container/worker-pool:latest.

• To specify a list of secrets to remove, use the --remove-secrets flag. The following command removes one secret mounted as a volume and another secret exposed as an environment variable:

  gcloud beta run worker-pools deploy WORKER_POOL --image IMAGE_URL \
  --remove-secrets=ENV_VAR_NAME,SECRET_FILE_PATH

Replace the following:

• WORKER_POOL: the name of your worker pool.
• IMAGE_URL: a reference to the container image that contains the worker pool, such as us-docker.pkg.dev/cloudrun/container/worker-pool:latest.
• ENV_VAR_NAME: the name of the environment variable.

• SECRET_FILE_PATH: the full path of the secret. For example, /mnt/secrets/primary/latest, where /mnt/secrets/primary/ is the mount path and latest is the secret path. You can also specify the mount and secret paths separately:

  --set-secrets MOUNT_PATH:SECRET_PATH=SECRET:VERSION

Use secrets in your code

For examples of accessing secrets in your code as environment variables, refer to the tutorial on end user authentication, particularly the section Handling sensitive configuration with Secret Manager.

Disallowed paths and limitations

The following limitations apply to mounting secrets:

• Cloud Run doesn't allow you to mount secrets at /dev, /proc and /sys, or on their subdirectories.
• Cloud Run doesn't allow you to mount multiple secrets at the same path because two volume mounts can't be mounted at the same location.

Overriding a directory

If the secret is mounted as a volume in Cloud Run, and the last directory in the volume mount path already exists, then any files or folders in the existing directory become inaccessible.

For example, if a secret called my-secret is mounted to path /etc/app_data, all the contents inside the app_data directory will be overwritten, and the only visible file is /etc/app_data/my-secret.

To avoid overwriting files in an existing directory, create a new directory for mounting the secret, for example, /etc/app_data/secrets, so that the mount path for the secret is /etc/app_data/secrets/my-secret.