비공개 DNS 구성하기

자체 DNS 서버를 가져와(bring your own) 개인 DNS와 HVN(HashiCorp Virtual Network) 사이의 이름 해석을 허용할 수 있어요. 모든 HCP Vault Dedicated 티어가 비공개 DNS를 지원해요.

출처: 문서

본문

자체 DNS 서버를 가져와 개인 DNS와 HVN 사이의 이름 해석을 허용할 수 있어요.

모든 HCP Vault Dedicated 티어가 비공개 DNS를 지원해요.

제한 사항

비공개 DNS 포워딩은 다음 제한과 함께 동작해요.

비공개 인증 기관(CA)의 TLS 인증서는 지원되지 않아요

기본 한도

비공개 DNS 포워딩에는 다음 기본 한도가 적용돼요.

DNS 포워딩 구성: HVN당 1개
DNS 포워딩 규칙: DNS 포워딩 구성당 5개
인바운드 엔드포인트 IP: 규칙당 2개

사용 사례에 따라 더 높은 한도를 요청하려면 지원 티켓을 만들어 주세요.

사전 요구 사항

AWS

HCP Portal 접근 권한
고유한 주소 공간으로 생성된 AWS HVN
존재하는 AWS VPC가 네트워크의 레코드에 대한 DNS 조회를 허용하도록 주소 공간 DNS 지원과 DNS 호스트 이름이 활성화된 상태로 구성
다음 방법 중 하나를 사용한 AWS HVN과 대상 VPC 사이의 유효한 연결:

VPC 피어링 연결이 대상 VPC와 HVN 사이에 존재하며, 두 네트워크 사이의 네트워크 트래픽을 허용하는 필요한 경로로 구성됨.Transit Gateway Attachment가 HVN과 대상 AWS 전송 게이트웨이 사이에 설정됨, 유효한 경로로 두 네트워크 사이의 트래픽을 허용. 참고: transit gateway를 사용할 때 Private DNS 기능이 제대로 동작하려면 HVN 라우트 테이블에 대상 VPC CIDR을 지정하는 유효한 hvn route가 생성되어야 해요.

대상 VPC의 비공개 호스팅 영역이 피어링 또는 TGW를 통해 HVN에 연결된 VPC와 연결되어 있음
대상 VPC에 보안 그룹이 존재하며, HVN CIDR 블록에서 자체 관리 DNS 서버 또는 AWS Route 53 VPC 엔드포인트로의 포트 53(UDP와 TCP 모두) 인바운드 트래픽을 허용
AWS Route 53을 사용한다면, HVN의 DNS 쿼리를 대상 VPC 엔드포인트로 라우팅할 수 있는 인바운드 리졸버 엔드포인트가 존재하는지 확인. Do53 프로토콜을 선택하고, 리졸버 엔드포인트에 대해 HVN CIDR 블록에서 포트 53으로 DNS(TCP와 UDP) 트래픽을 허용하도록 인바운드 규칙을 구성한 보안 그룹을 선택해 주세요.
클라이언트 ID와 시크릿이 있는 HCP 서비스 주체 사용자 생성

Azure

HCP Portal 접근 권한
고유한 주소 공간으로 생성된 Azure HVN
존재하는 Azure VNet이 네트워크의 레코드에 대한 DNS 조회를 허용하도록 주소 공간 DNS 지원과 DNS 호스트 이름이 활성화된 상태로 구성
VNet 피어링 연결을 사용한 Azure HVN과 대상 VNet 사이의 유효한 연결. 피어링이 대상 VPC와 HVN 사이에 존재하며, 두 네트워크 사이의 트래픽을 허용하는 필요한 경로로 구성됨.
대상 VNet의 Private DNS Zone이 피어링을 통해서만 HVN에 연결된 VNet과 연결됨
대상 VNet에 NSG(Network Security Group)가 존재하며, HVN CIDR 블록에서 자체 관리 DNS 서버 또는 Azure DNS Private Resolver 인바운드 엔드포인트로의 포트 53(UDP와 TCP 모두) 인바운드 트래픽을 허용
Azure Private DNS를 사용한다면, HVN의 DNS 쿼리를 대상 VNet 엔드포인트로 라우팅할 수 있는 Azure DNS Private Resolver 인바운드 엔드포인트가 존재하는지 확인. 리졸버 엔드포인트에 대해 HVN CIDR 블록에서 포트 53으로 DNS(TCP와 UDP) 트래픽을 허용하도록 인바운드 규칙을 구성한 VNet 서브넷과 연결된 Network Security Group을 선택해 주세요.
클라이언트 ID와 시크릿이 있는 HCP 서비스 주체 사용자 생성

HCP API 토큰 가져오기

HCP API로 토큰 요청

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

$ export HCP_ORG_ID=<HCP_ORG_ID> \
    HCP_PROJ_ID=<HCP_PROJ_ID> \
    HCP_NETWORK_ID=<HCP_NETWORK_ID> \
    PEERING_ID=<PEERING_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과 피어링 ID에 대한 환경 변수를 설정해요.

$ export HCP_NETWORK_ID=<HCP_NETWORK_ID> \
    PEERING_ID=<PEERING_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)

DNS 포워딩 만들기

참고

비공개 DNS 포워딩은 HCP Portal UI, HCP API, HCP Terraform provider 중 하나로 구성할 수 있어요. 이 가이드는 API 방법을 보여 줘요.

모든 비공개 DNS 포워딩 API 엔드포인트의 전체 목록은 HCP API 문서를 참고해 주세요.

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

$ echo $HCP_API_TOKEN $HCP_ORG_ID $HCP_PROJ_ID $HCP_NETWORK_ID $PEERING_ID

dnsforwardings 엔드포인트를 사용해 DNS 포워딩을 만들어요. data 블록에서 강조 표시된 항목을 환경에 맞는 값으로 업데이트해 주세요.

참고

inbound_endpoint_ips는 자체 관리 DNS 서버, AWS Route 53 엔드포인트, 또는 Azure 비공개 DNS 영역 VPC 엔드포인트의 IP 주소예요.DNS 포워딩 ID와 규칙 ID는 HCP 계정 전체에서 고유해야 해요.DNS 포워딩 ID와 규칙 ID는 32자를 초과할 수 없어요.region은 HVN의 호스팅 리전과 일치해야 해요.AWS의 경우 연결 유형에 따라 connection_type을 hvn-peering 또는 tgw-attachment로, Azure의 경우 hvn-peering으로 설정해 주세요.DNS 포워딩이 ACTIVE 상태가 된 후에 추가 규칙을 추가해 주세요.

연결 유형에 따라 적절한 예를 선택해 주세요.

HVN 피어링 연결

HVN 피어링(connection_type: "hvn-peering")으로 HVN을 VPC에 연결한 경우 이 예를 사용해요.

$ curl --location "https://api.cloud.hashicorp.com/network/2020-09-07/organizations/$HCP_ORG_ID/projects/$HCP_PROJ_ID/networks/$HCP_NETWORK_ID/dnsforwardings" \
  --request POST \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer ***" \
  --data '{ 
      "dnsForwarding": {
          "id": "dnsforwarding-byod", 
          "peering_id": "your-peering-connection-id", 
          "connection_type": "hvn-peering", 
          "rule": {
              "id": "staging-rule",
              "domain_name": "staging.byod.com",
              "inbound_endpoint_ips": ["10.0.0.12", "10.0.0.9"]
          },
          "hvn": { 
              "location": {
                  "region": {
                      "region": "us-west-2",
                      "provider": "aws"
                  }
              }
          }
      }
  }'

Transit Gateway Attachment

Transit Gateway(connection_type: "tgw-attachment")로 HVN을 VPC에 연결한 경우 이 예를 사용해요.

$ curl --location "https://api.cloud.hashicorp.com/network/2020-09-07/organizations/$HCP_ORG_ID/projects/$HCP_PROJ_ID/networks/$HCP_NETWORK_ID/dnsforwardings" \
  --request POST \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer ***" \
  --data '{ 
      "dnsForwarding": {
          "id": "dnsforwarding-tgw", 
          "peering_id": "your-tgw-attachment-id", 
          "connection_type": "tgw-attachment", 
          "rule": {
              "id": "staging-rule",
              "domain_name": "staging.internal.com",
              "inbound_endpoint_ips": ["10.0.0.12", "10.0.0.9"]
          },
          "hvn": { 
              "location": {
                  "region": {
                      "region": "us-east-1",
                      "provider": "aws"
                  }
              }
          }
      }
  }'

예제 출력:

{
  "dns_forwarding": {
    "id": "dnsforwarding-byod",
    "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": ""
    },
    "state": "CREATING",
    "peering_id": "HCP_NETWORK_PEERING_ID",
    "connection_type": "hvn-peering", 
    "rules": [
      {
        "hvn": {
          "type": "hashicorp.network.hvn",
          "id": "hvn-aws-latest-test-1",
          "uuid": "hvn-aws-latest-test-1",
          "location": {
            "organization_id": "c1597488-1053-4cc8-a536-e84cfef0ea7f",
            "project_id": "b1e20b0d-2411-47e6-adb0-88f39563fbec",
            "region": {
              "provider": "aws",
              "region": "us-west-2"
            }
          },
          "description": ""
        },
        "dns_forwarding_id": "dnsforwarding-byod",
        "state": "CREATING",
        "rule": {
          "id": "staging-rule",
          "domain_name": "staging.byod.com",
          "inbound_endpoint_ips": [
            "10.0.0.12",
            "10.0.0.9"
          ]
        },
        "created_at": "2025-05-14T12:49:52.457815118Z",
        "updated_at": "2025-05-14T12:49:52.457815118Z"
      }
    ],
    "created_at": "2025-05-14T12:49:52.457815118Z",
    "updated_at": "2025-05-14T12:49:52.457815118Z"
  },
  "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.dnsforwarding",
      "id": "dnsforwarding-byod",
      "uuid": "dnsforwarding-byod",
      "location": {
        "organization_id": "HCP_ORG_ID",
        "project_id": "HCP_PROJ_ID",
        "region": {
          "provider": "aws",
          "region": "us-west-2"
        }
      },
      "description": "DNS Forwarding (\"dnsforwarding-byod\")"
    },
    "created_at": "2025-05-14T12:49:52.464766Z",
    "updated_at": "2025-05-14T12:49:52.464766Z"
  }
}

비공개 DNS 포워딩 구성이 완료됐어요.

추가 포워딩 규칙 추가

참고

초기 DNS 포워딩 구성이 ACTIVE 상태가 된 후에 추가 포워딩 규칙을 추가할 수 있어요.

추가 도메인에 대한 포워딩 규칙을 더 추가하려면:

이전 단계의 DNS 포워딩 ID를 사용해 HCP_NETWORK_DNS_FORWARDING_ID 환경 변수를 설정해요.

$ export HCP_NETWORK_DNS_FORWARDING_ID=<DNS_FORWARDING_ID>

<DNS_FORWARDING_ID>를 DNS 포워딩 구성을 만들 때 사용한 ID로 바꿔 주세요(예: dnsforwarding-byod 또는 dnsforwarding-tgw).

추가 포워딩 규칙을 만들어요.

$ curl --location "https://api.cloud.hashicorp.com/network/2020-09-07/organizations/$HCP_ORG_ID/projects/$HCP_PROJ_ID/networks/$HCP_NETWORK_ID/dnsforwardings/$HCP_NETWORK_DNS_FORWARDING_ID/rules" \
  --request POST \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer ***" \
  --data '{
      "dnsForwardingRule": {
          "rule": {
              "id": "prod-rule",
              "domain_name": "prod.byod.com",
              "inbound_endpoint_ips": [
                  "10.0.0.13",
                  "10.0.0.14"
              ]
          },
          "hvn": {
              "location": {
                  "region": {
                      "region": "us-west-2",
                      "provider": "aws"
                  }
              }
          }
      }
  }' | jq

참고

dns_forwarding_id는 이전 단계에서 만든 DNS 포워딩 구성의 ID(예: "dnsforwarding-byod" 또는 "dnsforwarding-tgw")와 일치해야 해요.

예제 출력:

{
  "dns_forwarding_rule": {
    "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": ""
    },
    "dns_forwarding_id": "HCP_NETWORK_DNS_FORWARDING_ID",
    "state": "CREATING",
    "rule": {
      "id": "prod-rule",
      "domain_name": "prod.byod.com",
      "inbound_endpoint_ips": [
        "10.0.0.12",
        "10.0.0.11"
      ]
    },
    "created_at": "2025-05-14T13:40:59.044410083Z",
    "updated_at": "2025-05-14T13:40:59.044410143Z"
  },
  "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.dnsforwarding.rule",
      "id": "prod-rule",
      "uuid": "prod-rule",
      "location": {
        "organization_id": "HCP_ORG_ID",
        "project_id": "HCP_PROJ_ID",
        "region": {
          "provider": "aws",
          "region": "us-west-2"
        }
      },
      "description": "DNS Forwarding Rule (\"prod-rule\")"
    },
    "created_at": "2025-05-14T13:40:59.053776Z",
    "updated_at": "2025-05-14T13:40:59.053776Z"
  }
}

Terraform

HCP Terraform provider로도 비공개 DNS 포워딩을 관리할 수 있어요.

hcp_dns_forwarding — DNS 포워딩 구성을 만들고 관리해요
hcp_dns_forwarding_rule — 기존 DNS 포워딩에 대한 규칙을 만들고 관리해요

API

더 알아보기 (Learn more)

AWS PrivateLink 문서에서 비공개 엔드포인트 구성을 살펴볼 수 있어요.
HVN 피어링 문서에서 네트워크 연결을 배워 보세요.
Connectivity Tester 문서에서 내부 리소스 연결을 검증해 보세요.