Configure private DNS

Beta feature

Private DNS forwarding is in beta and available for Amazon Web Services (AWS).

Open a support ticket, including your HCP organization ID, to enroll in the private DNS forwarding beta.

You can configure your private DNS server(s) to allow resolution from a HashiCorp Virtual Network (HVN).

Prerequisites

The prerequisites listed are specific to the beta period. Check back at general availability for a list of supported providers and prerequisites.

Access to the HCP Portal
AWS HVN exists and is configured with a unique address space
AWS VPC exists and configured with its address space DNS support and DNS hostnames are enabled for the VPC to allow DNS lookups of records in the network.
Peering connection exists between the target VPC and the HVN, configured with the required routes to enable network traffic between the two networks.
Target VPC's private hosted zone is associated with the VPC that is peered with the HVN.
Security group exists in the target VPC, which allows inbound traffic on port 53 (both UDP and TCP) from the HVN CIDR block.
Inbound resolver endpoint exists that allows DNS queries from the HVN to be routed to the target VPC. Make sure that you select Do53 protocol and choose a Security Group for which you have configured the inbound rules to allow DNS (TCP and UDP) traffic on port 53 from the HVN CIDR block for the resolver endpoint.
HCP service principal user created with a client ID and secret.

Retrieve HCP API token

Note

During the beta period, configure private DNS using the HCP API.

Set environment variables for the HCP organization, HCP project, HVN, and peering ID.

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

Set environment variables for the HCP service principal user HCP_CLIENT_ID and HCP_CLIENT_SECRET:
```
$ export HCP_CLIENT_ID=<HCP_CLIENT_ID> HCP_CLIENT_SECRET=<HCP_CLIENT_SECRET>
```

Retrieve a HCP API token using a HCP service principal user HCP_CLIENT_ID, and HCP_CLIENT_SECRET and store it in the HCP_API_TOKEN variable.

$ 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)

Create DNS forwarding

Verify you have the required environment variables configured.

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

Use the dnsforwardings endpoint to create DNS forwarding.

$ 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 $HCP_API_TOKEN' \
  --data '{ 
      "dnsForwarding": {
          "id": "dnsforwarding-byod", 
          "peering_id": "peering-id" 
          "rule": {
              "id": "staging-forwarding-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"
                  }
              }
          }
      }
  }' | jq

Example output:

{
  "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",
    "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-forwarding-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"
  }
}

You have completed the private DNS forwarding configuratinon.

Configure private DNS

Prerequisites

Retrieve HCP API token

Create DNS forwarding

Tutorials