使用用户代管式服务账号运行 build

本文档介绍了如何将 build 配置为使用用户管理的服务账号。

如果您未为 build 指定用户代管式服务账号，Cloud Build 会自动使用默认的 Cloud Build 服务账号。此默认服务账号可能拥有不必要的广泛权限，例如访问您的 Cloud Source Repositories 和项目中的任何 Cloud Storage 存储桶。

我们建议遵循最小权限原则，为服务账号分配权限和角色，使其权限和角色范围限定为所执行的任务。例如，您可以使用一个服务账号来构建映像并将其推送到 Artifact Registry，如 Google Cloud 博客中所述。

准备工作

  • 启用 Cloud Build API 和 IAM API（如果尚未启用）。

    启用 API 所需的角色

    如需启用 API，您需要拥有 serviceusage.services.enable 权限。如果您创建了项目，则可能已经通过 Owner 角色 (roles/owner) 拥有此权限。否则，您可以通过 Service Usage Admin 角色 (roles/serviceusage.serviceUsageAdmin) 获取此权限。 了解如何授予角色。

    启用 API

  • 如果您打算使用此账号创建和管理凭据（例如创建短期有效的凭据），请启用 IAM Service Account Credentials API。

    启用 API 所需的角色

    如需启用 API，您需要拥有 serviceusage.services.enable 权限。如果您创建了项目，则可能已经通过 Owner 角色 (roles/owner) 拥有此权限。否则，您可以通过 Service Usage Admin 角色 (roles/serviceusage.serviceUsageAdmin) 获取此权限。 了解如何授予角色。

    启用 API

  • 如果您尚未创建服务账号，请创建一个服务账号。

设置服务账号

向用户代管式服务账号授予 IAM 角色，使其拥有运行 build 所需的权限。您还可以将 Cloud Build 配置为自动为新触发器选择此服务账号。

  1. 在 Google Cloud 控制台中，前往 Cloud Build 权限页面：

    前往权限

  2. 前往服务账号菜单，然后选择您的服务账号。如需选择其他项目中的服务账号，请点击切换项目。

  3. 如需将所选服务账号用作新触发器的服务账号，请开启设置为新触发器的预选服务账号。

  4. 在 Google Cloud 服务列表中，启用要向服务账号授予的 IAM 角色。

  5. 如果此处未列出构建流水线所需的角色，您可以在 IAM 配置页面中授予其他角色。

  6. 如果您选择了其他项目中的服务账号，请完成跨项目设置中的步骤。

如需详细了解 build 通常所需的 IAM 角色，请参阅以下信息：

设置构建日志

如果您为 build 指定了自己的服务账号，则必须将 build 日志存储在以下任一类型的存储桶中：

如果您创建了日志存储桶，请确保该存储桶没有保留政策，因为该政策可能会阻止 Cloud Build 将 build 日志写入存储桶。

您不能将日志存储在 Google Cloud拥有的日志存储桶中。

如需详细了解构建日志的存储位置，请参阅构建日志存储选项。

使用配置文件运行 build

如需使用配置文件手动运行 build，请执行以下操作：

  1. 在项目根目录中，创建一个名为 cloudbuild.yaml 或 cloudbuild.json 的Cloud Build 构建配置文件。

  2. 添加 serviceAccount 字段和首选的日志记录设置。

    • 如果要将构建日志存储在 Cloud Logging 中，请添加 logging 字段并将字段的值设置为 CLOUD_LOGGING_ONLY。

    • 如果您将构建日志存储在用户创建的 Cloud Storage 存储桶中，请执行以下操作：

      • 添加 logging 字段并将其值设置为 GCS_ONLY。
      • 添加 logsBucket 字段，并将其值设置为您的 Cloud Storage 存储桶位置。

    以下示例配置了 Cloud Build，使其使用用户代管式服务账号运行 build，并配置了 build 日志，使其存储在用户创建的 Cloud Storage 存储桶中：

    YAML 

    steps:
- name: 'bash'
  args: ['echo', 'Hello world!']
logsBucket: 'LOGS_BUCKET_LOCATION'
serviceAccount: 'projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT'
options:
  logging: GCS_ONLY

    JSON 

    {
  "steps": [
  {
    "name": "bash",
    "args": [
      "echo",
      "Hello world!"
    ]
  }
  ],
  "logsBucket": "LOGS_BUCKET_LOCATION",
  "serviceAccount": "projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT",
  "options": {
    "logging": "GCS_ONLY"
  }
}

    将 build 配置文件中的变量替换为以下内容：

    • LOGS_BUCKET_LOCATION：用于存储构建日志的 Cloud Storage 存储桶。例如 gs://mylogsbucket。
    • PROJECT_ID 是运行构建的 Google Cloud 项目的 ID。
    • SERVICE_ACCOUNT 是您要为构建指定的服务账号的电子邮件地址或唯一 ID。 例如，服务账号电子邮件地址如下所示：service-account-name@project-id.iam.gserviceaccount.com。

  3. 使用构建配置文件启动构建：

    gcloud builds submit --config CONFIG_FILE_PATH SOURCE_DIRECTORY

    将命令中的变量替换为以下值：

    • CONFIG_FILE_PATH 是构建配置文件的路径。
    • SOURCE_DIRECTORY 是源代码的路径或网址。

    如果您未在 gcloud builds submit 命令中指定 CONFIG_FILE_PATH 和 SOURCE_DIRECTORY，Cloud Build 会假定构建配置文件和源代码位于当前工作目录中。

使用触发器运行 build

如需使用您自己的服务账号通过 Cloud Build 触发器运行 build，请设置首选的日志记录选项，并在创建触发器时选择首选的服务账号。

如果您想为所有新触发器使用同一服务账号，可以配置 Cloud Build 以自动选择该服务账号。

  1. 在构建配置文件中：

    • 如果要将构建日志存储在 Cloud Logging 中，请添加 logging 字段并将字段的值设置为 CLOUD_LOGGING_ONLY。

    • 如果您将构建日志存储在用户创建的 Cloud Storage 存储桶中，请执行以下操作：

      • 添加 logging 字段并将其值设置为 GCS_ONLY。
      • 添加 logsBucket 字段，并将其值设置为您的 Cloud Storage 存储桶位置。

    以下示例将构建日志配置为存储在用户创建的 Cloud Storage 存储桶中：

    YAML 

    steps:
- name: 'bash'
  args: ['echo', 'Hello world!']
logsBucket: 'LOGS_BUCKET_LOCATION'
options:
  logging: GCS_ONLY

    JSON 

    {
  "steps": [
  {
    "name": "bash",
    "args": [
      "echo",
      "Hello world!"
    ]
  }
  ],
  "logsBucket": "LOGS_BUCKET_LOCATION",
  "options": {
    "logging": "GCS_ONLY"
  }
}

    将 LOGS_BUCKET_LOCATION 替换为用于存储 build 日志的 Cloud Storage 存储桶。例如 gs://mylogsbucket。

  2. 指定要用于构建触发器的服务账号：

    控制台

    1. 创建或修改构建触发器。

    2. 在服务账号字段中，指定您的服务账号。如需选择其他项目中的服务账号，请点击切换项目。

      如果您未指定服务账号，Cloud Build 会使用默认服务账号。

    3. 点击创建以保存您的构建触发器。

    gcloud

    创建构建触发器时，请使用 --service-account 标志指定服务账号。在以下示例中，gcloud 命令会创建一个从 Git 代码库拉取代码的构建触发器：

    gcloud builds triggers create github \
   --name=TRIGGER_NAME \
   --repo-name=REPO_NAME \
   --repo-owner=REPO_OWNER \
   --branch-pattern=BRANCH_PATTERN
   --build-config=BUILD_CONFIG_FILE
   --service-account=SERVICE_ACCOUNT
   --project=BUILD_PROJECT

    将 build 配置文件中的变量替换为以下值：

    • TRIGGER_NAME 是构建触发器的名称。
    • REPO_NAME 是代码库的名称。
    • REPO_OWNER 是代码库所有者的用户名。
    • BRANCH_PATTERN 是代码库中要在其上调用构建的分支名称。
    • TAG_PATTERN 是代码库中要在其上调用构建的标记名称。
    • BUILD_CONFIG_FILE 是构建配置文件的路径。
    • SERVICE_ACCOUNT 是您的服务账号，格式为 /projects/PROJECT_ID/serviceAccounts/ACCOUNT_ID_OR_EMAIL。
    • BUILD_PROJECT 是您要开始构建的项目。

跨项目设置

只有在未强制执行 iam.disableCrossProjectServiceAccountUsage 组织政策限制条件的情况下，您才能使用用户代管式服务账号在不同于创建该服务账号的项目中运行 build。默认情况下，系统会强制执行此限制条件。了解详情。

  • 以下命令会停用相应限制的强制执行，并授予必要的访问权限。在组织政策中设置限制条件之前，您的组织需要了解所涉及的安全权衡：

    gcloud resource-manager org-policies disable-enforce \
   iam.disableCrossProjectServiceAccountUsage \
   --project=SERVICE_ACCOUNT_PROJECT_ID

    在此命令中，SERVICE_ACCOUNT_PROJECT_ID 是包含用户代管式服务账号的项目

  • 在包含用户代管式服务账号的项目中，为运行 build 的项目的 Cloud Build 服务代理授予 roles/iam.serviceAccountTokenCreator 角色：

    gcloud projects add-iam-policy-binding SERVICE_ACCOUNT_PROJECT_ID \
    --member="serviceAccount:BUILD_SERVICE_AGENT" \
    --role="roles/iam.serviceAccountTokenCreator"

    将命令中的变量替换为以下内容：

    • SERVICE_ACCOUNT_PROJECT_ID：包含用户代管式服务账号的项目的 ID。
    • BUILD_SERVICE_AGENT：服务代理的电子邮件 ID，格式为 service-BUILD_PROJECT_NUMBER@gcp-sa-cloudbuild.iam.gserviceaccount.com，其中 BUILD_PROJECT_NUMBER 是您运行 build 的项目的项目编号。您可以从项目设置页面获取项目编号。

限制：

  • 您的 Google Cloud 项目必须位于 Google Cloud 组织中。

  • 您必须在命令行中使用 gcloud builds submit 或 gcloud builds triggers create 启动 build。

后续步骤