對 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 日誌檔案。

診斷步驟

將具有權限和 Linux 功能的偵錯容器部署為 Amazon ECS 任務：

設定下列環境變數。

將 user-input 取代為實際值。

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

使用名為 的 CLI JSON 檔案建立任務定義node-debugger.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

任務置放問題

以下是任務置放問題的症狀：

  • 任務停滯在 PENDING 狀態

  • 任務無法在 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

Resolution

若要解決任務置放問題，請依照下列步驟確保適當的組態和容量：

  • 驗證任務資源需求與可用容量

  • 檢查置放限制條件和策略

  • 確保已設定 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

Resolution

若要解決客服人員中斷連線問題，請遵循下列步驟：

  • 驗證容器執行個體的 IAM 角色許可

  • 檢查安全群組規則允許傳出 HTTPS 流量到 ECS 端點

  • 確保與 AWS 服務的網路連線

  • 視需要重新啟動 ECS 代理程式服務： nsenter -t 1 -m -p systemctl restart 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 受管執行個體的詳細資訊，請參閱下列資源：