使用 Secret

您的服务或作业可能需要具有需要 API 密钥、密码或其他敏感信息的依赖项。对于 Cloud Run，Google 建议您将此类敏感信息存储在 Secret Manager 中创建的 Secret 中。

您可以通过以下两种方式之一为您的容器提供 Secret：

  • 将每个 Secret 作为卷装载，使 Secret 可供文件以容器形式提供给容器。读取卷始终从 Secret Manager 中提取 Secret 值，因此可以与最新版本配合使用。此方法还非常适合 Secret 轮替。
  • 使用环境变量传递 Secret。环境变量在实例启动时解析，因此，如果您使用此方法，Google 建议您将 Secret 固定到特定版本，而不是使用最新的。

如需了解详情，请参阅 Secret Manager 最佳做法文档。

如何在部署和运行时检查 Secret

在部署服务或创建作业期间，系统会检查使用的所有 Secret（无论是作为环境变量还是作为卷装载），以确保用于运行容器的服务帐号有权访问它们。如果任何检查失败，则部署服务或创建作业将会失败。

在运行期间，当实例启动时：

  • 如果 Secret 是环境变量，则系统在启动实例之前会检索 Secret 的值，因此如果 Secret 检索失败，则实例不会启动。
  • 如果 Secret 作为卷装载，则在实例启动期间不执行检查。但是，在运行期间，如果 Secret 无法访问，则读取已装载的卷的尝试将失败。

卷所有权因执行环境和部署类型而异

装载卷时，拥有文件和目录的身份将因工作负载的执行环境以及部署是包含一个或多个容器而有所不同。

在要部署单个容器的第一代执行环境中，卷归容器使用的身份所有。在所有其他情况下，卷归 root 用户所有。包括：

  • 部署多个容器的第一代执行环境
  • 第二代环境

允许 Cloud Run 访问 Secret

您可以使用现有的 Secret Manager Secret，也可以创建新的 Secret。但是，如需允许 Cloud Run 服务访问 Secret，您必须向 Cloud Run 服务帐号授予 Secret Manager Secret Accessor 角色：

  1. 转到 Google Cloud 控制台中的 Secret Manager 页面

  2. 选择此 Secret，然后在右侧的“权限”标签页中，点击添加主账号。

  3. 在新主账号文本框中，输入 Cloud Run 服务的服务帐号电子邮件地址。

  4. 向其授予 Secret Manager Secret Accessor 角色。

将 Secret 设为可供 Cloud Run 访问

您可以将 Secret 设为对服务和作业可用。

对于 Cloud Run 服务

任何配置更改都会导致新修订版本的创建。后续修订版本也将自动采用此配置设置，除非您进行了明确更新。

您可以在部署新服务或更新现有服务并部署修订版本时，使用 Google Cloud 控制台、Google Cloud CLI 或 YAML 文件将 Secret 设为可供服务访问：

控制台

  1. 转到 Cloud Run

  2. 如果您是要配置一个新服务来作为部署目标，请点击创建服务。如果您要配置现有服务，请点击该服务，然后点击修改和部署新的修订版本。

  3. 如果您要配置新服务，请根据需要填写初始服务设置页面，然后点击容器、网络、安全性以展开服务配置页面。

  4. 点击容器标签页。

    图片

    • 在 Secret 下：
      • 点击引用 Secret。
      • 从 Secret 下拉列表中选择要使用的 Secret。
      • 在“引用方法”下拉菜单中，选择您要使用 Secret 的方法，即作为卷装载或作为环境变量公开。
      • 如果要将 Secret 作为卷装载：
        1. 在装载路径下，指定您要用于 Secret 的装载路径。
        2. 系统默认选择最新版本。您可以根据需要选择特定版本。在指定的 Secret 路径下，指定版本的路径和版本号。
        3. 点击完成。
      • 如果您将 Secret 作为环境变量公开，请执行以下操作：
        1. 提供变量的名称并选择 Secret 版本，或者选择 最新版以始终使用当前的 Secret 版本。
        2. 点击完成。

  5. 点击创建或部署。

命令行

要使 Secret 可访问您的服务，请输入以下某个命令。

  • 如需在部署服务时将 Secret 作为卷装载，请执行以下操作：

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

    您需要将其中的：

    • 将 SERVICE 替换为您的服务名称。
    • 将 IMAGE_URL 替换为对容器映像的引用，例如 us-docker.pkg.dev/cloudrun/container/hello:latest。 使用 Artifact Registry 时，网址的格式为 REGION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG。
    • 将 PATH 替换为卷的卷路径和 Secret 文件名。它必须以正斜杠开头，例如 /etc/secrets/dbconfig/password，其中 /etc/secrets/dbconfig/ 是卷的装载路径，password 是 Secret 的文件名。
    • 将 SECRET_NAME 替换为同一项目中的 Secret 名称，例如 mysecret。
    • 将 VERSION 替换为 Secret 版本。请使用 latest 获取最新版本，或者使用数字，例如 2。

  • 如需在部署服务时将 Secret 公开为环境变量，请执行以下操作：

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

    您需要将其中的：

    • 将 SERVICE 替换为您的服务名称。
    • 将 IMAGE_URL 替换为对容器映像的引用，例如 us-docker.pkg.dev/cloudrun/container/hello:latest。 使用 Artifact Registry 时，网址的格式为 REGION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG。
    • 将 ENV_VAR_NAME 替换为要与 Secret 搭配使用的环境变量的名称。
    • 将 SECRET_NAME 替换为同一项目中的 Secret 名称，例如 mysecret。
    • 将 VERSION 替换为 Secret 版本。请使用 latest 获取最新版本，或者使用数字，例如 2。

  • 您可以同时更新多个 Secret。为此，请使用英文逗号分隔每个 Secret 的配置选项。以下命令会更新一个作为卷装载的 Secret，以及另一个作为环境变量公开的 Secret。

    如需更新现有 Secret，请输入以下命令：

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

  • 要清除现有 Secret 并使新 Secret 可用于服务，请使用 --set-secrets 标志：

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

YAML

您可以使用 gcloud run services describe --format export 命令下载并查看现有服务配置，该命令会生成清理后的 YAML 格式的结果。然后按照后续说明修改字段，最后使用 gcloud run services replace 命令上传修改后的 YAML。请务必严格按照说明修改字段。

  1. 要查看和下载配置，请运行以下命令：

    gcloud run services describe SERVICE --format export > service.yaml

  2. 对于作为环境变量公开的 Secret，在 env 下根据需要更新 ENV_VAR、VERSION 和/或 SECRET_NAME。如果您已将多个 Secret 作为环境变量装载，将具有多个这些属性。

    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. 对于以文件路径形式装载的 Secret，您可以根据需要更新 MOUNT_PATH、VOLUME_NAME、VERSION、FILENAME 和/或 SECRET_NAME。如果您将多个 Secret 作为文件路径进行装载，则会拥有多个这些属性。

    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

    请注意，VOLUME_NAME 可以设置为任意名称。

    替换

    • 将 SERVICE 替换为您的 Cloud Run 服务的名称
    • 将 IMAGE_URL 替换为对容器映像的引用，例如 us-docker.pkg.dev/cloudrun/container/hello:latest。 使用 Artifact Registry 时，网址的格式为 REGION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG。
    • 将 REVISION 替换为新的修订版本名称或者将其删除（如果存在）。如果您提供新的修订版本名称，则该名称必须满足以下条件：
      • 开头为 SERVICE-
      • 仅包含小写字母、数字和 -
      • 不以 - 结尾
      • 不超过 63 个字符

  4. 使用以下命令将服务替换为其新配置：

    gcloud run services replace service.yaml

引用其他项目中的 Secret

如果您项目的服务帐号允许访问 Secret，那么您可以引用其他项目中的 Secret。

控制台

  1. 转到 Cloud Run

  2. 如果您是要配置一个新服务来作为部署目标，请点击创建服务。如果您要配置现有服务，请点击该服务，然后点击修改和部署新的修订版本。

  3. 如果您要配置新服务，请根据需要填写初始服务设置页面，然后点击容器、网络、安全性以展开服务配置页面。

  4. 点击容器标签页。

    图片

    • 在 Secret 下：
      • 点击引用 Secret。
      • 选择看不到您的 Secret？请输入 Secret 资源 ID（在 Secret 下拉列表中），以显示以下表单：

        跨项目 Secret

      • 在按资源 ID 添加 Secret 表单中，输入其他项目的 Secret，格式为 projects/PROJECT_NUMBER/secrets/SECRET_NAME。您也可以选择复制并粘贴其他项目中的资源 ID，具体方法是：选择 Secret，点击 Secret 右侧的操作省略号，从下拉菜单中选择复制资源 ID。
      • 点击添加 Secret。
      • 在“引用方法”下拉菜单中，选择您要使用 Secret 的方法，即作为卷装载或作为环境变量公开。
      • 如果要将 Secret 作为卷装载：
        1. 在装载路径下，指定您要用于 Secret 的装载路径。
        2. 系统默认选择最新版本。您可以根据需要选择特定版本。在指定的 Secret 路径下，指定版本的路径和版本号。
        3. 点击完成。
      • 如果您将 Secret 作为环境变量公开，请执行以下操作：
        1. 提供变量的名称并选择 Secret 版本，或者选择 最新版以始终使用当前的 Secret 版本。
        2. 点击完成。

  5. 点击创建或部署。

命令行

  • 如需在部署服务时将 Secret 作为卷装载，请执行以下操作：

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

    您需要将其中的：

    • 将 SERVICE 替换为您的服务名称。
    • 将 IMAGE_URL 替换为对容器映像的引用，例如 us-docker.pkg.dev/cloudrun/container/hello:latest。 使用 Artifact Registry 时，网址的格式为 REGION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG。
    • 将 PATH 替换为卷的卷路径和 Secret 文件名。它必须以正斜杠开头，例如 /etc/secrets/dbconfig/password，其中 /etc/secrets/dbconfig/ 是卷的装载路径，password 是 Secret 的文件名。
    • 将 PROJECT_NUMBER 替换为在其中创建 Secret 的项目的编号。
    • 将 SECRET_NAME 替换为 Secret 名称，例如 mysecret。
    • 将 VERSION 替换为 Secret 版本。请使用 latest 获取最新版本，或者使用数字，例如 2。

YAML

您可以使用 gcloud run services describe --format export 命令下载并查看现有服务配置，该命令会生成清理后的 YAML 格式的结果。然后按照后续说明修改字段，最后使用 gcloud run services replace 命令上传修改后的 YAML。请务必严格按照说明修改字段。

  1. 要查看和下载配置，请运行以下命令：

    gcloud run services describe SERVICE --format export > service.yaml

由于 API 兼容性的限制，Secret 位置必须存储在注解中。

  1. 对于作为环境变量公开的 Secret：

    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

    替换：

    • 将 SERVICE 替换为您的服务名称。
    • 将 IMAGE_URL 替换为对容器映像的引用，例如 us-docker.pkg.dev/cloudrun/container/hello:latest。 使用 Artifact Registry 时，网址的格式为 REGION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG。
    • ENV_VAR
    • 将 PROJECT_NUMBER 替换为在其中创建 Secret 的项目的编号。
    • 将 SECRET_NAME 替换为 Secret 名称，例如 mysecret。
    • 将 VERSION 替换为 Secret 版本。请使用 latest 获取最新版本，或者使用数字，例如 2。
    • 将 SECRET_LOOKUP_NAME 替换为任何具有有效 Secret 名称语法的名称（例如 my-secret），它可以与 SECRET_NAME 相同

  2. 对于作为文件路径装载的 Secret：

    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

    替换：

    • 将 SERVICE 替换为您的服务名称。
    • 将 IMAGE_URL 替换为对容器映像的引用，例如 us-docker.pkg.dev/cloudrun/container/hello:latest。 使用 Artifact Registry 时，网址的格式为 REGION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG。
    • 将 PATH 替换为卷的卷路径和 Secret 文件名。它必须以正斜杠开头，例如 /etc/secrets/dbconfig/password，其中 /etc/secrets/dbconfig/ 是卷的装载路径，password 是 Secret 的文件名。
    • 将 PROJECT_NUMBER 替换为在其中创建 Secret 的项目的编号。
    • 将 SECRET_NAME 替换为 Secret 名称，例如 mysecret。
    • 将 VERSION 替换为 Secret 版本。请使用 latest 获取最新版本，或者使用数字，例如 2。
    • 将 SECRET_LOOKUP_NAME 替换为任何具有有效 Secret 名称语法的名称（例如 my-secret），它可以与 SECRET_NAME 相同
    • 将 VOLUME_NAME 替换为任何名称（例如 my-volume），它可以与 SECRET_NAME 相同

对于 Cloud Run 作业

您可以使用 Google Cloud 控制台、Google Cloud CLI 或 YAML 将 Secret 设为可供作业访问：

控制台

  1. 转到 Cloud Run

  2. 如果要配置新作业，请点击作业标签页，然后根据需要填写初始作业设置页面。如果要配置现有作业，请点击作业，然后点击修改。

  3. 点击容器、变量和 Secret、连接、安全性以展开作业属性页面。

  4. 点击变量和 Secret 标签页。

    图片

    • 在“变量和 Secret”标签页中：
      • 在 Secret 下，点击引用 Secret
      • 从 Secret 下拉列表中选择要使用的 Secret。
      • 在“引用方法”下拉菜单中，选择您要使用 Secret 的方法，即作为卷装载或作为环境变量公开。
      • 如果要将 Secret 作为卷装载，
        1. 在装载路径下，指定您要用于 Secret 的装载路径。
        2. 系统默认选择最新版本。您可以根据需要选择特定版本。在指定的 Secret 路径下，指定版本的路径和版本号。
        3. 点击完成。
      • 如果您将 Secret 作为环境变量公开，请执行以下操作：
        1. 提供变量的名称并选择 Secret 版本，或者选择 最新版以始终使用当前的 Secret 版本。
        2. 点击完成。

  5. 点击创建或更新。

命令行

  • 如需在创建新作业时在环境变量中指定 Secret，请运行以下命令：

    gcloud run jobs create JOB_NAME \
--image IMAGE_URL \
--set-secrets ENV_VAR_NAME=SECRET_NAME:VERSION

    替换

    • 将 JOB_NAME 替换为作业的名称。
    • 将 ENV_VAR_NAME 替换为要用于 Secret 的环境变量的名称。
    • 将 SECRET_NAME 替换为同一项目中的 Secret 名称，例如 mysecret。
    • 将 VERSION 替换为 Secret 版本。请使用 latest 获取最新版本，或者使用数字，例如 2。
    • 将 IMAGE_URL 替换为对容器映像的引用，例如 us-docker.pkg.dev/cloudrun/container/job:latest。

    您可以使用英文逗号分隔列表指定多个环境变量/Secret 对。

  • 如需在更新作业时在环境变量中指定 Secret，请运行以下命令：

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

  • 如需在创建作业时将 Secret 作为卷装载，请运行以下命令：

    gcloud run jobs create JOB_NAME \
--image IMAGE_URL \
--set-secrets=PATH=SECRET_NAME:VERSION

    替换：

    • 将 JOB_NAME 替换为作业的名称。
    • 将 IMAGE_URL 替换为对容器映像的引用（例如 us-docker.pkg.dev/cloudrun/container/job:latest）。
    • 将 PATH 替换为卷的卷路径和 Secret 文件名。它必须以正斜杠开头，例如 /etc/secrets/dbconfig/password，其中 /etc/secrets/dbconfig/ 是卷的装载路径，password 是 Secret 的文件名。
    • 将 SECRET_NAME 替换为同一项目中的 Secret 名称，例如 mysecret。
    • 将 VERSION 替换为 Secret 版本。请使用 latest 获取最新版本，或者使用数字，例如 2。

  • 如需更新现有作业中的 Secret，请运行以下命令：

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

YAML

由于 API 兼容性的限制，Secret 位置必须存储在注解中。

使用 gcloud run jobs describe --format export 命令下载并查看现有作业配置，该命令会生成清理后的 YAML 格式的结果。然后，修改下述字段，并使用 gcloud run jobs replace 命令上传修改后的 YAML。请务必严格按照说明修改字段。

  1. 如需查看和下载配置，请运行以下命令：

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

  2. 对于作为环境变量公开的 Secret：

    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

    您需要将其中的：

    • 将 JOB 替换为作业的名称。
    • 将 IMAGE_URL 替换为对容器映像的引用，例如 us-docker.pkg.dev/cloudrun/container/hello:latest。 使用 Artifact Registry 时，网址的格式为 REGION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG。
    • 将 SECRET_NAME 替换为 Secret 名称，例如 mysecret。
    • 将 VERSION 替换为 Secret 版本。请使用 latest 获取最新版本，或者使用数字，例如 2。
    • 将 SECRET_LOOKUP_NAME 替换为任何具有有效 Secret 名称语法的名称（例如 my-secret），它可以与 SECRET_NAME 相同

  3. 对于作为文件路径装载的 Secret：

    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

    您需要将其中的：

    • 将 JOB_NAME 替换为作业的名称。
    • 将 IMAGE_URL 替换为对容器映像的引用，例如 us-docker.pkg.dev/cloudrun/container/hello:latest。 使用 Artifact Registry 时，网址的格式为 REGION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG。
    • 将 PATH 替换为卷的卷路径和 Secret 文件名。它必须以正斜杠开头，例如 /etc/secrets/dbconfig/password，其中 /etc/secrets/dbconfig/ 是卷的装载路径，password 是 Secret 的文件名。
    • 将 PROJECT_NUMBER 替换为在其中创建 Secret 的项目的编号。
    • 将 SECRET_NAME 替换为 Secret 名称，例如 mysecret。
    • 将 VERSION 替换为 Secret 版本。请使用 latest 获取最新版本，或者使用数字，例如 2。
    • 将 SECRET_LOOKUP_NAME 替换为任何具有有效 Secret 名称语法的名称（例如 my-secret），它可以与 SECRET_NAME 相同
    • 将 VOLUME_NAME 替换为任何名称（例如 my-volume），它可以与 SECRET_NAME 相同

查看 Secret 设置

如需查看 Cloud Run 服务的当前 Secret 设置，请执行以下操作：

控制台

  1. 转到 Cloud Run

  2. 点击您感兴趣的服务以打开“服务详细信息”页面。

  3. 点击修订版本标签页。

  4. 在右侧的详细信息面板中，Secret 设置列在 变量和 Secret标签页下。

命令行

  1. 使用以下命令：

    gcloud run services describe SERVICE

  2. 在返回的配置中找到并发设置。

如需查看 Cloud Run 作业的当前 Secret 设置，请执行以下操作：

控制台

  1. 转到 Cloud Run 作业

  2. 点击相关作业以打开作业详情页面。

  3. 点击配置标签页。

  4. 在配置详细信息中找到 Secret 设置。

命令行

  1. 使用以下命令：

    gcloud run jobs describe JOB_NAME

  2. 在返回的配置中找到并发设置。

在代码中使用 Secret

如需查看如何将代码中的 Secret 作为环境变量进行访问的示例，请参阅有关最终用户身份验证的教程，尤其是使用 Secret Manager 处理敏感配置部分。

不允许的路径及相关限制

Cloud Run 不允许您在 /dev、/proc、/sys 或其子目录上装载 Secret。

如果您要在 /tmp 上装载 Secret，并且使用的是第一代执行环境，请参阅在 /tmp 上装载 Secret 中的已知问题。

Cloud Run 不允许在同一路径上装载多个 Secret，因为两个卷装载无法装载到同一位置。