ECS Fargate 内にローカルから接続

本記事では ECS Fargate で起動したコンテナへ、ローカル環境から接続する手順についてご紹介します。

ユースケース

ECS Fargate でアプリケーションをデプロイした後、意図したファイルが配置されているか、コンテナの中身を確認したいケースがあると思います。

過去、ローカルではボリュームマウントに依存していたため、コンテナイメージに必要なファイルが含まれておらず、アプリケーションの設定ファイルが不足してサイト表示に失敗した経験がありました。
こういったデプロイミスを素早く特定し、解決するためにコンテナ内に接続する方法が役立ちます。

結論

以下を実施すれば、ECS Fargate 内のコンテナにローカルから接続することが可能です。
事前準備

  • aws cli をインストール
  • Session Manager プラグインをインストール

作業手順

  • ECS にて enableExecuteCommand が true となっていることを確認
  • aws ecs execute-command で対象コンテナに接続

事前準備

ローカルに必要なツールをインストールします。

aws cli をインストール

以下記事を参考に、aws cli をインストールします。また、対象のECSに接続するためにクレデンシャルの設定も必要になります。

Installing or updating to the latest version of the AWS CLI
※ mac の場合は brew でインストールするのが簡単です。

brew install awscli

以下のように表示されればインストール完了です。

$ aws --version
aws-cli/2.17.46 Python/3.11.10 Darwin/22.5.0 source/arm64

Session Manager プラグインをインストール

以下記事を参考に、Session Manager プラグインをインストールします。

Install the Session Manager plugin for the AWS CLI
※ mac の場合は brew でインストールするのが簡単です。

brew install --cask session-manager-plugin

以下のように表示されればインストール完了です。

$ session-manager-plugin --version
1.2.694.0

作業手順

ECS Service にて enableExecuteCommand が true となっていることを確認

接続対象の ECS において ECS Exec を利用可能か確認します。
以下コマンドを実行し、enableExecuteCommand がtrueになっていることを確認します。

aws ecs describe-services --cluster $CLUSTER_NAME --services $SERVICE_NAME | grep enableExecuteCommand

必要な情報

  • CLUSTER_NAME: ECS Cluster 名
  • SERVICE_NAME: ECS Service 名

以下のように true が返ってきた場合は、有効化されている状態です。
もし false が返ってきた場合は、無効化されている状態です。

$ aws ecs describe-services --cluster $CLUSTER_NAME --services $SERVICE_NAME | grep enableExecuteCommand
            "enableExecuteCommand": true

Tips: enableExecuteCommand を変更

もし true にしたい場合は –enable-execute-command で有効化することができます。

aws ecs update-service --cluster $CLUSTER_NAME --service $SERVICE_NAME --enable-execute-command | grep enableExecuteCommand

もし false にしたい場合は –disable-execute-command で無効化することができます。

aws ecs update-service --cluster $CLUSTER_NAME --service $SERVICE_NAME --disable-execute-command | grep enableExecuteCommand

注意: enableExecuteCommand の設定変更は新しいタスクにのみ反映されます。既存のタスクには反映されないため、タスク数の変更や再デプロイが必要です。

Tips: ECS Task にて enableExecuteCommand が true となっていることを確認

接続したいタスクにて enableExecuteCommand が true となっているかは、以下コマンドで確認できます。

aws ecs describe-tasks --cluster $CLUSTER_NAME --tasks $TASK_ID | grep enableExecuteCommand

必要な情報

  • CLUSTER_NAME: ECS Cluster 名
  • TASK_ID: ECS task ARN

aws ecs execute-command で対象コンテナに接続

以下コマンドで対象のコンテナに接続することができます。

aws ecs execute-command --cluster $CLUSTER_NAME --task $TASK_ID --container $CONTAINER_NAME --interactive --command "/bin/sh"

必要な情報

  • CLUSTER_NAME: ECS Cluster 名
  • TASK_ID: ECS task ARN
  • CONTAINER_NAME: タスク定義で指定したコンテナ名

補足情報

  • interactive: コンテナ内でインタラクティブシェルを起動するためのオプション。
  • command “/bin/sh”: コンテナで /bin/sh を起動し、シェル操作を行う。

以下のようにプロンプトが表示されれば接続成功となります。

$ aws ecs execute-command --cluster $CLUSTER_NAME --task $TASK_ID --container $CONTAINER_NAME --interactive --command "/bin/sh"

The Session Manager plugin was installed successfully. Use the AWS CLI to start a session.


Starting session with SessionId: ecs-execute-command-XXXXXXXXXXXX
#
# pwd
/
#
# uname -n
ip-X-X-X-C.ap-northeast-1.compute.internal
#
# cat /etc/os-release
PRETTY_NAME="Debian GNU/Linux 12 (bookworm)"
NAME="Debian GNU/Linux"
VERSION_ID="12"
VERSION="12 (bookworm)"
VERSION_CODENAME=bookworm
ID=debian
HOME_URL="https://www.debian.org/"
SUPPORT_URL="https://www.debian.org/support"
BUG_REPORT_URL="https://bugs.debian.org/"
#
# exit


Exiting session with sessionId: ecs-execute-command-XXXXXXXXXXXX

参考情報

所感

ECS Exec を使うことで、運用中のコンテナの中身を手軽に確認できてかなり便利な機能と感じました。
EC2 なら SSH だけでなく Session Manager や EC2 Instance Connect みたいな接続手段がありますが、Fargate は SSH 接続もできないため、ECS Exec の機能はトラブルシューティングやデバッグで役立つと思います。
最初に使うときは、IAM ポリシーの設定とか必要なツールのインストールを忘れずに準備する必要がありますが、一度セットアップすれば、開発者や運用担当者にとって便利なツールになると実感しました。