AWS PrivateLink 구성하기

AWS PrivateLink를 사용해 비공개 HCP Vault Dedicated 클러스터에 연결을 설정할 수 있어요. 이 기능을 사용하면 클러스터를 공개 인터넷에 노출하지 않아 공격 표면을 줄일 수 있어요.

출처: 문서

본문

essentials 또는 standard 티어 클러스터 필요

이 기능은 HCP Vault Dedicated essentials 또는 standard 티어 클러스터가 필요해요.

AWS PrivateLink를 사용해 비공개 HCP Vault Dedicated 클러스터에 연결을 설정할 수 있어요. 이 기능을 사용하면 클러스터를 공개 인터넷에 노출하지 않고 공격 표면을 줄일 수 있어요.

제한 사항

Essentials 및 Standard 티어의 프로덕션 티어 HCP Vault Dedicated 클러스터를 지원해요.
고객 VPC에서 HCP Vault Dedicated 클러스터로의 인바운드 연결을 지원해요.
소비자 엔드포인트 유형을 Endpoint services that use NLBs and GWLBS로 설정해야 해요.
대상 HVN에 피어링 또는 전송 게이트웨이가 구성되어 있지 않아야 해요.
VPC 간 전이적(transitive) 라우팅은 지원하지 않아요. 이 사용 사례에는 전송 게이트웨이를 사용해 주세요.
HCP Vault Dedicated 클러스터를 삭제하기 전에 PrivateLink 연결을 삭제해야 해요.

기본 한도

PrivateLink에는 다음 기본 한도가 있어요.

PrivateLink 서비스: HCP Vault Dedicated 클러스터당 1개
소비자 계정: PrivateLink 서비스당 10개
소비자 IP 범위: PrivateLink 서비스당 15개
PrivateLink 엔드포인트 연결: PrivateLink 서비스당 20개

더 높은 한도를 요청하려면 지원 티켓을 만들어 주세요.

사전 요구 사항

HCP Portal 접근 권한.
고유한 주소 공간으로 생성된 AWS HVN.
구성된 AWS HVN에 생성된 AWS HCP Vault Dedicated 클러스터.
대상/소비자 AWS VPC가 존재하고 주소 공간으로 구성됨.
Peering/TGW와 PrivateLink가 동시에 사용되지 않음.
클라이언트 ID와 시크릿이 있는 HCP 서비스 주체 사용자 생성.

PrivateLink 프로비저닝

PrivateLink 연결을 수립하는 것은 소비자(고객)와 제공자(HashiCorp)라는 두 유형의 사람이 관여하는 다단계 절차예요.

PrivateLink 서비스 생성 시작

Persona: 소비자

소비자는 주어진 HCP Vault Dedicated 클러스터에 대한 새 VPC Endpoint Service를 만드는 API 호출로 VPC PrivateLink Service 생성 절차를 시작해요.

CreatePrivateLink API는 새 HCP PrivateLink 서비스를 만들어 지정된 고객 AWS 계정 ARN, VPC CIDR, VPC 리전에 권한을 부여하고, 누가 PrivateLink를 통해 HCP Vault Dedicated 클러스터로의 인바운드 연결을 만들 수 있는지 제어해요.

이 API는 다음 단계에 필요한 고유한 external_name을 반환해요.

서비스가 AVAILABLE 상태로 전환될 때까지 기다린 다음 다음 섹션으로 진행해 주세요.

PrivateLink Service의 state와 external_name에 대한 자세한 내용은 GetPrivateLink API 문서를 참고해 주세요.

VPC Endpoint 만들기

Persona: 소비자

PrivateLink Service가 AVAILABLE 상태가 되면 소비자는 이전 단계에서 반환된 external_name을 사용해 VPC 내에 VPC Endpoint를 만들 수 있어요.

Endpoint services that use NLBs and GWLBS 엔드포인트 유형을 선택해 주세요.

이것이 HCP Vault Dedicated 클러스터에 대한 HCP VPC Endpoint Service로 연결 요청을 보내는 작업이에요.

연결 수락 및 엔드포인트 프로비저닝

Persona: 제공자

이것은 플랫폼이 수행하는 자동화된 단계예요. 요청이 성공적으로 검증되면 서비스가 연결 요청을 수락해요.

팁

연결 수락 절차는 완료하는 데 5~10분이 걸려요.

PrivateLink 연결이 수립되고, 소비자 VPC에서 연결된 HCP Vault Dedicated 클러스터로 포트 8200에서 비공개로 트래픽이 흐를 수 있어요.

HCP API 토큰 가져오기

Persona: 소비자

HCP API로 토큰 요청

HCP 조직, HCP 프로젝트, HVN에 대한 환경 변수를 설정해요.

$ export HCP_ORG_ID=<HCP_ORG_ID> \
    HCP_PROJ_ID=<HCP_PROJ_ID> \
    HCP_NETWORK_ID=<HCP_NETWORK_ID>

HCP 서비스 주체 사용자 HCP_CLIENT_ID와 HCP_CLIENT_SECRET에 대한 환경 변수를 설정해요.

$ export HCP_CLIENT_ID=<HCP_CLIENT_ID> HCP_CLIENT_SECRET=<HCP_CLIENT_SECRET>

HCP 서비스 주체 사용자 HCP_CLIENT_ID와 HCP_CLIENT_SECRET을 사용해 HCP API 토큰을 가져와 HCP_API_TOKEN 변수에 저장해요.

$ HCP_API_TOKEN=$(curl --location "https://auth.idp.hashicorp.com/oauth2/token" \
    --header "Content-Type: application/x-www-form-urlencoded" \
    --data-urlencode "client_id=$HCP_CLIENT_ID" \
    --data-urlencode "client_secret=$HCP_CLIENT_SECRET" \
    --data-urlencode "grant_type=client_credentials" \
    --data-urlencode "audience=https://api.hashicorp.cloud" | jq -r .access_token)

HCP CLI로 토큰 요청 — 이 단계들은 HCP CLI를 사용해 hcp profile init으로 구성했고, HVN을 만든 HCP 조직과 프로젝트를 선택했다고 가정해요.

HCP 서비스 주체 사용자 HCP_CLIENT_ID와 HCP_CLIENT_SECRET에 대한 환경 변수를 설정해요.

$ export HCP_CLIENT_ID=<HCP_CLIENT_ID> HCP_CLIENT_SECRET=<HCP_CLIENT_SECRET>

HCP 서비스 주체 클라이언트 시크릿은 처음 생성한 후에는 더 이상 사용할 수 없어요.

HVN에 대한 환경 변수를 설정해요.

$ export HCP_NETWORK_ID=<HCP_NETWORK_ID>

HCP에 인증해요.

$ hcp auth login

브라우저 기반 인증 워크플로를 완료해요.
HCP 조직과 프로젝트 ID에 대한 환경 변수를 설정해요.

$ export HCP_ORG_ID=$(hcp profile display --format json | jq -r .OrganizationID) \
     HCP_PROJ_ID=$(hcp profile display --format json | jq -r .ProjectID)

HCP CLI를 사용해 HCP API 토큰을 가져와 HCP_API_TOKEN 변수에 저장해요.

$ HCP_API_TOKEN=$(hcp auth print-access-token)

PrivateLink Service 만들기

Persona: 소비자

참고

PrivateLink는 HCP Portal UI 또는 HCP API로 구성할 수 있어요. 이 가이드는 API 방법을 보여 줘요.

모든 PrivateLink API 엔드포인트의 전체 목록은 HCP API 문서를 참고해 주세요.

필요한 환경 변수가 구성되어 있는지 확인해요.

$ echo $HCP_API_TOKEN $HCP_ORG_ID $HCP_PROJ_ID $HCP_NETWORK_ID

private-link-services 엔드포인트를 사용해 PrivateLink Service를 만들어요. data 블록에서 강조 표시된 항목을 환경에 맞는 값으로 업데이트해 주세요.

참고

consumer_accounts는 생성된 PrivateLink Service에 대한 접근을 허용하기 위해 Allowed Principals로 추가해야 하는 계정의 ARN 목록이에요.consumer_ip_ranges는 PrivateLink Service에 접근해야 하는 VPC의 IP 범위/CIDR 목록이에요.consumer_regions는 PrivateLink Service에서 지원할 클라우드 제공자 리전 목록이에요.vault_cluster_id는 PrivateLink Service와 연결할 HashiCorp Vault Dedicated 클러스터의 ID예요. 이는 Essentials/Standard 티어 HashiCorp Vault Dedicated 클러스터에 해당하는 유효한 ID여야 해요.PrivateLink Service ID는 HCP 프로젝트 내에서 고유해야 해요.PrivateLink Service ID는 36자를 초과할 수 없어요.PrivateLink가 AVAILABLE 상태로 전환된 후 VPC에 VPC Endpoint를 만들어 주세요.

예제:

$ curl --location "https://api.cloud.hashicorp.com/network/2020-09-07/organizations/$HCP_ORG_ID/projects/$HCP_PROJ_ID/networks/$HCP_NETWORK_ID/private-link-services" \
 --request POST \
 --header 'Content-Type: application/json' \
 --header "Authorization: Bearer ***" \
 --data '{
     "private_link_service": {
         "id": "privatelink-service",
         "vault_cluster_id": "vault-cluster-id",
         "consumer_accounts": ["ARN-1", "ARN-2"],
         "consumer_ip_ranges": ["IP-Range-1", "IP-Range-2"],
         "consumer_regions": ["us-east-1"],
         "hvn": {
             "location": {
                 "region": {
                     "region": "us-west-2",
                     "provider": "aws"
                 }
             }
         }
     }
 }'| jq

예제 출력:

{
   "private_link_service": {
     "id": "privatelink-service",
     "external_name": "PRIVATE_LINK_SERVICE_NAME",
     "hvn": {
       "type": "hashicorp.network.hvn",
       "id": "HCP_NETWORK_ID",
       "uuid": "HCP_NETWORK_ID",
       "location": {
         "organization_id": "HCP_ORG_ID",
         "project_id": "HCP_PROJ_ID",
         "region": {
           "provider": "aws",
           "region": "us-west-2"
         }
       },
       "description": "Description"
     },
     "state": "CREATING",
     "created_at": "2025-09-02T11:27:12.011Z",
     "updated_at": "2025-09-02T11:27:12.011Z",
     "vault_cluster_id": "vault-cluster-id",
     "consumer_regions": [
       "us-east-1"
     ],
     "default_region": "us-west-2",
     "consumer_accounts": [
       "ARN-1", "ARN-2"
     ],
     "consumer_ip_ranges": [
       "IP-Range-1", "IP-Range-2"
     ]
   },
   "operation": {
     "id": "OPERATION_ID",
     "state": "PENDING",
     "location": {
       "organization_id": "HCP_ORG_ID",
       "project_id": "HCP_PROJ_ID",
       "region": {
         "provider": "aws",
         "region": "us-west-2"
       }
     },
     "link": {
       "type": "hashicorp.network.private-link",
       "id": "privatelink-service",
       "uuid": "privatelink-service",
       "location": {
         "organization_id": "HCP_ORG_ID",
         "project_id": "HCP_PROJ_ID",
         "region": {
           "provider": "aws",
           "region": "us-west-2"
         }
       },
       "description": "PrivateLink Service (\"private-link-service\")"
     },
     "created_at": "2025-09-02T11:27:12.011Z",
     "updated_at": "2025-09-02T11:27:12.011Z"
   }
}

HCP Vault Dedicated 클러스터에 대한 PrivateLink Service 생성을 시작했어요.

PrivateLink 서비스 업데이트

서비스가 AVAILABLE 상태가 되면 기존 PrivateLink Service를 업데이트해 소비자 계정, 소비자 IP 범위, 소비자 리전을 변경할 수 있어요.

이전 단계의 PrivateLink Service ID를 사용해 HCP_NETWORK_PRIVATELINK_SERVICE_ID 환경 변수를 설정해요.

$ export HCP_NETWORK_PRIVATELINK_SERVICE_ID=<PRIVATELINK_SERVICE_ID>

<PRIVATELINK_SERVICE_ID>를 PrivateLink Service를 만들 때 사용한 ID로 바꿔 주세요(예: privatelink-service).

PrivateLink 서비스를 업데이트해요.

참고

add_consumer_accounts는 생성된 PrivateLink Service에 대한 접근을 허용하기 위해 Allowed Principals로 추가해야 하는 새 계정 ARN 목록이에요.remove_consumer_accounts는 생성된 PrivateLink Service에 대한 접근을 폐기하기 위해 Allowed Principals에서 제거해야 하는 계정의 ARN 목록이에요.add_consumer_ip_ranges는 PrivateLink Service에 접근해야 하는 VPC의 새 IP 범위/CIDR 목록이에요.remove_consumer_ip_ranges는 PrivateLink Service 접근에서 제거해야 하는 IP 범위/CIDR 목록이에요.add_consumer_regions는 PrivateLink Service에서 지원할 새 클라우드 제공자 리전 목록이에요.remove_consumer_regions는 PrivateLink Service에서 제거할 클라우드 제공자 리전 목록이에요.PrivateLink Service ID는 이전 단계에서 만든 PrivateLink Service의 ID(예: "privatelink-service")와 일치해야 해요.업데이트 작업을 수행하려면 PrivateLink가 AVAILABLE 상태여야 해요.

$ curl --location "https://api.cloud.hashicorp.com/network/2020-09-07/organizations/$HCP_ORG_ID/projects/$HCP_PROJ_ID/networks/$HCP_NETWORK_ID/private-link-services/$HCP_NETWORK_PRIVATELINK_SERVICE_ID" \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer ***" \
  --data '{
    "id": "privatelink-service",
    "add_consumer_accounts": ["ARN3", "ARN4"],
    "remove_consumer_accounts": ["ARN1"],
    "add_consumer_regions": ["us-east-2"],
    "remove_consumer_regions": ["us-east-1"],
    "add_consumer_ip_ranges": ["10.0.0.0/24"],
    "remove_consumer_ip_ranges": ["IP-Range-3"],
    "hvn": {
        "location": {
            "region": {
                "region": "us-west-2",
                "provider": "aws"
            }
        }
    }
}'| jq

예제 출력:

{
     "operation": {
         "id": "OPERATION_ID",
         "state": "PENDING",
         "location": {
             "organization_id": "HCP_ORG_ID",
             "project_id": "HCP_PROJ_ID",
             "region": {
                 "provider": "aws",
                 "region": "us-west-2"
             }
         },
         "link": {
             "type": "hashicorp.network.private-link",
             "id": "private-link-service",
             "uuid": "private-link-service",
             "location": {
                 "organization_id": "HCP_ORG_ID",
                 "project_id": "HCP_PROJ_ID",
                 "region": {
                     "provider": "aws",
                     "region": "us-west-2"
                 }
             },
             "description": "PrivateLink Service (\"private-link-service\")"
         },
         "created_at": "2025-09-01T18:53:48.930351Z",
         "updated_at": "2025-09-01T18:53:48.930351Z"
     }
}

API

더 알아보기 (Learn more)

비공개 접근 구성 문서에서 피어링·전송 게이트웨이를 살펴볼 수 있어요.
비공개 DNS 문서에서 자체 DNS 서버 구성 방법을 배워 보세요.
Connectivity Tester 문서에서 비공개 엔드포인트 연결을 검증해 보세요.