[AWS] ECS EC2 인스턴스가 클러스터에 등록되지 않는 문제 해결 (feat. ecs-agent 무한 대기)

이 글은 Velog에서 이전한 글입니다. Velog 원문 보기

해당 이슈는 Launch Template, user_data, IAM, 네트워크 설정이 모두 정상인 상태에서
ECS Optimized AMI 내부의 ecs-init가 ECS Agent 이미지를 준비(pull 및 기동)하는 과정에서
비정상적으로 대기(blocking) 상태에 빠지며 발생한 문제였다.

---

1. 문제 요약

ECS EC2 기반 클러스터에서 서비스 배포 시 다음 오류가 발생했다.

service sandbox-app-svc was unable to place a task because
no container instance met all of its requirements.
The reason for failure is:
No Container Instances were found in your capacity provider.

• ECS Service는 정상적으로 생성됨
• 하지만 Task는 단 한 개도 실행되지 않음
• ECS Cluster에 Container Instance가 전혀 등록되지 않은 상태

---

2. 관찰된 주요 증상

ECS / AWS 콘솔

• ECS Cluster: sandbox-ecs-cluster
• Capacity Provider 연결 상태: 정상
• ECS Service 이벤트:
  • 실패 메시지 1건만 존재
• 실패한 Task 자체가 생성되지 않음
  • 즉, Task placement 단계까지 도달하지 못함

---

ECS Container Instance 조회

aws ecs list-container-instances --cluster sandbox-ecs-cluster

{
  "containerInstanceArns": []
}

→ EC2는 존재하지만 ECS에 등록되지 않음

---

EC2 인스턴스 내부 상태

cat /etc/ecs/ecs.config
ECS_CLUSTER=sandbox-ecs-cluster

systemctl status ecs
Active: inactive (dead)

journalctl -u ecs
-- No entries --

docker ps | grep ecs
(출력 없음)

관찰 정리

• Docker 데몬: 정상 실행
• 네트워크(STS, ECS endpoint): 정상 통신
• IAM Role / Instance Profile: 정상 부여
• ecs-agent 컨테이너 자체가 존재하지 않음

---

3. 원인 분석 (결론)

❌ 문제가 아니었던 것들

• 네트워크 설정 문제 아님 (STS / ECS endpoint 정상)
• IAM 권한 문제 아님 (ecsInstanceRole 정상)
• user-data 미실행 문제 아님
• AMI 타입 문제 아님 (Amazon Linux 2 ECS Optimized AMI 사용)

---

✅ 실제 원인

ecs-init의 ECS Agent 이미지 준비 단계에서의 비정상적인 대기(blocking) 동작

• ECS EC2 인스턴스에서 ECS Agent는 Docker 컨테이너로 실행됨
• ecs-init은 부팅 시 다음 단계를 수행함:

1. Docker 상태 확인
2. /etc/ecs/ecs.config 로드
3. ECS Agent 이미지 pull
4. ECS Agent 컨테이너 실행
5. Agent가 healthy 상태가 될 때까지 대기

문제는 3~4번 단계에서 발생했다.

• ECS Agent 이미지 pull 또는 초기 기동이 지연/실패
• ecs-init은 이를 fatal error로 처리하지 않음
• systemd는 unit이 ready 상태가 되기를 계속 대기
• 결과적으로 ecs.service는 시작되지 않은 상태로 남음

---

이미지 경로 관련 오해 정리

정상적으로 사용해야 하는 ECS Agent 이미지 경로는 다음과 같다.

public.ecr.aws/ecs/amazon-ecs-agent:latest

일부 문서나 ecs-init 내부 구현에서는 아래와 같은 이름으로 컨테이너가 보이기도 한다.

amazon/amazon-ecs-agent:latest

이는 내부 태깅(alias) 또는 실행 방식에 따른 표현 차이로,
항상 잘못된 경로를 의미하는 것은 아니다.

이번 이슈의 본질은 이미지 이름 자체가 아니라,
ecs-init이 Agent 이미지 준비 단계에서 실패/지연 상황을 정상 종료하지 못하고
systemd와 함께 대기 상태에 빠지는 설계적 한계였다.

---

4. 왜 “무한 대기”처럼 보였는가?

내부 동작 흐름

내부 동작 흐름

1. ecs.service 시작
2. ecs-init 실행
3. Docker 상태 확인
4. ECS Agent 이미지 pull 및 초기 기동
5. Agent 컨테이너 health check 대기
6. ECS Cluster에 Container Instance 등록

: 4~5번 단계에서 정상적으로 빠져나오지 못함

하지만 이 과정에서:

• ecs-init은 즉시 실패하지 않음
• systemd는 unit이 “아직 준비 중”이라고 판단
• 명시적인 에러 로그가 거의 남지 않음

그래서 다음과 같은 현상이 발생했다.

증상	설명
systemctl start ecs 반환 안 됨	unit이 ready 상태가 아님
journalctl -u ecs 비어 있음	docker pull 실패 로그 미노출
/var/log/ecs/ecs-agent.log 없음	agent 컨테이너 자체가 없음
ECS Container Instance 0개	등록 실패

결과적으로 ECS Agent 미기동 → Container Instance 미등록 상태가 지속되었다.

---

5. 해결 방법 (실제 수행)

1. ECS Agent 이미지 수동 확인 및 pull

sudo systemctl stop ecs
sudo docker pull public.ecr.aws/ecs/amazon-ecs-agent:latest

2. ECS 서비스 재기동

sudo systemctl start ecs

3. ECS Agent 컨테이너 실행 확인

sudo docker ps | grep ecs

public.ecr.aws/ecs/amazon-ecs-agent:latest   "/agent"   Up (health: starting)

• 수 초 내 healthy 상태로 전환됨

4. ECS Container Instance 등록 확인

aws ecs list-container-instances --cluster sandbox-ecs-cluster

→ Container Instance 정상 등록됨
→ ECS Service 배포 성공

---

6. 최종 원인 한 줄 요약

ECS Optimized AMI 내부의 ecs-init이
ECS Agent 이미지 준비 단계에서 실패/지연을 정상 종료하지 못하고
systemd와 함께 대기 상태에 빠지면서
ECS EC2 인스턴스가 클러스터에 등록되지 않았다.

---

7. 재발 방지 가이드 (필수)

핵심은 user-data에서 ecs-init의 블로킹을 유발하지 않는 것이다.

권장 user-data 패턴

#!/bin/bash
set -euo pipefail

cat <<EOF > /etc/ecs/ecs.config
ECS_CLUSTER=${cluster_name}
ECS_AGENT_IMAGE=public.ecr.aws/ecs/amazon-ecs-agent:latest
EOF

systemctl enable ecs

# docker가 준비된 이후에만 ecs를 start (블로킹 방지)
(
  until systemctl is-active docker; do
    sleep 2
  done
  systemctl start ecs
) &

• restart 사용 ❌ (stop 포함 → 블로킹 위험)
• docker 준비 이후에만 start
• 백그라운드 실행으로 cloud-init 블로킹 방지

운영 시 체크 포인트

• ECS Optimized AMI 사용 여부
• ecs-init 동작 방식 이해
• ECS Agent 이미지 경로 명시 여부
• Service/Task 이전에 Container Instance 상태부터 확인

---

8. 느낀점

• ECS EC2 문제에서는 Service / Task보다 먼저 볼 것
  • ECS Container Instance
• 로그가 없을수록
  • “컨테이너 자체가 안 떠 있다”를 의심해야 함
• ecs-init + systemd 조합은
  • 실패 로그가 매우 불친절
• ECS EC2 장애의 상당수는
  • “ECS 문제가 아니라 EC2 문제”였다