이미지 풀 실패(Cannot pull image) 해결

이미지 풀 실패(Cannot pull image) 해결

Amazon ECS 태스크가 컨테이너 이미지를 가져오지 못하면 태스크가 시작에 실패해요. 이미지 풀 실패의 원인과 해결 방법을 알아보세요.

출처: 문서

본문

태스크가 시작될 때 컨테이너 에이전트가 이미지 레지스트리에서 이미지를 가져오지(pull) 못하면 CannotPullContainerError 오류가 발생해요. 이 경우 태스크가 STOPPED 상태가 됩니다.

일반적인 원인

이미지 풀 실패는 다음 이유로 발생할 수 있어요:

  • 잘못된 이미지 태그 또는 이름 – 이미지 URI의 태그가 존재하지 않거나 오타가 있어요.
  • 레지스트리 권한 부족 – Amazon ECR 같은 프라이빗 레지스트리의 이미지를 가져오려면 태스크 실행 역할(task execution role)에 ecr:GetAuthorizationToken, ecr:BatchGetImage 권한이 필요해요.
  • 인증 실패 – 프라이빗 레지스트리 자격 증명이 올바르지 않아요.
  • 네트워크 문제 – 레지스트리에 접근할 수 없는 경우(예: VPC 엔드포인트 누락).
  • 이미지 크기/형식 문제 – 일부 런타임 구성과 호환되지 않는 이미지.

해결 방법

  1. 이미지 URI와 태그가 올바른지 확인해요.
  2. 태스크 실행 역할에 ECR 권한이 있는지 확인해요.
  3. ECR 사용 시 ecr:GetAuthorizationToken을 포함한 필수 권한을 부여해요.
  4. 프라이빗 레지스트리를 사용한다면 자격 증명(credentialsParameter)이 올바른지 확인해요.
  5. VPC에서 레지스트리에 접근할 수 있는지(인터넷 게이트웨이 또는 VPC 엔드포인트) 확인해요.

더 알아보기 (Learn more)