配置用户指定的服务账号

为了遵循 Cloud Build 中的最小权限原则，您可以将 Cloud Build 配置为使用一个服务帐号只具有执行构建所需的足够权限。本页面介绍了如何设置服务帐号。

如果您未指定服务帐号，Cloud Build 可能会自动选择一个服务帐号来代表您执行构建。此服务帐号的权限可能对您的使用场景而言过于宽泛，例如访问您的 Cloud Source Repositories 和项目中的任何 Cloud Storage 存储桶。

为了改善项目的安全状况并降低配置错误或恶意用户的潜在影响，我们建议您遵循最小权限原则。利用此原则，您可以为每个服务帐号分配其所执行任务范围内的权限和角色。例如，您可以使用一个服务帐号构建映像并将其推送到 Artifact Registry，如 Google Cloud 博客中所示。

准备工作

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

启用 API
创建服务帐号（如果尚未创建）。

授予 IAM 权限

为了让您的构建能够访问其需要连接的服务，您必须授予一些角色和权限：

打开 Cloud Build 的“设置”页面：

打开 Cloud Build 的“设置”页面

您会看到服务帐号权限标签页：
从下拉列表中选择要更改其角色的服务帐号。
将您要添加的角色的状态设置为启用。
如果此处未列出您的构建流水线所需的角色，您可以在 IAM 配置页面中授予其他角色。

如需详细了解构建通常所需的角色，请参阅配置对 Cloud Build 资源的访问权限以及 Cloud Build IAM 角色和权限的完整列表。

设置构建日志

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

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

使用配置文件执行构建

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

在项目根目录中，创建一个名为 cloudbuild.yaml 或 cloudbuild.json 的Cloud Build 构建配置文件。
添加 serviceAccount 字段和首选日志记录设置。
- 如果您要将构建日志存储在 Cloud 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 是您运行构建的 Google Cloud 项目的 ID。
- SERVICE_ACCOUNT 是您要为构建指定的服务账号的电子邮件地址或唯一 ID。例如，服务帐号电子邮件地址如下所示：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 会假定构建配置文件和源代码位于当前工作目录中。

使用触发器执行构建

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

在构建配置文件中：
- 如果您要将构建日志存储在 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 替换为用于存储构建日志的 Cloud Storage 存储桶。例如 gs://mylogsbucket。
指定要用于构建触发器的服务账号：
控制台
如需使用 Google Cloud 控制台中的“触发器”页面运行构建，用户指定的服务帐号必须与构建触发器位于同一项目中。如需将触发器与跨项目服务帐号搭配使用，请使用 gcloud 工具创建构建触发器。
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
```
将构建配置文件中的占位值替换为以下内容：
- TRIGGER_NAME 是构建触发器的名称。
- REPO_NAME 是代码库的名称。
- REPO_OWNER 是代码库所有者的用户名。
- BRANCH_PATTERN 是代码库中要在其上调用构建的分支名称。
- TAG_PATTERN 是代码库中要在其上调用构建的标记名称。
- BUILD_CONFIG_FILE 是构建配置文件的路径。
- SERVICE_ACCOUNT 是与您的服务账号相关联的电子邮件地址。
- BUILD_PROJECT 是您开始构建的项目。

跨项目设置

如果用户指定的服务帐号所属的项目不同于您要启动构建的项目，请授予必要的访问权限：

在具有用户指定服务帐号的项目中，确保未强制执行 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：服务代理的电子邮件 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 在命令行中启动构建。如需使用 Google Cloud 控制台中的“触发器”页面，用户指定的服务帐号和构建触发器必须位于同一项目中。

后续步骤

详细了解 Cloud Build IAM 角色和权限。
了解服务帐号变更对构建作业的运行方式有何影响。