本页面介绍如何为构建配置用户指定的服务帐号。
默认情况下,Cloud Build 使用特殊服务帐号代表您执行构建。此服务帐号称为 Cloud Build 服务帐号,当您在 Google Cloud 项目中启用 Cloud Build API 时,系统会自动创建该服务帐号。此服务帐号默认拥有多个权限,例如更新构建或写入日志。
您可以指定自己的服务帐号,以代表您执行构建,而不是使用默认的 Cloud Build 服务帐号。您可以为每个项目指定任意数量的服务帐号。通过维护多个服务帐号,您可以根据服务帐号执行的任务向它们授予不同的权限。例如,您可以使用一个服务帐号来构建映像并推送到 Container Registry,然后使用另一个服务帐号来构建映像并推送到 Artifact Registry。
准备工作
-
启用 Cloud Build and IAM 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 submit
或gcloud beta builds triggers create
在命令行中启动构建。如需使用 Google Cloud Console 中的“触发器”页面,用户指定的服务帐号和构建触发器必须位于同一项目中。
设置构建日志
如需为构建指定您自己的服务帐号,您必须将构建日志存储在 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
) 角色。
- 要将映像或工件存储在 Artifact Registry 中,请向服务帐号授予 Artifact Registry Writer (
授予服务帐号运行构建所需的任何其他 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_NAME
是运行构建的 Cloud 项目的 ID。SERVICE_ACCOUNT
是您要为构建指定的服务帐号的电子邮件地址或唯一 ID。 例如my-sa-name@my-project-name.iam.gserviceaccount.com
。
- 添加
使用构建配置文件启动构建:
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
。
- 如果要将构建日志存储在 Logging 中,请添加
指定要用于构建触发器的服务帐号:
控制台
如需使用 Cloud Console 中的触发器界面运行构建,用户指定的服务帐号必须与构建触发器位于同一项目中。如需将触发器与跨项目服务帐号搭配使用,请使用
gcloud
工具创建构建触发器。- 创建或修改构建触发器。
- 在服务帐号字段中,指定您的服务帐号。如果您未指定服务帐号,则使用默认的 Cloud Build 服务帐号。
- 点击创建以保存您的构建触发器。
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 服务帐号的访问权限。