本文档介绍了如何将 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) 获得此权限。了解如何授予角色。 如果您计划使用此账号创建和管理凭据(例如创建短期有效凭据),请启用 IAM Service Account Credentials API。
启用 API 所需的角色
如需启用 API,您需要拥有
serviceusage.services.enable权限。如果您创建了项目,则可能已经通过 Owner 角色 (roles/owner) 拥有此权限。否则,您可以通过 Service Usage Admin 角色 (roles/serviceusage.serviceUsageAdmin) 获得此权限。了解如何授予角色。创建服务账号(如果您尚未创建)。
设置服务账号
向用户代管式服务账号授予 IAM 角色,使其拥有运行构建所需的权限。您还可以将 Cloud Build 配置为自动为新触发器选择此服务账号。
-
在 Google Cloud 控制台中,前往 settings Cloud Build 权限页面:
前往服务账号菜单,然后选择您的服务账号。如需选择其他项目中的服务账号,请点击切换项目。
如需将所选服务账号用作新触发器的服务账号,请开启设置为新触发器的预选服务账号。
在 Google Cloud 服务列表中,启用要授予服务账号的 IAM 角色。
如果您在构建流水线中所需的角色未在此处列出,您可以在 IAM 配置页面中授予其他角色。
如果您选择了其他项目中的服务账号,请完成跨项目设置中的步骤。
确定要配置的服务账号
在授予角色之前,请先验证为您的 build 配置了哪个服务账号:
现有构建触发器:检查触发器上配置的服务账号:
gcloud builds triggers describe TRIGGER_NAME \ --region=REGION \ --format="value(serviceAccount)"替换以下内容:
TRIGGER_NAME:构建触发器的名称。REGION:构建触发器所在的区域。
输出的解读如下:
- 如果该命令输出的服务账号资源名称采用
projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_EMAIL格式,请向该账号授予所需角色。此输出可以标识用户代管式服务账号或 Compute Engine 默认服务账号。 - 如果
serviceAccount字段为空,则触发器会使用旧版 Cloud Build 服务账号。只有在使用旧版默认服务账号的项目中,才支持在创建触发器时省略serviceAccount。在以下情况下,触发器创建会失败,并显示INVALID_ARGUMENT错误,指出您必须指定服务账号 (BYOSA is required when creating triggers):项目使用 Compute Engine 默认服务账号,或组织政策限制了默认服务账号。如果组织政策在构建时限制了默认服务账号,则构建会失败,并显示build.service_account must be specified due to the evaluation of the following org policies。
build 配置文件:如果您使用
gcloud builds submit手动运行 build,请检查cloudbuild.yaml文件中的serviceAccount字段。如果省略,Cloud Build 会使用默认构建服务账号,或者如果组织政策限制了默认服务账号,则会失败并显示build.service_account must be specified due to the evaluation of the following org policies。
所需的角色
为确保您的用户代管式服务账号具有使用用户代管式服务账号运行 build 所需的权限,请让您的管理员为您的用户代管式服务账号授予运行 build 的项目的以下 IAM 角色:
-
将构建日志写入并流式传输到 Cloud Logging:Logs Writer (
roles/logging.logWriter) -
从 Cloud Storage 存储桶下载源代码归档或依赖项:Storage Object Viewer (
roles/storage.objectViewer)
如需详细了解如何授予角色,请参阅管理对项目、文件夹和组织的访问权限。
您的管理员还可以通过自定义角色或其他预定义角色向您的用户代管式服务账号授予所需的权限。
服务账号模拟
如需允许 Cloud Build 和触发器使用用户代管式服务账号运行构建,请确保向用户代管式服务账号授予以下权限:
- 对于创建、更新或手动运行构建触发器(或使用
gcloud builds submit提交构建)的用户或自动化身份,请授予 Service Account User 角色 (roles/iam.serviceAccountUser),该角色包含iam.serviceAccounts.actAs权限。 - 对于 Cloud Build 服务代理 (
service-PROJECT_NUMBER@gcp-sa-cloudbuild.),需要iam.serviceAccounts.getAccessToken权限。在同一项目中,此权限默认包含在 Cloud Build Service Agent 角色 (roles/cloudbuild.serviceAgent) 中。如果该角色已被移除,或者用户代管式服务账号位于其他项目中,请授予 Service Account Token Creator 角色 (roles/iam.serviceAccountTokenCreator)。
如需详细了解构建通常所需的 IAM 角色,请参阅以下信息:
设置构建日志
为构建指定自己的服务账号时,您必须将构建日志存储在以下任一存储桶类型中:
用户项目中的 Cloud Storage 存储桶。这些存储桶可以是用户创建的存储桶,也可以是Google Cloud创建且归用户所有的存储桶。
如果您创建日志存储桶,请确保该存储桶没有保留政策,因为该政策可能会阻止 Cloud Build 将构建日志写入该存储桶。
您不能将日志存储在 Google Cloud拥有的日志存储桶中。
如需详细了解构建日志的存储位置,请参阅构建日志存储选项。
使用配置文件运行构建
如需使用配置文件手动运行构建,请执行以下操作:
在项目根目录中,创建一个名为
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_ONLYJSON
{ "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.。
使用构建配置文件启动构建:
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 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_ONLYJSON
{ "steps": [ { "name": "bash", "args": [ "echo", "Hello world!" ] } ], "logsBucket": "LOGS_BUCKET_LOCATION", "options": { "logging": "GCS_ONLY" } }将
LOGS_BUCKET_LOCATION替换为用于存储构建日志的 Cloud Storage 存储桶。例如gs://mylogsbucket。指定要用于构建触发器的服务账号:
控制台
在服务账号字段中,指定您的服务账号。如需选择其他项目中的服务账号,请点击切换项目。
在使用旧版 Cloud Build 服务账号的项目中,省略此字段会默认使用该旧版服务账号。在以下项目中,您必须选择服务账号,否则触发器创建会失败,并显示
INVALID_ARGUMENT错误,指示您需要指定服务账号:使用 Compute Engine 默认服务账号的项目,或通过组织政策限制默认服务账号的项目。点击创建以保存您的构建触发器。
gcloud
创建构建触发器时,请使用
--service-account标志指定服务账号。在不使用旧版默认服务账号的项目中,--service-account标志是必需的,否则触发器创建会失败,并显示INVALID_ARGUMENT错误,指示您需要指定服务账号。在以下示例中,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 是包含用户代管式服务账号的项目
在包含用户代管式服务账号的项目中,为运行构建的项目中的 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.,其中BUILD_PROJECT_NUMBER是您运行构建的项目编号。您可以从项目设置页面获取项目编号。
限制:
您的 Google Cloud 项目必须位于 Google Cloud 组织中。
您必须使用
gcloud builds submit或gcloud builds triggers create在命令行中启动构建。如果您在授予 IAM 角色时收到
service account not found错误,则可能需要手动创建服务代理。
后续步骤
- 详细了解 Cloud Build IAM 角色和权限。
- 了解服务账号变更对您运行 build 的方式有何影响。