Amazon ECS Managed Instances 문제 해결

다음 절차를 사용해 Amazon ECS Managed Instances를 문제 해결하세요. 여기에는 일반적인 문제, 진단 기법, 해결 단계가 포함돼요.

출처: 문서

본문

사전 준비 (Prerequisites)

Amazon ECS Managed Instances를 문제 해결하기 전에 다음 요구 사항이 갖춰져 있는지 확인하세요.

AWS CLI가 설치되고 적절한 권한으로 구성되어 있어요. 자세한 내용은 AWS Command Line Interface User Guide의 Installing or updating to the latest version of the AWS Command Line Interface를 참고하세요.
Amazon ECS Managed Instances 용량 공급자가 있는 클러스터에 접근할 수 있어요. 자세한 내용은 Creating a cluster for Amazon ECS Managed Instances를 참고하세요.

일반적인 문제 해결 시나리오 (Common troubleshooting scenarios)

Amazon ECS Managed Instances 컨테이너 에이전트 로그 보기

인스턴스에서 실행되는 특권(privileged) 컨테이너에 연결해 Amazon ECS Managed Instances의 Amazon ECS 로그 파일을 볼 수 있어요.

진단 단계

권한과 Linux 능력이 있는 디버그 컨테이너를 Amazon ECS 태스크로 배포합니다. 다음 환경 변수를 설정합니다. 사용자 입력을 사용자의 값으로 바꾸세요.

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

태스크 배치 문제 (Task placement issues)

다음은 태스크 배치 문제의 증상이에요.

PENDING 상태에 갇힌 태스크
Amazon ECS Managed Instances에서 시작에 실패하는 태스크
리소스 부족 오류

진단 단계 – 태스크 배치 문제를 진단하고 클러스터 용량, 컨테이너 인스턴스, 시스템 서비스에 대한 정보를 수집하려면 다음 명령을 실행하세요.

# 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 Managed Instances 용량 공급자가 구성되어 있는지 확인합니다.
태스크와 컨테이너 인스턴스 보안 그룹에 Amazon ECS 에이전트 관리 엔드포인트에 대한 트래픽을 허용하는 아웃바운드 규칙이 있는지 확인합니다.

네트워킹 문제 (Networking issues)

다음은 네트워킹 문제의 증상이에요.

외부 서비스에 도달할 수 없는 태스크
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

리소스 제약 (Resource constraints)

다음은 네트워킹 문제의 증상이에요.

메모리 한도로 인해 종료된 태스크
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 status ecs 
nsenter -t 1 -m -p systemctl status containerd 

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

그렇지 않으면 Amazon ECS Managed Instances를 강제로 등록 해제합니다. 다음 명령을 실행하세요.

# 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 역할 권한을 확인합니다.
보안 그룹 규칙이 ECS 엔드포인트로의 아웃바운드 HTTPS 트래픽을 허용하는지 확인합니다.
AWS 서비스에 대한 네트워크 연결을 확인합니다.
필요한 경우 ECS 에이전트 서비스를 다시 시작합니다: nsenter -t 1 -m -p systemctl restart ecs
/etc/ecs/ecs.config의 ECS_CLUSTER 구성이 클러스터 이름과 일치하는지 확인합니다.

Amazon ECS Managed Instances의 로그 분석 (Log Analysis in Amazon ECS Managed Instances)

시스템 로그 (System logs)

다음 명령을 사용해 시스템 로그를 검토하고 관리형 인스턴스의 잠재적 문제를 식별합니다.

# 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 Managed Instance의 콘솔 출력 가져오기

Amazon EC2 인스턴스 ID를 사용해 콘솔 출력을 검색합니다. 사용자 입력을 사용자의 값으로 바꾸세요.

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

정리 (Cleanup)

디버그 태스크를 중지하고 태스크 정의를 등록 해제하려면 다음을 실행하세요.

# 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 Managed Instances 문제 해결