使用用户代管式服务账号运行 build

本文档介绍了如何将 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) 获得此权限。了解如何授予角色。

    启用 API

  • 如果您计划使用此账号创建和管理凭据(例如创建短期有效凭据),请启用 IAM Service Account Credentials API。

    启用 API 所需的角色

    如需启用 API,您需要拥有 serviceusage.services.enable 权限。如果您创建了项目,则可能已经通过 Owner 角色 (roles/owner) 拥有此权限。否则,您可以通过 Service Usage Admin 角色 (roles/serviceusage.serviceUsageAdmin) 获得此权限。了解如何授予角色。

    启用 API

  • 创建服务账号(如果您尚未创建)。

设置服务账号

向用户代管式服务账号授予 IAM 角色,使其拥有运行构建所需的权限。您还可以将 Cloud Build 配置为自动为新触发器选择此服务账号。

  1. 在 Google Cloud 控制台中,前往 Cloud Build 权限页面:

    前往权限

  2. 前往服务账号菜单,然后选择您的服务账号。如需选择其他项目中的服务账号,请点击切换项目。

  3. 如需将所选服务账号用作新触发器的服务账号,请开启设置为新触发器的预选服务账号。

  4. 在 Google Cloud 服务列表中,启用要授予服务账号的 IAM 角色。

  5. 如果您在构建流水线中所需的角色未在此处列出,您可以在 IAM 配置页面中授予其他角色。

  6. 如果您选择了其他项目中的服务账号,请完成跨项目设置中的步骤。

确定要配置的服务账号

在授予角色之前,请先验证为您的 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 Build 将构建日志写入该存储桶。

您不能将日志存储在 Google Cloud拥有的日志存储桶中。

如需详细了解构建日志的存储位置,请参阅构建日志存储选项。

使用配置文件运行构建

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

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

  2. 添加 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"
      }
    }
    
    

    将 build 配置文件中的变量替换为以下内容:

    • LOGS_BUCKET_LOCATION:用于存储构建日志的 Cloud Storage 存储桶。例如 gs://mylogsbucket。
    • PROJECT_ID 是运行构建的 Google Cloud 项目的 ID。
    • SERVICE_ACCOUNT 是您要为构建指定的服务账号的电子邮件地址或唯一 ID。 例如,服务账号邮箱如下所示:service-account-name@project-id.。
  3. 使用构建配置文件启动构建:

    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 以自动选择服务账号。

  1. 在构建配置文件中:

    • 如果要将构建日志存储在 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。

  2. 指定要用于构建触发器的服务账号:

    控制台

    1. 创建或修改构建触发器。

    2. 在服务账号字段中,指定您的服务账号。如需选择其他项目中的服务账号,请点击切换项目。

      在使用旧版 Cloud Build 服务账号的项目中,省略此字段会默认使用该旧版服务账号。在以下项目中,您必须选择服务账号,否则触发器创建会失败,并显示 INVALID_ARGUMENT 错误,指示您需要指定服务账号:使用 Compute Engine 默认服务账号的项目,或通过组织政策限制默认服务账号的项目。

    3. 点击创建以保存您的构建触发器。

    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 错误,则可能需要手动创建服务代理。

后续步骤