aws.ec2.vpcendpoint pulumi로 VPC 엔드포인트 운영하기

Pulumi에서 aws.ec2.vpcendpoint는 AWS VPC 엔드포인트를 선언적으로 관리하는 리소스예요. Gateway와 Interface의 차이를 먼저 정하고 serviceName, subnetIds, routeTableIds 같은 입력을 맞춰야 배포 후 연결 문제를 줄일 수 있어요. 이 글은 공식 문서에서 확인한 범위를 기준으로 구성 절차와 운영 시 판단 기준을 정리해요.

한눈에 보기

aws.ec2.vpcendpoint는 Pulumi AWS provider의 EC2 리소스로, VPC 엔드포인트를 코드로 선언할 때 사용해요. VPC 엔드포인트는 VPC 안에서 AWS 서비스나 PrivateLink 서비스에 사설로 접근하기 위한 진입점이에요. 따라서 리소스를 만들기 전에 어떤 서비스에 접근할지, Gateway와 Interface 중 무엇이 맞는지, DNS 이름을 어떻게 해석할지를 먼저 정해야 해요.

Pulumi 리소스에서는 vpcId와 serviceName이 기본 축이에요. Gateway 엔드포인트는 routeTableIds를 함께 지정하고, Interface 엔드포인트는 subnetIds와 securityGroupIds를 함께 검토해요. privateDnsEnabled는 Interface 엔드포인트에서 서비스의 기본 DNS 이름을 VPC 안에서 사설로 해석할 때 중요한 입력이에요. 이 값들을 무리하게 한 번에 바꾸기보다는 엔드포인트 유형과 대상 서비스를 먼저 확정한 뒤 배포하는 편이 안전해요.

운영 관점에서는 Pulumi 코드만 보는 것으로 충분하지 않아요. AWS 콘솔이나 CLI에서 엔드포인트 상태, 라우팅 테이블 경로, 서브넷 연결, 보안 그룹 규칙, 엔드포인트 정책을 함께 확인해야 해요. Pulumi는 원하는 상태를 선언하는 도구이고, 실제 연결성은 VPC의 네트워크 설정과 DNS 설정이 함께 맞아야 확보돼요.

비교 표

항목	Gateway 엔드포인트	Interface 엔드포인트	Gateway Load Balancer 엔드포인트
주 사용 대상	S3, DynamoDB처럼 라우팅 기반으로 연결하는 서비스	PrivateLink를 지원하는 AWS 서비스와 엔드포인트 서비스	보안 어플라이언스와 트래픽 검사 장비
Pulumi 주요 입력	vpcId, serviceName, routeTableIds	vpcId, serviceName, subnetIds, securityGroupIds, privateDnsEnabled	vpcId, serviceName, subnetIds
연결 방식	라우팅 테이블에 서비스 경로를 추가	서브넷에 엔드포인트 네트워크 인터페이스를 연결	게이트웨이 로드 밸런서를 통해 트래픽 전달
보안 그룹	직접 연결하지 않음	보안 그룹으로 접근 제어	구성에 따라 별도 검토 필요
DNS 처리	서비스별 DNS 동작을 문서에서 확인	privateDnsEnabled로 사설 DNS 해석 가능	서비스 구성과 문서 확인 필요
운영 시 확인점	라우팅 테이블과 엔드포인트 정책	서브넷, 보안 그룹, DNS 설정	어플라이언스 상태와 라우팅

표는 이해를 돕기 위한 큰 구분이에요. 실제 지원 여부와 세부 입력은 사용하는 리전과 서비스, Pulumi AWS provider 버전에 따라 달라질 수 있으므로 공식 문서를 함께 확인해요.

단계별 방법

준비: VPC와 서브넷, 라우팅 확인

먼저 엔드포인트를 붙일 VPC와 서브넷, 라우팅 테이블을 확인해요. Gateway 엔드포인트는 라우팅 테이블에 경로를 추가하는 방식이라 어떤 라우팅 테이블이 대상인지 분명해야 해요. Interface 엔드포인트는 서브넷과 보안 그룹이 필요하므로 서브넷의 가용 영역과 보안 그룹 규칙도 함께 살펴요.

VPC의 DNS 설정도 미리 확인하는 편이 좋아요. Interface 엔드포인트에서 privateDnsEnabled를 사용하려면 VPC의 DNS 지원과 관련 설정이 PrivateLink 요구 사항에 맞아야 해요. 기존에 같은 이름을 사용하는 사설 DNS가 있다면 충돌 가능성도 점검해요.

서비스 이름 정하기

serviceName은 리전과 서비스에 따라 달라요. 예를 들어 S3 Gateway 엔드포인트는 com.amazonaws.<리전>.s3 형태를 사용해요. 리전 코드가 실제 VPC 리전과 맞는지 확인하는 것이 중요해요.

Interface 엔드포인트라면 대상 서비스가 PrivateLink를 지원하는지, 해당 리전에서 엔드포인트를 만들 수 있는지 확인해요. 서비스 이름을 잘못 넣으면 Pulumi 배포 단계에서 오류가 나거나, 배포는 되었지만 애플리케이션 연결이 되지 않을 수 있어요.

Pulumi 리소스 선언

Gateway 예시는 new aws.ec2.VpcEndpoint("s3-endpoint", { vpcId: vpc.id, serviceName: "com.amazonaws.ap-northeast-2.s3", vpcEndpointType: "Gateway", routeTableIds: [routeTable.id] });처럼 작성할 수 있어요. 이때 vpcEndpointType을 Gateway로 지정하고, 연결할 라우팅 테이블을 routeTableIds에 넣어요.

Interface 예시는 new aws.ec2.VpcEndpoint("api-endpoint", { vpcId: vpc.id, serviceName: "com.amazonaws.ap-northeast-2.execute-api", vpcEndpointType: "Interface", subnetIds: [subnet.id], securityGroupIds: [sg.id], privateDnsEnabled: true });처럼 구성할 수 있어요. 서브넷은 엔드포인트 네트워크 인터페이스가 배치될 위치이므로, 애플리케이션이 있는 가용 영역과 연결성을 고려해요.

엔드포인트 정책이 필요하면 policy에 JSON 문서를 넣어 접근 범위를 제한해요. 정책은 서비스 전체를 열어 두기보다 필요한 주체와 작업만 허용하는 방향으로 설계해요. 정책 변경은 연결성에 직접 영향을 줄 수 있으므로 배포 전후로 애플리케이션 동작을 확인해요.

배포와 검증

pulumi up으로 변경을 적용한 뒤 pulumi stack output이나 AWS 콘솔에서 엔드포인트 상태를 확인해요. Gateway라면 라우팅 테이블에 경로가 생겼는지, Interface라면 서브넷의 네트워크 인터페이스와 보안 그룹이 의도대로 연결됐는지 봐요. 애플리케이션에서는 공인 엔드포인트가 아니라 엔드포인트를 통한 DNS 이름으로 접근하는지도 확인해요.

배포 후에는 같은 VPC 안의 테스트 인스턴스나 작업 환경에서 실제 요청을 보내 보는 것이 좋아요. DNS가 사설로 해석되는지, 보안 그룹이 필요한 트래픽을 허용하는지, 라우팅이 엔드포인트로 향하는지를 순서대로 확인해요. 문제가 생기면 Pulumi 코드보다 VPC 네트워크 설정과 DNS 설정을 먼저 의심해 보는 편이 빠를 때가 많아요.

상황별 선택

S3와 DynamoDB처럼 라우팅 테이블 기반으로 연결하는 서비스는 Gateway 엔드포인트가 일반적인 선택이에요. 이 경우 보안 그룹을 직접 붙이는 방식이 아니라 라우팅과 엔드포인트 정책을 중심으로 접근을 관리해요. 여러 라우팅 테이블을 사용하는 VPC라면 어떤 라우팅 테이블에 경로를 넣을지 명확히 정해야 해요.

PrivateLink를 지원하는 서비스에 사설 IP로 접근해야 한다면 Interface 엔드포인트를 검토해요. privateDnsEnabled를 켜면 서비스의 기본 DNS 이름을 VPC 안에서 사설로 해석할 수 있어요. 다만 기존 DNS 구조와 충돌하지 않는지, 서브넷과 보안 그룹이 애플리케이션 요구에 맞는지 함께 확인해요.

보안 어플라이언스나 트래픽 검사 장비를 VPC에 연결해야 한다면 Gateway Load Balancer 엔드포인트를 검토해요. 이 유형은 일반적인 서비스 접근보다 네트워크 경로와 어플라이언스 상태가 중요하므로, Pulumi로 만들기 전에 라우팅과 가용성 설계를 먼저 정리해요.

주의할 점

serviceName의 리전이 VPC 리전과 다르면 엔드포인트가 의도대로 동작하지 않을 수 있어요.
privateDnsEnabled를 켤 때 기존 사설 DNS와 이름이 겹치지 않는지 확인해요.
Gateway 엔드포인트는 보안 그룹이 아니라 라우팅 테이블과 엔드포인트 정책으로 접근을 통제해요.
vpcEndpointType 변경은 리소스 교체를 유발할 수 있으므로 기존 연결에 미치는 영향을 먼저 검토해요.
엔드포인트 정책을 지나치게 넓게 두면 접근 범위가 커질 수 있어요.
요금은 엔드포인트 유형과 트래픽 형태에 따라 다르므로 AWS 요금 문서와 서비스 문서를 확인해요.

Pulumi에서 리소스를 교체하면 같은 이름을 유지하더라도 내부적으로 새 리소스가 만들어질 수 있어요. 운영 환경에서는 변경 전에 pulumi preview로 교체 여부를 확인하고, 애플리케이션의 연결 대상이 바뀌지 않는지 점검해요. 특히 Interface 엔드포인트의 서브넷이나 보안 그룹을 바꾸는 경우에는 배포 중 일시적인 연결 단절 가능성도 고려해요.

자주 묻는 질문

aws.ec2.vpcendpoint와 VPC 엔드포인트 서비스는 같은 개념인가요?

aws.ec2.vpcendpoint는 Pulumi가 AWS API를 호출해 VPC 엔드포인트를 만들고 관리하는 리소스예요. VPC 엔드포인트 서비스는 PrivateLink에서 제공하는 서비스 쪽 개념이므로 같은 이름처럼 보여도 역할이 달라요. Pulumi에서는 엔드포인트 리소스의 serviceName에 대상 서비스를 지정해요.

Gateway 엔드포인트에 보안 그룹을 붙일 수 있나요?

Gateway 엔드포인트는 보안 그룹을 직접 연결하는 방식이 아니에요. 라우팅 테이블과 엔드포인트 정책으로 접근 범위를 관리하고, 필요한 경우 서비스 쪽 정책도 함께 확인해요. Interface 엔드포인트라면 서브넷과 보안 그룹을 지정하는 흐름을 사용해요.

privateDnsEnabled는 언제 켜야 하나요?

Interface 엔드포인트에서 AWS 서비스의 기본 DNS 이름을 VPC 안에서 사설로 해석하고 싶을 때 켜요. 이때 VPC의 DNS 설정과 DHCP 옵션 세트가 PrivateLink 요구 사항에 맞는지 확인해야 해요. 기존에 같은 이름을 쓰는 사설 DNS가 있다면 충돌 여부를 먼저 점검해요.

출처

VPC 엔드포인트를 운영하다 보면 라우팅 테이블과 DNS 설정이 함께 얽히는 경우가 많아요. Pulumi의 운영 가이드와 AWS PrivateLink 문서를 함께 보면서 변경 전후 연결성을 확인하는 습관이 좋아요. 관련 운영 글은 Pulumi Operations 문서에서 배포와 상태 관리 흐름을 이어서 확인해 보세요.