配置用户指定的服务帐号

本页面介绍如何为构建配置用户指定的服务帐号。

默认情况下,Cloud Build 使用特殊服务帐号代表您执行构建。此服务帐号称为 Cloud Build 服务帐号,当您在 Google Cloud 项目中启用 Cloud Build API 时,系统会自动创建该服务帐号。此服务帐号默认拥有多个权限,例如更新构建或写入日志。

您可以指定自己的服务帐号,以代表您执行构建,而不是使用默认的 Cloud Build 服务帐号。您可以为每个项目指定任意数量的服务帐号。通过维护多个服务帐号,您可以根据服务帐号执行的任务向它们授予不同的权限。例如,您可以使用一个服务帐号来构建映像并推送到 Container Registry,然后使用另一个服务帐号来构建映像并推送到 Artifact Registry。

准备工作

  • 启用 Cloud Build and IAM API。

    启用 API

  • 如需使用本指南中的命令行示例,请安装并配置 Google Cloud CLI

  • 确保您已经创建了要使用的服务帐号。 您必须在运行构建所在的 Cloud 项目中创建该帐号。

跨项目设置

如果用户指定的服务帐号与您要开始构建的项目不在同一个项目中,请授予必要的访问权限:

  • 在包含用户指定的服务帐号的项目中,确保 iam.disableCrossProjectServiceAccountUsage 组织政策限制条件未强制执行。默认情况下,系统会强制执行此限制条件。如需停用此组织政策限制条件,请运行以下命令,其中 SERVICE_ACCOUNT_PROJECT_ID 是包含用户指定服务帐号的项目:

       gcloud resource-manager org-policies disable-enforce \
          iam.disableCrossProjectServiceAccountUsage \
          --project=SERVICE_ACCOUNT_PROJECT_ID
    
  • 在具有用户指定的服务帐号的项目中,为正在运行构建的项目的 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:格式为 service-BUILD_PROJECT_NUMBER@gcp-sa-cloudbuild.iam.gserviceaccount.com 的服务代理的电子邮件 ID,其中 BUILD_PROJECT_NUMBER 是运行构建的项目的项目编号。您可以从项目设置页面获取项目编号。

限制:

  • 您的 Cloud 项目必须位于 Google Cloud 组织中。
  • 您必须使用 gcloud builds submitgcloud beta builds triggers create 在命令行中启动构建。如需使用 Google Cloud Console 中的“触发器”页面,用户指定的服务帐号和构建触发器必须位于同一项目中。

设置构建日志

如需为构建指定您自己的服务帐号,您必须将构建日志存储在 Cloud Logging 或用户创建的 Cloud Storage 存储桶中。您不能将日志存储在默认日志存储桶中。

必需的 IAM 权限

有关向服务帐号授予 IAM 角色的说明,请参阅配置对资源的访问权限

从命令行运行构建

  1. 在项目根目录中,创建名为 cloudbuild.yamlcloudbuild.json 的 Cloud Build 构建配置文件。

  2. 在构建配置文件中:

    • 添加 serviceAccount 字段,并指定您的服务帐号的电子邮件地址。
    • 如果要将构建日志存储在 Logging 中,请添加 logging 字段并将字段的值设置为 CLOUD_LOGGING_ONLY
    • 如果要将构建日志存储在用户创建的 Cloud Storage 存储桶中,请执行以下操作:
      • 添加 logging 字段并将其值设置为 GCS_ONLY
      • 添加 logsBucket 字段,并将其值设置为您的 Cloud Storage 存储桶位置。

    使用用户指定的服务帐号时,不能将日志存储在默认日志存储桶中。

    以下构建配置文件将 Cloud 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"
      }
    }
    

    将构建配置文件中的占位值替换为以下内容:

    • LOGS_BUCKET_LOCATION:用于存储构建日志的 Cloud Storage 存储桶。例如 gs://mylogsbucket
    • PROJECT_NAME 是运行构建的 Cloud 项目的 ID。
    • SERVICE_ACCOUNT 是您要为构建指定的服务帐号的电子邮件地址或唯一 ID。 例如 my-sa-name@my-project-name.iam.gserviceaccount.com
  3. 使用构建配置文件启动构建:

     gcloud builds submit --config CONFIG_FILE_PATH SOURCE_DIRECTORY
    

将上述命令中的占位值替换为以下内容:

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

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

使用构建触发器运行构建

  1. 在源代码库中,创建一个名为 cloudbuild.yamlcloudbuild.json 的 Cloud Build 构建配置文件。

  2. 在构建配置文件中:

    • 如果要将构建日志存储在 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:用于存储构建日志的 Cloud Storage 存储桶。例如 gs://mylogsbucket
  3. 指定要用于构建触发器的服务帐号:

    控制台

    如需使用 Cloud Console 中的触发器界面运行构建,用户指定的服务帐号必须与构建触发器位于同一项目中。如需将触发器与跨项目服务帐号搭配使用,请使用 gcloud 工具创建构建触发器。

    1. 创建或修改构建触发器
    2. 服务帐号字段中,指定您的服务帐号。如果您未指定服务帐号,则使用默认的 Cloud Build 服务帐号
    3. 点击创建以保存您的构建触发器。

    gcloud

    创建构建触发器时,请使用 --service-account 标志指定服务帐号。如果您未指定服务帐号,则使用默认的 Cloud Build 服务帐号。在以下示例中,gcloud 命令会在源代码位于 GitHub 中时创建一个构建触发器:

     gcloud beta 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
    

    将构建配置文件中的占位值替换为以下内容:

    • TRIGGER_NAME 是构建触发器的名称。
    • REPO_NAME 是代码库的名称。
    • REPO_OWNER 是代码库所有者的用户名。
    • BRANCH_PATTERN 是代码库中要在其上调用构建的分支名称。
    • TAG_PATTERN 是代码库中要在其上调用构建的标记名称。
    • BUILD_CONFIG_FILE 是构建配置文件的路径。
    • SERVICE_ACCOUNT 是与您的服务帐号相关联的电子邮件地址。
    • BUILD_PROJECT 是您要在其中开始构建的项目。

构建触发器会调用构建以响应与触发器关联的事件。例如,触发器会在将源代码推送到代码库时执行。如需详细了解触发器,请参阅创建和管理构建触发器

后续步骤