Published on

pulumi awsx npm 설치와 활용: AWS 인프라 구성 가이드

Authors
  • avatar
    Name
    Indo Yoon
    Twitter

pulumi awsx npm이라는 검색어는 결국 "Pulumi에서 AWS 리소스를 조금 더 짧은 코드로 정의하려면 npm 패키지 @pulumi/awsx를 어떻게 설치하고 쓰는가"로 좁혀집니다. 결론부터 말하면, Pulumi CLI와 Node.js 프로젝트를 준비한 뒤 npm install @pulumi/awsx로 패키지를 추가하고, VPC나 로드 밸런서, ECS 서비스 같은 상위 수준 컴포넌트를 코드에서 불러 쓰면 돼요. 이 글은 설치 순서와 최소 예시, 그리고 awsx를 쓰는 편이 나은 상황과 그렇지 않은 상황을 함께 정리해요.

한눈에 보기

pulumi awsx npm은 서로 다른 세 가지를 한 문장에 묶은 표현이에요. 첫째는 인프라를 코드로 관리하는 도구인 Pulumi, 둘째는 AWS 리소스를 상위 수준 컴포넌트로 감싼 AWSX 라이브러리, 셋째는 그 라이브러리를 배포하는 npm 패키지 @pulumi/awsx입니다.

  • 패키지 이름은 @pulumi/awsx이고, npm 공개 레지스트리에서 설치해요.
  • Pulumi CLI와 Node.js 런타임이 먼저 준비되어야 해요.
  • VPC, 로드 밸런서, ECS 서비스처럼 여러 리소스가 얽히는 구성을 적은 코드로 표현할 수 있어요.
  • 세밀한 옵션 제어가 필요한 부분은 @pulumi/aws의 개별 리소스를 섞어 쓰는 편이 안전해요.

즉 awsx는 Pulumi를 대체하는 도구가 아니라, Pulumi 위에서 동작하는 편의 계층이에요. 이 점을 먼저 잡아 두면 이후 선택 기준이 훨씬 단순해집니다.

@pulumi/awsx 패키지가 하는 일

Pulumi의 기본 AWS 프로바이더인 @pulumi/aws는 AWS API와 거의 일대일로 대응하는 리소스를 제공해요. 반면 @pulumi/awsx는 그 리소스들을 조합해 만든 컴포넌트를 제공합니다. 예를 들어 서브넷과 라우팅 테이블, 인터넷 게이트웨이를 각각 선언하는 대신 VPC 컴포넌트 하나로 시작할 수 있어요.

공식 문서 기준으로 awsx는 EC2, ECS, 로드 밸런서, API 게이트웨이 같은 영역의 컴포넌트를 제공하고, 예전 방식의 crosswalk 리소스는 classic 네임스페이스로 옮겨져 있어요. 그래서 오래된 예제를 그대로 붙여 넣으면 임포트 경로가 맞지 않아 오류가 나는 경우가 있어요. 예제를 참고할 때는 어떤 버전대의 문서인지 먼저 확인하는 습관이 필요합니다.

컴포넌트는 내부적으로 여러 AWS 리소스를 만들고, 그 결과를 하나의 객체로 묶어 돌려줘요. 덕분에 서브넷 ID 목록이나 보안 그룹 참조를 직접 연결하는 배선 작업이 줄어듭니다. 대신 컴포넌트가 노출하지 않는 옵션은 건드릴 수 없어서, 세밀한 튜닝이 필요한 순간에는 한 단계 내려가야 해요.

클래식 프로바이더와 비교

항목@pulumi/aws 단독@pulumi/awsx 함께 사용
추상화 수준AWS 리소스 단위여러 리소스를 묶은 컴포넌트 단위
코드 분량상대적으로 많음상대적으로 적음
세부 옵션 제어폭이 넓음컴포넌트가 노출한 범위
변경 영향 범위리소스 단위로 좁게 관리컴포넌트 단위로 함께 바뀔 수 있음
잘 맞는 상황네트워크·보안을 직접 설계할 때표준 구성을 빠르게 반복할 때

표에서 알 수 있듯이 우열 관계가 아니라 역할 분담에 가까워요. 같은 스택 안에서 VPC는 awsx로, 세밀한 IAM 정책은 클래식 리소스로 작성하는 혼합 방식이 흔히 쓰입니다.

단계별 설치와 첫 배포

사전 준비

Pulumi CLI를 공식 문서의 설치 안내에 따라 준비하고, pulumi version으로 동작을 확인해요. AWS 자격 증명은 Pulumi의 AWS 프로바이더가 읽을 수 있는 형태로 설정되어 있어야 합니다. 로컬에서 실습한다면 AWS CLI 프로파일을 활용하는 방식이 가장 단순해요.

스택을 어디에 둘지도 정해야 해요. Pulumi Cloud를 쓰거나, S3 같은 저장소를 백엔드로 지정할 수 있어요. 팀 단위 운영이라면 상태 저장소와 잠금 동작을 먼저 정하고 시작하는 편이 나중이 편합니다.

프로젝트 만들기

TypeScript 템플릿으로 시작하면 Pulumi.yaml, package.json, 진입점 파일이 한 번에 만들어져요. 기존 Node.js 저장소에 얹을 때는 pulumi new 대신 pulumi init 성격의 설정을 직접 추가하고 package.json 스크립트만 맞춰도 됩니다.

프로젝트 이름과 스택 이름은 배포 대상 구분의 기준이 돼요. 개발, 스테이징, 운영을 스택으로 나누는 구성이 일반적입니다.

패키지 설치

프로젝트 디렉터리에서 npm으로 패키지를 추가해요.

npm install @pulumi/awsx

이때 @pulumi/pulumi와 @pulumi/aws가 함께 설치되거나 이미 존재하는 경우가 많아요. 다만 버전 조합은 프로젝트마다 다를 수 있으니, 설치 후 package.json과 잠금 파일을 열어 실제로 어떤 버전이 잡혔는지 확인하는 편이 안전합니다. CI 환경에서는 npm ci로 잠금 파일 기준 설치를 하는 것이 재현성에 유리해요.

코드 작성

진입점 파일에서 awsx 모듈을 불러오고 컴포넌트를 선언해요. 아래는 흐름을 보여 주기 위한 최소 형태이고, 실제 옵션 이름은 사용 중인 패키지 버전의 문서를 확인해야 합니다.

import * as pulumi from "@pulumi/pulumi";
import * as awsx from "@pulumi/awsx";

const vpc = new awsx.ec2.Vpc("app-vpc", {
  numberOfAvailabilityZones: 2,
});

const listener = new awsx.lb.ApplicationListener("app-listener", {
  port: 80,
});

const service = new awsx.ecs.FargateService("app-service", {
  cluster: "app-cluster",
  taskDefinitionArgs: {
    containers: {
      app: {
        image: "nginx:latest",
        memory: 512,
        portMappings: [listener],
      },
    },
  },
});

코드에서 중요한 점은 컴포넌트가 만들어 준 객체를 다음 컴포넌트에 그대로 넘길 수 있다는 거예요. 리스너를 서비스에 넘기면 로드 밸런서와 대상 그룹 연결이 내부에서 처리됩니다.

미리보기와 배포

pulumi preview로 어떤 리소스가 생성·변경·삭제되는지 먼저 확인해요. 실제 반영은 pulumi up으로 하고, 결과는 pulumi stack output으로 확인할 수 있어요. 삭제는 pulumi destroy이며, 운영 스택에서는 미리보기 결과를 반드시 사람이 검토하는 절차를 두는 편이 좋아요.

상황별 선택 기준

표준적인 웹 서비스 구성을 빠르게 반복해야 한다면 awsx가 잘 맞아요. 로드 밸런서와 컨테이너 서비스를 연결하는 작업이 짧아지고, 팀원이 읽어야 할 코드가 줄어듭니다.

반대로 네트워크 대역, 라우팅, 보안 그룹 규칙을 직접 설계해야 하는 조직이라면 클래식 리소스 중심이 낫습니다. awsx 컴포넌트가 감춘 부분을 다시 열어야 하는 상황이 반복되면 오히려 코드가 길어져요.

이미 @pulumi/aws로 작성한 스택이 있다면 전면 교체보다 신규 컴포넌트에만 awsx를 도입하는 방식이 현실적이에요. 한 스택 안에서 두 접근을 섞어도 되고, 리소스 참조는 서로 주고받을 수 있습니다.

주의할 점

  • 예제와 실제 버전이 다르면 임포트 경로에서 먼저 오류가 나요. 공식 문서의 버전 표기를 확인해야 합니다.
  • 컴포넌트 업그레이드는 내부 리소스 교체로 이어질 수 있어요. 미리보기에서 교체 표시를 반드시 확인하세요.
  • 상태 파일은 팀 공용 저장소에 두고 잠금이 동작하도록 설정해야 해요. 로컬 상태로 협업하면 충돌이 잦아집니다.
  • 컨테이너 이미지 태그를 최신으로 두면 배포마다 결과가 달라져요. 태그를 고정하는 편이 재현성에 좋습니다.
  • 삭제 보호나 유지 정책 같은 안전장치는 스택 수준에서 별도로 챙겨야 해요.

자주 묻는 질문

npm의 @pulumi/awsx와 Pulumi CLI는 무슨 관계인가요?

CLI는 인프라를 계획하고 적용하는 실행 도구이고, npm 패키지는 그 계획을 코드로 표현할 때 쓰는 라이브러리예요. CLI 없이 패키지만 설치해서는 배포가 되지 않고, 패키지 없이 CLI만으로는 awsx 컴포넌트를 쓸 수 없습니다. 둘은 역할이 달라서 함께 준비해야 해요.

awsx를 쓰면 Terraform이나 CloudFormation을 대체할 수 있나요?

Pulumi는 상태를 자체적으로 관리하는 IaC 도구라서, 같은 대상을 다른 도구로 관리하던 스택을 그대로 옮기면 리소스가 중복 생성될 수 있어요. 기존 도구로 만든 리소스를 가져오는 절차를 먼저 설계해야 합니다. 무턱대고 병행하면 상태가 두 곳으로 갈라져요.

기존 @pulumi/aws 코드와 함께 쓸 수 있나요?

가능해요. 같은 스택 안에서 awsx 컴포넌트와 클래식 리소스를 함께 선언하고 서로의 출력값을 참조할 수 있습니다. 다만 두 접근이 같은 리소스를 건드리지 않도록 역할을 나눠 두는 편이 안전해요.

버전을 올릴 때 무엇을 확인해야 하나요?

미리보기 결과에서 리소스 교체 여부를 먼저 확인하고, 컴포넌트가 노출하는 옵션 이름이 바뀌지 않았는지 문서를 대조해요. 교체가 발생하는 업그레이드는 유지 보수 시간대에 나눠서 적용하는 편이 좋습니다.

출처

배포 이후 운영까지 생각한다면 상태 저장소 구성과 스택 분리 전략을 함께 보는 편이 좋아요. 관련해서는 Pulumi 스택과 상태 백엔드 운영 정리 글에서 스택 분리, 잠금, 백엔드 이전 절차를 이어서 다루고 있으니 함께 읽어 보시면 도움이 됩니다.

Discuss on Twitter • View on GitHub