Using secrets

Your service might need to have dependencies requiring API keys, passwords 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 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 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.

Allowing Cloud Run to access a secret

You can use an existing Secret Manager secret or create a new secret. However, in order to allow a Cloud Run service to access the secret, you must grant the Secret Manager Secret Accessor role to the Cloud Run service account:

  1. Go to the Secret Manager page in the Cloud Console

  2. Select the secret and in the right side permissions tab, click Add Principal.

  3. In the New principals textbox, enter the service account email for your Cloud Run service.

  4. Grant it the role Secret Manager Secret Accessor.

Making a secret accessible to a service

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 Cloud Console, the gcloud command-line tool, or a YAML file when you deploy a new service or update an existing service and deploy a revision:

Console

  1. Go to Cloud Run

  2. Click Create Service if you are configuring a new service you are deploying to. If you are configuring an existing service, click on the service, then click Edit and Deploy New Revision.

  3. If you are configuring a new service, fill out the initial service settings page as desired, then click Next > Advanced settings to reach the service configuration page.

  4. Click the Variables & Secrets tab.

    image

  5. In the Variables & Secrets tab:

    • Under Secrets, click Reference a Secret
    • Select the secret you want to use from the Secret pulldown list.
    • In the Reference method pulldown menu, select the way you want to use your secret, mounted as a volume or exposed as environment variables.
    • If you are mounting the secret as a volume,
      1. Under Mount path, specify the mount path you are using for secrets.
      2. By default, the latest version is selected. You can select a specific version if you want. Under Specified paths for secret versions, specify the path to the version and the version number.
      3. Click Done.
    • If you are exposing the secret as an environment variable:
      1. Supply the Name of the variable and select the secret version, or latest to always use the current secret version.
      2. Click Done.

  6. Click Create or Deploy.

Command line

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
    • 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.
    • VERSION with the secret version. Use latest for latest version, or an integer, 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
    • ENV_VAR_NAME with the name of the environment variable you want to use with the secret.
    • SECRET_NAME with the secret name.
    • VERSION with the secret version. Use latest for latest version, or an integer, for example, 2.
  • You can update multiple secrets at once. 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

You can download and view existing service configuration using the gcloud run services describe --format export command, which yields cleaned results in YAML format. You can then modify the fields described below and upload the modified YAML using the gcloud run services replace command. Make sure you only modify fields as documented.

  1. To view and download the 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:
        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:
        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.

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

    gcloud run services replace service.yaml

Referencing secrets from other projects

You can reference a secret from another project, if your project's service account has been allowed to access the secret.

Console

  1. Go to Cloud Run

  2. Click Create Service if you are configuring a new service you are deploying to. If you are configuring an existing service, click on the service, then click Edit and Deploy New Revision.

  3. If you are configuring a new service, fill out the initial service settings page as desired, then click Next > Advanced settings to reach the service configuration page.

  4. Click the Variables & Secrets tab.

    image

  5. In the Variables & Secrets tab:

    • Under Secrets, click Reference a Secret
    • Select Don't see your secret? Enter secret resource ID from the Secret pulldown list, to display the following form:

      Cross project secrets

    • In the Add a secret by resource ID form, enter the secret from the other project, in the format projects/PROJECT_NUMBER/secrets/SECRET_NAME. You can alternatively copy and paste the resource ID from the other project if you have access to it, by selecting the secret, clicking the Actions ellipsis at the right of the secret, and selecting Copy resource ID from the pulldown menu.
    • Click Add secret.
    • In the Reference method pulldown menu, select the way you want to use your secret, mounted as a volume or exposed as environment variables.
    • If you are mounting the secret as a volume,
      1. Under Mount path, specify the mount path you are using for secrets.
      2. By default, the latest version is selected. You can select a specific version if you want. Under Specified paths for secret versions, specify the path to the version and the version number.
      3. Click Done.
    • If you are exposing the secret as an environment variable:
      1. Supply the Name of the variable and select the secret version, or latest to always use the current secret version.
      2. Click Done.

  6. Click Create or Deploy.

Command line

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

    gcloud run deploy SERVICE --image IMAGE_URL  \
    --update-secrets=PATH=project/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
    • 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.
    • VERSION with the secret version. Use latest for latest version, or an integer, for example, 2.

Viewing secrets settings

To view the current secrets settings for your service:

Console

  1. 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 Variables & Secrets tab.

Command line

  1. Use the following command:

    gcloud run services describe SERVICE
  2. Locate the secrets setting in the returned configuration.

YAML

You can download and view existing service configuration using the gcloud run services describe --format export command, which yields cleaned results in YAML format. You can then modify the fields described below and upload the modified YAML using the gcloud run services replace command. Make sure you only modify fields as documented.

  1. To view and download the 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:
          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
    • ENV_VAR
    • PROJECT_NUMBER with the project number for the project the secret was created in.
    • SECRET_NAME with the secret name.
    • VERSION with the secret version. Use latest for latest version, or an integer, 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:
          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
    • 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.
    • VERSION with the secret version. Use latest for latest version, or an integer, 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

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