セッションマネージャーで実行中のビルドを表示する - AWS CodeBuild
前提条件ビルドの一時停止ビルドを開始しますビルドコンテナに接続するビルドを再開する

セッションマネージャーで実行中のビルドを表示する

AWS CodeBuild では、実行中のビルドを一時停止し、AWS Systems Manager Session Manager を使用してビルドコンテナに接続して、コンテナの状態を表示できます。

注記

この機能は、Windows 環境では使用できません。

前提条件

ビルドセッションでセッションマネージャーを使用できるようにするには、ビルドのセッション接続を有効にする必要があります。次の 2 つの前提条件があります。

  • CodeBuild Linux 標準キュレーションイメージには、すでに SSM エージェントがインストールされており、SSM エージェント コンテナモードが有効になっています。

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

    1. SSM Agent をインストールします。詳細については、AWS Systems Manager ユーザーガイドの「Linux 用 EC2 インスタンスに SSM Agent を手動でインストールする」を参照してください。SSM Agent は、バージョン 3.0.1295.0 以降である必要があります。

    2. ファイルをコピーする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 ポリシーが必要です。

    {
  "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:<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>/*"
      ]
    }
  ]
}

    詳細については、AWS Systems Manager ユーザーガイドの「セッションアクティビティのログ記録と監査」を参照してください。

ビルドの一時停止

ビルドを一時停止するには、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ファイルを作成し、この時点でビルドを一時停止します。

ビルドを開始します

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

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

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

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

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

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

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

ビルドコンテナに接続する

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

CodeBuild コンソール

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

AWS CLI
注記

この手順を実行するには、ローカルマシンにセッションマネージャプラグインがインストールされている必要があります。詳細については、AWS Systems Manager ユーザーガイドの「AWS CLI 用の Session Manager プラグインをインストールする」を参照してください。

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

ビルドを再開する

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

$ codebuild-resume