- Published on
pulumi awsx.ecr image: ECR 이미지 빌드와 배포 이해
- Authors
- Name
- Indo Yoon
pulumi awsx.ecr image는 AWSX에서 ECR 이미지를 빌드하고 푸시한 뒤, 배포에 쓸 이미지 URI를 제공하는 리소스예요. 핵심은 repositoryUrl과 빌드 경로를 정확히 연결하고, ECS 같은 서비스의 image 값에 그 결과를 넘기는 것이에요. 이 글은 공식 문서에서 확인한 범위 안에서 개념, 절차, 선택 기준을 정리해요.
한눈에 보기
awsx.ecr.Image는 Dockerfile이 있는 디렉터리를 빌드 컨텍스트로 삼아 이미지를 만들고, 지정한 ECR 리포지토리에 푸시해요. 이 리소스는 ECR 리포지토리 자체를 새로 정의하는 역할보다, 이미 만들어진 리포지토리 주소에 이미지를 밀어 넣는 역할에 가까워요. 그래서 보통 awsx.ecr.Repository로 리포지토리를 준비한 뒤 그 url을 repositoryUrl에 넘겨요.
awsx.ecr.Image의 결과는 imageUri로 참조할 수 있어요. 이 값을 ECS 태스크 정의나 다른 컨테이너 실행 리소스의 이미지 값에 연결하면, Pulumi가 만든 이미지를 배포 흐름에서 바로 사용할 수 있어요. 다만 이미지 빌드와 푸시가 Pulumi 실행 환경의 Docker와 AWS 권한에 의존한다는 점은 미리 확인해야 해요.
비교 표
| 항목 | awsx.ecr.Image | 직접 빌드 후 참조 |
|---|---|---|
| 빌드 실행 | Pulumi 업데이트 과정에서 Docker 빌드와 푸시를 함께 처리해요. | CI나 로컬에서 빌드와 푸시를 먼저 끝내요. |
| Pulumi가 아는 값 | imageUri 출력으로 이미지 위치를 참조해요. | 이미지 URI나 다이제스트를 변수로 전달해요. |
| 적합한 상황 | 작은 서비스나 Pulumi 안에서 배포 흐름을 단순화할 때 좋아요. | 빌드 캐시, 보안 스캔, 다중 플랫폼 빌드를 CI에서 다룰 때 좋아요. |
| 주의점 | 실행 환경의 Docker와 AWS 권한을 확인해야 해요. | 이미지가 먼저 존재해야 하고 태그 불변성을 따로 관리해야 해요. |
표에서 보듯 두 방식은 이미지를 만드는 위치가 달라요. Pulumi가 빌드까지 맡으면 리소스 정의가 단순해지지만, 빌드 환경을 Pulumi 실행 환경과 맞춰야 해요. 반대로 CI가 빌드를 맡으면 배포 승인과 이미지 스캔을 분리하기 쉽지만, Pulumi는 이미지 URI만 참조하도록 역할을 나눠야 해요.
단계별 방법
먼저 ECR 리포지토리를 준비해요. awsx.ecr.Repository를 사용하면 리포지토리를 Pulumi 리소스로 관리할 수 있고, 이미지 리소스에는 그 url을 넘길 수 있어요. 리포지토리 이름과 리전, 계정이 포함된 주소를 직접 문자열로 넣기보다 리소스 출력을 사용하는 편이 안전해요.
다음으로 빌드 컨텍스트를 정리해요. path에는 Dockerfile과 빌드에 필요한 파일이 있는 디렉터리를 지정해요. Dockerfile 이름이나 위치가 일반적이지 않다면 dockerfile 옵션으로 따로 지정할 수 있어요. 빌드 인자가 필요하면 args를, 빌드 환경 변수가 필요하면 env를 검토해요.
import * as awsx from "@pulumi/awsx";
const repo = new awsx.ecr.Repository("app-repo");
const image = new awsx.ecr.Image("app-image", {
repositoryUrl: repo.url,
path: "./app",
});
export const imageUri = image.imageUri;
위 예시처럼 리포지토리와 이미지 리소스를 나눠 정의하면 역할이 분명해져요. 이미지 리소스는 path의 Dockerfile을 기준으로 빌드하고, 결과를 ECR에 푸시한 뒤 imageUri를 출력해요. 이 출력을 ECS 서비스나 태스크 정의 쪽에서 참조하도록 연결해요.
마지막으로 pulumi up을 실행해요. 이때 Pulumi 실행 환경에 Docker CLI가 준비되어 있어야 하고, ECR에 로그인하거나 푸시할 수 있는 AWS 자격 증명과 권한이 필요해요. 미리보기와 실제 업데이트에서 빌드가 언제 일어나는지도 함께 확인해요.
상황별 선택
Pulumi 안에서 이미지 빌드와 배포를 한 흐름으로 묶고 싶다면 awsx.ecr.Image가 잘 맞아요. 리포지토리, 이미지, 서비스 정의를 같은 코드베이스에서 관리할 수 있어서 작은 서비스나 초기 구성에서 특히 편해요.
이미 CI에서 이미지 빌드와 푸시를 안정적으로 처리하고 있다면 Pulumi는 이미지 URI만 참조하게 두는 편이 명확해요. 빌드 캐시, 이미지 스캔, 서명, 다중 플랫폼 빌드 같은 작업을 CI에 맡기고, Pulumi는 배포 대상 리소스를 관리하는 식이에요.
배포 재현성을 중요하게 본다면 태그보다 다이제스트를 고정하는 방식을 검토해요. 태그는 같은 이름으로 덮어쓸 수 있기 때문에, 운영 환경에서는 태그 불변성 설정이나 다이제스트 참조를 함께 고려하는 편이 좋아요.
주의할 점
awsx.ecr.Image는 Pulumi 실행 환경에서 Docker 빌드를 수행해요. 따라서 로컬에서 실행하든 CI 러너에서 실행하든 Docker CLI와 빌드에 필요한 도구가 준비되어 있는지 확인해야 해요.
ECR 푸시 권한도 중요해요. AWS 자격 증명이 올바르더라도 리포지토리에 이미지를 푸시할 권한이 없으면 배포가 중단될 수 있어요. 리포지토리 정책과 실행 역할을 함께 점검해요.
repositoryUrl에는 리포지토리 이름만 넣지 말고 ECR 리포지토리 주소를 넣어야 해요. awsx.ecr.Repository의 url 출력을 사용하면 이런 실수를 줄일 수 있어요.
빌드 컨텍스트가 너무 크면 빌드 시간과 전송량이 늘어날 수 있어요. .dockerignore를 정리하고, path 아래에 필요한 파일만 두는 습관이 좋아요.
배포 대상 아키텍처와 이미지 플랫폼이 맞는지도 확인해요. 특히 Graviton 같은 다른 아키텍처를 사용한다면 platform 옵션이나 CI 빌드 설정이 배포 환경과 일치해야 해요.
자주 묻는 질문
awsx.ecr.Image와 awsx.ecr.Repository는 어떻게 다른가요?
awsx.ecr.Image는 이미지 빌드와 푸시를 담당하고, awsx.ecr.Repository는 ECR 리포지토리 자체를 관리해요. 그래서 보통 리포지토리를 먼저 만들고 그 url을 이미지 리소스의 repositoryUrl에 넘겨요. 두 리소스의 역할을 나눠 이해하면 구성이 단순해져요.
repositoryUrl에는 무엇을 넣어야 하나요?
ECR 리포지토리의 주소를 넣어야 해요. 보통 awsx.ecr.Repository의 url 출력을 사용하고, 리포지토리 이름만 넣지 않도록 주의해요. 리전과 계정이 포함된 주소 형태인지 확인하면 좋아요.
Pulumi 실행 환경에 Docker가 꼭 필요한가요?
awsx.ecr.Image를 쓰면 Pulumi 실행 환경에서 Docker 빌드가 일어나요. 따라서 로컬이나 CI 러너에 Docker CLI가 준비되어 있어야 하고, ECR 푸시 권한도 필요해요. 이미지를 다른 단계에서 빌드한다면 AWSX 이미지 리소스 대신 URI 참조 방식을 검토해요.
이미지 태그가 계속 바뀌면 어떻게 관리하나요?
태그가 계속 바뀌면 배포 재현성이 떨어질 수 있어요. ECR의 태그 불변성 설정이나 이미지 다이제스트 고정을 검토하고, 빌드 산출물을 CI에서 일관되게 관리해요. Pulumi는 그 결과 URI를 참조하도록 역할을 나누면 좋아요.
출처
관련 운영 글은 Pulumi AWS ECR 배포 운영 체크리스트에서 이어서 확인할 수 있어요. 이미지 빌드 위치, 권한 분리, 태그 운영을 함께 점검해 보세요.