AWS Builder Center: Learn, Build and Connect with builders in the AWS community

AWS Builder Center is the official home for builders on AWS. Share and read what others are working on, follow people who inspire you, explore training and workshops, and find tools to support what you're building.

Amazon ECS エージェントが接続解除される場合のトラブルシューティング方法を教えてください。

所要時間3分

Amazon Elastic Container Service (Amazon ECS) のコンテナインスタンスが接続解除されました。

簡単な説明

Amazon ECS コンテナエージェントが通常の動作の一環として 1 時間に複数回切断および再接続することは想定内です。数分間しか続かない変更イベントは想定内であり、コンテナエージェントまたはコンテナインスタンスの問題を示しているとは限りません。

ただし、コンテナエージェントが長期間切断された状態状態のままである場合、コンテナインスタンスは Amazon ECS クラスターの一部として動作できなくなります。この問題は、次のいずれかの理由によって引き起こされる可能性があります。

ネットワークの問題により、インスタンスと Amazon ECS 間の通信が妨げられている。
コンテナエージェントに、Amazon ECS エンドポイントと通信するために必要な AWS Identity and Access Management (IAM) アクセス許可がない。
コンテナインスタンス内のホストまたは Docker デーモンに問題がある。
基盤となるホストでリソースの競合が発生している。

最新バージョンの Amazon ECS コンテナエージェントを使用することはベストプラクティスです。

解決策

**注: ** 以下の解決策は、Amazon ECS 最適化 Amazon Linux 2023 AMI に適用されます。

SSH キーを使用して Amazon EC2 インスタンスに接続できます。SSH キーを生成していない場合は、AWS Systems Manager の機能である Session Manager を使用してインスタンスに接続できます。デフォルトでは、Systems Manager Agent は Amazon Linux 2023 AMI および Amazon Linux 2023 ECS 最適化ベース AMI にインストールされています。

コンテナインスタンス上でコンテナエージェントが実行されていることを確認する

Amazon ECS コンテナエージェントのステータスと接続状態を確認するには、コンテナインスタンス上で次のいずれかのコマンドを実行してください。

sudo systemctl status ecs

sudo docker ps -f name=ecs-agent

出力には active と表示され、次のようになります。

ecs.service - Amazon Elastic Container Service - container agent
        Loaded: loaded (/usr/lib/systemd/system/ecs.service; enabled; preset: disabled)
        Active: active (running) since Thu 2026-02-19 08:42:39 UTC; 1min 17s ago
          Docs: https://aws.amazon.com/documentation/ecs/
     Main PID: 2578 (amazon-ecs-init)
        Tasks: 5 (limit: 9497)
       Memory: 136.5M
          CPU: 214ms
       CGroup: /system.slice/ecs.service
               └─2578 /usr/libexec/amazon-ecs-init start
CONTAINER ID  IMAGE                           COMMAND   CREATED         STATUS
8ab4e7c372d7  amazon/amazon-ecs-agent:latest  "/agent"  2 minutes ago   Up 2 minutes (healthy)

問題がエージェントの切断によるものである場合は、次のコマンドを実行して ECS エージェントを再起動してください。

sudo systemctl restart ecs

**注: ** 上記のコマンドを実行した後、出力は返されません。

エージェントが実行中であることを確認するには、次のコマンドを実行してください。

sudo systemctl status ecs

Docker サービスがコンテナインスタンス上で実行されていることを確認する

影響を受けるコンテナインスタンス上で Docker サービスが実行中であることを確認するには、次のコマンドを実行してください。

sudo systemctl status docker

出力には active と表示され、次のようになります。

docker.service - Docker Application Container Engine
        Loaded: loaded (/usr/lib/systemd/system/docker.service; disabled; preset: disabled)
        Active: active (running) since Thu 2026-02-19 08:42:37 UTC; 3min 46s ago
   TriggeredBy: docker.socket
          Docs: https://docs.docker.com
     Main PID: 2314 (dockerd)
        Tasks: 13
       Memory: 485.3M
          CPU: 4.846s
       CGroup: /system.slice/docker.service
               └─2314 /usr/bin/dockerd -H fd:// --containerd=/run/containerd/containerd.sock --default-ulimit nofile=32768:65536

Docker サービスが非アクティブになる場合は、次のコマンドを実行して Docker サービスを再起動してください。

sudo systemctl restart docker

**注: ** 上記のコマンドを実行した後、出力は返されません。

Docker サービスが再起動したことを確認するには、次のコマンドを実行してください。

sudo systemctl status docker

コンテナエージェントと Docker のログファイルを確認する

コンテナインスタンスがまだ切断状態の場合は、コンテナホスト上のコンテナエージェントと Docker のログファイルを確認してください。

次のログファイルで、"error"、"warn"、"agent transition state" などのキーワードを確認します。

Amazon ECS コンテナエージェントの最新のログは /var/log/ecs/ecs-agent.log で確認する。/var/log/ecs/ecs-agent-log.timestamp にフィルタリングすることで、ローテーションされたログを確認できる
Amazon ECS init ログは /var/log/ecs/ecs-init.log で表示できる
/var/log/cloud-init.log に配置されたユーザーデータ実行ログを確認する
コマンド sudo journalctl -u docker を実行し、Docker デーモンログを確認する

Linux を使用している場合は、停止したエージェントコンテナの詳細情報として終了コードも確認できます。

終了コードを取得するには、次のコマンドを実行します。

docker inspect <your container ID>

**注: ** your container ID を停止したコンテナの ID に置き換えてください。

Amazon ECS ログコレクターを使用して、Amazon ECS の一般オペレーティングシステムログ、Docker ログ、コンテナエージェントログを収集できます。

IAM インスタンスプロファイルに必要なアクセス許可があることを確認する

コンテナエージェントがまだ切断状態の場合は、コンテナインスタンスに関連付けられた IAM インスタンスプロファイルに必要な IAM アクセス許可があることを確認してください。

SSH または Session Manager を使用してインスタンスに接続してください。

インスタンスに関連付けられたインスタンスプロファイルのインスタンスメタデータを表示するには、次のコマンドを実行してください。

TOKEN=$(curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600")
curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/iam/info

出力は次のようになります。

{
   "Code" : "Success",
   "LastUpdated" : "2026-02-19T08:42:14Z",
   "InstanceProfileArn" : "arn:aws:iam::1122334455:instance-profile/ecsInstanceRole",
   "InstanceProfileId" : "AIPA4VIZXOFF55F72XIZN"
}

IAM ロールにコンテナインスタンスに必要な正しいアクセス許可が含まれていることを確認する。
特定の認証情報エラーを確認するには、次のコマンドを実行してコンテナエージェントログを確認してください。
```
cat /var/log/ecs/ecs-agent.log.YYYY-MM-DD-##
```
**注: ** YYYY-MM-DD-## を関連タイムスタンプに置き換えてください。

コンテナエージェントのログは 1 時間ごとにローテーションされます。サフィックスは自動的に現在の日時に合わせて変更されます。問題が発生した日時範囲とログ ID を含むようにコマンドを更新してください。

コンテナインスタンスに ECS エージェントを実行するための十分なリソースがあることを確認する

タスクのメモリまたは CPU 使用率が高い場合、コンテナインスタンスに ECS エージェントを実行するための十分なリソースがない可能性があります。

Amazon ECS コンテナエージェントは、Docker の ReadMemInfo() 関数を使用して、オペレーティングシステムで利用可能なメモリ量をクエリします。

オペレーティングシステムで認識されている合計メモリを表示するには、コンテナインスタンスで次のコマンドを実行してください。

free -b

Amazon ECS 最適化 Amazon Linux 2023 AMI を実行している t2.large インスタンスの出力例:

               total        used        free      shared  buff/cache   available
Mem:     8327938048   337494016  6402355200      557056  1588088832  7745118208
Swap:             0           0           0

コンテナインスタンス上の Amazon ECS コンテナエージェントおよびその他の重要なシステムプロセス用にメモリを予約することができます。このメモリを予約することで、タスクのコンテナが同じメモリを競合しないことを確認するのに役立ちます。詳細については、『Amazon ECS Linux コンテナインスタンスのメモリを予約する』を参照してください。

環境変数 ECS_CLUSTER に正しいクラスター名が含まれることを確認する

Amazon ECS コンテナエージェントの設定パラメータ ECS_CLUSTER に誤ったクラスター名が設定されている場合、コンテナインスタンスはクラスターに参加できません。/etc/ecs/ecs.config ファイルの内容を確認し、このパラメータを検証するには、次のコマンドを実行してください。

cat /etc/ecs/ecs.config

ECS エージェントが ECS エンドポイントと通信できることを確認する

ECS エンドポイントに接続するには、ネットワークアクセスコントロールリストとコンテナインスタンスのセキュリティグループがポート 443 (HTTPS) でのアウトバウンド接続を許可している必要があります。

コンテナインスタンスがパブリックサブネットにある場合は、インスタンスにパブリック IP アドレスがあり、サブネットのルートテーブルにインターネットゲートウェイへのルートがあることを確認してください。

コンテナインスタンスがプライベートサブネットにある場合は、サブネットのルートテーブルに NAT ゲートウェイへのルートがあるか、Amazon ECS の VPC エンドポイントを設定していることを確認してください。

ECS エンドポイント (ACS/TCS) へのアウトバウンド接続を確認するには、コンテナインスタンスで次のいずれかのコマンドを実行してください。

sudo yum install telnet -y
telnet ecs.REGION.amazonaws.com 443

または

curl https://ecs.REGION.amazonaws.com

**注: ** REGION を AWS リージョンに置き換えてください。

次のベストプラクティスを確認します。

アプリケーションで Amazon ECS 最適化 AMI に利用できない特定のオペレーティングシステムまたは Docker バージョンが必要でない限り、Amazon ECS 最適化 Linux AMI を使用して ECS ワークロードを実行する。
Amazon ECS コンテナエージェントの最新バージョンを使用する。最新バージョンには強化された機能や重要な更新が含まれている。
CPU とメモリの制限を適用してタスクを設定する。