Configure secrets for services

Your service 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 service 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, 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 identity you use for the container owns the secret volume. In all other cases, root owns the volume. This includes:

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

Before you begin

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

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 service
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 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

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

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 the following:
- SERVICE: the name of your service.
- IMAGE_URL: 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 follows the format of LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
- PATH: 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: 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 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 the following:
- SERVICE: the name of your service.
- IMAGE_URL: 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 follows the format of LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG .
- 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.
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

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
```

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

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 the following:
- SERVICE: the name of your Cloud Run service.
- IMAGE_URL: 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 follows the format of 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
Replace the service with its new configuration using the following command:
```
gcloud run services replace service.yaml
```

Terraform

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"
}

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]
}

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

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]
}

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

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

YAML

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.

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 the following:
- SERVICE: the name of your service.
- IMAGE_URL: 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 follows the format of LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
- ENV_VAR: the name of the environment variable.
- PROJECT_NUMBER: the project number for the project the secret was created in.
- SECRET_NAME: the secret name—for example, mysecret.
- VERSION: the secret version. Use latest for latest version, or a number—for example, 2.
- SECRET_LOOKUP_NAME: any name that has a valid secret name syntax—for example, my-secret, it can be the same as SECRET_NAME.
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 the following:
- SERVICE: the name of your service.
- IMAGE_URL: 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 follows the format of LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG .
- PATH: 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: the project number for the project the secret was created in.
- SECRET_NAME: the secret name—for example, mysecret.
- VERSION: the secret version. Use latest for latest version, or a number—for example, 2.
- SECRET_LOOKUP_NAME: any name that has a valid secret name syntax—for example, my-secret, it can be the same as SECRET_NAME.
- VOLUME_NAME: any name—for example, my-volume, it can be the same as SECRET_NAME.

Terraform

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

Add the following to a google_cloud_run_v2_service resource in your Terraform configuration:

For secrets exposed as environment variables:

resource "google_cloud_run_v2_service" "default" {
  name     = "SERVICE_NAME"
  location = "REGION"

  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:

SERVICE_NAME: the name of your Cloud Run job.
REGION: the Google Cloud region. For example, europe-west1.
IMAGE_URL: 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 follows the format of LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG .
SECRET_NAME: the secret name—for example mysecret.
PROJECT_ID: the project ID the secret was created in.
VERSION: the secret version. Use latest for latest version, or a number—for example, 2.

For secrets mounted as file paths:

resource "google_cloud_run_v2_service" "default" {
  name     = "SERVICE_NAME"
  location = "REGION"

  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:

SERVICE_NAME: the name of your Cloud Run job.
REGION with the Google Cloud region. For example, europe-west1.
IMAGE_URL: 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 follows the format of LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
VOLUME_NAME: any name—for example, my-volume, it can be the same as SECRET_NAME
MOUNT_PATH: 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_ID: the project ID the secret was created in.
SECRET_NAME: the secret name—for example mysecret.

View secrets settings

Remove secrets from a service

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

Console

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

Go to Cloud Run
Select your service from the list, and click Edit and deploy new revision.
Click the Container(s) tab.
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.
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.
Click Deploy.

gcloud

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

To remove all secrets, run the following command:
```
gcloud run deploy SERVICE --image IMAGE_URL \
--clear-secrets
```
Replace the following:
- SERVICE: the name of your service.
- IMAGE_URL: 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 follows the format of LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG .
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 run deploy SERVICE --image IMAGE_URL \
--remove-secrets=ENV_VAR_NAME,SECRET_FILE_PATH
```
Replace the following:
- SERVICE: the name of your service.
- IMAGE_URL: 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 follows the format of LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG .
- 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

Limitations

Disallowed paths

Regional secrets

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.

Configure secrets for services Stay organized with collections Save and categorize content based on your preferences.

How secrets are checked at deployment and runtime

Volume ownership

Before you begin

Required roles

Make a secret accessible to Cloud Run

Console

gcloud

YAML

Terraform

Compose

Reference secrets from other projects

Console

gcloud

YAML

Terraform

View secrets settings

Console

gcloud

Remove secrets from a service

Console

gcloud

Use secrets in your code

Limitations

Disallowed paths

Regional secrets

Overriding a directory