デバッグに Amazon ECS Exec を使用する - Amazon Elastic Container Service

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

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

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

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

アーキテクチャー

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

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

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

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

  • ECS Exec は Linux コンテナのためにのみサポートされています。

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

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

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

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

  • ECS Exec セッションのデフォルトのアイドルタイムアウト時間は 20 分です。詳細については、AWS Systems Manager ユーザーガイドアイドルセッションのタイムアウト値を指定しますを参照してください。

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

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

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

  • ECS Exec は一部の CPU とメモリを使用します。タスク定義で CPU とメモリリソースの割り当てを指定するときは、それに対応する必要があります。

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

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

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

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

  • 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 以上を使用する必要があります。詳細については、「AWS Fargate プラットフォームのバージョン」を参照してください。

ECS Exec の有効化と使用

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

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

タスク IAM ロールに次のポリシーを使用して、必要な SSM アクセス許可を追加します。

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

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

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

{ "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-serviceupdate-servicestart-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 を有効にしたら、次のコマンドを実行して、タスクが使用可能な状態であることを確認します。ExecuteCommandAgentlastStatus プロパティが 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 フラグを使用する必要があります。

次のコマンドでは、ID が task-id のタスクで、container-name という名前のコンテナに対してインタラクティブな /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 に正しくアップロードするには、コンテナイメージで scriptcat をインストールする必要があるため、ご注意ください。クラスター作成の詳細については、create-cluster を参照してください。

注記

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

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

CloudWatchEncryptionEnabled オプションを true に設定するときは、AWS KMS customer managed key を使用してロググループを暗号化する必要があります。ロググループを暗号化する方法については、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 key) を使用した暗号化に必要な IAM 許可

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

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

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

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

以下のユーザーまたはグループのポリシー例では、独自の KMS key を使用するために必要な許可が含まれています。KMS key の 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", "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 Container Service のアクション、リソース、および条件キーを参照してください。

[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 Checker を使用した確認

Amazon ECS Exec Checker スクリプトにより、Amazon ECS クラスターとタスクが ECS Exec 機能を使用するための前提条件を満たしていることを確認および検証できます。このツールを使用するには、AWS CLI の最新バージョンが必要であり、jq が使用可能であることが必要です。詳細については、GitHub の Amazon ECS Exec Checker を参照してください。

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

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

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

  • 速度が遅いか、ネットワークレイテンシーが生じたため、SSM エージェントが接続されていません。しばらく待ってから execute-command 操作を再試行してください。