翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

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

ビルドセッションでセッションマネージャーを使用できるようにするには、ビルドのセッション接続を有効にする必要があります。次の 2 つの前提条件があります。
+ CodeBuild Linux 標準キュレーションイメージには、すでに SSM エージェントがインストールされており、SSM エージェント コンテナモードが有効になっています。

  ビルドにカスタムイメージを使用している場合は、次の操作を行います。

  1. SSM Agent をインストールします。詳細については、 AWS Systems Manager ユーザーガイドの「[Linux 用 EC2 インスタンスに SSM Agent を手動でインストールする](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.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>

ビルドセッションでセッションマネージャーを使用できるようにするには、ビルドのセッション接続を有効にする必要があります。これを行うには、ビルドを開始するときに、以下の手順を実行します。

1. [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home) で AWS CodeBuild コンソールを開きます。

1. ナビゲーションペインで、**[ビルドプロジェクト]** を選択します。ビルドプロジェクトを選択した後、[**Start build with overrides**] を選択します。

1. [**Advanced build overrides (高度なビルドの上書き)**] を選択します。

1. [**Environment**] セクションで、[**Enable session connection**] オプションを選択します。このオプションが選択されていない場合、**codebuild-breakpoint** および **codebuild-resume** コマンドは無視されます。

1. その他の必要な変更を行い、[**Start build**] を選択します。

1. コンソールでビルドステータスを監視します。セッションが利用可能になると、**AWS セッションマネージャー**リンクが [**Build status**] セクションに表示されます。

## ビルドコンテナに接続する
<a name="ssm-connect"></a>

ビルドコンテナには、次の 2 つのいずれかに接続できます。

CodeBuild コンソール  
ウェブブラウザで、**AWS セッションマネージャー**リンクをクリックして、ビルドコンテナに接続します。ターミナルセッションが開き、ビルドコンテナを表示して制御できます。

AWS CLI  
この手順を実行するには、ローカルマシンにセッションマネージャプラグインがインストールされている必要があります。詳細については、「 AWS Systems Manager ユーザーガイド[」の「 CLI AWS 用の Session Manager プラグインのインストール](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html)」を参照してください。

1. **batch-get-builds** APIを呼び出し、ビルドIDに置き換えて、セッションターゲット識別子を含むビルドに関する情報を取得します。セッションターゲット識別子のプロパティ名は、`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>

ビルドコンテナーを調べ終わったら、**codebuild-resume** コマンドをコンテナーシェルから実行します。

```
$ codebuild-resume
```