Amazon ECS マネージドインスタンスのトラブルシューティング - Amazon Elastic Container Service
前提条件一般的なトラブルシューティングのシナリオAmazon ECS マネージドインスタンスのログ分析EC2 AWS CLI を使用して Amazon ECS マネージドインスタンスからコンソール出力を取得するクリーンアップその他のリソース

Amazon ECS マネージドインスタンスのトラブルシューティング

次の手順を使用して、一般的な問題、診断手法、解決手順など、Amazon ECS マネージドインスタンスのトラブルシューティングを行います。

前提条件

Amazon ECS マネージドインスタンスのトラブルシューティングを行う前に、次の要件を満たしていることを確認してください。

一般的なトラブルシューティングのシナリオ

Amazon ECS マネージドインスタンスコンテナエージェントログの表示

これらの Amazon ECS ログファイルは、インスタンスで実行されている特権コンテナに接続することで、Amazon ECS マネージドインスタンスで表示できます。

診断手順

Amazon ECS タスクとして権限と Linux 機能を備えたデバッグコンテナをデプロイします。

次の環境変数を設定します。

user-input を独自の値に置き換えます。

export ECS_CLUSTER_NAME="your-cluster-name"
export AWS_REGION="your-region"
export ACCOUNT_ID="your-account-id"

node-debugger.json という CLI JSON ファイルを使用してタスク定義を作成します。

cat << EOF > node-debugger.json
{
  "family": "node-debugger",
  "taskRoleArn": "arn:aws:iam::${ACCOUNT_ID}:role/ecsTaskExecutionRole",
  "executionRoleArn": "arn:aws:iam::${ACCOUNT_ID}:role/ecsTaskExecutionRole",
  "cpu": "256",
  "memory": "1024",
  "networkMode": "host",
  "pidMode": "host",
  "requiresCompatibilities": ["MANAGED_INSTANCES", "EC2"],
  "containerDefinitions": [
    {
      "name": "node-debugger",
      "image": "public.ecr.aws/amazonlinux/amazonlinux:2023",
      "essential": true,
      "privileged": true,
      "command": ["sleep", "infinity"],
      "healthCheck": {
          "command": ["CMD-SHELL", "echo debugger || exit 1"],
          "interval": 30,
          "retries": 3,
          "timeout": 5
      },
      "linuxParameters": {
        "initProcessEnabled": true
      },
      "mountPoints": [
        {
          "sourceVolume": "host-root",
          "containerPath": "/host",
          "readOnly": false
        }
      ],
      "logConfiguration": {
        "logDriver": "awslogs",
        "options": {
          "awslogs-group": "/aws/ecs/node-debugger",
          "awslogs-create-group": "true",
          "awslogs-region": "${AWS_REGION}",
          "awslogs-stream-prefix": "ecs"
        }
      }
    }
  ],
  "volumes": [
    {
      "name": "host-root",
      "host": {
        "sourcePath": "/"
      }
    }
  ]
}
EOF

タスクを登録して実行します。以下のコマンドを実行します。

aws ecs register-task-definition --cli-input-json file://node-debugger.json

TASK_ARN=$(aws ecs run-task \
  --cluster $ECS_CLUSTER_NAME \
  --task-definition node-debugger \
  --enable-execute-command \
  --capacity-provider-strategy capacityProvider=managed-instances-default,weight=1 \
  --query 'tasks[0].taskArn' --output text)

# Wait for task to be running
aws ecs wait tasks-running --cluster $ECS_CLUSTER_NAME --tasks $TASK_ARN

コンテナに接続します。以下のコマンドを実行してください。

aws ecs execute-command \
  --cluster $ECS_CLUSTER_NAME \
  --task $TASK_ARN \
  --container node-debugger \
  --interactive \
  --command "/bin/sh"

Amazon ECS エージェントログを確認します。

コンテナのインタラクティブセッションで、次のコマンドを実行します。

# Install required tools
yum install -y util-linux-core

# View ECS agent logs
nsenter -t 1 -m -p cat /var/log/ecs/ecs-agent.log | tail -50

# Check agent registration
nsenter -t 1 -m -p grep "Registered container instance" /var/log/ecs/ecs-agent.log

Example Output:

{"level":"info","time":"2025-10-16T12:39:37.665","msg":"Registered container instance with cluster!"}

# Verify capabilities
nsenter -t 1 -m -p grep "Response contained expected value for attribute" /var/log/ecs/ecs-agent.log

エージェントメトリクスを確認します。

次のコマンドを実行して、ログを表示します。

# View metrics logs
nsenter -t 1 -m -p cat /var/log/ecs/metrics.log | tail -20

タスク配置の問題

以下は、タスク配置の問題で見られる症状です。

  • タスクが保留中状態でスタックする

  • Amazon ECS マネージドインスタンスでタスク開始に失敗する

  • リソース不足のエラーが発生する

診断手順

次のコマンドを実行して、タスク配置の問題を診断し、クラスター容量、コンテナインスタンス、システムサービスに関する情報を収集します。

# Check cluster capacity
aws ecs describe-clusters --clusters cluster-name --include STATISTICS

# Check cluster capacity providers
aws ecs describe-clusters --clusters cluster-name --include STATISTICS --query 'clusters[].capacityProviders'

# List container instances
aws ecs list-container-instances --cluster cluster-name

# Check container instance details
aws ecs describe-container-instances --cluster cluster-name --container-instances container-instance-arn

# Check container instance remaining resources CPU/Mem
aws ecs describe-container-instances --cluster $ECS_CLUSTER_NAME --container-instances container-instance-arn --query 'containerInstances[].remainingResources'

# Check container instance Security Group
aws ecs describe-container-instances --cluster $ECS_CLUSTER_NAME --container-instances container-instance-arn --query 'containerInstances[].ec2InstanceId' --output text
aws ec2 describe-instances --instance-ids instance-id --query 'Reservations[0].Instances[0].SecurityGroups'
aws ec2 describe-security-groups --group-ids security-group-id

システムサービスのモニタリング:

# Check Containerd status
nsenter -t 1 -m -p systemctl status containerd.service

# Check Amazon ECS container agent status
nsenter -t 1 -m -p systemctl status ecs

解決策

タスク配置の問題を解決するには、以下の手順に従って、適切な設定と容量であることを確認してください。

  • タスクリソースの要件と使用可能な容量を検証する

  • 配置の制約と戦略を確認する

  • Amazon ECS マネージドインスタンスのキャパシティプロバイダーが設定されていることを確認する

  • タスクとコンテナインスタンスのセキュリティグループに、Amazon ECS エージェント管理エンドポイントのトラフィックを許可するアウトバウンドルールがあることを確認する

ネットワーキングの問題

ネットワークの問題では、次のような症状が見られます。

  • タスクが外部サービスに到達できない

  • DNS 解決に問題がある

診断手順

ネットワーク接続のテスト:

デバッグコンテナで次のコマンドを実行します。

注記

キャパシティプロバイダーまたは Amazon ECS タスクにアタッチされたセキュリティグループがトラフィックを許可していることを確認します。

# Install DNS Utility
yum install bind-utils -y

# Test DNS resolution
nslookup amazon.com

# Test external connectivity
curl -I https://amazon.com

リソースの制約

ネットワークの問題では、次のような症状が見られます。

  • タスクがメモリ制限により強制終了される

  • CPU スロットリングが発生する

  • ディスク容量に問題がある

診断手順

コマンドを実行して、リソースとコンテナの制限をモニタリングします。

リソースのモニタリング:

# Check memory usage
nsenter -t 1 -m -p free -h

# Check disk usage
nsenter -t 1 -m -p lsblk

# Check disk usage
nsenter -t 1 -m -p df -h

コンテナの制限:

# Check OOM kills
nsenter -t 1 -m -p dmesg | grep -i "killed process"

コンテナインスタンスエージェントが切断される問題

コンテナインスタンスエージェントの切断の問題には、次のような症状が見られます。

  • Amazon ECS コンソールで、コンテナインスタンスが切断されたと表示される

  • 特定のインスタンスにタスクを配置できない

  • ログでエージェント登録が失敗している

診断手順

ECS Exec がアクセス可能なホストで既存の権限タスクが実行中の場合は、次のコマンドを実行してエージェント接続の問題を診断します。

# check service status 
nsenter -t 1 -m -p systemctl restart ecs 
nsenter -t 1 -m -p systemctl restart containerd 

# restart stopped services 
nsenter -t 1 -m -p systemctl restart ecs 
nsenter -t 1 -m -p systemctl restart containerd

それ以外の場合は、Amazon ECS マネージドインスタンスを強制的に登録解除します。次のコマンドを実行します。

# list ECS Managed Instance container
aws ecs list-container-instances --cluster managed-instances-cluster --query 'containerInstanceArns' --output text

# deregister the specific container instance
aws ecs deregister-container-instance \
    --cluster $ECS_CLUSTER_NAME \
    --container-instance container-instance-arn \
    --force

解決策

エージェントの切断の問題を解決するには、次の手順に従います。

  • コンテナインスタンスの IAM ロールのアクセス許可を検証する

  • セキュリティグループルールが、ECS エンドポイントへのアウトバウンド HTTPS トラフィックを許可していることを確認する

  • AWS サービスへのネットワーク接続を確認する

  • 必要に応じて、nsenter -t 1 -m -p systemctl restart ecs で ECS エージェントサービスを再起動する

  • /etc/ecs/ecs.config の ECS_CLUSTER 設定がクラスター名と一致することを確認する

Amazon ECS マネージドインスタンスのログ分析

システムログ

次のコマンドを使用して、システムログを確認し、マネージドインスタンスの潜在的な問題を特定します。

# Check system messages
nsenter -t 1 -m -p journalctl --no-pager -n 50

# Check kernel logs
nsenter -t 1 -m -p dmesg | tail -20

# Check for disk space errors
nsenter -t 1 -m -p journalctl --no-pager | grep -i "no space\|disk full\|enospc"

EC2 AWS CLI を使用して Amazon ECS マネージドインスタンスからコンソール出力を取得する

Amazon EC2 インスタンス ID を使用してコンソール出力を取得します。

user-input を独自の値に置き換えます。

aws ec2 get-console-output --instance-id instance-id --latest --output text

クリーンアップ

以下を実行して、デバッグタスクを停止し、タスク定義を登録解除します。

# Stop debug task
aws ecs stop-task --cluster $ECS_CLUSTER_NAME --task $TASK_ARN

# Deregister task definition (optional)
aws ecs deregister-task-definition --task-definition node-debugger

その他のリソース

Amazon ECS マネージドインスタンスのトラブルシューティングの詳細については、次のリソースを参照してください。