本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 使用 Session Manager 偵錯組建
<a name="session-manager"></a>

在 中 AWS CodeBuild，您可以暫停執行中的組建，然後使用 AWS Systems Manager Session Manager 連線到組建容器，並檢視容器的狀態。

**注意**  
此功能不適用於 Windows 環境。

**Topics**
+ [

## 先決條件
](#ssm.prerequisites)
+ [

## 暫停建置
](#ssm-pause-build)
+ [

## 啟動建置
](#ssm-start-build)
+ [

## 連線至建置容器
](#ssm-connect)
+ [

## 繼續建置
](#ssm-resume-build)

## 先決條件
<a name="ssm.prerequisites"></a>

若要允許 Session Manager 與建置工作階段搭配使用，您必須啟用建置的工作階段連線。有兩個先決條件：
+ CodeBuild Linux 標準精選映像已安裝 SSM 代理程式並啟用 SSM 代理程式 ContainerMode。

  如果您使用建置的自訂映像，請執行下列動作：

  1. 安裝 SSM Agent。如需詳細資訊，請參閱 AWS Systems Manager 《 使用者指南》中的在 [Linux 的 EC2 執行個體上手動安裝 SSM 代理](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-manual-agent-install.html)程式。SSM Agent 版本必須為 3.0.1295.0 或更新版本。

  1. 將檔案 [https://github.com/aws/aws-codebuild-docker-images/blob/master/ubuntu/standard/5.0/amazon-ssm-agent.json](https://github.com/aws/aws-codebuild-docker-images/blob/master/ubuntu/standard/5.0/amazon-ssm-agent.json) 複製到映像中的 `/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 Logs  
如果使用 CloudWatch Logs 存放日誌，請將下列許可新增至 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>

若要暫停建置，請在 buildspec 檔案中的任何建置階段插入 **codebuild-breakpoint**命令。建置將在此時暫停，這可讓您連線至建置容器，並檢視其目前狀態的容器。

例如，將下列項目新增至 buildspec 檔案中的建置階段。

```
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>

若要允許 Session Manager 與建置工作階段搭配使用，您必須啟用建置的工作階段連線。若要這樣做，在開始建置時，請依照下列步驟執行：

1. 在 https：//[https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home) 開啟 AWS CodeBuild 主控台。

1. 在導覽窗格中，選擇 **Build projects (建置專案)**。選擇建置專案，然後選擇**使用覆寫開始建置**。

1. 選擇 **Advanced build overrides (進階組建覆寫)**。

1. 在**環境**區段中，選擇**啟用工作階段連線**選項。如果未選取此選項，則會忽略所有 **codebuild-breakpoint**和 **codebuild-resume**命令。

1. 進行任何其他所需的變更，然後選擇**開始建置**。

1. 在 主控台中監控建置狀態。當工作階段可用時，**AWS 工作階段管理員**連結會出現在**建置狀態**區段中。

## 連線至建置容器
<a name="ssm-connect"></a>

您可以透過下列兩種方式之一連線到建置容器：

CodeBuild 主控台  
在 Web 瀏覽器中，開啟 **AWS Session Manager** 連結以連線至建置容器。終端機工作階段隨即開啟，可讓您瀏覽和控制建置容器。

AWS CLI  
您的本機電腦必須安裝此程序的 Session Manager 外掛程式。如需詳細資訊，請參閱 AWS Systems Manager 《 使用者指南》中的[安裝 CLI AWS 的 Session Manager 外掛程式](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
```