教程：配置 CodeBuild托管的 Buildkite 运行器

本教程向您展示如何配置 CodeBuild 项目以运行 Buildkite 作业。有关将 Buildkite 与配合 CodeBuild 使用的更多信息，请参阅。自我管理的 Buildkite 运行器进来了 AWS CodeBuild

要完成本教程，您首先必须：

• 可以访问 Buildkite 组织。有关设置 Buildkite 账户和组织的更多信息，您可以关注此入门教程。

• 创建配置为使用自托管运行器的 Buildkite 管道、集群和队列。有关设置这些资源的更多信息，可以参考 Buildkite 管道安装教程。

  

第 1 步：生成 Buildkite 代理令牌

在此步骤中，您将在 Buildkite 中生成代理令牌，该令牌将用于对 CodeBuild 自托管运行器进行身份验证。有关此资源的更多信息，请参阅 Buildkite 代理令牌。

生成 Buildkite 代理令牌

1. 在你的 Buildkite 集群中，选择代理代币，然后选择新代币。

2. 为令牌添加描述，然后单击 “创建令牌”。

3. 保存代理令牌值，以便稍后在 CodeBuild 项目设置过程中使用该值。

   

第 2 步：使用 webhook 创建 CodeBuild 项目

使用 webhook 创建 CodeBuild 项目

1. 在 https://console.aws.amazon.com/codesuite/codebuild /home 中打开 AWS CodeBuild 控制台。

2. 创建自托管的构建项目。有关更多信息，请参阅 创建构建项目（控制台） 和 运行构建（控制台）。

   • 在 “项目配置” 中，选择 “运行器项目”。在 Runner 中：

     • 对于 Runner 提供商，请选择 Buildkit e。

     • 对于 Buildkite 代理令牌，请使用创建密钥页面选择创建新的代理令牌。系统将提示您在中 AWS Secrets Manager 创建一个新的密钥，其密钥值等于您在上面生成的 Buildkite 代理令牌。

     • （可选）如果您想为作业使用 CodeBuild 托管凭据，请在 Buildkite 源凭证选项下选择作业的源存储库提供商，并确认已为您的账户配置了凭据。此外，请验证您的 Buildkite 管道是否使用 HTTPS 进行结账。

     注意

     Buildkite 需要编译环境中的源证书才能提取任务的来源。有关可将 Buildkite 身份验证到私有存储库用的来源凭证选项，请参阅。

   • （可选）在环境中：

     • 选择支持的环境映像和计算。

       请注意，您可以选择在 Buildkite YAML 步骤中使用标签来覆盖图像和实例设置。有关更多信息，请参阅 第 4 步：更新你的 Buildkite 工作流程步骤。

   • （可选）在 Buildspec 中：

     • 除非作为标签添加，否则默认情况下buildspec-override: "true"，您的构建规范将被忽略。相反， CodeBuild 将覆盖它以使用设置自托管运行器的命令。

       注意

       CodeBuild 不支持 Buildkite 自托管运行器版本的 buildspec 文件。对于内联构建规范，如果您已配置 CodeBuild 托管源凭据，则需要 git-credential-helper在构建规范中启用

3. 继续使用默认值，然后选择创建构建项目。

4. 保存 “创建 Webhook” 弹出窗口中的负载网址和密钥值。要么按照弹出窗口中的说明创建新的 Buildkite 组织 webhook，要么继续下一节。

第 3 步：在 Buildkite 中创建一个 CodeBuild webhook

在此步骤中，您将使用 CodeBuild webhook 中的有效负载 URL 和 S ecret 值在 Buildkite 中创建一个新的 webhook。此 webhook 将用于在有效的 Buildkite 作业启动 CodeBuild 时触发构建。

在 Buildkite 中创建新的 webhook

1. 导航到你的 Buildkite 组织的 “设置” 页面。

2. 在 “集成” 下，选择 “通知服务”。

3. 选择 Webhook 框旁边的 “添加”。在添加 Webhook 通知页面中，使用以下配置：

   1. 在 Webhook 网址下，添加已保存的负载网址值。

   2. 在 “令牌” 下，确认已选中 “按原样 X-Buildkite-Token发送令牌”。将你的 webhook 密钥值添加到 “令牌” 字段。

   3. 在下方，确认选中了按原样 X-Buildkite-Token发送令牌。将你的 webhook 密钥值添加到 “令牌” 字段。

   4. 在 “事件” 下，选择 job.scheduled webhook 事件。

   5. （可选）在 Pipelin es 下，您可以选择仅触发特定管道的构建。

4. 选择添加 Webhook 通知。

第 4 步：更新你的 Buildkite 工作流程步骤

在此步骤中，您将更新 Buildkite 管道的步骤，以便添加必要的标签和可选的替代项。有关支持的标签覆盖的完整列表，请参阅 CodeBuild托管的 Buildkite 运行器支持的标签覆盖。

更新您的工作流程步骤

1. 选择 Buildkite 管道，选择 “设置”，然后选择 “步骤”，即可导航到 Buildkite 工作流程步骤页面。

   如果您尚未选择 “转换为 YAML 步骤”，请选择 “转换为 YAML 步骤”。

   

2. 您至少需要指定一个引用管道名称的 Buildkite 代理标签。 CodeBuild 需要项目名称才能将 Buildkite 作业的 AWS相关设置链接到特定 CodeBuild 项目。通过在 YAML 中包含项目名称 CodeBuild ，可以调用具有正确项目设置的作业。

   agents:
     project: "codebuild-<project name>"

   以下是仅使用项目标签的 Buildkite 工作流步骤示例：

   agents:
     project: "codebuild-myProject"
   steps:
     - command: "echo \"Hello World\""

   您也可以在标签中覆盖映像和计算类型。有关可用映像的列表，请参阅计算 CodeBuild托管的 Buildkite 运行器支持的图像。标签中的计算类型和映像将覆盖项目的环境设置。要覆盖 CodeBuild EC2 或 Lambda 计算版本的环境设置，请使用以下语法：

   agents:
     project: "codebuild-<project name>"
     image: "<environment-type>-<image-identifier>"
     instance-size: "<instance-size>"

   以下是包含图像和实例大小覆盖的 Buildkite 工作流步骤示例：

   agents:
     project: "codebuild-myProject"
     image: "arm-3.0"
     instance-size: "small"
   steps:
     - command: "echo \"Hello World\""

   您可以在标签中覆盖构建所用的实例集。这将覆盖在您的项目中配置的实例集设置，以便使用指定的实例集。有关更多信息，请参阅在预留容量队列上运行构建。

   要替换 Amazon EC2 计算版本的队列设置，请使用以下语法：

   agents:
     project: "codebuild-<project name>"
     fleet: "<fleet-name>"
   

   要同时覆盖构建所用的实例集和映像，请使用以下语法：

   agents:
     project: "codebuild-<project name>"
     fleet: "<fleet-name>"
     image: "<environment-type>-<image-identifier>"

   以下是带有队列和图像覆盖的 Buildkite 管道步骤的示例：

   agents:
     project: "codebuild-myProject"
     fleet: "myFleet"
     image: "arm-3.0"
   steps:
     - command: "echo \"Hello World\""

3. 您可以选择在自托管 Buildkite 运行器构建期间运行内联 buildspec 命令（有关更多详细信息，运行 INSTALL、PRE_BUILD 和 POST_BUILD 阶段的 buildspec 命令请参阅）。要指定该 CodeBuild 版本应在 Buildkite 自托管运行器构建期间运行 buildspec 命令，请使用以下语法：

   agents:
     project: "codebuild-<project name>"
     buildspec-override: "true"

   以下是带有 buildspec 覆盖的 Buildkite 管道的示例：

   agents:
     project: "codebuild-myProject"
     buildspec-override: "true"
   steps:
     - command: "echo \"Hello World\""

4. 或者，您可以在 CodeBuild 支持的标签之外提供标签。在覆盖构建的属性时会忽略这些标签，但不会导致 webhook 请求失败。例如，添加 myLabel: “testLabel" 作为标签不会阻止构建运行。

第 5 步：查看您的结果

每当你的管道中启动 Buildkite 作业时， CodeBuild 都会通过 Buildkite job.scheduled webhook 收到一个 webhook 事件。对于你的 Buildkite 版本中的每项任务，都 CodeBuild 将启动一个构建来运行一个临时的 Buildkite 运行器。运行器负责执行单个 Buildkite 作业。作业完成后，运行器和关联的构建过程会立即终止。

要查看您的工作流程作业日志，请导航到您的 Buildkite 管道并选择最新的构建（您可以通过选择 “新建构建” 来触发新构建）。每项任务的关联 CodeBuild 构建启动并启动任务后，您应该可以在 Buildkite 控制台中看到该任务的日志

将 Buildkite 身份验证到私有存储库

如果您在 Buildkite 管道中配置了私有存储库，那么 Buildkite 需要构建环境中的额外权限才能提取存储库，因为 Buildkite 不会向自托管的运行器提供凭据以从私有存储库中提取存储库。要对外部私有源存储库的 Buildkite 自托管运行器代理进行身份验证，可以使用以下选项之一。

要使用进行身份验证 CodeBuild

CodeBuild 为支持的源类型提供托管凭据处理。要使用 CodeBuild 源证书提取作业的源存储库，您可以使用以下步骤：

1. 在 CodeBuild 控制台中，导航到编辑项目或使用中的步骤创建新 CodeBuild 项目第 2 步：使用 webhook 创建 CodeBuild 项目。

2. 在 Buildkite 源证书选项下，选择作业的源存储库提供商。

   1. 如果您想使用账户级 CodeBuild 凭证，请验证其配置是否正确。此外，如果您的项目配置了内联构建规范，请验证 git-credential-helper是否已启用。

   2. 如果您想使用项目级别的 CodeBuild 凭据，请选择 “仅为此项目使用覆盖凭据”，然后为您的项目设置凭据。

3. 在 Buildkite 工作流设置中，导航到存储库设置。将您的源存储库签出设置设置设置为使用 HTTPS 签出

   

使用 Buildkite 机密进行身份验证

Buildkite 维护了一个 ssh-checkout 插件，该插件可用于使用 ssh 密钥对外部源存储库的自托管运行器进行身份验证。密钥值存储为 Buildkite 密钥，并在尝试拉取私有存储库时由 Buildkite 自托管的运行器代理自动获取。要为您的 Buildkite 管道配置 ssh-checkout 插件，您可以使用以下步骤：

1. 使用您的电子邮件地址生成私有和公共 ssh 密钥，例如 ssh-keygen -t rsa -b 4096 -C "[e-mail]"

2. 将公钥添加到您的私有源存储库中。例如，您可以按照本指南为 GitHub 账户添加密钥。

3. 向你的 Buildkite 集群添加一个新的 SSH 密钥密钥。在你的 Buildkite 集群中，选择密钥 → 新密钥。在密钥字段中为您的密钥添加一个名称，然后将您的 SSH 私钥添加到 “值” 字段中：

   

4. 在 Buildkite 管道中，导航到存储库设置并将结账设置为使用 SSH。

   

5. 更新您的管道 YAML 步骤以使用该git-ssh-checkout插件。例如，以下管道 YAML 文件使用带有上述 Buildkite 密钥的签出操作：

   agents:
     project: "codebuild-myProject"
   steps:
     - command: "npm run build"
       plugins:
         - git-ssh-checkout#v0.4.1:
             ssh-secret-key-name: 'SOURCE_SSH_KEY'

6. 在其中运行 Buildkite 自托管运行器作业时 CodeBuild，Buildkite 现在将在提取私有存储库时自动使用你配置的密钥值

运行器配置选项

您可以在项目配置中指定以下环境变量来修改自托管运行器的安装配置：

• CODEBUILD_CONFIG_BUILDKITE_AGENT_TOKEN: CodeBuild 将从 AWS Secrets Manager 中获取配置为该环境变量值的秘密值，以便注册 Buildkite 自托管的运行器代理。此环境变量必须是类型SECRETS_MANAGER，其值应是你在 Secrets Manager 中的密钥名称。所有 Buildkite 运行器项目都需要一个 Buildkite 代理令牌环境变量。

• CODEBUILD_CONFIG_BUILDKITE_CREDENTIAL_DISABLE: 默认情况下， CodeBuild会将账户或项目级别的源凭据加载到构建环境中，因为 Buildkite 代理使用这些凭据来提取作业的源存储库。要禁用此行为，您可以将此环境变量添加到项目中，并将该值设置为true，这样可以防止将源凭据加载到构建环境中。