사전 조건 일반적인 문제 해결 시나리오 Amazon ECS 관리형 인스턴스에서 로그 분석 EC2 AWS CLI를 사용하여 Amazon ECS 관리형 인스턴스에서 콘솔 출력 가져오기 정리 추가 리소스

Amazon ECS 관리형 인스턴스 드레이닝 문제 해결

다음 절차에 따라 일반적인 문제, 진단 기법 및 해결 단계를 포함하여 Amazon ECS 관리형 인스턴스 문제를 해결합니다.

사전 조건

Amazon ECS 관리형 인스턴스 문제를 해결하기 전에 다음 요구 사항을 이행하고 있는지 확인합니다.

적절한 권한으로 AWS CLI가 설치 및 구성됨

자세한 내용은 AWS Command Line Interface 사용 설명서의 AWS Command Line Interface 최신 버전의 설치 또는 업데이트를 참조하세요.
Amazon ECS 관리형 인스턴스 용량 공급자를 사용하여 클러스터에 액세스합니다. 자세한 내용은 Amazon ECS 관리형 인스턴스용 클러스터 생성 섹션을 참조하세요.

일반적인 문제 해결 시나리오

Amazon ECS 관리형 인스턴스 컨테이너 에이전트 로그 보기

인스턴스에서 실행되는 권한 있는 컨테이너에 연결하여 Amazon ECS 관리형 인스턴스에서 이러한 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

태스크 배치 문제

다음은 태스크 배치 문제의 증상입니다.

태스크가 보류 중 상태에서 멈춤
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 서비스에 대한 네트워크 연결성 확인
필요한 경우 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 관리형 인스턴스에서 콘솔 출력 가져오기

EC2 인스턴스 ID를 사용하여 콘솔 출력을 검색합니다.

모든 사용자 입력을 사용자의 값으로 바꿉니다.


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

정리

다음을 실행하여 Deug 태스크를 중지하고 태스크 정의를 등록 취소합니다.


# 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 관리형 인스턴스 문제 해결에 대한 자세한 내용은 다음 리소스를 참조하세요.

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

AWS Fargate 제한 할당량

Amazon ECS 관리형 인스턴스 드레이닝 문제 해결