Published on

pulumi aws native npm: 설치와 선택 기준

Authors
  • avatar
    Name
    Indo Yoon
    Twitter

pulumi aws native npm은 @pulumi/aws-native 패키지를 npm으로 설치해 AWS Cloud Control API 기반 리소스를 TypeScript로 정의하는 방법입니다. 기존 @pulumi/aws와 이름이 비슷하지만 리소스 스키마와 지원 범위가 다르므로, 설치 전에 필요한 리소스가 AWS Native에 있는지 확인해야 합니다. 아래에서는 공식 문서에서 확인할 수 있는 설치 절차와 선택 기준, 운영 시 주의할 점을 정리합니다.

한눈에 보기

pulumi aws native npm의 핵심은 언어 SDK와 Pulumi 공급자를 구분하는 것입니다. npm 패키지는 TypeScript와 JavaScript 코드에서 AWS 리소스를 선언할 수 있게 해 주고, 실제 AWS 리소스 생성은 Pulumi CLI가 공급자 플러그인을 통해 수행합니다. 따라서 패키지 설치만으로 배포가 끝나지 않으며 Pulumi 프로젝트, AWS 자격 증명, 스택 구성이 함께 필요합니다.

  • 패키지 이름: @pulumi/aws-native
  • 기반: AWS Cloud Control API와 CloudFormation 리소스 스키마
  • 코드 예: awsNative.s3.Bucket
  • 배포 명령: pulumi preview, pulumi up
  • 확인 위치: Pulumi Registry의 AWS Native 패키지 문서

AWS Native는 CloudFormation과 유사한 리소스 모델을 원하는 팀에 적합하고, 클래식 공급자는 기존 코드와 예제가 많은 환경에 적합합니다. 어느 쪽이 항상 우월하다고 단정할 수는 없으므로 리소스별 지원 여부와 마이그레이션 비용을 함께 봐야 합니다.

비교 표: AWS Native와 클래식 공급자

항목@pulumi/aws-native@pulumi/aws
패키지 성격AWS Cloud Control API 기반 공급자AWS API를 Pulumi 리소스로 감싼 클래식 공급자
리소스 스키마CloudFormation 리소스 스키마와 연결Pulumi가 관리하는 클래식 스키마
속성 이름CloudFormation 스키마에 가까운 이름클래식 공급자 고유 이름
지원 범위Cloud Control API가 지원하는 리소스 중심넓은 역사와 예제, 부가 기능
적합한 경우CloudFormation 정합성, 신규 리소스 추적기존 코드, 풍부한 예제, 마이그레이션
주의리소스별 지원 여부 확인AWS Native와 혼용 시 소유권 분리

표에서 보듯 AWS Native는 CloudFormation 스키마와의 정합성이 중요한 조직에 맞고, 클래식 공급자는 기존 운영 노하우를 그대로 활용하려는 조직에 맞습니다. 특히 같은 AWS 리소스라도 공급자에 따라 속성 이름과 기본값이 다를 수 있으므로, 선택 전에 Pulumi Registry에서 대상 리소스의 문서를 확인하는 편이 안전합니다.

단계별 방법: npm 설치부터 배포까지

먼저 Pulumi CLI가 설치된 환경에서 TypeScript 프로젝트를 준비합니다. 기존 프로젝트가 있다면 package.json이 있는 디렉터리에서 진행하고, 새 프로젝트라면 공식 템플릿으로 시작할 수 있습니다.

  • 프로젝트 준비: pulumi new typescript로 TypeScript 프로젝트를 만들거나 기존 Pulumi 프로젝트를 사용합니다. Pulumi CLI와 AWS 자격 증명이 준비되어 있어야 합니다.
  • 패키지 설치: 프로젝트 디렉터리에서 AWS Native SDK를 설치합니다.
npm install @pulumi/aws-native
  • 리전과 자격 증명 설정: pulumi config set aws-native:region ap-northeast-2처럼 리전을 지정합니다. AWS 자격 증명은 환경 변수, AWS 프로파일, 역할 수임 등 AWS SDK가 지원하는 방식으로 준비합니다.
  • 리소스 선언: TypeScript 파일에서 AWS Native 패키지를 가져와 리소스를 선언합니다.
import * as awsNative from "@pulumi/aws-native";

const bucket = new awsNative.s3.Bucket("site-assets", {
    bucketName: "example-site-assets",
});

export const bucketName = bucket.bucketName;
  • 미리보기와 배포: pulumi preview로 변경 계획을 확인하고, 문제가 없으면 pulumi up을 실행합니다. 스택 상태는 Pulumi 백엔드에 저장되므로 팀 작업에서는 백엔드 위치와 접근 권한을 먼저 정해야 합니다.
  • 정리: 실습 스택은 pulumi destroy로 리소스를 제거합니다. 실제 운영 스택에서는 리소스 보호 옵션과 상태 백업 정책을 함께 검토합니다.

npm 패키지는 코드에서 사용할 SDK이고, 실제 공급자 플러그인은 Pulumi가 실행 과정에서 준비해 사용합니다. 따라서 package.json의 의존성과 Pulumi 스택 구성이 함께 버전 관리되어야 재현 가능한 배포를 만들 수 있습니다.

상황별 선택

새 프로젝트에서 CloudFormation 스키마와 같은 리소스 모델을 원한다면 AWS Native를 먼저 검토할 수 있습니다. AWS Cloud Control API가 다루는 리소스를 코드로 선언하고, Pulumi Registry에서 해당 리소스의 문서와 속성을 확인할 수 있다면 선택지가 됩니다.

반대로 기존 @pulumi/aws 코드가 많거나, AWS Native에서 아직 다루지 않는 리소스와 속성이 필요하거나, 커뮤니티 예제와 기존 운영 노하우를 그대로 쓰고 싶다면 클래식 공급자가 현실적입니다. 마이그레이션은 리소스별 차이를 확인한 뒤 단계적으로 진행하는 편이 안전합니다.

혼용도 가능합니다. 예를 들어 네트워크는 클래식 공급자로, 특정 신규 리소스는 AWS Native로 선언할 수 있습니다. 다만 같은 리소스를 AWS Native 공급자와 클래식 공급자 양쪽에서 관리하면 상태 충돌과 예기치 않은 삭제가 생길 수 있으므로, 리소스 소유권을 명확히 나누고 pulumi preview에서 교체 여부를 확인해야 합니다.

주의할 점

  • 패키지 이름 혼동: @pulumi/aws-native는 AWS Native SDK이고, @pulumi/aws는 클래식 공급자입니다. package.json과 import 문에서 패키지 이름을 다시 확인합니다.
  • 리소스 지원 범위: AWS Native는 AWS Cloud Control API가 지원하는 범위에 영향을 받습니다. 필요한 리소스와 속성이 Pulumi Registry에 있는지 먼저 확인합니다.
  • 속성 이름과 기본값: 클래식 공급자와 AWS Native는 같은 AWS 리소스라도 속성 이름, 기본값, 출력 이름이 다를 수 있습니다. 마이그레이션 시 pulumi preview의 diff를 반드시 읽습니다.
  • 기존 리소스 가져오기: Pulumi import를 사용할 수 있지만 리소스별 지원과 식별자 형식이 다를 수 있습니다. 가져오기 전에 문서와 preview로 상태를 확인합니다.
  • 자격 증명과 리전: AWS Native 공급자도 AWS 자격 증명이 필요합니다. CI에서는 장기 키를 코드에 넣지 말고 OIDC나 역할 기반 자격 증명을 검토합니다.
  • 상태 관리: Pulumi 스택 상태에는 리소스 메타데이터가 들어갑니다. 백엔드 접근 제어, 잠금, 백업을 운영 절차에 포함합니다.

자주 묻는 질문

pulumi aws native npm 패키지 이름은 무엇인가요?

npm에서 설치하는 패키지는 @pulumi/aws-native입니다. 코드에서는 보통 import * as awsNative from "@pulumi/aws-native" 형태로 가져옵니다. 패키지 이름에 pulumi와 aws-native가 함께 들어가므로 클래식 @pulumi/aws와 혼동하지 않아야 합니다.

기존 @pulumi/aws와 함께 사용할 수 있나요?

같은 Pulumi 프로젝트에서 AWS Native와 클래식 공급자를 함께 참조할 수 있습니다. 다만 같은 AWS 리소스를 양쪽에서 관리하지 않도록 소유권을 나누고, 배포 전에 pulumi preview로 교체와 삭제 계획을 확인해야 합니다. 기존 리소스를 옮길 때는 단계적으로 검증하는 편이 안전합니다.

AWS Native가 모든 AWS 리소스를 지원하나요?

아닙니다. AWS Native는 AWS Cloud Control API와 CloudFormation 리소스 스키마가 제공하는 범위의 영향을 받습니다. 필요한 리소스가 Pulumi Registry의 AWS Native 문서에 있는지 확인하고, 없으면 클래식 공급자나 다른 도구를 검토해야 합니다.

npm 설치만 하면 바로 배포할 수 있나요?

아닙니다. Pulumi CLI, Pulumi 스택, AWS 자격 증명, 리전 설정이 함께 필요합니다. 패키지는 코드에서 리소스를 선언하기 위한 SDK이고, 실제 배포는 pulumi preview와 pulumi up 같은 Pulumi 명령으로 진행합니다.

출처

관련 운영 글: Pulumi 스택 상태와 AWS 배포 운영 체크리스트에서 상태 백엔드, 자격 증명, 미리보기 중심 배포 습관을 함께 확인할 수 있습니다.

Discuss on Twitter • View on GitHub