- Published on
pulumi aws provider 설정과 버전 관리 핵심 정리
- Authors
- Name
- Indo Yoon
pulumi aws provider는 Pulumi 프로그램이 선언한 AWS 리소스를 실제 API 호출로 옮겨 주는 플러그인입니다. 그래서 배포가 갑자기 실패하거나 예상하지 못한 교체가 계획에 잡힐 때 가장 먼저 확인해야 할 곳은 프로그램 코드가 아니라 provider 설정과 버전이에요. 이 글은 설치 경로, 자격 증명 전달 방식, 버전 고정 정책을 어떤 순서로 정리하면 좋은지 다뤄요.
한눈에 보기
Pulumi 엔진은 원하는 상태와 현재 상태를 비교해 변경 계획을 세우고, 그 계획을 실제 호출로 바꾸는 일은 provider가 맡아요. 즉 "무엇을 바꿀지"는 엔진이, "어떻게 바꿀지"는 provider가 결정하는 구조예요. 이 분업을 이해하면 오류 메시지가 어느 쪽에서 나온 것인지 빠르게 구분할 수 있어요.
- 설치: 언어별 패키지 의존성에 추가하면 실행 시점에 플러그인을 내려받아요.
- 자격 증명: 환경 변수, 스택 설정, AWS 프로필, IAM 역할 같은 경로로 전달해요.
- 리전: 스택 설정에 명시해 두면 실행 환경이 달라져도 같은 결과가 나와요.
- 버전: 선언과 잠금 파일로 고정하고, 올릴 때는 별도 브랜치에서 먼저 확인해요.
- 상태: 리소스의 실제 식별자는 상태 백엔드에 남고 코드에는 속성만 남아요.
pulumi aws provider가 하는 일
Pulumi 프로그램은 원하는 상태를 코드로 선언하고, 엔진은 이전에 기록된 상태와 비교해 변경 계획을 만들어요. 이때 provider는 리소스 타입별 스키마와 생성·조회·수정·삭제 동작을 제공하고, 호출 결과로 받은 실제 식별자를 상태에 기록해요. 그래서 코드에는 리전과 이름 같은 속성만 남고, 실제로 발급된 식별자는 상태 파일 쪽에 저장되는 구조예요.
provider는 입력값 검증과 기본값 적용도 담당해요. 이름을 생략했을 때 자동으로 붙는 규칙이나 서로 배타적인 속성 조합을 걸러내는 작업이 여기에서 이뤄져요. 그래서 같은 프로그램이라도 provider 버전이 달라지면 검증 규칙이 바뀌면서 미리보기 결과가 달라질 수 있어요.
AWS provider는 Pulumi CLI나 언어 런타임과 별도로 배포되고 버전이 매겨져요. 필요하면 스택마다 다른 버전을 쓰는 것도 가능하지만, 그만큼 "지금 이 스택이 어떤 버전을 쓰는지"를 저장소에서 확인할 수 있게 관리하는 편이 좋아요.
자격 증명과 리전 설정 비교
자격 증명을 어디에 두느냐에 따라 재현성과 보안 속성이 크게 달라져요. 아래 표는 공식 문서에서 안내하는 대표적인 경로를 상황별로 정리한 것이에요.
| 설정 방식 | 지정 위치 | 잘 맞는 상황 | 유의할 점 |
|---|---|---|---|
| 환경 변수 | 실행 셸 또는 파이프라인 잡 환경 | 임시 실행, 로컬 실험 | 셸마다 값이 달라 재현이 어려워요 |
| Pulumi 설정 | pulumi config set aws:region | 스택 단위 기본값 고정 | 민감한 값은 시크릿으로 저장해야 해요 |
| AWS 프로필 | 공유 자격 증명 파일의 프로필 이름 | 여러 계정을 오가는 개발 | 파일이 없는 실행 환경에서는 쓸 수 없어요 |
| IAM 역할 | 실행 주체에 연결된 역할 | 서버·파이프라인에서 장기 키 없이 배포 | 권한 범위를 좁혀 두지 않으면 위험해요 |
| 공유 자격 증명 파일 | 로컬 홈 디렉터리 | 데스크톱 개발 | 컨테이너 이미지에는 보통 들어 있지 않아요 |
리전은 자격 증명과 별개 항목이에요. 스택 설정에 리전을 넣어 두면 같은 프로그램을 다른 리전에서 실험할 때 코드를 고치지 않아도 돼요.
단계별 설정 방법
첫 단계는 프로젝트 의존성에 provider를 추가하는 일이에요. 언어별 패키지 관리자로 AWS 패키지를 설치하면 되고, 어떤 언어를 쓰든 리소스 타입 앞에 붙는 접두사는 같아요. 이 선언이 곧 버전 범위를 정하는 지점이므로 여기에서 느슨한 범위를 쓰지 않는 편이 좋아요.
두 번째는 리전 지정이에요. pulumi config set aws:region 형태로 스택 설정에 넣고, 이 값이 저장소에 함께 남도록 설정 파일을 커밋해요. 코드에 리전을 하드코딩하면 스택을 복제해 다른 리전을 시험할 때 프로그램을 고쳐야 해요.
세 번째는 자격 증명 전달이에요. 로컬에서는 프로필, 파이프라인에서는 실행 주체에 연결된 역할을 쓰는 식으로 환경별로 나눠요. 한 스택에서 여러 경로가 동시에 살아 있으면 어느 값이 실제로 쓰였는지 추적하기 어려워지므로, 환경마다 한 가지 경로만 남기는 편이 안전해요.
네 번째는 미리보기로 확인하는 일이에요. pulumi preview는 실제 변경 없이 계획만 보여 주고, 새로 만드는 리소스와 교체되는 리소스, 삭제되는 리소스를 구분해서 알려 줘요. 교체 표시가 붙은 리소스는 서비스 중단으로 이어질 수 있으니 여기에서 한 번 멈추는 습관이 필요해요.
다섯 번째는 스택 분리예요. 개발·스테이징·운영을 스택으로 나누고 각 스택에 설정을 따로 넣으면, 설정 변경이 코드 리뷰 대상이 되고 배포 이력도 스택 단위로 남아요.
상황별 선택 가이드
로컬 개발에서는 프로필과 스택 설정 조합이 가장 다루기 쉬워요. 자격 증명 파일을 이미 관리하고 있다면 새로 만들 것이 없고, 리전만 스택에 고정하면 실수로 다른 리전에 리소스를 만드는 일을 줄일 수 있어요.
파이프라인에서는 실행 주체에 연결된 역할을 쓰는 방식이 권장돼요. 액세스 키를 저장소나 파이프라인 변수에 두지 않아도 되고, 권한은 역할 쪽에서 조정할 수 있어요. 배포 잡마다 역할을 나누면 운영 스택에만 강한 권한을 주는 구성도 가능해요.
계정이나 리전을 한 프로그램에서 함께 다뤄야 한다면 provider 별칭을 써요. 기본 provider는 하나만 두고, 예외가 필요한 리소스에만 별칭이 붙은 provider를 지정하면 리소스마다 리전을 명시하는 번거로움을 줄일 수 있어요. 다만 별칭 이름이 바뀌면 상태 해석이 어긋날 수 있으니 한 번 정한 이름은 유지하는 편이 좋아요.
이미 다른 도구로 관리하던 리소스를 넘겨받는 상황이라면 가져오기 절차를 먼저 익혀 두세요. 선언만 추가하면 새로 만들려고 하므로, 기존 리소스의 식별자를 지정해 상태에 연결하는 단계가 필요해요.
주의할 점
버전 범위를 느슨하게 두면 어느 시점부터 미리보기 결과가 달라질 수 있어요. 잠금 파일을 저장소에 커밋하고, 올릴 때는 별도 브랜치에서 미리보기 결과를 비교한 뒤 병합하는 절차를 권해요.
자격 증명 경로가 여러 개 살아 있는 상태도 흔한 사고 원인이에요. 로컬 셸에 남은 환경 변수와 스택 설정이 동시에 존재하면, 의도한 계정이 아닌 곳에 리소스가 만들어질 수 있어요.
상태 백엔드 위치도 함께 정해야 해요. 팀 단위로 운영한다면 잠금과 이력이 남는 원격 백엔드를 쓰고, 접근 권한을 배포 주체와 좁혀 두세요.
삭제 보호와 교체 동작은 리소스 속성에 따라 갈려요. 이름이나 일부 네트워크 속성을 바꾸면 같은 리소스가 교체 대상으로 잡힐 수 있으므로, 미리보기에서 교체 표시를 확인하는 절차를 생략하지 않는 편이 좋아요.
자주 묻는 질문
pulumi aws provider 버전은 어떻게 고정하나요?
프로젝트 의존성 선언과 패키지 관리자의 잠금 파일로 고정해요. 잠금 파일을 저장소에 커밋해 두면 다른 개발자와 파이프라인이 같은 버전을 쓰게 되고, 올릴 때는 의존성만 바꾼 별도 변경으로 분리해 미리보기 결과를 비교할 수 있어요.
자격 증명이 적용되지 않을 때는 무엇을 먼저 확인해야 하나요?
실행 셸에 남아 있는 환경 변수와 스택 설정 중 어느 쪽이 우선하는지부터 확인해요. 그다음 사용 중인 프로필 이름이 실제 파일에 존재하는지, 파이프라인이라면 실행 주체에 역할이 연결되어 있는지를 차례로 점검하면 원인을 좁힐 수 있어요.
스택마다 다른 리전을 쓰려면 어떻게 하나요?
스택 설정에 리전을 넣고 스택별로 값을 다르게 지정해요. 한 프로그램 안에서 여러 리전을 함께 다뤄야 한다면 기본 provider는 그대로 두고, 예외가 필요한 리소스에만 별칭을 붙인 provider를 연결하는 방식이 관리하기 쉬워요.
Terraform용 AWS provider와 무엇이 다른가요?
리소스 스키마와 API 호출을 담당한다는 점은 비슷하지만, Pulumi에서는 언어 런타임 안에서 프로그램을 작성하고 엔진이 상태와 변경 계획을 관리해요. provider 자체도 독립적으로 배포되므로, 기존에 쓰던 개념을 그대로 옮기기보다는 현재 스택의 버전과 설정을 기준으로 판단하는 편이 좋아요.
출처
- Pulumi AWS provider 레지스트리: https://www.pulumi.com/registry/packages/aws/
- Pulumi AWS provider 설치 및 설정 안내: https://www.pulumi.com/registry/packages/aws/installation-configuration/
- Pulumi provider 개념 문서: https://www.pulumi.com/docs/iac/concepts/providers/
배포 파이프라인에서 자격 증명을 어떤 주체에 맡기고 권한을 어디까지 좁힐지는 provider 설정만큼 중요해요. 역할 기반으로 배포 주체를 분리하고 스택별 권한을 정리하는 방법은 AWS 배포 자격 증명 관리 글에서 이어서 확인할 수 있어요.