Zenn
🐳

AWS ECS Execを活用しよう！設定時の注意点と実践ガイド

に公開
AWS
Docker
ECS
SSM
container
tech

ECS Execでコンテナ内に直接ログイン！設定のポイントと活用法

コンテナ環境でのデバッグって面倒だと思ったことありませんか？🤔
「ログを見ても原因が分からない...」「実際に中に入って確認したい...」そんな時に役立つのが ECS Exec です！

この記事では、AWS ECS Execの設定方法から活用のコツまで、私が実際に苦労した経験をもとに解説していきます。

ECS Execとは？

ECS Exec は、AWS ECSのタスクで実行されているコンテナ内に直接ログインできる機能です。2021年3月にリリースされた比較的新しい機能で、コンテナのトラブルシューティングやデバッグが格段に簡単になりました。

従来の方法との違い

従来は、コンテナ内を調査するために以下のような面倒な作業が必要でした：

  • SSHデーモンを含むカスタムイメージの作成
  • デバッグ用コンテナの追加デプロイ
  • ログの詳細な出力設定

ECS Execを使えば、AWS CLIから一発でコンテナ内にシェルを取得できます！まるでKubernetesのkubectl execのような感覚で使えるんです。

aws ecs execute-command \
    --cluster my-cluster \
    --task 12345abcde \
    --container my-container \
    --command "/bin/bash" \
    --interactive

ECS Execの仕組み

ECS Execは、AWS Systems Manager (SSM) Session Managerを活用して実現されています。

  1. AWS CLIからコマンドを発行
  2. ECSサービスがリクエストを受け取る
  3. SSM Session Managerが安全な通信チャネルを確立
  4. コンテナ内でシェルが起動
  5. 入出力がSSMを経由してCLIに転送される

この仕組みにより、コンテナ自体に特別なログイン機能を持たせなくても内部にアクセスできるようになります。

ECS Execを有効化するための条件

ECS Execを使うには、いくつかの条件を満たす必要があります。一つでも欠けると動作しないので注意しましょう！

必須条件チェックリスト

  • AWS CLIバージョン 2.3.6 以降
  • AWS CLIのセッションマネージャープラグインがインストール済み
  • EC2の場合：ECSに最適化されたAMI（Bottlerocketを含む）
  • Fargateの場合：プラットフォームバージョン 1.4.0以上
  • SSMエンドポイントへのアクセス確保（インターネット接続またはVPCエンドポイント）
  • タスク実行ロールにSSMの権限が付与されている

IAM権限の設定

タスク実行ロールには、以下のSSMに関連する権限が必要です：

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

ECS ExecをサービスやタスクDで有効化する方法

新規サービス作成時

新しくサービスを作成する際は、enable-execute-commandオプションを追加します：

aws ecs create-service \
    --cluster my-cluster \
    --task-definition my-task-def \
    --enable-execute-command \  # この行がポイント！
    --service-name my-service \
    --launch-type FARGATE \
    --network-configuration "awsvpcConfiguration={subnets=[subnet-12344321],securityGroups=[sg-12344321],assignPublicIp=ENABLED}" \
    --desired-count 1

既存サービスの更新

既存のサービスを更新する場合は、update-serviceコマンドを使用します：

aws ecs update-service \
    --cluster my-cluster \
    --service my-service \
    --enable-execute-command

タスク定義での設定

タスク定義でもECS Execを有効にするために、以下の設定が必要です：

{
  "containerDefinitions": [
    {
      "name": "my-container",
      "image": "my-image:latest",
      // その他の設定...
      "linuxParameters": {
        "initProcessEnabled": true  // これを追加
      }
    }
  ],
  "executionRoleArn": "arn:aws:iam::123456789012:role/ecsTaskExecutionRole",
  "taskRoleArn": "arn:aws:iam::123456789012:role/ecsTaskRole",  // SSM権限を持つロール
  "enableExecuteCommand": true  // これを追加
}

設定の確認方法

設定が正しく行われたかは、以下のコマンドで確認できます：

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

出力の中に、enableExecuteCommandがtrueになっていれば成功です！

ネットワークモードによる注意点

ECS Execはネットワークモードによって設定が異なります。特にセキュリティグループとIPアドレスの扱いに違いがあるので要注意！

ネットワークモード別の特徴

ネットワークモード ENIの付与先 セキュリティグループの適用先 パブリックIP割り当て
awsvpc タスク タスク 可能（Fargateでパブリックサブネットの場合）
bridge EC2インスタンス EC2インスタンス 不可（EC2のIPを使用）
host EC2インスタンス EC2インスタンス 不可（EC2のIPを使用）

プライベートサブネットでの注意点

プライベートサブネットでECS Execを使う場合、SSMエンドポイントへのアクセスパスが必要です。以下のいずれかを設定しましょう：

  1. VPCエンドポイントの設定（推奨）

    • ssmmessages用のVPCエンドポイントを作成
    • セキュリティグループで適切なアクセス許可を設定

  2. NAT Gatewayの利用

    • プライベートサブネットからインターネットへの経路確保
    • コスト面で少し高くなる可能性あり

EC2でawsvpcモードを使う場合の注意点

EC2インスタンスでawsvpcモードを使う場合、タスクにENIは付与されますが、パブリックIPを割り当てられません。以下のエラーが出ることがあります：

aws ecs update-service --cluster my-cluster \
  --service my-service \
  --network-configuration "awsvpcConfiguration={subnets=['subnet-1234'],securityGroups=['sg-1234'],assignPublicIp='ENABLED'}"

An error occurred (InvalidParameterException) when calling the UpdateService operation: Assign public IP is not supported for this launch type.

この場合も、VPCエンドポイントかNAT Gatewayが必要になります。

よくあるトラブルと解決策

1. ECS Execが接続できない

考えられる原因と解決策:

  • SSM Session Managerプラグインがインストールされていない → プラグインをインストール
  • IAM権限が不足している → タスクロールにSSM権限を追加
  • ネットワーク接続の問題 → Reachability Analyzerで疎通確認

2. 「コンテナが見つからない」エラー

An error occurred (InvalidParameterException) when calling the ExecuteCommand operation: 
The container my-container is not found in task.

解決策:
正確なコンテナ名を指定しているか確認。大文字小文字や空白にも注意！

3. セキュリティグループの設定ミス

解決策:
Reachability Analyzerで疎通確認を行い、適切なセキュリティグループルールを設定する。

4. readonlyRootFilesystemによるエラー

ECS ExecはSSMエージェントがコンテナ内にファイルを作成する必要があります。タスク定義でreadonlyRootFilesystem: trueを設定していると動作しません。

解決策:

  • readonlyRootFilesystem: falseに変更する
  • または、書き込み可能なボリュームをマウントしてSSMに必要なパスを確保する

ECS Execの実用的な使い方

1. ファイルシステムの調査

aws ecs execute-command --cluster my-cluster --task task-id --container my-container --command "ls -la /app" --interactive

2. 環境変数の確認

aws ecs execute-command --cluster my-cluster --task task-id --container my-container --command "env" --interactive

3. プロセスの状態確認

aws ecs execute-command --cluster my-cluster --task task-id --container my-container --command "ps aux" --interactive

4. 設定ファイルの確認

aws ecs execute-command --cluster my-cluster --task task-id --container my-container --command "cat /etc/nginx/nginx.conf" --interactive

セキュリティ上の注意点

ECS Execを使用すると、コンテナ内でroot権限のシェルが実行されます。これはDockerfileでUSER設定をしていても同様です。セキュリティ上、以下の点に注意しましょう：

  1. アクセス制限

    • ECS Execを使用できるIAMユーザー/ロールを制限する
    • 必要な時だけECS Execを有効にする

  2. ログ監査

    • ECS Execのセッションをログに記録する
      • この場合はタスクロールにログ出力の権限を付与すること
    • CloudTrailでAPIコール履歴を監視する

  3. 実行コマンドの制限

    • 実行できるコマンドを制限するポリシーを検討する

まとめ

ECS Execは設定箇所が多岐にわたりますが、一度設定してしまえばコンテナデバッグの強力な味方になります！🚀

ポイント:

  • ECS Execを有効化するにはサービス設定とIAM権限の両方が必要
  • ネットワークモードによってセキュリティグループやIPアドレスの扱いが異なる
  • プライベートサブネットではVPCエンドポイントかNAT Gatewayが必須
  • readonlyRootFilesystemが有効だとECS Execは動作しない
  • Reachability Analyzerを活用してネットワーク疎通を確認しよう

私も最初はハマりましたが、これらのポイントを押さえておけば問題なく設定できるはずです。困ったときはこの記事を参考にしてみてくださいね！

参考リンク

Discussion