지난 글에서는 git tag 푸시로 GitHub Actions => ECR push => ECS 롤링 배포가 되는 CI/CD 파이프라인을 구성했다.
이번 글에서는 구축 과정에서 실제로 마주쳤던 오류들을 증상 => 원인 => 확인 => 해결 순서로 정리했다.
같은 에러를 다시 만났을 때 해결 방법을 바로 떠올릴 수 있도록, 내가 확인했던 포인트까지 함께 정리했다.
0. 내 배포 구성
- Trigger:
git tag v0.0.1 && git push --tags - CI: GitHub Actions (OIDC)
- Image: Amazon ECR
- Runtime: Amazon ECS + Service 롤링 배포
- Secret: AWS Secrets Manager → Task Definition secrets.valueFrom 주입
- Log: CloudWatch Logs (awslogs)
1. 내가 확인한 정보들
나는 에러가 났을때 아래 정보들을 확인했다.
- GitHub Actions 로그: OIDC/권한, ECR push, ECS deploy 단계
- ECS Service 이벤트: 배포 실패 이유
- ECS Task 목록/상세: STOPPED 이유, exit code
- CloudWatch Logs: 스프링 부트 로그
2. 클러스터 생성 실패: Unable to assume the service linked role
클러스터 생성 중 아래 오류가 발생했다.
CreateCluster Invalid Request: Unable to assume the service linked role. Please verify that the ECS service linked role exists.
에러 로그
클러스터 service-cluster 생성 중 오류가 발생했습니다.
Resource handler returned message: "Invalid request provided: CreateCluster Invalid Request: Unable to assume the service linked role.
Please verify that the ECS service linked role exists. (Service: AmazonECS; Status Code: 400; Error Code: InvalidParameterException;
Request ID: c2aa1ff6-cda9-4955-84ae-ad63fb144861; Proxy: null)" (RequestToken: 3747083a-bed9-1901-3746-7539ec34229c, HandlerErrorCode: InvalidRequest)ECS가 내부적으로 사용하는 Service linked role이 계정에 없거나(삭제), ECS가 그 Role을 Assume 할 수 없는 상태다.
원인
- 현재 계정/권한 정책이 iam:CreateServiceLinkedRole 같은 작업을 막음
- 드물게 IAM 설정이 꼬여 Role이 있으나 ECS가 정상 assume 실패
확인 방법
IAM 콘솔 => Roles(역할)에서 아래 이름을 검색한다. AWSServiceRoleForECS
가 있는지 찾아본다.
해결 방법
Service linked role을 생성한다.
생성후에 클러스터 생성을 다시 시도하면 해결된다.
3. GitHub Actions 배포 실패: Error: Service is INACTIVE
GitHub Actions의 amazon-ecs-deploy-task-definition 단계에서 아래 에러가 났다.
Error: Service is INACTIVE
의미
워크플로우가 가리키는 ECS 서비스가 존재는 하되 INACTIVE 상태라는 뜻이다.
원인
- 서비스가 삭제되었거나
- 생성이 실패해서 활성화되지 못했거나
- 다른 이름/다른 클러스터를 가르키는데 변수만 남아있는 경우
확인 방법
- ECS 콘솔 → Cluster → Services에서 weblog-service가 ACTIVE인지 확인
- GitHub Variables의 ECS_CLUSTER, ECS_SERVICE가 콘솔 이름과 일치하는지 확인
나는 github variables에 이름 설정이 동일하지 않아 오류가 났었다.
해결
- 서비스가 없거나 비활성(INACTIVE)이면 서비스를 정상 생성한다.
- 서비스 이름이 바뀌었다면 GitHub Variables의 ECS_SERVICE를 최신으로 수정한다.
4. ECS 배포 실패: ECS Deployment Circuit Breaker was triggered
ECS 쪽 이벤트에서 아래 메시지가 보였다.
ECS Deployment Circuit Breaker was triggered
이 메시지는 ECS가 배포를 포기했다는 뜻이다. 원인은 task에 있다.
의미
배포된 새 태스크들이 정상 상태에 도달하지 못해서 ECS가 자동으로 배포를 중단한 것이다.
원인
- 태스크가 뜨자마자 죽는다 (컨테이너 exit)
- 헬스체크가 계속 실패한다 (ALB/컨테이너 헬스체크)
- 초기화 단계에서 막힌다 (Secrets/Logs/Pull 등 ResourceInitializationError)
해결
1. ECS → Service → Tasks 탭에서 STOPPED가 있는지 확인
2. STOPPED 태스크 클릭 → Stopped reason / Container exit code 확인
3. Container → CloudWatch logs 열기
4. 로그에서 원인을 확인하고 수정하기
5. 태스크가 계속 중지됨: Essential container in task exited + Exit code 1
Tasks 목록에서 반복적으로 아래 상태가 쌓였다.
Essential container in task exited
그리고 Task 상세에서 컨테이너가:
Stopped | 종료 코드: 1
의미
스프링 부트 컨테이너가 실행 직후 에러로 종료된 것이다.
서비스는 태스크를 유지해야 하므로 재기동을 반복하다가 배포가 실패한다.
원인
- DB 연결 실패 (보안그룹/URL/계정/비번)
- 환경변수 누락 (SPRING_DATASOURCE_URL, USERNAME 등)
- Secrets Manager 주입 실패로 필수 값이 비어있음
- 포트 불일치(앱이 8080인데 설정은 다른 포트 설정)
확인 방법
CloudWatch Logs에서 스프링이 왜 죽었는지를 보거나 태스크가 중단되었을때 태스크 로그에서 스프링 로그를 확인해보면 된다.
나의 경우에는 secret manager에서 ARN 키 지정을 잘못 사용해서 DB 연결이 실패해 저 오류가 났었다.
해결
- RDS 보안그룹 인바운드에 ECS 태스크 보안그룹을 Source로 허용했는지
- Task Definition의 DB URL/USERNAME이 정확한지
- 비밀번호는 environment가 아니라 secrets로 들어가며 ARN 포맷이 맞는지
- 포트 설정이 8080 기준으로 일치하는지
6. 초기화 단계에서 막힘: ResourceInitializationError: failed to validate ...
Tasks 목록에 아래처럼 뜨고 바로 STOPPED 됐다.
ResourceInitializationError: failed to validate ...
원인
- Secrets 주입 단계 실패
- CloudWatch Logs 설정 문제
- Execution Role의 ECR pull 권한 부족
확인 방법
STOPPED task를 클릭해 상세 메시지에서 secrets, logs, pull 키워드를 확인한다.
나의 경우는 task-definition에 awslog-group이름과 실제 log group 이름이 달라서 오류가 났었다.
해결 방향
- secrets 관련: Execution Role에 secretsmanager:GetSecretValue 추가, ARN/키 지정(:password::) 재확인
- logs 관련: Log Group 존재 여부, Execution Role의 logs 권한 및 region/이름 일치 확인
- pull 관련: ECR 권한 및 네트워크 점검
7. 결론
특히 권한이나 리소스 이름(서비스/클러스터/로그 그룹) 같은 기초 설정이 아주 조금만 달라도 배포가 전혀 안됬다.
나의 경우 문제가 생겼을 때는 바로 STOPPED task와 CloudWatch logs를 먼저 확인하는 것이 가장 빠르게 해결이 됬다.
