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

# 使用会话管理器调试构建
<a name="session-manager"></a>

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

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

**Topics**
+ [

## 先决条件
](#ssm.prerequisites)
+ [

## 暂停构建
](#ssm-pause-build)
+ [

## 启动构建。
](#ssm-start-build)
+ [

## 连接到构建容器
](#ssm-connect)
+ [

## 恢复构建
](#ssm-resume-build)

## 先决条件
<a name="ssm.prerequisites"></a>

要允许会话管理器与构建会话一起使用，必须为构建启用会话连接。有两个先决条件：
+ CodeBuild Linux 标准精选映像已经安装了 SSM 代理并启用了 SSM 代理。 ContainerMode 

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

  1. 安装 SSM 代理 有关更多信息，请参阅《 AWS Systems Manager 用户指南》中的[在 Linux EC2 实例上手动安装 SSM 代理](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-manual-agent-install.html)。SSM 代理必须是 3.0.1295.0 或更高版本。

  1. 将文件 [https://github.com/aws/aws-codebuild-docker-images/blob/master/ubuntu/standard/5.0/amazon-ssm-agent.js](https://github.com/aws/aws-codebuild-docker-images/blob/master/ubuntu/standard/5.0/amazon-ssm-agent.json) on 复制到图像中的目录中。`/etc/amazon/ssm/`这将在 SSM 代理中启用容器模式。
**注意**  
自定义映像需要最新的 SSM 代理才能使此功能按预期运行。
+  CodeBuild 服务角色必须具有以下 SSM 策略：

------
#### [ JSON ]

****  

  ```
  {
     "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:us-east-1:111122223333:log-group:*:*"
          },
          {
              "Effect": "Allow",
              "Action": [
                  "logs:CreateLogStream",
                  "logs:PutLogEvents"
              ],
              "Resource": "arn:aws:logs:us-east-1:111122223333:log-group:MyLogGroup:*"
          }
      ]
  }
  ```  
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>/*"
        ]
      }
    ]
  }
  ```

  有关更多信息，请参阅《AWS Systems Manager 用户指南》**中的[审核和记录会话活动](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-logging-auditing.html)。

## 暂停构建
<a name="ssm-pause-build"></a>

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

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

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

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

## 启动构建。
<a name="ssm-start-build"></a>

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

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

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

1. 选择**高级构建覆盖**。

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

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

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

## 连接到构建容器
<a name="ssm-connect"></a>

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

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

AWS CLI  
您的本地计算机必须安装会话管理器插件才能执行此过程。有关更多信息，请参阅《 AWS Systems Manager 用户指南[》中的 “安装适用于 AWS CLI 的会话管理器插件](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html)”。

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

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

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

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

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

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

## 恢复构建
<a name="ssm-resume-build"></a>

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

```
$ codebuild-resume
```