配置用户指定的服务帐号

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

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

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

准备工作

启用 Cloud Build and IAM API。
启用 API
如需使用本指南中的命令行示例，请安装并配置 Google Cloud CLI。

注意：如果您之前安装了 Google Cloud CLI，请运行 gcloud components update 以确保您拥有最新版本。
确保您已经创建了要使用的服务帐号。您必须在运行构建所在的 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 submit 或 gcloud beta builds triggers create 在命令行中启动构建。如需使用 Google Cloud 控制台中的“触发器”页面，用户指定的服务帐号和构建触发器必须位于同一项目中。

设置构建日志

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

如需将日志存储在 Cloud Storage 存储桶中，请按照将构建日志存储在用户创建的存储桶中中的说明进行操作。切勿在日志存储桶上设置保留政策，因为这可能会阻止 Cloud Build 将构建日志写入存储桶。
如需将构建日志存储在 Logging 中，请向服务帐号授予 Logs Writer (roles/logging.logWriter) 角色。如需详细了解其他必要的服务帐号角色，请参阅必需的 IAM 权限。
如需详细了解存储构建日志的位置，请参阅选择存储构建日志的位置。

必需的 IAM 权限

如需使用用户指定的服务帐号启动构建，请求构建的用户需要具有服务帐号的项目中的 Service Account User (roles/iam.serviceAccountUser) IAM 角色。
如需将构建日志存储在 Logging 中，请向服务帐号授予 Logs Writer (roles/logging.logWriter) 角色。
如果您将任何构建映像或工件存储在 Artifact Registry、Container Registry 或 Cloud Storage 中，请授予必要的访问权限：
- 要将映像或工件存储在 Artifact Registry 中，请向服务帐号授予 Artifact Registry Writer (roles/artifactregistry.writer) 角色。
- 如需将映像存储在 Container Registry 中，请向服务帐号授予 Storage Admin (roles/storage.admin) 角色。
- 如需将工件存储在 Cloud Storage 中，请向服务帐号授予 Storage Object Admin (roles/storage.objectAdmin) 角色。
授予服务帐号运行构建所需的任何其他 IAM 权限。例如，如果您的构建需要部署到 App Engine，则服务帐号需要 App Engine Admin 角色；如果您的构建指定来自 Cloud Storage 存储桶的来源，则服务帐号需要 Storage Admin 角色。

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

从命令行运行构建

在项目根目录中，创建名为 cloudbuild.yaml 或 cloudbuild.json 的 Cloud Build 构建配置文件。
在构建配置文件中：
- 添加 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_ID 是运行构建的 Cloud 项目的 ID。
- SERVICE_ACCOUNT 是您要为构建指定的服务帐号的电子邮件地址或唯一 ID。例如，服务帐号电子邮件地址如下所示：service-account-name@project-id.iam.gserviceaccount.com。
在此示例中，serviceAccount 字段的值为 projects/project-id/serviceAccounts/service-account-name@project-id.iam.gserviceaccount.com。

使用 build 配置文件启动构建：

 gcloud builds submit --config CONFIG_FILE_PATH SOURCE_DIRECTORY

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

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

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

使用构建触发器运行构建

在源代码库中，创建一个名为 cloudbuild.yaml 或 cloudbuild.json 的 Cloud Build 构建配置文件。
在构建配置文件中：
- 如果要将构建日志存储在 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。
注意：如果您在构建配置中指定服务帐号，则在运行触发器时，该服务帐号会在构建调用期间被忽略。只有为触发器指定的服务帐号将用于通过触发器调用的构建。
指定要用于构建触发器的服务帐号：
控制台
如需使用 Google 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 是您启动构建的项目。

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

后续步骤

如需详细了解默认 Cloud Build 服务帐号，请参阅 Cloud Build 服务帐号。
如需了解如何向默认 Cloud Build 服务帐号授予权限，请参阅配置 Cloud Build 服务帐号的访问权限。