Configure secrets for jobs

Your job might require API keys, passwords, certificates, orother sensitive information for its dependencies. For Cloud Run,Google recommends storing this sensitive information in a secret you create inSecret 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 secretavailable to the container as files. When reading a volume, Cloud Runalways fetches the secret value from the Secret Manager to usethe value with the latest version. This method also works well with secretrotation.
  • Pass a secret usingenvironment variables.Environment variables are resolved at instance startup time, so if you usethis method, Google recommends that you pin the secret to a particular versioninstead of usinglatest as the version.

For more information, see Secret Managerbest practices.

How secrets are checked at deployment and runtime

During job creation, Cloud Run checks all the secretsyou use. The check ensures that the service account that runs the container haspermission to access these secrets.

During runtime, when instances start up:

  • If the secret is an environment variable, Cloud Run retrieves thevalue of the secret prior to starting the instance. If the secret retrievalprocess fails, the instance doesn't start.
  • If you mount the secret as a volume, Cloud Run doesn't perform anychecks during instance startup. However, during runtime, if a secret isinaccessible, attempts to read the mounted volume fail.

Volume ownership

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

When you mount a secret volume using the second generation executionenvironment, which is always the case for job, root owns thevolume.

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 theserviceusage.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:

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

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

For a list of IAM roles and permissions that are associated withCloud Run, seeCloud Run IAM rolesandCloud Run IAM permissions.If your Cloud Run job interfaces withGoogle Cloud APIs, such as Cloud Client Libraries, see theservice identity configuration guide.For more information about granting roles, seedeployment permissionsandmanage access.

Make a secret accessible to Cloud Run

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

Console

  1. In the Google Cloud console, go to the Cloud RunJobs page:

    Go to Cloud Run

  2. ClickDeploy container to fill outthe initial job settings page. If you are configuring an existing job,select the job, then clickView and edit job configuration.

  3. ClickContainer(s), Volumes, Connections, Security to expand the job properties page.

  4. Click theVariables & Secrets tab.

    image

    • In the Variables & Secrets tab:

      • To expose the secret as an environment variable:

        1. Click theContainer(s) tab.
        2. In theVariables and Secrets tab, clickReference a secret.
        3. In theName 1 field, enter the name of the environment variable.
        4. From theSecret list, select the secret you want to use.
        5. From theVersion 1 list, select the version of the secret to reference.
        6. ClickDone.
        7. ClickCreate orDeploy.

      • To mount secret as a volume:

        1. Click theVolumes tab and selectAdd volume.
        2. In theVolume type list, selectSecret.
        3. In theVolume name field, enter a name or accept the default name.
        4. From theSecret list, select the secret you want to use.
        5. In thePath 1 field, enter the name of the file to mount.
        6. In theVersion 1 list, select the version of the secret toreference. By default, the latest version is selected. You can selecta specific version if you want.
        7. ClickDone.
        8. Navigate to theContainer(s) tab to mount your secret to the container.
        9. In theVolume mounts tab, and clickMount volume.
        10. From theName 1 list, select your volume name.
        11. In theMount path 1 field, enter the mount path for this secret.This is the directory where all versions of your secret are placed.
        12. ClickDone.
        13. ClickCreate orDeploy.

  5. ClickCreate orUpdate.

gcloud

Note: You can update multiple secrets at the same time. To do this, separate theconfiguration options for each secret with a comma.

YAML

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

  1. If you are creating a new job, skip this step.If you are updating an existing job, download itsYAML configuration:

    gcloudrunjobsdescribeJOB_NAME--formatexport>job.yaml

  2. For secrets exposed as environment variables:

    apiVersion:run.googleapis.com/v1kind:Jobmetadata:name:JOBspec:template:spec:template:spec:containers:-env:-name:SECRET_NAMEvalueFrom:secretKeyRef:key:VERSIONname:SECRET_LOOKUP_NAMEimage:IMAGE_URL

    Replace the following:

    • JOB: the name of your job.
    • IMAGE_URL: a reference to thecontainer image—forexample,us-docker.pkg.dev/cloudrun/container/job:latest.
    • SECRET_NAME: the secret name—for example,mysecret.
    • VERSION: the secret version. Uselatestfor latest version, or a number—for example,2.
    • SECRET_LOOKUP_NAME: any name that has avalid secret name syntax—for example,my-secret. It can be the same asSECRET_NAME.

  3. For secrets mounted as file paths:

    apiVersion:run.googleapis.com/v1kind:Jobmetadata:name:JOB_NAMEspec:template:spec:template:spec:containers:-image:IMAGE_URLvolumeMounts:-mountPath:MOUNT_PATHname:VOLUME_NAMEvolumes:-name:VOLUME_NAMEsecret:items:-key:VERSIONpath:FILENAMEsecretName:SECRET_LOOKUP_NAME

    Replace the following:

    • JOB_NAME: the name of your job.
    • IMAGE_URL: a reference to thecontainer image—forexample,us-docker.pkg.dev/cloudrun/container/job:latest.
    • PATH: the mount path of the volume andfilename of the secret. It must start with a leading slash—for example,/etc/secrets/dbconfig/password, where/etc/secrets/dbconfig/ is themount path of the volume, andpassword is the filename of the secret.
    • PROJECT_NUMBER: the project number for theproject the secret was created in.
    • SECRET_NAME: the secret name—for example,mysecret.
    • VERSION: the secret version. Uselatestfor latest version, or a number—for example,2.
    • SECRET_LOOKUP_NAME: any name that has avalid secret name syntax—for example,my-secret. It can be the same asSECRET_NAME.
    • VOLUME_NAME: any name—for example,my-volume. Itcan be the same asSECRET_NAME.

Terraform

To learn how to apply or remove a Terraform configuration, seeBasic Terraform commands.

Add the following to agoogle_cloud_run_v2_job resource in your Terraform configuration:

For secrets exposed as environment variables:

resource"google_cloud_run_v2_job""default"{name="JOB_NAME"location="REGION"template{template{containers{image="IMAGE_URL"env{name="SECRET_NAME"value_source{secret_key_ref{secret="SECRET_NAME"version="VERSION"}}}}}}}

Replace the following:

  • JOB_NAME: the name of your Cloud Run job.
  • REGION: the Google Cloud region. For example,europe-west1.
  • IMAGE_URL: a reference to thecontainer image—forexample,us-docker.pkg.dev/cloudrun/container/job:latest.
  • SECRET_NAME: the secret name—for example,mysecret.
  • VERSION: the secret version. Uselatest for latestversion, or a number—for example,2.

For secrets mounted as file paths:

resource"google_cloud_run_v2_job""default"{name="JOB_NAME"location="REGION"template{template{containers{image="IMAGE_URL"volume_mounts{name="VOLUME_NAME"mount_path="MOUNT_PATH"}}volumes{name="VOLUME_NAME"secret{secret="SECRET_NAME"}}}}}

Replace the following:

  • JOB_NAME: the name of your Cloud Run job.
  • REGION: the Google Cloud region. For example,europe-west1.
  • IMAGE_URL: a reference to thecontainer image—forexample,us-docker.pkg.dev/cloudrun/container/job:latest.
  • VOLUME_NAME: any name—for example,my-volume. It can be thesame asSECRET_NAME.
  • MOUNT_PATH: the mount path of the volume andfilename of the secret. It must start with a leading slash—for example,/etc/secrets/dbconfig/password, where/etc/secrets/dbconfig/ is themount path of the volume, andpassword is the filename of the secret.
  • SECRET_NAME: the secret name—for example,mysecret.

Referencing secrets from other projects

You can reference a secret from another project, if your project's serviceaccount has beenallowed to access the secret.

Console

  1. In the Google Cloud console, go to the Cloud RunJobs page:

    Go to Cloud Run

  2. ClickDeploy container to fill outthe initial job settings page. If you are configuring an existing job,select the job, then clickView and edit job configuration.

  3. ClickContainer(s), Volumes, Connections, Security to expand the job properties page.

  4. Click theVariables & Secrets tab.

    image

    • In the Variables & Secrets tab:

      • To expose the secret as an environment variable:

        1. Click theContainer(s) tab.
        2. In theVariables and Secrets tab, clickReference a secret.
        3. In theName 1 field, enter the name of the environment variable.
        4. From theSecret list, clickEnter 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. Fordetailed instructions on how to find your project number, seeCreating and managing projects.

          • SECRET_NAME: The name of the secret inSecret Manager.

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

        7. ClickDone.

        8. ClickCreate orDeploy.

      • To mount secret as a volume:

        1. Click theVolumes tab and selectAdd volume.
        2. In theVolume type list, selectSecret.
        3. In theVolume name field, enter a name or accept the default name.
        4. From theSecret list, clickEnter 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. Fordetailed instructions on how to find your project number, seeCreating and managing projects.

          • SECRET_NAME: The name of the secret inSecret Manager.

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

        7. In theVersion 1 list, select the version of the secret toreference. By default, the latest version is selected. You can selecta specific version if you want.

        8. ClickDone.

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

        10. In theVolume mounts tab, and clickMount volume.

        11. From theName 1 list, select your volume name.

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

        13. ClickDone.

        14. ClickCreate orDeploy.

  5. ClickCreate orUpdate.

gcloud

  • To mount a secret as a volume when updating a job:

    gcloudrunjobsupdateJOB_NAME\--imageIMAGE_URL\--update-secrets=PATH=projects/PROJECT_NUMBER/secrets/SECRET_NAME:VERSION
    • JOB_NAME: the name of your job.
    • IMAGE_URL: a reference to thecontainer image—forexample,us-docker.pkg.dev/cloudrun/container/job:latest.
    • PATH: the mount path of the volume andfilename of the secret. It must start with a leading slash—for example,/etc/secrets/dbconfig/password, where/etc/secrets/dbconfig/ is themount path of the volume, andpassword is the filename of the secret.
    • PROJECT_NUMBER: the project number for theproject the secret was created in.
    • SECRET_NAME: the secret name—for example,mysecret.
    • VERSION: the secret version. Uselatestfor latest version, or a number—for example,2.

YAML

  1. If you are creating a new job, skip this step.If you are updating an existing job, download itsYAML configuration:

    gcloudrunjobsdescribeJOB_NAME--formatexport>job.yaml

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

  1. For secrets exposed as environment variables:

    apiVersion:run.googleapis.com/v1kind:Jobmetadata:name:JOBspec:template:metadata:annotations:run.googleapis.com/secrets:SECRET_LOOKUP_NAME:projects/PROJECT_NUMBER/secrets/SECRET_NAMEspec:template:spec:containers:-env:-name:SECRET_NAMEvalueFrom:secretKeyRef:key:VERSIONname:SECRET_LOOKUP_NAMEimage:IMAGE_URL

    Replace the following:

    • JOB: the name of your job.
    • IMAGE_URL: a reference to thecontainer image—forexample,us-docker.pkg.dev/cloudrun/container/job:latest.
    • SECRET_NAME: the secret name—for example,mysecret.
    • VERSION: the secret version. Uselatestfor latest version, or a number—for example,2.
    • PROJECT_NUMBER: the project number for theproject the secret was created in.
    • SECRET_LOOKUP_NAME: any name that has avalid secret name syntax—for example,my-secret. It can be the same asSECRET_NAME.

  2. For secrets mounted as file paths:

    apiVersion:run.googleapis.com/v1kind:Jobmetadata:name:JOB_NAMEspec:template:metadata:annotations:run.googleapis.com/secrets:SECRET_LOOKUP_NAME:projects/PROJECT_NUMBER/secrets/SECRET_NAMEspec:template:spec:containers:-image:IMAGE_URLvolumeMounts:-mountPath:MOUNT_PATHname:VOLUME_NAMEvolumes:-name:VOLUME_NAMEsecret:items:-key:VERSIONpath:FILENAMEsecretName:SECRET_LOOKUP_NAME

    Replace the following:

    • JOB_NAME: the name of your job.
    • IMAGE_URL: a reference to thecontainer image—forexample,us-docker.pkg.dev/cloudrun/container/job:latest.
    • PATH: the mount path of the volume andfilename of the secret. It must start with a leading slash—for example,/etc/secrets/dbconfig/password, where/etc/secrets/dbconfig/ is themount path of the volume, andpassword is the filename of the secret.
    • PROJECT_NUMBER: the project number for theproject the secret was created in.
    • SECRET_NAME: the secret name—for example,mysecret.
    • VERSION: the secret version. Uselatestfor latest version, or a number—for example,2.
    • SECRET_LOOKUP_NAME: any name that has avalid secret name syntax—for example,my-secret, it can be the same asSECRET_NAME.
    • VOLUME_NAME: any name—for example,my-volume,it can be the same asSECRET_NAME.

Terraform

To learn how to apply or remove a Terraform configuration, seeBasic Terraform commands.

Add the following to agoogle_cloud_run_v2_job resource in your Terraform configuration:

For secrets exposed as environment variables:

resource"google_cloud_run_v2_job""default"{name="JOB_NAME"location="REGION"template{template{containers{image="IMAGE_URL"env{name="SECRET_NAME"value_source{secret_key_ref{secret="projects/PROJECT_ID/secrets/SECRET_NAME"version="VERSION"}}}}}}}

Replace the following:

  • JOB_NAME: the name of your Cloud Run job.
  • REGION: the Google Cloud region. For example,europe-west1.
  • IMAGE_URL: a reference to thecontainer image—forexample,us-docker.pkg.dev/cloudrun/container/job:latest.
  • SECRET_NAME: the secret name—for example,mysecret.
  • PROJECT_ID: the project ID the secret was created in.
  • VERSION: the secret version. Uselatest for latestversion, or a number—for example,2.

For secrets mounted as file paths:

resource"google_cloud_run_v2_job""default"{name="JOB_NAME"location="REGION"template{template{containers{image="IMAGE_URL"volume_mounts{name="VOLUME_NAME"mount_path="MOUNT_PATH"}}volumes{name="VOLUME_NAME"secret{secret="projects/PROJECT_ID/secrets/SECRET_NAME"}}}}}

Replace the following:

  • JOB_NAME: the name of your Cloud Run job.
  • REGION: the Google Cloud region—for example,europe-west1.
  • IMAGE_URL: a reference to thecontainer image—forexample,us-docker.pkg.dev/cloudrun/container/job:latest.
  • VOLUME_NAME: any name—for example,my-volume, it can be thesame asSECRET_NAME.
  • MOUNT_PATH: the mount path of the volume andfilename of the secret. It must start with a leading slash—for example,/etc/secrets/dbconfig/password, where/etc/secrets/dbconfig/ is themount path of the volume, andpassword is the filename of the secret.
  • PROJECT_ID: the project ID the secret was created in.
  • SECRET_NAME: the secret name—for example,mysecret.

View secrets settings

To view the current secrets settings for yourCloud Run job:

Console

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

    Go to Cloud Run jobs

  2. Click the job you are interested in to open theJob details page.

  3. ClickView and Edit job configuration.

  4. Locate the secrets setting in the configurationdetails.

gcloud

  1. Use the following command:

    gcloudrunjobsdescribeJOB_NAME

  2. Locate the secrets setting in the returnedconfiguration.

Limitations

The following sections describe the limitations that apply to mounting secrets.

Disallowed paths

  • 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 pathbecause two volume mounts can't be mounted at the same location.

Regional secrets

Cloud Run does not supportregional secrets.

Overriding a directory

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

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

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

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-18 UTC.