Configure secrets

Your service might need to have dependencies requiring API keys, passwords, certificates, or other sensitive information. For Cloud Run, Google recommends that you store this type of sensitive information in a secret created in Secret Manager.

You can make a secret available to your containers in either of two ways:

  • Mount each secret as a volume, which makes the secret available to the container as files. Reading a volume always fetches the secret value from Secret Manager, so it can be used 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 rather than using latest.

For more information, refer to the Secret Manager best practices document.

How secrets are checked at deployment and runtime

During service deployment, all secrets used, whether as environment variable or mounted as a volume, are checked to ensure the service account used to run the container has access to them. If any check fails, the service deployment fails.

During runtime, when instances start up:

  • If the secret is an environment variable, the value of the secret is retrieved prior to starting the instance, so if secret retrieval fails, the instance does not start.
  • If the secret is mounted as a volume, no check is performed during instance startup. However, during runtime, if a secret is inaccessible, attempts to read the mounted volume will fail.

Volume ownership differs by execution environment and deployment type

When you mount a secret volume, the identity owning the files and directories differs depending on the workload's execution environment and on whether the deployment consists of one or multiple containers.

In the first generation execution environment where you are deploying a single container, the secret volume is owned by the identity used for the container. In all other cases, the volume is owned by root. This includes:

  • First generation execution environment where you are deploying multiple containers
  • The second generation environment

Before you begin

  1. Enable the Secret Manager API.

    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:

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

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 service 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 service using the Google Cloud console, the Google Cloud CLI, or a YAML file when you deploy a new service or update an existing service, 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. Click Deploy container and select Service to configure a new service. Fill out the initial service settings page, then click Container(s), volumes, networking, security to expand the service configuration page.

  3. If you are configuring an existing service, click the service, 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 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 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.

    • To expose the secret as an environment variable:

      1. Click the Container 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.

gcloud

To make a secret accessible to your service, enter one of the following commands.

  • To mount the secret as a volume when deploying a service:

    gcloud run deploy SERVICE --image IMAGE_URL  \
--update-secrets=PATH=SECRET_NAME:VERSION

    Replace:

    • SERVICE with the name of your service.
    • 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 shape LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
    • PATHwith the mount path of the volume and filename of the secret. It must start with a leading slash, for example: /etc/secrets/dbconfig/password, where /etc/secrets/dbconfig/ is the mount path of the volume, and password is the filename of the secret.
    • SECRET_NAME with the secret name in the same project, e.g. mysecret.
    • VERSION with the secret version. Use latest for latest version, or a number, for example, 2.

  • To expose the secret as an environment variable when deploying a service:

    gcloud run deploy SERVICE \
--image IMAGE_URL \
--update-secrets=ENV_VAR_NAME=SECRET_NAME:VERSION

    Replace:

    • SERVICE with the name of your service.
    • 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 shape LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
    • ENV_VAR_NAME with the name of the environment variable you want to use with the secret.
    • SECRET_NAME with the secret name in the same project, e.g. mysecret.
    • VERSION with the secret version. Use latest for latest version, or a number, for example, 2.

  • You can update multiple secrets at the same time. To do this, 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, enter the following command:

    gcloud run deploy SERVICE --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 service, use the --set-secrets flag:

    gcloud run services update SERVICE \
--set-secrets="ENV_VAR_NAME=SECRET_NAME:VERSION"

YAML

  1. 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

  2. For secrets exposed as environment variables, under env, update the ENV_VAR, VERSION, and/or SECRET_NAME as desired. If you have multiple secrets mounted as environment variables, you will have multiples of these attributes.

    apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: SERVICE
spec:
  template:
    metadata:
      name: REVISION
    spec:
      containers:
      - image: IMAGE_URL
        env:
        - name: ENV_VAR
          valueFrom:
            secretKeyRef:
              key: VERSION
              name: SECRET_NAME

  3. For secrets mounted as file paths, update the MOUNT_PATH, VOLUME_NAME, VERSION, FILENAME, and/or SECRET_NAME as desired. If you have multiple secrets mounted as file paths, you will have multiples of these attributes.

    apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: SERVICE
spec:
  template:
    metadata:
      name: REVISION
    spec:
      containers:
      - image: IMAGE_URL
        volumeMounts:
        - mountPath: MOUNT_PATH
          name: VOLUME_NAME
      volumes:
      - name: VOLUME_NAME
        secret:
          items:
          - key: VERSION
            path: FILENAME
          secretName: SECRET_NAME

    Note that VOLUME_NAME can be set to any name.

    Replace

    • SERVICE with the name of your Cloud Run service
    • 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 shape LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
    • REVISION with a new revision name or delete it (if present). If you supply a new revision name, it must meet the following criteria:
      • Starts with SERVICE-
      • Contains only lowercase letters, numbers and -
      • Does not end with a -
      • Does not exceed 63 characters

  4. Replace the service with its new configuration using the following command:

    gcloud run services replace service.yaml

Terraform

  1. Create a secret and a secret version.

    resource "google_secret_manager_secret" "default" {
  secret_id = "my-secret"
  replication {
    auto {}
  }
}

resource "google_secret_manager_secret_version" "default" {
  secret      = google_secret_manager_secret.default.name
  secret_data = "this is secret data"
}

  2. Create a service account and grant it access to the secret:

    resource "google_service_account" "default" {
  account_id   = "cloud-run-service-account"
  display_name = "Service account for Cloud Run"
}

resource "google_secret_manager_secret_iam_member" "default" {
  secret_id = google_secret_manager_secret.default.id
  role      = "roles/secretmanager.secretAccessor"
  # Grant the new deployed service account access to this secret.
  member     = "serviceAccount:${google_service_account.default.email}"
  depends_on = [google_secret_manager_secret.default]
}

  3. Secret Manager secrets can be accessed from Cloud Run as mounted file paths or as environment variables.

    1. For secrets mounted as file paths, reference the Secret Manager resource in the volumes parameter. The name corresponds with an entry in the volume_mounts parameter:

      resource "google_cloud_run_v2_service" "mounted_secret" {
  name     = "service-with-mounted-secret"
  location = "us-central1"
  ingress  = "INGRESS_TRAFFIC_ALL"

  deletion_protection = false # set to "true" in production

  template {
    volumes {
      name = "my-service-volume"
      secret {
        secret = google_secret_manager_secret.default.secret_id
        items {
          version = "latest"
          path    = "my-secret"
          mode    = 0 # use default 0444
        }
      }
    }
    containers {
      image = "us-docker.pkg.dev/cloudrun/container/hello"
      volume_mounts {
        name       = "my-service-volume"
        mount_path = "/secrets"
      }
    }
    service_account = google_service_account.default.email
  }
  depends_on = [google_secret_manager_secret_version.default]
}

    2. For secrets exposed as environment variables, reference the Secret Manager resource in the env parameter:

      resource "google_cloud_run_v2_service" "env_variable_secret" {
  name     = "service-with-env-var-secret"
  location = "us-central1"
  ingress  = "INGRESS_TRAFFIC_ALL"

  deletion_protection = false # set to "true" in production

  template {
    containers {
      image = "us-docker.pkg.dev/cloudrun/container/hello"
      env {
        name = "MY_SECRET"
        value_source {
          secret_key_ref {
            secret  = google_secret_manager_secret.default.secret_id
            version = "latest"
          }
        }
      }
    }
    service_account = google_service_account.default.email
  }
  depends_on = [google_secret_manager_secret_version.default]
}

Reference secrets from other projects

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

Console

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

    Go to Cloud Run

  2. Click Deploy container and select Service to configure a new service. Fill out the initial service settings page, then click Container(s), volumes, networking, security to expand the service configuration page.

  3. If you are configuring an existing service, click the service, 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 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 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.

    • To expose the secret as an environment variable:

      1. Click the Container 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.

gcloud

  • To mount a secret as a volume when deploying a service:

    gcloud run deploy SERVICE --image IMAGE_URL  \
--update-secrets=PATH=projects/PROJECT_NUMBER/secrets/SECRET_NAME:VERSION

    Replace:

    • SERVICE with the name of your service.
    • 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 shape LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
    • PATHwith the mount path of the volume and filename of the secret. It must start with a leading slash, for example: /etc/secrets/dbconfig/password, where /etc/secrets/dbconfig/ is the mount path of the volume, and password is the filename of the secret.
    • PROJECT_NUMBER with the project number for the project the secret was created in.
    • SECRET_NAME with the secret name, e.g. mysecret.
    • VERSION with the secret version. Use latest for latest version, or a number, for example, 2.

YAML

  1. 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

Due to constraints around API compatibility, the secret locations must be stored in an annotation.

  1. For secrets exposed as environment variables:

    apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: SERVICE
spec:
  template:
    metadata:
      annotations:
        run.googleapis.com/secrets: SECRET_LOOKUP_NAME:projects/PROJECT_NUMBER/secrets/SECRET_NAME
    spec:
      containers:
      - image: IMAGE_URL
        env:
        - name: ENV_VAR
          valueFrom:
            secretKeyRef:
              key: VERSION
              name: SECRET_LOOKUP_NAME

    Replace:

    • SERVICE with the name of your service.
    • 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 shape LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
    • ENV_VAR
    • PROJECT_NUMBER with the project number for the project the secret was created in.
    • SECRET_NAME with the secret name, e.g. mysecret.
    • VERSION with the secret version. Use latest for latest version, or a number, for example, 2.
    • SECRET_LOOKUP_NAME with any name that has a valid secret name syntax (e.g. my-secret), it can be the same as SECRET_NAME

  2. For secrets mounted as file paths:

    apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: SERVICE
spec:
  template:
    metadata:
      annotations:
        run.googleapis.com/secrets: SECRET_LOOKUP_NAME:projects/PROJECT_NUMBER/secrets/SECRET_NAME
    spec:
      containers:
      - image: IMAGE_URL
        volumeMounts:
        - mountPath: MOUNT_PATH
          name: VOLUME_NAME
      volumes:
      - name: VOLUME_NAME
        secret:
          items:
          - key: VERSION
            path: FILENAME
          secretName: SECRET_LOOKUP_NAME

    Replace:

    • SERVICE with the name of your service.
    • 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 shape LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
    • PATHwith the mount path of the volume and filename of the secret. It must start with a leading slash, for example: /etc/secrets/dbconfig/password, where /etc/secrets/dbconfig/ is the mount path of the volume, and password is the filename of the secret.
    • PROJECT_NUMBER with the project number for the project the secret was created in.
    • SECRET_NAME with the secret name, e.g. mysecret.
    • VERSION with the secret version. Use latest for latest version, or a number, for example, 2.
    • SECRET_LOOKUP_NAME with any name that has a valid secret name syntax (e.g. my-secret), it can be the same as SECRET_NAME
    • VOLUME_NAME with any name (e.g. my-volume), it can be the same as SECRET_NAME

View secrets settings

To view the current secrets settings for your Cloud Run service:

Console

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

    Go to Cloud Run

  2. Click the service you are interested in to open the Service details page.

  3. Click the Revisions tab.

  4. In the details panel at the right, the secrets setting is listed under the Container tab.

gcloud

  1. Use the following command:

    gcloud run services describe SERVICE

  2. Locate the secrets setting in the returned configuration.

Use secrets in your code

For examples on 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

Cloud Run does not allow you to mount secrets at /dev, /proc and /sys, or on their subdirectories.

If you are mounting secrets on /tmp and you are using first generation execution environment, refer to the known issue on mounting secrets on /tmp.

Cloud Run does not allow you to mount multiple secrets at the same path because two volume mounts cannot 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.