ECS Execの使い方｜Fargateのコンテナに入る設定と失敗の原因

ECS Exec は、Fargate や EC2 で動いている ECS タスクのコンテナに、SSH なしでシェルを開く機能です。 仕組みは Systems Manager の Session Manager で、ECS（Fargate）のエージェントがコンテナの中で SSM エージェントを動かし、手元の AWS CLI と Session Manager プラグインがそこへつなぎます。

aws ecs execute-command \
  --cluster app \
  --task 0123456789abcdef0123456789abcdef \
  --container app \
  --interactive \
  --command "/bin/sh"

使えるようにするには、次の4つがそろっている必要があります。

確認環境：AWS CLI 1.46.1・Python 3.11（Linux）。amazon-ecs-exec-checker v0.7（GitHub の最新コミット）を、moto 5.2.4 のサーバーモードに作ったクラスター・タスク定義・タスク・IAM ロール・VPC エンドポイントに向けて動かし、出力を確かめました。moto が返さない項目（enableExecuteCommand・managedAgents など）と、moto に無い iam simulate-principal-policy は、実際の API の形に合わせて応答を補うラッパーを用意しています。aws ecs execute-command は、ExecuteCommand・DescribeTasks を返す擬似のエンドポイントと、引数を表示する擬似のプラグインで、CLI がプラグインへ渡す中身を確かめました。前提・権限・エラーの意味・制限は Amazon ECS のドキュメントと API リファレンスで確認しています（確認日 2026年10月13日）。

仕組み：execute-command で何が起きるか

AWS CLI のソース（awscli/customizations/ecs/executecommand.py）と、手元で動かした結果から分かる流れです。

1. CLI が引数なしで session-manager-plugin を起動し、入っているか確かめる（無ければここで終わる）
2. ECS の ExecuteCommand API を呼ぶ。ECS が SSM のセッションを作り、session（sessionId・streamUrl・tokenValue）を返す
3. DescribeTasks でコンテナの runtimeId を取る
4. プラグインに次の6つを渡して起動し、プラグインが streamUrl（WebSocket）につなぐ

擬似のプラグインで受け取った引数です（session の値は擬似エンドポイントが返したもの）。

ARG[0]: {"sessionId": "ecs-execute-command-0a1b2c3d4e5f67890", "streamUrl": "wss://ssmmessages.ap-northeast-1.amazonaws.com/v1/data-channel/...", "tokenValue": "..."}
ARG[1]: ap-northeast-1
ARG[2]: StartSession
ARG[3]:                      ← プロファイル名（未指定なら空）
ARG[4]: {"Target": "ecs:app_0123456789abcdef0123456789abcdef_0123456789abcdef0123456789abcdef-1234567890"}
ARG[5]: http://127.0.0.1:5140   ← ECS のエンドポイント

ターゲットは ecs:クラスター名_タスクID_コンテナのruntimeId です。手元の PC も ssmmessages に WebSocket でつなぐため、社内プロキシで WebSocket が止められていると、API の呼び出しは成功してもシェルが開きません。

--interactive を付けないと、CLI が Missing required parameter in input: "interactive" で止まりました。ドキュメントでは、ECS は対話型のセッションだけに対応していて、interactive は true を指定するとされています。

設定①：タスクロールの権限

ECS Exec の権限は「タスクロール」に付けます。 イメージの取得やログの送信に使う「タスク実行ロール」ではありません。

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

aws iam put-role-policy --role-name app-task-role \
  --policy-name ecs-exec --policy-document file://ecs-exec.json

コマンドの記録（後述）を CloudWatch Logs や S3 に送るなら、タスクロールにその権限も足します。

EC2 起動タイプでタスクロールが無いときは、インスタンスのロールが使われます。タスクロールの役割の違いは、関連記事「ECSタスク定義JSONの書き方｜Fargate必須項目と環境変数secrets」で扱っています。

設定②：タスク定義

{
  "family": "app",
  "requiresCompatibilities": ["FARGATE"],
  "networkMode": "awsvpc",
  "cpu": "256",
  "memory": "512",
  "taskRoleArn": "arn:aws:iam::123456789012:role/app-task-role",
  "executionRoleArn": "arn:aws:iam::123456789012:role/ecsTaskExecutionRole",
  "containerDefinitions": [
    {
      "name": "app",
      "image": "public.ecr.aws/docker/library/python:3.13-slim",
      "essential": true,
      "command": ["python", "-m", "http.server", "8080"],
      "linuxParameters": { "initProcessEnabled": true },
      "readonlyRootFilesystem": false
    }
  ]
}

設定③：ECS Exec を有効にしてタスクを起動する

# サービス（新しいデプロイで、新しいタスクから有効になる）
aws ecs update-service --cluster app --service web \
  --enable-execute-command --force-new-deployment

# 単発のタスク
aws ecs run-task --cluster app --task-definition app --launch-type FARGATE \
  --enable-execute-command \
  --network-configuration "awsvpcConfiguration={subnets=[subnet-xxxx],securityGroups=[sg-xxxx],assignPublicIp=DISABLED}"

ECS Exec は、すでに動いているタスクには有効にできません（ドキュメント）。 update-service --enable-execute-command だけでは設定前に起動したタスクが残るため、--force-new-deployment で入れ替えます。

有効になったかは describe-tasks で確かめます。

aws ecs describe-tasks --cluster app --tasks 0123456789abcdef0123456789abcdef \
  --query 'tasks[0].{exec:enableExecuteCommand,status:lastStatus,pv:platformVersion,agents:containers[].managedAgents[]}'

ドキュメントでは、enableExecuteCommand が true で、managedAgents の ExecuteCommandAgent の lastStatus が RUNNING なら使える状態です。タスクが RUNNING になってすぐは、エージェントがまだ PENDING のことがあります。

設定④：ネットワーク

aws ec2 create-vpc-endpoint --vpc-id vpc-xxxx --vpc-endpoint-type Interface \
  --service-name com.amazonaws.ap-northeast-1.ssmmessages \
  --subnet-ids subnet-xxxx --security-group-ids sg-endpoint \
  --private-dns-enabled

エンドポイントのセキュリティグループは、タスクのセキュリティグループからの HTTPS（443）を受け付けるようにします。

設定⑤：手元の準備（CLI とプラグイン）

# Ubuntu・Debian
curl "https://s3.amazonaws.com/session-manager-downloads/plugin/latest/ubuntu_64bit/session-manager-plugin.deb" -o "session-manager-plugin.deb"
sudo dpkg -i session-manager-plugin.deb

# macOS（Apple シリコン）
curl "https://s3.amazonaws.com/session-manager-downloads/plugin/latest/mac_arm64/session-manager-plugin.pkg" -o "session-manager-plugin.pkg"
sudo installer -pkg session-manager-plugin.pkg -target /
sudo ln -s /usr/local/sessionmanagerplugin/bin/session-manager-plugin /usr/local/bin/session-manager-plugin

session-manager-plugin --version

プラグインが無いと、CLI は API を呼ぶ前に止まりました（--cluster が存在しない名前でも同じメッセージ）。

SessionManagerPlugin is not found. Please refer to SessionManager Documentation here: http://docs.aws.amazon.com/console/systems-manager/session-manager-plugin-not-found

プラグインの入れ方は、EC2 に Session Manager でつなぐ手順と同じです。関連記事「Session ManagerでEC2に接続する方法｜SSH鍵なしの手順」で扱っています。

使い方：execute-command の例

# シェルを開く
aws ecs execute-command --cluster app --task <タスクID> --container app \
  --interactive --command "/bin/sh"

# 1つのコマンドだけ実行する（これも --interactive が必須）
aws ecs execute-command --cluster app --task <タスクID> --container app \
  --interactive --command "env"

# サービスの最初のタスクに入る
TASK=$(aws ecs list-tasks --cluster app --service-name web \
  --desired-status RUNNING --query 'taskArns[0]' --output text)
aws ecs execute-command --cluster app --task "$TASK" --container app \
  --interactive --command "/bin/sh"

amazon-ecs-exec-checker で確かめる

AWS が GitHub で公開している check-ecs-exec.sh は、手元の CLI・プラグイン、クラスター・タスク・ロールの権限・VPC エンドポイントをまとめて調べるスクリプトです。 jq と AWS CLI が要ります。

git clone https://github.com/aws-containers/amazon-ecs-exec-checker.git
cd amazon-ecs-exec-checker
./check-ecs-exec.sh app 0123456789abcdef0123456789abcdef    # クラスター名 タスクID

出力の実物（つながる設定）

ドキュメントどおりの設定（ロギングは CloudWatch Logs、タスクロールには ssmmessages だけ）で動かした出力です（色を外しています）。

-------------------------------------------------------------
Prerequisites for the AWS CLI to use ECS Exec
-------------------------------------------------------------
  AWS CLI Version        | OK (aws-cli/1.46.1 Python/3.11.15 Linux/... botocore/1.43.62)
  Session Manager Plugin | Missing
-------------------------------------------------------------
Checks on ECS task and other resources
-------------------------------------------------------------
  Cluster Configuration  |
     KMS Key       : Not Configured
     Audit Logging : OVERRIDE
     S3 Bucket Name: Not Configured
     CW Log Group  : /ecs/exec-audit, Encryption Enabled: false
  Can I ExecuteCommand?  | arn:aws:sts::123456789012:user/moto
     ecs:ExecuteCommand: allowed
     ssm:StartSession denied?: implicitDeny
  Task Status            | RUNNING
  Launch Type            | Fargate
  Platform Version       | 1.4.0
  Exec Enabled for Task  | OK
  Container-Level Checks |
      Managed Agent Status
         1. RUNNING for "app"
      Init Process Enabled (app:1)
         1. Enabled - "app"
      Read-Only Root Filesystem (app:1)
         1. Disabled - "app"
  Task Role Permissions  | arn:aws:iam::123456789012:role/app-task-role
     ssmmessages:CreateControlChannel: allowed
     ssmmessages:CreateDataChannel: allowed
     ssmmessages:OpenControlChannel: allowed
     ssmmessages:OpenDataChannel: allowed
     -----
     logs:DescribeLogGroups: implicitDeny
     logs:CreateLogStream: implicitDeny
     logs:DescribeLogStreams: implicitDeny
     logs:PutLogEvents: implicitDeny
  VPC Endpoints          | SKIPPED (vpc-5cc7662ca44699534 - No additional VPC endpoints required)
  Environment Variables  | (app:1)
       1. container "app"
       - AWS_ACCESS_KEY: not defined
       - AWS_ACCESS_KEY_ID: not defined
       - AWS_SECRET_ACCESS_KEY: not defined
  PidMode                | Not Configured

この結果から、2つの問題が分かります。 手元にプラグインが無いこと（Missing）と、記録先に CloudWatch Logs を選んだのに、タスクロールに logs:* の権限が無いこと（implicitDeny）です。

失敗する設定での表示

最後の行は見落としがちです。コンテナの環境変数にアクセスキーを入れていると、SSM エージェントはタスクロールではなくそのキーで動きます。

つながらない原因の表

AWS re:Post のナレッジセンターでは、TargetNotConnectedException の原因として、上のほかに pidMode の共有と readonlyRootFilesystem も挙げられています。

コマンドの記録（監査ログ）

誰がいつ入ったかは CloudTrail の ExecuteCommand で、中で何を打ったかはクラスターの executeCommandConfiguration で記録します。

aws logs create-log-group --log-group-name /ecs/exec-audit

aws ecs update-cluster --cluster app \
  --configuration 'executeCommandConfiguration={logging=OVERRIDE,logConfiguration={cloudWatchLogGroupName=/ecs/exec-audit,cloudWatchEncryptionEnabled=false}}'

aws ecs describe-clusters --clusters app --include CONFIGURATIONS \
  --query 'clusters[0].configuration'

moto で作ったときの describe-clusters の結果です。

{
  "executeCommandConfiguration": {
    "logging": "OVERRIDE",
    "logConfiguration": {
      "cloudWatchLogGroupName": "/ecs/exec-audit",
      "cloudWatchEncryptionEnabled": false
    }
  }
}

CloudTrail で誰が実行したかを調べる方法は、関連記事「CloudTrailで誰が操作したか調べる｜lookup-eventsとAthena」で扱っています。

aws cloudtrail lookup-events \
  --lookup-attributes AttributeKey=EventName,AttributeValue=ExecuteCommand \
  --query 'Events[].[EventTime,Username]' --output table

セキュリティ：最小権限の例

ECS Exec で入ると root でシェルが使えます。 開発環境だけ、特定のコンテナだけ、のように絞ります。ドキュメントの条件キーを使った例です。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ExecOnlyDevTasks",
      "Effect": "Allow",
      "Action": ["ecs:ExecuteCommand", "ecs:DescribeTasks"],
      "Resource": [
        "arn:aws:ecs:ap-northeast-1:123456789012:cluster/app",
        "arn:aws:ecs:ap-northeast-1:123456789012:task/app/*"
      ],
      "Condition": {
        "StringEquals": { "aws:ResourceTag/environment": "development" }
      }
    },
    {
      "Sid": "NoExecIntoProdContainer",
      "Effect": "Deny",
      "Action": "ecs:ExecuteCommand",
      "Resource": "*",
      "Condition": {
        "StringEquals": { "ecs:container-name": "production-app" }
      }
    },
    {
      "Sid": "NoDirectSsmSession",
      "Effect": "Deny",
      "Action": "ssm:StartSession",
      "Resource": "arn:aws:ecs:*:*:task/*"
    }
  ]
}

条件キーの書き方は、関連記事「IAMポリシーConditionの書き方｜条件演算子と条件キー一覧」で扱っています。組織全体で禁止するなら、関連記事「AWS OrganizationsのSCPの書き方｜例文とテンプレート」の方法も使えます。

よくある質問

Q. ECS コンソールから入れますか。 A. 入れます。2025年9月4日の AWS の発表では、タスクの詳細画面でコンテナを選んで「Connect」を押すと、CloudShell の中で対話型のセッションが開くと説明されています。サービスやタスクを作る・更新する画面で ECS Exec を有効にすることもでき、画面には同じことをする AWS CLI のコマンドも表示されます。前提（タスクロールの権限・通信）は CLI と同じです。

Q. EC2 起動タイプでも同じですか。 A. ほぼ同じです。ECS に最適化された AMI（Bottlerocket を含む）で使えます。タスクロールが無いときはインスタンスのロールが使われます。チェッカーは ECS エージェントの版（1.50.2 以上）も見ます。

Q. ファイルを手元にコピーできますか。 A. execute-command の引数（クラスター・タスク・コンテナ・コマンド・interactive）に、ファイルを転送するものはありません。小さなテキストなら --command "cat /path/file" で表示できます。大きなファイルは、タスクロールの権限で S3 に置く方法があります。

Q. ポートフォワードはできますか。 A. execute-command にはありません。Session Manager の AWS-StartPortForwardingSessionToRemoteHost などを使う方法がありますが、その場合は ssm:StartSession を許可することになり、ECS Exec の記録は通りません。

まとめ

• 必要なのは「--enable-execute-command で起動したタスク」「タスクロールの ssmmessages 4つ」「手元の Session Manager プラグイン」「タスクから ssmmessages への通信」
• 既存のタスクには後から付けられない。サービスは --force-new-deployment で入れ替える
• readonlyRootFilesystem: true は対応していない。initProcessEnabled: true が勧められている
• つながらないときは check-ecs-exec.sh クラスター タスクID で、プラグイン・権限・エンドポイント・環境変数のアクセスキーまで確かめる
• 記録は CloudTrail の ExecuteCommand（誰が）と executeCommandConfiguration（何を）。記録先の権限はタスクロールに
• root で入れるため、タグ・コンテナ名で絞り、ssm:StartSession を拒否する

参考・出典

確認日はいずれも 2026年10月13日です。

• Amazon ECS 開発者ガイド「Monitor Amazon ECS containers with ECS Exec」：https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-exec.html
• Amazon ECS 開発者ガイド「Troubleshoot Amazon ECS Exec issues」：https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-exec-troubleshooting.html
• Amazon ECS 開発者ガイド「Amazon ECS task IAM role（ECS Exec permissions）」：https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html
• Amazon ECS API リファレンス「ExecuteCommand」：https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ExecuteCommand.html
• AWS Systems Manager ユーザーガイド「Install the Session Manager plugin for the AWS CLI」：https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html
• AWS re:Post ナレッジセンター「ECS Exec の TargetNotConnectedException」：https://repost.aws/knowledge-center/ecs-error-execute-command
• AWS「ECS Exec is now available in the AWS Management Console」（2025年9月4日）：https://aws.amazon.com/about-aws/whats-new/2025/09/ecs-exec-aws-management-console
• GitHub「aws-containers/amazon-ecs-exec-checker」：https://github.com/aws-containers/amazon-ecs-exec-checker
• GitHub「aws/aws-cli（awscli/customizations/ecs/executecommand.py）」：https://github.com/aws/aws-cli

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。