HCP Vault Connectivity Tester

The HCP Connectivity Tester is a self-service diagnostic tool that verifies network reachability from your HCP Vault Dedicated cluster to internal resources, including databases, identity providers, LDAP servers, and DNS resolvers. It lets you confirm that DNS resolution, TCP reachability, and network connectivity are working correctly across your HashiCorp Virtual Network (HVN). Use it before configuring Vault integrations such as database secrets engines, LDAP authentication, or MFA providers.

Without this tool, network failures only surface after you deploy a Vault configuration, producing vague error logs that require engineering escalation. The connectivity tester gives you clear, structured diagnostics similar to common CLI diagnostic commands — equivalent to running dig, nc, curl, ping, or traceroute — without needing to interpret raw logs or configure Vault first.

Prerequisites

Access to the HCP Portal.
AWS HCP Vault Dedicated cluster created in the configured AWS HVN.
A VPC peering connection or Transit Gateway attachment (AWS only) established between the two networks. Refer to HVN peering for setup instructions.
(API only) An HCP service principal with a client ID and secret.
(Optional) BYO-DNS configured in the HVN to test private DNS resolution against your internal resolver.
(Optional) AWS PrivateLink configured to test reachability over a private endpoint.

Limitations

The connectivity tester supports HCP Vault Dedicated clusters only.
The connectivity tester supports the clusters primary HVN. After a backup region is promoted, connectivity to features such as BYO-DNS or PrivateLink is not retained in the promoted region.
This tool does not validate application-layer protocols (for example, LDAP bind or database authentication).
This tool does not perform continuous monitoring or alerting. It is an on-demand diagnostic tool.

Supported tests

Test	`type` enum value	CLI equivalent	What it checks
DNS lookup	`CONNECTIVITY_COMMAND_TYPE_DIG`	`dig +noall +answer <hostname> @<nameserver>`	Resolves a hostname using your DNS server and returns the resolved IP addresses
TCP reachability	`CONNECTIVITY_COMMAND_TYPE_NC`	`nc -z -v <hostname> <port>`	Attempts a TCP connection to a hostname and port and reports open, closed, or unreachable
TLS / curl	`CONNECTIVITY_COMMAND_TYPE_CURL`	`curl https://<hostname>:<port>`	Performs a TLS handshake to confirm a TLS-capable service is reachable
Ping (ICMP)	`CONNECTIVITY_COMMAND_TYPE_PING`	`ping -c 5 <hostname>`	Sends ICMP echo requests to verify basic host reachability
Traceroute	`CONNECTIVITY_COMMAND_TYPE_TRACEROUTE`	`traceroute <hostname>`	Maps the network path between the Vault cluster and the target host

Test cluster connectivity

You can run the connectivity tester using the HCP Portal, of the HCP API.

You can run connectivity test as a user logged into the HCP Portal.

Sign in to the HCP Portal.
In the left navigation, select Vault Dedicated.
Select the cluster you want to test from the cluster list.
Select the Test connectivity button on the Quick actions panel.
In the Connectivity Tester panel, select the test type (Dig, Curl, NC, Ping, or Traceroute).
Enter the required parameters for the selected test type, then select Start test.
Review the structured diagnostic output displayed in the results panel.

Before you can use the HCP APIs, you need to generate a bearer token. You can generate a bearer token by authenticating against the HCP IDP or using the HCP CLI.

Generate bearer token

Set environment variables for your HCP organization, project, and cluster.

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

Set environment variables for your HCP service principal credentials.

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

Retrieve an HCP API token 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)

Set environment variables for your HCP service principal credentials.

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

Authenticate to HCP.
```
$ hcp auth login
```
Complete the browser-based authentication workflow.

Set environment variables for your HCP organization and project.

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

Set the environment variable for your cluster.
```
$ export HCP_CLUSTER_ID=<HCP_CLUSTER_ID>
```

Retrieve an HCP API token.

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

Run connectivity tests

The following steps use the HCP API. To use the HCP Portal instead, refer to HCP Portal.

Verify you have the required environment variables configured.

$ echo $HCP_API_TOKEN $HCP_ORG_ID $HCP_PROJ_ID $HCP_CLUSTER_ID

Submit a connectivity test request by sending a POST request to the test-connectivity endpoint.

$ curl --location "https://api.cloud.hashicorp.com/vault/2020-11-25/organizations/$HCP_ORG_ID/projects/$HCP_PROJ_ID/clusters/$HCP_CLUSTER_ID/test-connectivity" \
 --request POST \
 --header 'Content-Type: application/json' \
 --header "Authorization: Bearer $HCP_API_TOKEN" \
 --data '{
   "connection_info": [
     {
       "type": "CONNECTIVITY_COMMAND_TYPE_DIG",
       "hostname": "database.internal.corp"
     }
   ]
 }' | jq

API reference

The HCP Vault Dedicate connectivity tester API provides an endpoint for initiaing tests. There are different tests available based on various network scenarios.

Versioning

The HCP Vault Dedicated API version is 2023-05-01.

Prerequisites

Retrieve an access token for authentication.

Test connectivity

POST /vault/2020-11-25/organizations/{organization_id}/projects/{project_id}/clusters/{cluster_id}/test-connectivity

The request body accepts a connection_info array. Each element is a flat object with a type enum and the parameters for that test. You can submit one or more tests in a single request.

{
  "connection_info": [
    {
      "type": "<CONNECTIVITY_COMMAND_TYPE_*>",
      "hostname": "<hostname-or-ip>",
      "port": 0
    }
  ]
}

Request

Command types and parameters

`type`	`hostname`	`port`	`resolver_ip`	Description
`CONNECTIVITY_COMMAND_TYPE_DIG`	Required	—	Optional	DNS lookup. Resolves `hostname`, optionally using the specified `resolver_ip` IP.
`CONNECTIVITY_COMMAND_TYPE_NC`	Required	Required	—	TCP reachability check. Attempts a TCP connection to `hostname` on `port`.
`CONNECTIVITY_COMMAND_TYPE_CURL`	Required	Required	—	TLS connectivity check. Performs a TLS handshake to `hostname` on `port`.
`CONNECTIVITY_COMMAND_TYPE_PING`	Required	—	—	ICMP reachability. Sends 5 echo requests to `hostname`.
`CONNECTIVITY_COMMAND_TYPE_TRACEROUTE`	Required	—	—	Network path trace from the Vault cluster to `hostname`.

Field validation

Field	Type	Required	Validation rules
`type`	enum	Yes	Must be one of the `CONNECTIVITY_COMMAND_TYPE_*` values listed above.
`hostname`	string	Yes	Valid FQDN or IPv4 address of the target connecting to Vault. Max 253 characters. RFC 1123 compliant. No whitespace, shell metacharacters (`;`, `&`, `\\|`, `, `$`), or flag prefixes (`-`).
`port`	uint32	Yes (`NC`, `CURL` only)	Integer in range 1–65535.
`resolver_ip`	string	Optional (`DIG` only)	Valid IPv4 or IPv6 address. Validated against the blocked address list. Omit to use the HVN default resolver.

Example: all test types

The following example submits all five test types in a single request.

$ curl --location "https://api.cloud.hashicorp.com/vault/2020-11-25/organizations/$HCP_ORG_ID/projects/$HCP_PROJ_ID/clusters/$HCP_CLUSTER_ID/test-connectivity" \
    --request POST \
    --header 'Content-Type: application/json' \
    --header "Authorization: Bearer $HCP_API_TOKEN" \
    --data '{
      "connection_info": [
        {
          "type": "CONNECTIVITY_COMMAND_TYPE_DIG",
          "hostname": "database.internal.corp"
        },
        {
          "type": "CONNECTIVITY_COMMAND_TYPE_NC",
          "hostname": "database.internal.corp",
          "port": 6689
        },
        {
          "type": "CONNECTIVITY_COMMAND_TYPE_CURL",
          "hostname": "internal-api.corp",
          "port": 443
        },
        {
          "type": "CONNECTIVITY_COMMAND_TYPE_PING",
          "hostname": "database.internal.corp"
        },
        {
          "type": "CONNECTIVITY_COMMAND_TYPE_TRACEROUTE",
          "hostname": "database.internal.corp"
        }
      ]
    }' | jq

Example output (success):

{
  "connection_results": [
    {
      "command_type": "CONNECTIVITY_COMMAND_TYPE_DIG",
      "status": "CONNECTION_STATUS_SUCCESS",
      "detail": "database.internal.corp resolved to [10.0.1.42]",
      "error": null,
      "duration_ms": "8"
    },
    {
      "command_type": "CONNECTIVITY_COMMAND_TYPE_NC",
      "status": "CONNECTION_STATUS_SUCCESS",
      "detail": "Connection to database.internal.corp port 6689 [tcp] succeeded",
      "error": null,
      "duration_ms": "12"
    },
    {
      "command_type": "CONNECTIVITY_COMMAND_TYPE_CURL",
      "status": "CONNECTION_STATUS_SUCCESS",
      "detail": "TLS handshake to internal-api.corp:443 succeeded",
      "error": null,
      "duration_ms": "95"
    },
    {
      "command_type": "CONNECTIVITY_COMMAND_TYPE_PING",
      "status": "CONNECTION_STATUS_SUCCESS",
      "detail": "5 packets transmitted, 5 received, 0% packet loss",
      "error": null,
      "duration_ms": "104"
    },
    {
      "command_type": "CONNECTIVITY_COMMAND_TYPE_TRACEROUTE",
      "status": "CONNECTION_STATUS_SUCCESS",
      "detail": "traceroute to database.internal.corp (10.0.1.42), 30 hops max\n 1  10.0.0.1  1.234 ms\n 2  10.0.1.42  2.456 ms",
      "error": null,
      "duration_ms": "310"
    }
  ]
}

Example output (failure):

{
  "connection_results": [
    {
      "command_type": "CONNECTIVITY_COMMAND_TYPE_NC",
      "status": "CONNECTION_STATUS_FAILURE",
      "detail": "",
      "error": {
        "code": "TIMEOUT",
        "message": "dial tcp 12.54.32.55:53: i/o timeout"
      },
      "duration_ms": "20000"
    },
    {
      "command_type": "CONNECTIVITY_COMMAND_TYPE_CURL",
      "status": "CONNECTION_STATUS_FAILURE",
      "detail": "",
      "error": {
        "code": "HOSTNAME_UNRESOLVED",
        "message": "DNS resolution failed for \"internal-api.corp\": lookup internal-api.corp on 127.0.0.53:53: no such host"
      },
      "duration_ms": "75"
    }
  ]
}

Response reference

`TestConnectivityResponse`

Field	Type	Description
`connection_results`	array	List of results, one per submitted test command, in submission order.
`connection_results[].command_type`	string	The `CONNECTIVITY_COMMAND_TYPE_*` value of the executed test.
`connection_results[].status`	string	`CONNECTION_STATUS_SUCCESS` or `CONNECTION_STATUS_FAILURE`.
`connection_results[].detail`	string	Human-readable diagnostic output on success. Empty string on failure.
`connection_results[].error`	object \| null	`null` on success. Contains `code` and `message` on failure.
`connection_results[].error.code`	string	Machine-readable error code. See Error codes below.
`connection_results[].error.message`	string	Human-readable error description.
`connection_results[].duration_ms`	string	Elapsed time for the test in milliseconds.

Note

The blocklist is enforced at both input validation and post-DNS-resolution stages. This prevents DNS rebinding attacks where a hostname initially passes validation but resolves to a blocked internal IP at runtime.

Audit logging

Every connectivity test invocation is recorded in the HCP audit log with the following fields:

Caller identity (organization_id, project_id, user token subject)
Invocation timestamp
Cluster ID
Test result (CONNECTION_STATUS_SUCCESS or CONNECTION_STATUS_FAILURE)

Troubleshooting

The results of the connectivity test help you determine what troubleshooting steps to consider.

`HOSTNAME_UNRESOLVED` returned

Verify that:

The target hostname exists in your private DNS zone.
If using a custom resolver_ip (DIG only), confirm the resolver_ip is correct and reachable from the HVN.
BYO-DNS is configured and the security group on your DNS server allows inbound UDP/TCP traffic on port 53 from the HVN CIDR.

`TIMEOUT` returned for an `NC` test

Verify that:

The target service is running and listening on the specified port.
Security groups or firewall rules allow inbound TCP traffic on the port from the HVN CIDR.
VPC peering or Transit Gateway routes are correctly configured between the HVN and the target VPC.

`TIMEOUT` returned for all tests (host unreachable)

Verify that:

VPC peering or Transit Gateway attachment is established and in the ACTIVE state.
Route tables in both the HVN and the target VPC include entries for the other network's CIDR.
There are no network ACLs blocking traffic between the two networks.

`TLS_HANDSHAKE_FAILED` returned for a `CURL` test

Before running a CURL test, run a CONNECTIVITY_COMMAND_TYPE_NC test to confirm basic TCP connectivity. Then verify that:

The service on the target host is TLS-enabled and configured with a valid certificate.
The port is open and reachable.

`INTERNAL_ERROR` returned

If an unexpected internal error occurs, retry the test. If the error persists, create a support ticket and include the cluster_id and the connection_info parameters you submitted.

HCP Vault Connectivity Tester

Prerequisites

Limitations

Supported tests

Test cluster connectivity

API reference

Versioning

Prerequisites

Test connectivity

Request

Command types and parameters

Field validation

Example: all test types

Response reference

TestConnectivityResponse

Audit logging

Troubleshooting

HOSTNAME_UNRESOLVED returned

TIMEOUT returned for an NC test

TIMEOUT returned for all tests (host unreachable)

TLS_HANDSHAKE_FAILED returned for a CURL test

INTERNAL_ERROR returned

`TestConnectivityResponse`

`HOSTNAME_UNRESOLVED` returned

`TIMEOUT` returned for an `NC` test

`TIMEOUT` returned for all tests (host unreachable)

`TLS_HANDSHAKE_FAILED` returned for a `CURL` test

`INTERNAL_ERROR` returned