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

本文档介绍了如何将 build 配置为使用用户管理的服务账号。

如果您未为 build 指定用户代管式服务账号,Cloud Build 会自动使用默认 Cloud Build 服务账号。此默认服务账号可能具有不必要的广泛权限,例如对 Cloud Source Repositories 和项目中任何 Cloud Storage 存储桶的访问权限。

我们建议遵循最小权限原则,为服务账号分配与其执行的任务范围相符的权限和角色。例如,您可以使用一个服务账号来构建映像并将其推送到 Artifact Registry,如 Cloud de Confiance by S3NS Blog 中所示。

准备工作

  • 启用 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 角色,使其拥有运行 build 所需的权限。您还可以将 Cloud Build 配置为自动为新触发器选择此服务账号。

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

    前往权限

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

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

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

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

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

如需详细了解构建通常所需的 IAM 角色,请参阅以下信息:

设置构建日志

为 build 指定自己的服务账号时,您必须将 build 日志存储在以下任一类型的存储桶中:

如果您创建日志存储桶,请确保该存储桶没有保留政策,因为该政策可能会阻止 Cloud Build 将构建日志写入该存储桶。

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

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

使用配置文件运行构建

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

  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 是运行构建的 Cloud de Confiance 项目的 ID。
    • SERVICE_ACCOUNT 是您要为构建指定的服务账号的电子邮件地址或唯一 ID。 例如,服务账号电子邮件地址如下所示:service-account-name@project-id.s3ns.iam.gserviceaccount.com。
  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 会使用默认服务账号。

    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
    

    将 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.s3ns-system.iam.gserviceaccount.com,其中 BUILD_PROJECT_NUMBER 是您运行 build 的项目的项目编号。您可以从项目设置页面获取项目编号。

限制:

  • 您的 Cloud de Confiance 项目必须位于 Cloud de Confiance by S3NS 组织中。

  • 您必须使用 gcloud builds submit 或 gcloud builds triggers create 在命令行中启动构建。

  • 如果您在授予 IAM 角色时收到 service account not found 错误,则可能需要手动创建服务代理。

后续步骤