HCP Vault Connectivity Tester

HCP Connectivity Tester는 HCP Vault Dedicated 클러스터에서 데이터베이스, 아이덴티티 제공자, LDAP 서버, DNS 리졸버 같은 내부 리소스까지의 네트워크 도달 가능성(reachability)을 검증해 주는 셀프서비스 진단 도구예요. DNS 해석, TCP 도달 가능성, 네트워크 연결이 HVN(HashiCorp Virtual Network) 전반에서 올바르게 동작하는지 확인할 수 있어요. 데이터베이스 시크릿 엔진, LDAP 인증, MFA 제공자 같은 Vault 통합을 구성하기 전에 사용해 보세요.

출처: 문서

본문

HCP Connectivity Tester는 HCP Vault Dedicated 클러스터에서 데이터베이스, 아이덴티티 제공자, LDAP 서버, DNS 리졸버 같은 내부 리소스까지의 네트워크 도달 가능성을 검증하는 셀프서비스 진단 도구예요. DNS 해석, TCP 도달 가능성, 네트워크 연결이 HVN 전반에서 올바르게 동작하는지 확인할 수 있어요. 데이터베이스 시크릿 엔진, LDAP 인증, MFA 제공자 같은 Vault 통합을 구성하기 전에 사용해 보세요.

이 도구가 없으면 네트워크 장애는 Vault 구성을 배포한 뒤에야 표면화되어, 엔지니어링 에스컬레이션이 필요한 모호한 오류 로그를 만들어 냈어요. 연결 테스터는 dig, nc, curl, ping, traceroute를 실행하는 것과 동등한, 흔한 CLI 진단 명령과 유사한 명확하고 구조화된 진단 결과를 제공해요. 원시 로그를 해석하거나 Vault를 먼저 구성할 필요가 없어요.

사전 요구 사항

HCP Portal 접근 권한
구성된 AWS HVN에 생성된 AWS HCP Vault Dedicated 클러스터
두 네트워크 사이에 설정된 VPC 피어링 연결 또는 Transit Gateway 어태치먼트(AWS 전용). 설정 방법은 HVN 피어링을 참고해 주세요.
(API 전용) 클라이언트 ID와 시크릿이 있는 HCP 서비스 주체(service principal)
(선택) 내부 리졸버에 대한 비공개 DNS 해석을 테스트하도록 HVN에 구성된 BYO-DNS
(선택) 비공개 엔드포인트를 통한 도달 가능성을 테스트하도록 구성된 AWS PrivateLink

제한 사항

연결 테스터는 HCP Vault Dedicated 클러스터만 지원해요.
연결 테스터는 클러스터의 기본 HVN을 지원해요. 백업 리전이 승격된 후에는 승격된 리전에서 BYO-DNS나 PrivateLink 같은 기능에 대한 연결이 유지되지 않아요.
이 도구는 애플리케이션 계층 프로토콜(예: LDAP bind, 데이터베이스 인증)을 검증하지 않아요.
이 도구는 지속적인 모니터링이나 알림을 수행하지 않아요. 온디맨드 진단 도구예요.

지원되는 테스트

테스트	`type` enum 값	CLI 동등 명령	확인하는 내용
DNS 조회	`CONNECTIVITY_COMMAND_TYPE_DIG`	`dig +noall +answer <hostname> @<nameserver>`	DNS 서버를 사용해 호스트 이름을 해석하고 해석된 IP 주소를 반환해요
TCP 도달 가능성	`CONNECTIVITY_COMMAND_TYPE_NC`	`nc -z -v <hostname> <port>`	호스트 이름과 포트에 TCP 연결을 시도하고 열림(open), 닫힘(closed), 도달 불가(unreachable)를 보고해요
TLS / curl	`CONNECTIVITY_COMMAND_TYPE_CURL`	`curl https://<hostname>:<port>`	TLS 핸드셰이크를 수행해 TLS 지원 서비스에 도달 가능한지 확인해요
Ping (ICMP)	`CONNECTIVITY_COMMAND_TYPE_PING`	`ping -c 5 <hostname>`	기본 호스트 도달 가능성을 검증하기 위해 ICMP 에코 요청을 보내요
Traceroute	`CONNECTIVITY_COMMAND_TYPE_TRACEROUTE`	`traceroute <hostname>`	Vault 클러스터와 대상 호스트 사이의 네트워크 경로를 파악해요

클러스터 연결 테스트

연결 테스터를 HCP Portal 또는 HCP API로 실행할 수 있어요.

HCP Portal에서 실행

HCP Portal에 로그인한 사용자로 연결 테스트를 실행할 수 있어요.

HCP Portal에 로그인해요.
왼쪽 탐색에서 Vault Dedicated를 선택해요.
클러스터 목록에서 테스트할 클러스터를 선택해요.
Quick actions 패널에서 Test connectivity 버튼을 선택해요.
Connectivity Tester 패널에서 테스트 유형(Dig, Curl, NC, Ping, Traceroute)을 선택해요.
선택한 테스트 유형에 필요한 파라미터를 입력한 다음 Start test를 선택해요.
결과 패널에 표시되는 구조화된 진단 출력을 검토해요.

HCP API에서 실행

HCP API를 사용하려면 먼저 베어러 토큰(bearer token)을 생성해야 해요. HCP IDP에 인증하거나 HCP CLI를 사용해 베어러 토큰을 생성할 수 있어요.

베어러 토큰 생성 — 서비스 주체로

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

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

HCP 서비스 주체 자격 증명에 대한 환경 변수를 설정해요.

$ export HCP_CLIENT_ID=<HCP_CLIENT_ID> HCP_CLIENT_SECRET=<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 서비스 주체 자격 증명에 대한 환경 변수를 설정해요.

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

HCP에 인증해요.

$ hcp auth login

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

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

클러스터에 대한 환경 변수를 설정해요.

$ export HCP_CLUSTER_ID=<HCP_CLUSTER_ID>

HCP API 토큰을 가져와요.

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

연결 테스트 실행

다음 단계는 HCP API를 사용해요. HCP Portal을 사용하려면 HCP Portal을 참고해 주세요.

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

$ echo $HCP_API_TOKEN $HCP_ORG_ID $HCP_PROJ_ID $HCP_CLUSTER_ID

test-connectivity 엔드포인트로 POST 요청을 보내 연결 테스트 요청을 제출해요.

$ 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 ***" \
 --data '{
   "connection_info": [
     {
       "type": "CONNECTIVITY_COMMAND_TYPE_DIG",
       "hostname": "database.internal.corp"
     }
   ]
 }' | jq

API 레퍼런스

HCP Vault Dedicated 연결 테스터 API는 테스트를 시작하는 엔드포인트를 제공해요. 다양한 네트워크 시나리오에 따라 사용할 수 있는 테스트가 달라져요.

버전 관리

HCP Vault Dedicated API 버전은 2023-05-01이에요.

사전 요구 사항

인증을 위해 접근 토큰 가져오기

연결 테스트

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

요청 본문은 connection_info 배열을 받아요. 각 요소는 type enum과 그 테스트의 파라미터를 가진 평면 객체예요. 단일 요청에 하나 이상의 테스트를 제출할 수 있어요.

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

요청

명령 유형과 파라미터

`type`	`hostname`	`port`	`resolver_ip`	설명
`CONNECTIVITY_COMMAND_TYPE_DIG`	필수	—	선택	DNS 조회. `hostname`을 해석하며, 선택적으로 지정된 `resolver_ip` IP를 사용해요.
`CONNECTIVITY_COMMAND_TYPE_NC`	필수	필수	—	TCP 도달 가능성 확인. `port`의 `hostname`에 TCP 연결을 시도해요.
`CONNECTIVITY_COMMAND_TYPE_CURL`	필수	필수	—	TLS 연결 확인. `port`의 `hostname`에 TLS 핸드셰이크를 수행해요.
`CONNECTIVITY_COMMAND_TYPE_PING`	필수	—	—	ICMP 도달 가능성. `hostname`에 에코 요청 5개를 보내요.
`CONNECTIVITY_COMMAND_TYPE_TRACEROUTE`	필수	—	—	Vault 클러스터에서 `hostname`까지의 네트워크 경로 추적.

필드 검증

필드	유형	필수	검증 규칙
`type`	enum	예	위에 나열된 `CONNECTIVITY_COMMAND_TYPE_*` 값 중 하나여야 해요.
`hostname`	string	예	Vault에 연결하는 대상의 유효한 FQDN 또는 IPv4 주소. 최대 253자. RFC 1123 준수. 공백, 셸 메타문자(`;`, `&`, `\|`, ```, `$`), 플래그 접두사(`-`)가 없어야 해요.
`port`	uint32	예(`NC`, `CURL`만)	1–65535 범위의 정수.
`resolver_ip`	string	선택(`DIG`만)	유효한 IPv4 또는 IPv6 주소. 차단 주소 목록에 대해 검증돼요. 생략하면 HVN 기본 리졸버를 사용해요.

예: 모든 테스트 유형

다음 예는 단일 요청에 다섯 가지 테스트 유형을 모두 제출해요.

$ 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 ***" \
    --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

성공 시 예제 출력:

{
  "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"
    }
  ]
}

실패 시 예제 출력:

{
  "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"
    }
  ]
}

응답 레퍼런스

`TestConnectivityResponse`

필드	유형	설명
`connection_results`	array	제출된 각 테스트 명령에 대한 결과 목록으로, 제출 순서대로 정렬돼요.
`connection_results[].command_type`	string	실행된 테스트의 `CONNECTIVITY_COMMAND_TYPE_*` 값.
`connection_results[].status`	string	`CONNECTION_STATUS_SUCCESS` 또는 `CONNECTION_STATUS_FAILURE`.
`connection_results[].detail`	string	성공 시 사람이 읽을 수 있는 진단 출력. 실패 시 빈 문자열.
`connection_results[].error`	object \| null	성공 시 `null`. 실패 시 `code`와 `message`를 포함해요.
`connection_results[].error.code`	string	기계가 읽을 수 있는 오류 코드. 아래 오류 코드를 참고해 주세요.
`connection_results[].error.message`	string	사람이 읽을 수 있는 오류 설명.
`connection_results[].duration_ms`	string	테스트에 걸린 시간(밀리초).

참고

차단 목록(blocklist)은 입력 검증과 DNS 해석 후 단계 양쪽에서 적용돼요. 이는 호스트 이름이 처음에는 검증을 통과하지만 런타임에 차단된 내부 IP로 해석되는 DNS 리바인딩 공격을 방지해요.

감사 로깅

모든 연결 테스트 호출은 다음 필드와 함께 HCP 감사 로그에 기록돼요.

호출자 아이덴티티(organization_id, project_id, 사용자 토큰 subject)
호출 타임스탬프
클러스터 ID
테스트 결과(CONNECTION_STATUS_SUCCESS 또는 CONNECTION_STATUS_FAILURE)

문제 해결

연결 테스트의 결과를 통해 어떤 문제 해결 단계를 고려해야 할지 판단할 수 있어요.

`HOSTNAME_UNRESOLVED` 반환

다음을 확인해 주세요.

대상 호스트 이름이 개인 DNS 영역에 존재하는지.
사용자 지정 resolver_ip를 사용 중이라면(DIG만), resolver_ip가 올바르고 HVN에서 도달 가능한지.
BYO-DNS가 구성되어 있고 DNS 서버의 보안 그룹이 HVN CIDR에서 포트 53으로 인바운드 UDP/TCP 트래픽을 허용하는지.

`NC` 테스트에 `TIMEOUT` 반환

다음을 확인해 주세요.

대상 서비스가 지정된 포트에서 실행 중이고 수신 대기하고 있는지.
보안 그룹 또는 방화벽 규칙이 HVN CIDR에서 해당 포트로 인바운드 TCP 트래픽을 허용하는지.
VPC 피어링 또는 Transit Gateway 경로가 HVN과 대상 VPC 사이에 올바르게 구성되어 있는지.

모든 테스트에 `TIMEOUT` 반환(호스트 도달 불가)

다음을 확인해 주세요.

VPC 피어링 또는 Transit Gateway 어태치먼트가 설정되고 ACTIVE 상태인지.
HVN과 대상 VPC 양쪽의 라우트 테이블에 상대 네트워크의 CIDR 항목이 포함되어 있는지.
두 네트워크 사이의 트래픽을 차단하는 네트워크 ACL이 없는지.

`CURL` 테스트에 `TLS_HANDSHAKE_FAILED` 반환

CURL 테스트를 실행하기 전에 CONNECTIVITY_COMMAND_TYPE_NC 테스트를 먼저 실행해 기본 TCP 연결을 확인해 주세요. 그런 다음 다음을 확인해 주세요.

대상 호스트의 서비스가 TLS를 활성화하고 유효한 인증서로 구성되어 있는지.
포트가 열려 있고 도달 가능한지.

`INTERNAL_ERROR` 반환

예기치 않은 내부 오류가 발생하면 테스트를 다시 시도해 주세요. 오류가 지속되면 지원 티켓을 만들고 제출한 cluster_id와 connection_info 파라미터를 포함해 주세요.

더 알아보기 (Learn more)

BYO-DNS (비공개 DNS) 문서에서 자체 DNS 서버를 가져오는 방법을 살펴볼 수 있어요.
AWS PrivateLink 문서에서 비공개 엔드포인트 구성을 배워 보세요.
HVN 피어링 문서에서 네트워크 연결을 설정해 보세요.

HCP Vault Connectivity Tester