Configure secrets

Your job 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 job creation, 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 job creation 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 volume using the second generation execution environment, which is the case for jobs, the volume is owned by root.

Before you begin

You can use an existing Secret Manager secret or create a new 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 job
Service Account User (roles/iam.serviceAccountUser) on the service identity

To allow Cloud Run to access the secret, the service account 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 job 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

You can make a secret accessible to your job using the Google Cloud console, the Google Cloud CLI, or YAML:

Console

In the Google Cloud console, go to the Cloud Run jobs page:

Go to Cloud Run
If you are configuring a new job, click the Jobs tab and fill out the initial job settings page as desired. If you are configuring an existing job, click the job, then click Edit.
Click Container, variables and secrets, connections, security to expand the job properties page.
Click the Variables & Secrets tab.
- In the Variables & Secrets tab:
  - Under Secrets, click Add a secret reference
  - 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.
Click Create or Update.

Command line

To specify the secret in an environment variable when creating a new job:
```
gcloud run jobs create JOB_NAME \
--image IMAGE_URL \
--set-secrets ENV_VAR_NAME=SECRET_NAME:VERSION
```
Replace
- JOB_NAME with the name of your job.
- ENV_VAR_NAME with the name of the environment variable to use for 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.
- Replace IMAGE_URL with a reference to the container image, for example, us-docker.pkg.dev/cloudrun/container/job:latest.
You can specify several environment variable/secret pairs, using a comma delimited list.

To specify the secret in an environment variable when updating a job:

gcloud run jobs update JOB_NAME \
--set-secrets ENV_VAR_NAME=SECRET_NAME:VERSION

To mount the secret as a volume when creating a job:
```
gcloud run jobs create JOB_NAME \
--image IMAGE_URL \
--set-secrets=PATH=SECRET_NAME:VERSION
```
Replace:
- JOB_NAME with the name of your job.
- IMAGE_URL with a reference to the container image, for example, us-docker.pkg.dev/cloudrun/container/job: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 in the same project, e.g. mysecret.
- VERSION with the secret version. Use latest for latest version, or a number, for example, 2.

To update a secret in an existing job:

gcloud run jobs update JOB_NAME \
--update-secrets=PATH=SECRET_NAME:VERSION

YAML

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

Download and view existing job configuration using the gcloud run jobs describe --format export command, which yields cleaned results in YAML format. Then modify the fields described below and upload the modified YAML using the gcloud run jobs replace command. Make sure you only modify fields as documented.

To view and download the configuration:

gcloud run jobs describe JOB_NAME --format export > job.yaml

For secrets exposed as environment variables:
```
apiVersion: run.googleapis.com/v1
kind: Job
metadata:
  name: JOB
spec:
  template:
    spec:
      template:
        spec:
          containers:
          - env:
            - name: SECRET_NAME
              valueFrom:
                secretKeyRef:
                  key: VERSION
                  name: SECRET_LOOKUP_NAME
            image: IMAGE_URL 
```
Replace:
- JOB with the name of your job.
- 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
- 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
For secrets mounted as file paths:
```
apiVersion: run.googleapis.com/v1
kind: Job
metadata:
  name: JOB_NAME
spec:
  template:
    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_LOOKUP_NAME
```
Replace:
- JOB_NAME with the name of your job.
- 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, for example 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

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

In the Google Cloud console, go to the Cloud Run jobs page:

Go to Cloud Run
If you are configuring a new job, click the Jobs tab and fill out the initial job settings page as desired. If you are configuring an existing job, click the job, then click Edit.
Click Container, variables and secrets, connections, security to expand the job properties page.
Click the Variables & Secrets tab.
- In the Variables & Secrets tab:
  - Under Secrets, click Add a secret reference
  - Select Enter secret manually from the Secrets pulldown list to display the following form:
  - 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.
Click Create or Update.

Command line

To mount a secret as a volume when updating a job:
```
gcloud run jobs update JOB_NAME \
--image IMAGE_URL \
--update-secrets=PATH=projects/PROJECT_NUMBER/secrets/SECRET_NAME:VERSION
```
- JOB_NAME with the name of your job.
- 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

To view and download the configuration:

gcloud run jobs describe JOB_NAME --format export > job.yaml

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

For secrets exposed as environment variables:
```
apiVersion: run.googleapis.com/v1
kind: Job
metadata:
  name: JOB
spec:
  template:
    metadata:
      annotations:
        run.googleapis.com/secrets: SECRET_LOOKUP_NAME:projects/PROJECT_NUMBER/secrets/SECRET_NAME
    spec:
      template:
        spec:
          containers:
          - env:
            - name: SECRET_NAME
              valueFrom:
                secretKeyRef:
                  key: VERSION
                  name: SECRET_LOOKUP_NAME
            image: IMAGE_URL 
```
Replace:
- JOB with the name of your job.
- 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
- SECRET_NAME with the secret name, for example mysecret.
- VERSION with the secret version. Use latest for latest version, or a number, for example, 2.
- PROJECT_NUMBER with the project number for the project the secret was created in.
- 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.
For secrets mounted as file paths:
```
apiVersion: run.googleapis.com/v1
kind: Job
metadata:
  name: JOB_NAME
spec:
  template:
    metadata:
      annotations:
        run.googleapis.com/secrets: SECRET_LOOKUP_NAME:projects/PROJECT_NUMBER/secrets/SECRET_NAME
    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_LOOKUP_NAME
```
Replace:
- JOB_NAME with the name of your job.
- 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, for example 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 job:

Console

In the Google Cloud console, go to the Cloud Run jobs page:

Go to Cloud Run jobs
Click the job you are interested in to open the Job details page.
Click the Configuration tab.
Locate the secrets setting in the configuration details.

Command line

Use the following command:
```
gcloud run jobs describe JOB_NAME
```
Locate the secrets setting in the returned configuration.

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 being mounted to path /etc/app_data, all the contents inside the app_data directory will be overwritten. To avoid overwriting an existing directory, provide a path that would create a new directory, ex. /etc/app_data/secrets. This will create a mount path /etc/app_data/secrets/my-secret which will contain the secret.