본문으로 건너뛰기

[ECR] Amazon ECR 리포지토리 생성 및 이미지 푸시 가이드

Prerequisite​

본 가이드를 진행하기 전에 다음 항목이 준비되어 있어야 합니다:

  • AWS 계정 접근 권한: ECR 리포지토리를 생성할 수 있는 IAM 권한이 필요합니다.
  • Docker 설치: 로컬 환경에 Docker가 설치되어 있어야 합니다.
    • macOS: Docker Desktop 설치
    • Windows: Docker Desktop 설치
    • 설치 확인: 터미널에서 docker --version 명령어 실행
  • AWS CLI 설치 및 구성: AWS 명령줄 도구가 설치되고 자격 증명이 설정되어 있어야 합니다.
    • 설치 확인: aws --version
    • 자격 증명 설정: aws configure
  • Docker 이미지 준비: ECR에 업로드할 Docker 이미지가 로컬에 빌드되어 있거나 빌드 가능한 상태여야 합니다.

알아두기​

ECR(Elastic Container Registry)이란?

  • AWS에서 제공하는 Docker 컨테이너 이미지를 저장하고 관리하는 서비스입니다.
  • Docker Hub와 유사하지만 AWS 환경과 완벽하게 통합되어 있습니다.
  • Private 저장소로 운영되어 보안이 강화됩니다.

주요 용어

  • 리포지토리(Repository): Docker 이미지를 저장하는 공간 (예: my-app, web-server)
  • 이미지 태그(Tag): 이미지의 버전을 구분하는 레이블 (예: latest, v1.0, prod)
  • 레지스트리 URI: ECR 리포지토리의 주소 (예: 123456789012.dkr.ecr.ap-northeast-2.amazonaws.com)

Process​

1. ECR 리포지토리 생성​

AWS 콘솔에서 ECR 리포지토리를 생성하는 단계입니다.

  1. AWS Management Console에 로그인합니다.

  2. 검색창에 **"ECR"**을 입력하거나 서비스 목록에서 Elastic Container Registry를 선택합니다.

  3. 왼쪽 메뉴에서 **프라이빗 레지스트리/리포지토리(Repositories)**를 클릭합니다.

  4. 우측 상단의 리포지토리 생성(Create repository) 버튼을 클릭합니다.

  5. 리포지토리 설정을 입력합니다:

   일반 설정

  • 리포지토리 이름(Repository name):
    • 간결한 이름을 입력합니다. 리포지토리는 네임스페이스를 지원하며, 이를 사용하여 유사한 리포지토리를 그룹화할 수 있습니다.
    • 이름은 문자로 시작해야 하며 소문자, 숫자 및 특수 문자(._-/)만 포함할 수 있습니다.
    • 최소 2자, 최대 256자까지 입력 가능합니다.
    • 예시: my-web-app, backend/api-server, frontend-app

(중요) 리포지토리 이름은 생성 후 변경할 수 없으므로 신중하게 정합니다.

이미지 태그 설정

  • 이미지 태그 변경 가능성(Tag mutability):
    • Mutable(변경 가능): 이미지 태그를 덮어쓸 수 있습니다. (기본값)
    • Immutable(변경 불가): 이미지 태그를 덮어쓸 수 없습니다. 동일한 태그로 푸시 시 에러가 발생합니다.

알아두기: 프로덕션 환경에서는 Immutable 설정을 권장하여 실수로 이미지가 덮어써지는 것을 방지할 수 있습니다.

  • 변경 가능한 태그 제외(Mutable tag exclusion) (선택사항):
    • 특정 태그 패턴을 변경 불가능하게 설정할 수 있습니다.
    • 와일드카드(*)를 사용하여 패턴을 지정합니다.
    • 예시: prod-*, release-* 등의 프로덕션 관련 태그만 보호

암호화 설정

  • 암호화 구성(Encryption configuration):
    • AES-256 (기본값, 권장): 업계 표준 Advanced Encryption Standard (AES) 암호화를 사용합니다.
    • AWS KMS: AWS Key Management Service(KMS)에 저장된 키를 사용하여 리포지토리의 이미지를 암호화합니다.

(Notice) 리포지토리 생성 후에는 암호화 설정을 변경할 수 없습니다.

이미지 스캔 설정 - deprecated

  • 푸시할 때 스캔(Scan on push):
    • 활성화 시 리포지토리에 푸시된 후 각 이미지를 자동으로 보안 취약점 스캔을 수행합니다.
    • 비활성화 시 각 이미지 스캔을 수동으로 시작해야 합니다.

(Notice) 이 설정은 deprecated(사용 중단 예정)되었으며, 레지스트리 수준 구성으로 이동되었습니다. 새로운 방식의 스캔 설정은 ECR 레지스트리 설정에서 리포지토리 필터링을 통해 구성할 수 있습니다.

  1. 하단의 리포지토리 생성(Create repository) 버튼을 클릭합니다.  
  2. 생성이 완료되면 리포지토리 목록에서 새로 생성된 리포지토리를 확인할 수 있습니다.

2. 리포지토리 URI 확인​

생성된 리포지토리의 주소를 확인하는 단계입니다.

  1. 리포지토리 목록에서 방금 생성한 리포지토리 이름을 클릭합니다.

  2. 상단의 URI 정보를 확인하고 복사합니다.

URI 형식: [AWS계정ID].dkr.ecr.[리전].amazonaws.com/[리포지토리명]

예시: 123456789012.dkr.ecr.ap-northeast-2.amazonaws.com/my-web-app

[스크린샷]

(Notice) 이 URI는 이미지 태그 작업과 푸시 작업에 필요하므로 메모장에 복사해 둡니다.

3. Docker 이미지 준비​

ECR에 업로드할 Docker 이미지를 준비합니다.

기존 이미지가 있는 경우

  1. 터미널에서 로컬 Docker 이미지 목록을 확인합니다.

docker images

예시 출력:

REPOSITORY TAG IMAGE ID CREATED SIZE my-app latest abc123def456 2 hours ago 500MB

새로운 이미지를 빌드하는 경우

  1. Dockerfile이 있는 디렉토리로 이동합니다.

cd /path/to/your/project

  1. Docker 이미지를 빌드합니다.

docker build -t [이미지명] .

예시:

docker build -t my-web-app .

  1. 빌드가 완료되면 이미지를 확인합니다.

docker images

4. ECR 인증 (Docker Login)​

Docker 클라이언트가 ECR에 접근할 수 있도록 인증하는 단계입니다.

  1. 터미널에서 다음 명령어를 실행하여 ECR 로그인을 수행합니다.

AWS CLI v2 사용 (권장)

aws ecr get-login-password --region [리전명] | docker login --username AWS --password-stdin [AWS계정ID].dkr.ecr.[리전명].amazonaws.com

예시:

aws ecr get-login-password --region ap-northeast-2 | docker login --username AWS --password-stdin 123456789012.dkr.ecr.ap-northeast-2.amazonaws.com

  1. 로그인 성공 시 Login Succeeded 메시지가 출력됩니다.

(중요) 이 인증은 12시간 동안 유효하며, 만료 시 다시 로그인해야 합니다.

5. Docker 이미지 태그 지정​

로컬 이미지에 ECR 리포지토리 주소로 태그를 추가합니다.

  1. 다음 형식으로 이미지에 태그를 지정합니다.

docker tag [로컬이미지명]:[태그] [ECR리포지토리URI]:[태그]

예시:

docker tag my-web-app:latest 123456789012.dkr.ecr.ap-northeast-2.amazonaws.com/my-web-app:latest

버전별 태그 예시:

docker tag my-web-app:latest 123456789012.dkr.ecr.ap-northeast-2.amazonaws.com/my-web-app:v1.0.0

  1. 태그가 정상적으로 지정되었는지 확인합니다.

docker images

예시 출력:

REPOSITORY TAG IMAGE ID CREATED SIZE my-web-app latest abc123def456 2 hours ago 500MB 123456789012.dkr.ecr.ap-northeast-2.amazonaws.com/my-web-app latest abc123def456 2 hours ago 500MB

6. ECR에 이미지 푸시​

태그가 지정된 이미지를 ECR 리포지토리로 업로드합니다.

  1. 다음 명령어로 이미지를 푸시합니다.

docker push [ECR리포지토리URI]:[태그]

예시:

docker push 123456789012.dkr.ecr.ap-northeast-2.amazonaws.com/my-web-app:latest

  1. 푸시 진행 상황이 터미널에 표시됩니다.

The push refers to repository [123456789012.dkr.ecr.ap-northeast-2.amazonaws.com/my-web-app] abc123def: Pushed 456789ghi: Pushed latest: digest: sha256:1234567890abcdef... size: 2421

(Notice) 이미지 크기에 따라 업로드 시간이 소요될 수 있습니다. 네트워크 상태를 확인하세요.

7. ECR 콘솔에서 이미지 확인​

업로드된 이미지를 AWS 콘솔에서 확인합니다.

  1. AWS 콘솔의 ECR 서비스로 돌아갑니다.

  2. 리포지토리 목록에서 해당 리포지토리를 클릭합니다.

  3. 이미지(Images) 탭에서 업로드된 이미지를 확인할 수 있습니다.

표시 정보:

  • 이미지 태그
  • 푸시된 시간
  • 이미지 크기
  • 취약점 스캔 결과 (스캔이 활성화된 경우)

8. ECR 이미지 풀(Pull) 및 실행​

ECR에 저장된 이미지를 다른 환경(다른 PC, EC2 인스턴스 등)에서 가져와 사용하는 단계입니다.

ECR 로그인

  1. 이미지를 가져올 환경에서 터미널을 열고 ECR에 로그인합니다.

aws ecr get-login-password --region [리전명] | docker login --username AWS --password-stdin [AWS계정ID].dkr.ecr.[리전명].amazonaws.com

예시:

aws ecr get-login-password --region ap-northeast-2 | docker login --username AWS --password-stdin 123456789012.dkr.ecr.ap-northeast-2.amazonaws.com

  1. Login Succeeded 메시지가 출력되면 로그인 성공입니다.

이미지 풀(Pull)

  1. ECR 리포지토리에서 이미지를 로컬로 다운로드합니다.

docker pull [ECR리포지토리URI]:[태그]

예시:

docker pull 123456789012.dkr.ecr.ap-northeast-2.amazonaws.com/my-web-app:latest

  1. 다운로드가 완료되면 로컬 이미지 목록을 확인합니다.

docker images ```

예시 출력: ``` REPOSITORY TAG IMAGE ID CREATED SIZE 123456789012.dkr.ecr.ap-northeast-2.amazonaws.com/my-web-app latest abc123def456 2 hours ago 500MB

이미지 실행

  1. 다운로드한 이미지를 컨테이너로 실행합니다.

docker run -d -p [호스트포트]:[컨테이너포트] [ECR리포지토리URI]:[태그]

예시:

docker run -d -p 80:80 123456789012.dkr.ecr.ap-northeast-2.amazonaws.com/my-web-app:latest

옵션 설명:

  • -d: 백그라운드에서 컨테이너 실행 (detached mode)
  • -p 80:80: 호스트의 80번 포트를 컨테이너의 80번 포트로 연결
  1. 실행 중인 컨테이너를 확인합니다.

docker ps ```

예시 출력: ``` CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES abc123def456 123456789012.dkr.ecr.ap-northeast-2.amazonaws.com/my-web-app:latest "docker-entrypoint.s…" 5 seconds ago Up 4 seconds 0.0.0.0:80->80/tcp amazing_curie

Trouble Shooting​

no basic auth credentials​

증상: docker push 실행 시 no basic auth credentials 에러 발생

원인: ECR 로그인이 만료되었거나 로그인을 하지 않은 상태입니다.

해결 방법:

  1. ECR 로그인 명령어를 다시 실행합니다.

aws ecr get-login-password --region ap-northeast-2 | docker login --username AWS --password-stdin 123456789012.dkr.ecr.ap-northeast-2.amazonaws.com

denied: Your authorization token has expired

증상: 이미지 푸시 중 authorization token 만료 에러 발생

원인: ECR 인증 토큰은 12시간 동안만 유효하며, 그 이후에는 재로그인이 필요합니다.

해결 방법:

  1. ECR에 다시 로그인합니다.

aws ecr get-login-password --region ap-northeast-2 | docker login --username AWS --password-stdin 123456789012.dkr.ecr.ap-northeast-2.amazonaws.com

Repository does not exist​

증상: 이미지 푸시 시 리포지토리가 존재하지 않는다는 에러 발생

원인:

  • ECR 콘솔에서 리포지토리를 생성하지 않았습니다.
  • 리포지토리 이름이나 리전이 잘못되었습니다.

해결 방법:

  1. ECR 콘솔에서 리포지토리가 생성되어 있는지 확인합니다.
  2. 리전이 올바른지 확인합니다 (예: ap-northeast-2).
  3. 리포지토리 이름의 대소문자와 철자를 정확히 확인합니다.

​

retrying in ... seconds

증상: 이미지 푸시가 매우 느리거나 계속 재시도됩니다.

원인: 네트워크 연결이 불안정하거나 이미지 크기가 매우 큽니다.

해결 방법:

  1. 네트워크 연결 상태를 확인합니다.
  2. .dockerignore 파일을 활용하여 불필요한 파일을 제외하고 이미지 크기를 줄입니다.
  3. 안정적인 네트워크 환경에서 다시 시도합니다.

​

Cannot connect to the Docker daemon

증상: docker 명령어 실행 시 Docker daemon 연결 에러 발생

원인: Docker가 실행되고 있지 않습니다.

해결 방법:

  1. Docker Desktop을 실행합니다 (macOS/Windows).
  2. Linux의 경우 Docker 서비스를 시작합니다:

sudo systemctl start docker

또 다른 질문이 있으십니까? 문의 등록

Copyright © NxtCloud. All rights reserved.

본 문서는 넥스트클라우드(NxtCloud)의 지적 재산으로 보호됩니다. 넥스트클라우드의 서면 동의 없이 본 문서의 전체 또는 일부를 무단으로 복제, 배포, 전송, 게시하거나 2차적 저작물을 작성하는 것을 금지합니다.

문의: support@nxtcloud.kr