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

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

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

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

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

Architecture

ECS Exec は、AWS Systems Manager (SSM) セッションマネージャーを使用して実行中のコンテナとの接続を確立し、AWS Identity and Access Management (IAM) ポリシーを使用して実行中のコンテナで実行中のコマンドへのアクセスを制御します。これは、必要な SSM エージェントバイナリをコンテナにバインドマウントすることによって実現されます。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は Linux コンテナでのみサポートされます。

  • ECS は現在、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 を参照してください。

  • 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 ロールを含める必要があります。詳細については、「IAM ポリシーの追加と削除」を参照してください。

タスク 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 を有効にしたら、次のコマンドを実行して、タスクが使用可能な状態であることを確認します。lastStatusExecuteCommandAgent プロパティが 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 は --configuration コマンドと create-cluster コマンドの両方に対して update-cluster フラグをサポートします。また、コマンドログを 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カスタマーマネージドキーを使用する必要があります。ロググループを暗号化する方法については、「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", "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 機能を使用するための前提条件を満たしていることを確認および検証できます。このツールには、AWS CLIの最新バージョンとjqが利用可能であることが必要です。詳細については、GitHub で「Amazon ECS Exec チェッカー」を参照してください。

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

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

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

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