使用会话管理器调试构建 - Amazon CodeBuild
先决条件暂停构建启动构建。连接到构建容器恢复构建
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

使用会话管理器调试构建

在中 Amazon CodeBuild，您可以暂停正在运行的构建，然后使用 Amazon Systems Manager 会话管理器连接到生成容器并查看容器的状态。

注意

此功能在 Windows 环境中不可用。

先决条件

要允许会话管理器与构建会话一起使用，必须为构建启用会话连接。有两个先决条件：

  • CodeBuild Linux 标准精选映像已经安装了 SSM 代理并启用了 SSM 代理。 ContainerMode

    如果您在针对构建使用自定义映像，请执行以下操作：

    1. 安装 SSM 代理 有关更多信息，请参阅《 Amazon Systems Manager 用户指南》中的在 Linux EC2 实例上手动安装 SSM 代理。SSM 代理必须是 3.0.1295.0 或更高版本。

    2. 将文件 https://github.com/aws/aws-codebuild-docker-images/blob/master/ubuntu/standard/5.0/amazon-ssm-agent.js on 复制到图像中的目录中。/etc/amazon/ssm/这将在 SSM 代理中启用容器模式。

    注意

    自定义映像需要最新的 SSM 代理才能使此功能按预期运行。

  • CodeBuild 服务角色必须具有以下 SSM 策略：

    {
   "Version": "2012-10-17", 
   "Statement": [
     {
       "Effect": "Allow",
       "Action": [
          "ssmmessages:CreateControlChannel",
          "ssmmessages:CreateDataChannel",
          "ssmmessages:OpenControlChannel",
          "ssmmessages:OpenDataChannel"
       ],
       "Resource": "*"
     }
   ]
}

    在开始构建时，您可以让 CodeBuild 控制台自动将此策略附加到您的服务角色。您也可以将此策略手动附加到您的服务角色。

  • 如果您在 Systems Manager 首选项中启用了 “审核和记录会话活动”，则 CodeBuild 服务角色还必须具有其他权限。权限会有所不同，具体取决于日志的存储位置。

    CloudWatch 日志

    如果使用 CloudWatch 日志存储日志，请向 CodeBuild 服务角色添加以下权限：

    {
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "logs:DescribeLogGroups",
      "Resource": "arn:aws:logs:<region-id>:<account-id>:log-group:*:*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "logs:CreateLogStream",
        "logs:PutLogEvents"
      ],
      "Resource": "arn:aws:logs:<region-id>:<account-id>:log-group:<log-group-name>:*"
    }
  ]
}
    Amazon S3

    如果使用 Amazon S3 存储您的日志，请向 CodeBuild 服务角色添加以下权限：

    {
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetEncryptionConfiguration",
        "s3:PutObject"
      ],
      "Resource": [
        "arn:aws:s3:::<bucket-name>",
        "arn:aws:s3:::<bucket-name>/*"
      ]
    }
  ]
}

    有关更多信息，请参阅《Amazon Systems Manager 用户指南》中的审核和记录会话活动。

暂停构建

要暂停构建，请在构建规范文件中的任意构建阶段插入 codebuild-breakpoint 命令。此时将暂停构建，这样您就可以连接到构建容器并查看当前状态下的容器。

例如，将以下内容添加到您的构建规范文件中的构建阶段。

phases:
  pre_build:
    commands:
      - echo Entered the pre_build phase...
      - echo "Hello World" > /tmp/hello-world
      - codebuild-breakpoint

此代码会创建 /tmp/hello-world 文件，然后在此时暂停构建。

启动构建。

要允许会话管理器与构建会话一起使用，必须为构建启用会话连接。为此，开始构建时，请按照以下步骤执行：

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

  2. 在导航窗格中，选择构建项目。选择构建项目，然后选择使用覆盖启动构建。

  3. 选择高级构建覆盖。

  4. 在环境部分中，选择启用会话连接选项。如果未选择此选项，则会忽略所有 codebuild-breakpoint 和 codebuild-resume 命令。

  5. 执行任何其他所需更改，然后选择启动构建。

  6. 在控制台中监控构建状态。当会话可用时，Amazon 会话管理器链接将显示在构建状态部分中。

连接到构建容器

您可以通过以下两种方式之一连接到构建容器：

CodeBuild 控制台

在 Web 浏览器中，打开 Amazon 会话管理器链接以连接到构建容器。将打开一个终端会话，允许您浏览和控制构建容器。

Amazon CLI
注意

您的本地计算机必须安装会话管理器插件才能执行此过程。有关更多信息，请参阅《 Amazon Systems Manager 用户指南》中的 “安装适用于 Amazon CLI 的会话管理器插件”。

  1. 使用构建 ID 调用 batch-get-builds api 以获取有关构建的信息，包括会话目标标识符。会话目标标识符属性名称因 aws 命令的输出类型而异。这就是为什么要将 --output json 添加到命令中。

    aws codebuild batch-get-builds --ids <buildID> --region <region> --output json

  2. 复制 sessionTarget 属性值。sessionTarget 属性名称会因 aws 命令的输出类型而异。这就是在上一步骤中将 --output json 添加到命令中的原因。

  3. 使用以下命令连接到构建容器。

    aws ssm start-session --target <sessionTarget> --region <region>

在此示例中，请验证 /tmp/hello-world 文件是否存在且包含文本 Hello World。

恢复构建

完成对构建容器的检查后，从容器 shell 中发出 codebuild-resume 命令。

$ codebuild-resume