デバッグ用にAmazon ECS Exec を使用

Amazon ECS Exec を使用すれば、最初にホストコンテナのオペレーティングシステムとやり取りしたり、インバウンドポートを開いたり、SSH キーを管理したりすることなく、コンテナと直接やり取りできます。ECS Exec を使用して、Amazon EC2 インスタンスまたは AWS Fargate で実行されているコンテナでコマンドを実行したり、シェルを取得したりできます。これにより、診断情報を収集し、エラーを迅速にトラブルシューティングすることが容易になります。たとえば、開発コンテキストでは、ECS を使用して、コンテナ内のさまざまなプロセスと簡単にやり取りし、アプリケーションのトラブルシューティングを行うことができます。また、実稼働シナリオでは、これを使用して、コンテナへのブレークグラスアクセスを行って問題をデバッグできます。

Amazon ECS API、AWS Command Line Interface (AWS CLI)、AWS、SDK、または AWS Copilot CLI から ECS Exec を使用して、実行中の Linux または Windows コンテナでコマンドを実行できます。ECS Exec の使用方法と AWS コパイロットCLI を使用した動画チュートリアルの詳細については、コパイロット Github のドキュメントを参照してください。

ECS Exec を使用すれば、より厳格なアクセスコントロールポリシーを維持し、コンテナアクセスを監査することもできます。この機能を選択的に有効にすることで、コマンドを実行できるユーザーと、それらのコマンドを実行できるタスクを制御できます。各コマンドとその出力のログを使用して、ECS Exec を使って実行されたタスクを監査したり、CloudTrail を使ってコンテナにアクセスしたユーザーを監査したりできます。

アーキテクチャ

ECS Exec は、AWS Systems Manager (SSM) セッションマネージャーを使用して実行中のコンテナとの接続を確立し、AWS Identity and Access Management (IAM) ポリシーを使用して実行中のコンテナで実行中のコマンドへのアクセスを制御します。これは、必要な SSM Agent バイナリをコンテナにバインドマウントすることによって実現されます。Amazon ECS または AWS Fargate エージェントは、アプリケーションコードと一緒にコンテナ内で SSM コアエージェントをスタートする責任があります。詳細については、 Systems Manager のセッションマネージャーを参照してください。

AWS CloudTrail を使用してコンテナにアクセスしたユーザーを監査し、各コマンド (およびその出力) を Amazon S3 または Amazon CloudWatch Logs に記録できます。独自の暗号化キーを使用してローカルクライアントとコンテナ間のデータを暗号化するには、AWS Key Management Service (AWS KMS) キーを指定する必要があります。

ECS Exec を使用するための考慮事項

このトピックでは、ECS Exec の使用に関する次の側面に精通している必要があります:

• ECS Exec は、次のインフラストラクチャで実行されるタスクでサポートされています。

  • Amazon EC2 上の Linux コンテナを任意の Amazon ECS に最適化された AMI（Bottlerocketを含む）

  • 外部インスタンス（ECS Anywhere）上の Linux および Windows コンテナ

  • AWS Fargate 上の Linux および Windows コンテナ

  • 次の Windows Amazon ECS に最適化された AMI 上のAmazon EC2 上の Windows コンテナ（コンテナエージェントバージョン 1.56 以降を使用）：

    • Amazon ECS に最適化された Windows Server 2022 Full AMI

    • Amazon ECS に最適化された Windows Server 2022 Core AMI

    • Amazon ECS に最適化された Windows Server 2019 Full AMI

    • Amazon ECS に最適化された Windows Server 2019 Core AMI

    • Amazon ECS に最適化された Windows Server 20H2 Core AMI

• ECS は現在、AWS Management Console を使用してサポートされていません。

• ECS Exec は現在、Auto Scaling グループのキャパシティープロバイダーを使用して起動されたタスクに対応していません。

• Amazon ECS にインターフェイス Amazon VPC エンドポイントを使用している場合、Systems Manager セッションマネージャーのインターフェイス Amazon VPC エンドポイントを作成する必要があります。Systems Manager Session Manager VPC エンドポイントの詳細については、AWS Systems Manager ユーザーガイドのSession Manager に VPC エンドポイントを設定するためにAWS PrivateLinkを使用するを参照してください。

• Amazon ECS にインターフェイス Amazon VPC エンドポイントを使用していて、暗号化に AWS KMS key を使用している場合には、AWS KMS key 用のインターフェイス Amazon VPC エンドポイントも作成する必要があります。詳細については、 「AWS Key Management Service デベロッパーガイド」の「VPC エンドポイントを介した AWS KMS key への接続」を参照してください。

• 既存のタスクに対して ECS Exec をオンにすることはできません。新しいタスクに対してのみオンにできます。

• ユーザーが ECS Exec を使用してコンテナ上でコマンドを実行すると、これらのコマンドは root ユーザーとして実行されます。コンテナにユーザー ID を指定しても、SSM エージェントとその子プロセスは root として実行されます。

• ECS Exec セッションのアイドルタイムアウト時間は 20 分です。この値は変更できません。

• SSM エージェントは、必要なディレクトリやファイルを作成するために、コンテナのファイルシステムに書き込みができる必要があります。したがって、readonlyRootFilesystemタスク定義パラメータ、またはその他の方法を使ってルートファイルシステムを読み取り専用にすることは、サポートされません。

• ユーザーは、コンテナコンテキスト内で使用可能なすべてのコマンドを実行できます。一部の操作 (コンテナのメインプロセスの終了、コマンドエージェントの終了、依存関係の削除) によって、孤立プロセスとゾンビプロセスが発生する可能性があります。ゾンビプロセスをクリーンアップするには、タスク定義に initProcessEnabled フラグを追加することをお勧めします。

• execute-commandアクション外部の SSM セッションを開始することは可能ですが、これにより、セッションはログに記録されず、セッション制限に対してカウントされません。IAM ポリシーを使用した ssm:start-session操作を拒否して、このアクセスを制限することをお勧めします。詳細については、「[Start Session (セッション開始)] 操作へのアクセス制限」を参照してください。

• ECS Exec は一部の CPU とメモリを使用します。タスク定義で CPU とメモリリソースの割り当てを指定する場合は、この点を考慮する必要があります。

• AWS CLI バージョン 1.22.3 以降、または AWS CLI バージョン 2.3.6 以降を使用する必要があります。AWS CLI をアップデートする情報については、AWS Command Line Interface ユーザーガイドバージョン 2 の「AWS CLI の最新バージョンのインストールまたはアップデート」を参照してください。

• run-task を使用して非同期配置 (インスタンスなしでタスクを起動) でマネージドスケーリングを使用するクラスターでタスクを起動する場合、ECS Exec を使用できません。

• Microsoft Nano Server コンテナに対して ECS Exec を実行することはできません。Nano Server コンテナの詳細については、Docker ウェブサイトの「Nano Server」を参照してください。

ECS Exec を使用するための前提条件

ECS Exec の使用を開始する前に、次の操作が完了していることを確認してください。

• AWS CLI をインストールして設定します。詳細については、「AWS CLI」を参照してください。

• AWS CLI のセッションマネージャープラグインをインストールします。詳細については、に セッション マネージャー プラグインのインストールAWS CLI を参照してください。

• ECS Exec には、タスクが Amazon EC2 でホストされているか AWS Fargate でホストされているかに応じて、バージョン要件があります:

  • Amazon EC2 を使用している場合は、2021 年 1 月 20 日以降にリリースされた Amazon ECS 最適化 AMI を、エージェントバージョン 1.50.2 以上で使用する必要があります。詳細については、Amazon ECS 最適化 AMI を参照してください。

  • AWS Fargate を使用している場合、プラットフォームバージョン 1.4.0 以上 (Linux) または 1.0.0 (Windows) を使用する必要があります。詳細については、の「AWS Fargateプラットフォームバージョン」を参照してください。

ECS Exec の使用

ECS Exec に必要な IAM アクセス許可

ECS Exec 機能には、マネージド型 SSM エージェント (execute-command エージェント) と SSM サービス間の通信に必要なアクセス許可をコンテナに付与するためのタスク IAM ロール ロールが必要です。詳細については、「Amazon ECS タスクの IAM ロール」を参照してください。次のアクセス許可をタスク IAM ロールに追加し、タスク定義にタスク IAM ロールを含める必要があります。詳細については、「IAM ポリシーの追加と削除」を参照してください。

タスク IAM ロールに次のポリシーを使用して、必要な SSM アクセス許可を追加します。タスク IAM ロールの詳細については、「タスク IAM ロール」を参照してください。

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

オプションのタスク定義の変更

タスク定義パラメーター initProcessEnabled を true に設定すると、コンテナ内で init プロセスが開始され、見つかったゾンビ SSM Agent の子プロセスがすべて削除されます。以下に例を示します。

{
    "taskRoleArn": "ecsTaskRole",
    "networkMode": "awsvpc",
    "requiresCompatibilities": [
        "EC2",
        "FARGATE"
    ],
    "executionRoleArn": "ecsTaskExecutionRole",
    "memory": ".5 gb",
    "cpu": ".25 vcpu",
    "containerDefinitions": [
        {
            "name": "amazon-linux",
            "image": "amazonlinux:latest",
            "essential": true,
            "command": ["sleep","3600"],
            "linuxParameters": {
                "initProcessEnabled": true
            }
        }
    ],
    "family": "ecs-exec-task"
}

タスクとサービスに対する ECS Exec をオンにする

次の AWS CLI コマンド:(create-service、update-service、start-task、または run-task) のいずれかを使用するときに、--enable-execute-command フラグを指定することにより、サービスおよびスタンドアロンタスクの ECS Exec 機能をオンにすることができます。

例えば、次のコマンドを実行すると、ECS Exec 機能が新しく作成されたサービスに対してオンになります。サービス作成の詳細については、create-service を参照してください。

aws ecs create-service \
    --cluster cluster-name \
    --task-definition task-definition-name \
    --enable-execute-command \
    --service-name service-name \
    --desired-count 1

タスクに対して ECS Exec をオンにしたら、次のコマンドを実行して、タスクが使用可能な状態であることを確認できます。ExecuteCommandAgent の lastStatus プロパティが RUNNING として表示され、enableExecuteCommand プロパティが true に設定されている場合、タスクの準備が整います。

aws ecs describe-tasks \
    --cluster cluster-name \
    --tasks task-id

以下の出力スニペットは、表示される可能性があるものの例です。

{
    "tasks": [
        {
            ...
            "containers": [
                {
                    ...
                    "managedAgents": [
                        {
                            "lastStartedAt": "2021-03-01T14:49:44.574000-06:00",
                            "name": "ExecuteCommandAgent",
                            "lastStatus": "RUNNING"
                        }
                    ]
                }
            ],
            ...
            "enableExecuteCommand": true,
            ...
        }
    ]
}

ECS Exec を使用してコマンド実行

ExecuteCommandAgent が実行されていることを確認したら、以下のコマンドを使用してコンテナ上でインタラクティブシェルを開くことができます。タスクに複数のコンテナが含まれている場合は、--containerフラグを使うコンテナ名を指定する必要があります。Amazon ECS はインタラクティブセッションの開始のみをサポートするため、--interactiveフラグを使用する必要があります。

次のコマンドでは、task-idのidを使ったタスクで、コンテナ名という名前のコンテナに対して、インタラクティブな /bin/sh コマンドを実行します。

aws ecs execute-command --cluster cluster-name \
    --task task-id \
    --container container-name \
    --interactive \
    --command "/bin/sh"

ECS Exec を使用するログ記録と監査

タスクとサービスでのログと監査をオンにする

Amazon ECS は、タスク定義で構成されている awslogs ログドライバーを使用してログを CloudWatch Logs に送信することにより、ECS Exec を使用して実行されるログコマンドのデフォルト設定を提供します。カスタム構成を提供する場合、AWS CLI は create-cluster コマンドと update-cluster コマンドの両方に対して --configuration フラグをサポートします。また、コマンドログを Amazon S3 または CloudWatch Logs に正しくアップロードするには、コンテナイメージで script と cat をインストールする必要があるため、ご注意ください。クラスター作成の詳細については、create-cluster を参照してください。

注記

この設定では、execute-command セッションのログ記録のみを処理します。アプリケーションのログには影響しません。

以下の例では、サービスを作成し、出力を cloudwatch-log-group-name という名前の CloudWatch Logs LogGroup と s3-bucket-name という名前の Amazon S3 バケットに記録します。

CloudWatchEncryptionEnabledオプションをtrueに設定した場合、ロググループの暗号化にAWS KMSカスタマーマネージドキーを使用する必要があります。ロググループを暗号化する方法については、「Amazon CloudWatch Logsユーザーガイド」のAWS Key Management Serviceを使用してCloudWatch Logsのログデータを暗号化するを参照してください。

aws ecs create-cluster \
    --cluster-name cluster-name \
    --configuration executeCommandConfiguration="{ \
        kmsKeyId=string, \
        logging=OVERRIDE, \
        logConfiguration={ \
            cloudWatchLogGroupName=cloudwatch-log-group-name, \
            cloudWatchEncryptionEnabled=true, \
            s3BucketName=s3-bucket-name, \
            s3EncryptionEnabled=true, \
            s3KeyPrefix=demo \
        } \
    }"

logging プロパティにより、ECS Exec のログ機能の動作が決まります:

• NONE: ログ記録はオフ状態です

• DEFAULT: ログは構成済みの awslogs ドライバーに送信されます (ドライバーが構成されていない場合、ログは保存されません)

• OVERRIDE:ログは、提供された Amazon CloudWatch Logs LogGroup、Amazon S3 バケット、またはその両方に送信されます。

Amazon CloudWatch Logs または Amazon S3 ロギングに必要な IAM アクセス許可

ログ記録を有効にするには、 タスク定義で参照されるAmazon ECSタスクロールに追加のアクセス許可が必要です。これらの追加アクセス許可は、ポリシーとしてタスクロールに追加することが可能です。ログを Amazon CloudWatch Logs または Amazon S3 のどちらに送信するかによって異なります。

Amazon CloudWatch Logs

次のポリシー例では、Amazon CloudWatch Logs について必須のアクセス許可を追加しています。

{
   "Version": "2012-10-17",
   "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "logs:DescribeLogGroups"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
               "logs:CreateLogStream",
               "logs:DescribeLogStreams",
               "logs:PutLogEvents"
            ],
            "Resource": "arn:aws:logs:region:account-id:log-group:/aws/ecs/cloudwatch-log-group-name:*"
        }
   ]
}

Amazon S3

次のインラインポリシー例では、Amazon S3 について必須のアクセス許可を追加しています。

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

独自のAWS KMS key (KMS キー ) を使用した暗号化に必要な IAM アクセス許可

デフォルトでは、ローカルクライアントとコンテナ間で転送されるデータは、AWS が提供する TLS 1.2 暗号化を使用します。独自の KMS キー を使用してデータをさらに暗号化するには、KMS キー を作成し、タスク IAM ロールに kms:Decrypt アクセス権限を追加する必要があります。このアクセス許可は、データを復号化するためにコンテナによって使用されます。KMS キーの 作成の詳細については、キーを作成する を参照してください。

AWS KMS アクセス許可を必要とするタスク IAM ロールに次のインリングポリシーを追加します。詳細については、「ECS Exec に必要な IAM アクセス許可」を参照してください。

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "kms:Decrypt"
            ],
            "Resource": "kms-key-arn"
        }
    ]
}

独自の KMS キー を使用してデータを暗号化するには、execute-command アクションを使用するユーザーまたはグループに kms:GenerateDataKey アクセス許可が付与されている必要があります。

以下のユーザーまたはグループのポリシー例では、独自の KMS キー を使用するために必要なアクセス許可が含まれています。KMS キーのAmazon リソースネーム (ARN) を指定する必要があります。

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "kms:GenerateDataKey"
            ],
            "Resource": "kms-key-arn"
        }
    ]
}

IAM ポリシーを使用して ECS Exec へのアクセスを制限する

次の IAM ポリシー条件キーの 1 つ以上を使用して、execute-command API アクションへのユーザーアクセスを制限できます。

• aws:ResourceTag/clusterTagKey

• ecs:ResourceTag/clusterTagKey

• aws:ResourceTag/taskTagKey

• ecs:ResourceTag/taskTagKey

• ecs:container-name

• ecs:cluster

• ecs:task

• ecs:enable-execute-command

以下の IAM ポリシーの例では、ユーザーは environment キーと development 値を持つタグのあるタスク内で実行されているコンテナと、cluster-nameという名前のクラスターでコマンドを実行できます。

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ecs:ExecuteCommand",
                "ecs:DescribeTasks"
            ],
            "Resource": "arn:aws:ecs:region:aws-account-id:task/cluster-name/*",
            "Condition": {
                "StringEquals": {
                    "ecs:ResourceTag/environment": "development"
                }
            }
        }
    ]
}

次の IAM ポリシーの例では、コンテナ名が production-app の場合、ユーザーは execute-command API を使用できません。

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Deny",
            "Action": [
                "ecs:ExecuteCommand"
            ],
            "Resource": "*",
            "Condition": {
                "StringEquals": {                    
                    "ecs:container-name": "production-app"
                }
            }
        }
    ]
}

次の IAM ポリシーを使用するユーザーは、ECS Exec がオフ状態の場合にのみタスクを起動できます。

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ecs:RunTask",
                "ecs:StartTask",
                "ecs:CreateService",
                "ecs:UpdateService"
            ],
            "Resource": "*",
            "Condition": {
                "StringEquals": {                    
                    "ecs:enable-execute-command": "false"
                }
            }
        }
    ]
}

注記

execute-command API 操作には、リクエスト内のタスクとクラスターリソースのみが含まれるため、クラスタータグとタスクタグのみが評価されます。

IAM ポリシー条件キーの詳細については、「サービス認証リファレンス」の「Amazon Elastic コンテナサービス のアクション、リソース、および条件キー」を参照してください。

[Start Session (セッション開始)] 操作へのアクセス制限

ECS Exec の外部コンテナで SSM セッションを開始することは可能ですが、セッションがログに記録されない可能性があります。ECS Exec 以外で開始されたセッションも、セッションクォータに対してカウントされません。IAM ポリシーを使用して Amazon ECS タスクに対する ssm:start-session アクションを直接拒否することで、このアクセスを制限することをお勧めします。使用されているタグに基づいて、すべての Amazon ECS タスクまたは特定のタスクへのアクセスを拒否できます。

以下は、指定されたクラスター名を持つすべてのリージョンのタスクに対する ssm:start-sessionアクション へのアクセスを拒否する IAM ポリシーの例です。オプションで、cluster-name にワイルドカードを含めることができます。

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Deny",
            "Action": "ssm:StartSession",
            "Resource": "arn:aws:ecs:*:111122223333:task/cluster-name/*"
        }
    ]
}

以下は、タグキー Task-Tag-Key とタグ値 Exec-Task でタグ付けされたすべてのリージョンのリソースに対する ssm:start-session アクションへのアクセスを拒否する IAM ポリシーの例です。

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Deny",
            "Action": "ssm:StartSession",
            "Resource": "*",
            "Condition": {
                "StringEquals": {
                    "aws:ResourceTag/Task-Tag-Key": "Exec-Task"
                }
            }
        }
    ]
}

ECS Exec に関する問題のトラブルシューティング

ECS Exec の使用時にエラーが発生する理由を診断するトラブルシューティングに関する注意事項を以下に示します。

Amazon ECS Execチェッカーを使用して検証する

Amazon ECS Exec チェッカー スクリプトを使用すると、Amazon ECS クラスターとタスクが ECS Exec 機能を使用するための前提条件を満たしていることを確認および検証できます。Exec チェッカースクリプトは、AWS CLI 環境およびクラスターを両方認証して、お客様に代わってさまざまな API を呼び出して ECS Exec のタスクの準備が整います。このツールには、AWS CLIの最新バージョンとjqが利用可能であることが必要です。詳細については、GitHub で「Amazon ECS Exec チェッカー」を参照してください。

execute-command 呼び出し時のエラー

The execute command failed エラーが発生した場合は、以下の原因が考えられます。

• タスクに必要なアクセス許可がありません。タスクの起動に使用されるタスク定義にタスク IAM のロールが定義されていること、およびロールに必要なアクセス許可があることを確認します。詳細については、「ECS Exec に必要な IAM アクセス許可」を参照してください。

• SSM エージェントがインストールまたは実行されていません

• Amazon ECS のインターフェイス Amazon VPC エンドポイントがありますが、システムマネージャーセッションマネージャー用のものはありません