Azure Private Link - ClickHouse Documentation

이 가이드에서는 Azure Private Link를 사용하여 Azure(고객 소유 서비스 및 Microsoft Partner 서비스 포함)와 ClickHouse Cloud 간에 가상 네트워크를 통한 비공개 연결을 제공하는 방법을 설명합니다. Azure Private Link는 데이터가 퍼블릭 인터넷에 노출되지 않도록 하여 네트워크 아키텍처를 단순화하고 Azure 내 endpoint 간 연결을 안전하게 보호합니다. Azure는 Private Link를 통한 리전 간 연결을 지원합니다. 이를 통해 ClickHouse 서비스가 배포된 서로 다른 리전에 있는 VNet 간 연결을 설정할 수 있습니다.

리전 간 트래픽에는 추가 요금이 부과될 수 있습니다. 최신 Azure 문서를 확인하십시오.

Azure Private Link를 활성화하려면 다음 단계를 수행하십시오.

Private Link용 Azure connection alias를 가져옵니다
Azure에서 Private Endpoint를 생성합니다
Private Endpoint Resource ID를 ClickHouse Cloud 조직에 추가합니다
Private Endpoint Resource ID를 서비스 허용 목록에 추가합니다
Private Link를 사용하여 ClickHouse Cloud 서비스에 액세스합니다

ClickHouse Cloud Azure PrivateLink는 resourceGUID 대신 Resource ID 필터를 사용하도록 변경되었습니다. 이전 버전과의 호환성을 위해 resourceGUID를 계속 사용할 수 있지만, Resource ID 필터로 전환할 것을 권장합니다. 마이그레이션하려면 Resource ID를 사용하여 새 endpoint를 생성하고 이를 서비스에 연결한 후, 기존 resourceGUID 기반 endpoint를 제거하면 됩니다.

주의

ClickHouse는 Azure 리전 내에서 동일한 게시된 Private Link service를 재사용할 수 있도록 서비스를 그룹화하려고 합니다. 하지만 이러한 그룹화는 보장되지 않으며, 특히 서비스가 여러 ClickHouse 조직에 분산되어 있는 경우에는 더욱 그렇습니다. ClickHouse 조직의 다른 서비스에 대해 이미 Private Link가 구성되어 있다면, 이러한 그룹화 덕분에 대부분의 단계를 건너뛰고 마지막 단계인 서비스 허용 목록에 Private Endpoint Resource ID 추가로 바로 진행할 수 있는 경우가 많습니다. Terraform 예시는 ClickHouse Terraform 프로바이더 리포지토리에서 확인할 수 있습니다.

Private Link용 Azure connection alias 가져오기

옵션 1: ClickHouse Cloud 콘솔

ClickHouse Cloud 콘솔에서 PrivateLink로 연결할 서비스를 연 다음 설정 메뉴를 엽니다. Private Endpoint 설정 버튼을 클릭하십시오. Private Link 설정에 사용할 Service name과 DNS name을 메모해 두십시오. Service name과 DNS name을 메모해 두십시오. 다음 단계에서 필요합니다.

옵션 2: API

시작하기 전에 ClickHouse Cloud API Key가 필요합니다. 새 키를 생성하거나 기존 키를 사용할 수 있습니다. API Key를 준비했다면, 명령을 실행하기 전에 다음 환경 변수를 설정하세요.

REGION=<region code, use Azure format, for example: westus3>
PROVIDER=azure
KEY_ID=<Key ID>
KEY_SECRET=<Key secret>
ORG_ID=<set ClickHouse organization ID>
SERVICE_NAME=<Your ClickHouse service name>

리전, provider 및 서비스 이름으로 필터링하여 ClickHouse INSTANCE_ID를 확인하십시오:

INSTANCE_ID=$(curl --silent --user "${KEY_ID:?}:${KEY_SECRET:?}" \
"https://api.clickhouse.cloud/v1/organizations/${ORG_ID:?}/services" | \
jq ".result[] | select (.region==\"${REGION:?}\" and .provider==\"${PROVIDER:?}\" and .name==\"${SERVICE_NAME:?}\") | .id " -r)

Private Link에 사용할 Azure connection alias와 Private DNS 호스트명을 확인합니다:

curl --silent --user "${KEY_ID:?}:${KEY_SECRET:?}" "https://api.clickhouse.cloud/v1/organizations/${ORG_ID:?}/services/${INSTANCE_ID:?}/privateEndpointConfig" | jq  .result
{
  "endpointServiceId": "production-westus3-0-0.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.westus3.azure.privatelinkservice",
  "privateDnsHostname": "xxxxxxxxxx.westus3.privatelink.azure.clickhouse.cloud"
}

endpointServiceId를 메모해 두세요. 다음 단계에서 사용합니다.

Azure에서 Private Endpoint 생성

이 섹션에서는 Azure Private Link를 통해 ClickHouse를 구성할 때 필요한 ClickHouse 관련 세부 정보를 설명합니다. Azure 관련 단계는 어디를 확인해야 하는지 안내하기 위한 참고용으로 제공되며, Azure 클라우드 제공업체의 사전 고지 없이 변경될 수 있습니다. 사용 사례에 맞게 Azure 구성을 검토하십시오.필수 Azure Private Endpoint 및 DNS 레코드 구성은 ClickHouse의 책임 범위에 포함되지 않습니다.Azure 구성 작업과 관련된 문제가 있으면 Azure Support에 직접 문의하십시오.

이 섹션에서는 Azure에서 Private Endpoint를 생성합니다. Azure Portal 또는 Terraform을 사용할 수 있습니다.

옵션 1: Azure Portal을 사용하여 Azure에서 Private Endpoint 만들기

Azure Portal에서 Private Link Center → Private Endpoints를 엽니다. Create 버튼을 클릭하여 Private Endpoint 생성 대화 상자를 엽니다.

다음 화면에서 아래 옵션을 지정합니다.

Subscription / Resource Group: Private Endpoint에 사용할 Azure subscription 및 resource group을 선택합니다.
Name: Private Endpoint의 이름을 설정합니다.
Region: Private Link를 통해 ClickHouse Cloud에 연결할 VNet이 배포된 지역을 선택합니다.

위 단계를 완료한 후 Next: Resource 버튼을 클릭합니다.

Connect to an Azure resource by resource ID or alias 옵션을 선택합니다. Resource ID or alias에는 Private Link용 Azure connection alias 가져오기 단계에서 얻은 endpointServiceId를 사용합니다. Next: Virtual Network 버튼을 클릭합니다.

Virtual network: Private Link를 사용하여 ClickHouse Cloud에 연결할 VNet을 선택합니다
Subnet: Private Endpoint를 생성할 subnet을 선택합니다

선택 사항:

Application security group: ASG를 Private Endpoint에 연결한 뒤, Network Security Groups에서 이를 사용해 Private Endpoint로 들어오거나 나가는 네트워크 트래픽을 필터링할 수 있습니다.

Next: DNS 버튼을 클릭합니다. Next: Tags 버튼을 클릭합니다.

선택적으로 Private Endpoint에 태그를 추가할 수 있습니다. Next: Review + create 버튼을 클릭합니다.

마지막으로 Create 버튼을 클릭합니다. 생성된 Private Endpoint의 Connection status는 Pending 상태가 됩니다. 이 Private Endpoint를 서비스 허용 목록에 추가하면 Approved 상태로 변경됩니다. Private Endpoint와 연결된 network interface를 열고 Private IPv4 address(이 예시에서는 10.0.0.4)를 복사합니다. 이 정보는 다음 단계에서 필요합니다.

옵션 2: Terraform을 사용해 Azure에서 Private Endpoint 생성하기

아래 템플릿을 사용하여 Terraform으로 Private Endpoint를 생성하십시오:

resource "azurerm_private_endpoint" "example_clickhouse_cloud" {
  name                = var.pe_name
  location            = var.pe_location
  resource_group_name = var.pe_resource_group_name
  subnet_id           = var.pe_subnet_id

  private_service_connection {
    name                              = "test-pl"
    private_connection_resource_alias = "<data from 'Obtain Azure connection alias for Private Link' step>"
    is_manual_connection              = true
  }
}

Private Endpoint Resource ID 가져오기

Private Link를 사용하려면 서비스 허용 목록에 Private Endpoint 연결 Resource ID를 추가해야 합니다. Private Endpoint Resource ID는 Azure Portal에 표시됩니다. 이전 단계에서 생성한 Private Endpoint를 열고 JSON View를 클릭하십시오. properties 아래에서 id 필드를 찾아 이 값을 복사하십시오. 권장 메서드: Resource ID 사용 레거시 메서드: resourceGUID 사용 하위 호환성을 위해 resourceGUID도 계속 사용할 수 있습니다. resourceGuid 필드를 찾아 이 값을 복사하십시오.

Private Link용 DNS 설정

Private Link를 통해 리소스에 액세스하려면 Private DNS 존(${location_code}.privatelink.azure.clickhouse.cloud)을 생성한 후 VNet에 연결해야 합니다.

Private DNS 존 생성

옵션 1: Azure Portal 사용 Azure Portal을 사용해 Azure Private DNS 존을 생성하는 방법은 이 가이드를 참고하십시오. 옵션 2: Terraform 사용 다음 Terraform 템플릿을 사용해 Private DNS 존을 생성하십시오:

resource "azurerm_private_dns_zone" "clickhouse_cloud_private_link_zone" {
  name                = "${var.location}.privatelink.azure.clickhouse.cloud"
  resource_group_name = var.resource_group_name
}

와일드카드 DNS 레코드 만들기

와일드카드 레코드를 생성하고 Private Endpoint를 가리키도록 설정합니다. 옵션 1: Azure Portal 사용

MyAzureResourceGroup 리소스 그룹을 열고 ${region_code}.privatelink.azure.clickhouse.cloud Private DNS 영역을 선택합니다.
- Record set을 선택합니다.
Name에 *를 입력합니다.
IP Address에 Private Endpoint에 표시된 IP 주소를 입력합니다.
OK를 선택합니다.

옵션 2: Terraform 사용 다음 Terraform 템플릿을 사용하여 와일드카드 DNS 레코드를 생성합니다:

resource "azurerm_private_dns_a_record" "example" {
  name                = "*"
  zone_name           = var.zone_name
  resource_group_name = var.resource_group_name
  ttl                 = 300
  records             = ["10.0.0.4"]
}

가상 네트워크 링크 생성

Private DNS 존을 가상 네트워크에 연결하려면 가상 네트워크 링크를 생성해야 합니다. 옵션 1: Azure Portal 사용 다음 가이드를 따라 가상 네트워크를 Private DNS 존에 연결하십시오. 옵션 2: Terraform 사용

DNS를 구성하는 방법은 다양합니다. 사용 사례에 맞게 DNS를 설정하십시오.

Private Link용 Azure connection alias 가져오기 단계에서 확인한 “DNS name”이 Private Endpoint IP 주소를 가리키도록 설정해야 합니다. 이렇게 하면 VPC/Network 내의 서비스/구성 요소가 해당 이름을 올바르게 해석할 수 있습니다.

DNS 설정 확인

xxxxxxxxxx.westus3.privatelink.azure.clickhouse.cloud 도메인은 Private Endpoint의 IP를 가리켜야 합니다. (이 예시에서는 10.0.0.4입니다).

nslookup xxxxxxxxxx.westus3.privatelink.azure.clickhouse.cloud.
Server: 127.0.0.53
Address: 127.0.0.53#53

Non-authoritative answer:
Name: xxxxxxxxxx.westus3.privatelink.azure.clickhouse.cloud
Address: 10.0.0.4

ClickHouse Cloud 조직에 Private Endpoint Resource ID를 추가합니다

옵션 1: ClickHouse Cloud 콘솔

조직에 엔드포인트를 추가하려면 서비스 허용 목록에 Private Endpoint Resource ID 추가 단계로 이동하십시오. ClickHouse Cloud 콘솔에서 Private Endpoint Resource ID를 서비스 허용 목록에 추가하면 조직에도 자동으로 추가됩니다. 엔드포인트를 제거하려면 Organization details -> Private Endpoints를 열고 삭제 버튼을 클릭하십시오.

옵션 2: API

명령을 실행하기 전에 다음 환경 변수를 설정하세요:

PROVIDER=azure
KEY_ID=<Key ID>
KEY_SECRET=<Key secret>
ORG_ID=<set ClickHouse organization ID>
ENDPOINT_ID=<Private Endpoint Resource ID>
REGION=<region code, use Azure format>

Private Endpoint Resource ID 가져오기 단계에서 확인한 정보를 사용해 ENDPOINT_ID 환경 변수를 설정합니다. 다음 명령을 실행하여 Private Endpoint를 추가합니다:

cat <<EOF | tee pl_config_org.json
{
  "privateEndpoints": {
    "add": [
      {
        "cloudProvider": "azure",
        "id": "${ENDPOINT_ID:?}",
        "description": "Azure private endpoint",
        "region": "${REGION:?}"
      }
    ]
  }
}
EOF

다음 명령을 실행하여 Private Endpoint를 삭제할 수도 있습니다:

cat <<EOF | tee pl_config_org.json
{
  "privateEndpoints": {
    "remove": [
      {
        "cloudProvider": "azure",
        "id": "${ENDPOINT_ID:?}",
        "region": "${REGION:?}"
      }
    ]
  }
}
EOF

Private Endpoint를 추가하거나 제거한 후, 다음 명령을 실행하여 조직에 적용하십시오:

curl --silent --user "${KEY_ID:?}:${KEY_SECRET:?}" -X PATCH -H "Content-Type: application/json" "https://api.clickhouse.cloud/v1/organizations/${ORG_ID:?}" -d @pl_config_org.json

서비스의 허용 목록에 Private Endpoint Resource ID 추가

기본적으로 ClickHouse Cloud 서비스는 Private Link 연결이 승인되고 설정된 경우에도 Private Link를 통해 사용할 수 없습니다. Private Link를 통해 사용할 각 서비스의 Private Endpoint Resource ID를 명시적으로 허용 목록에 추가해야 합니다.

옵션 1: ClickHouse Cloud 콘솔

ClickHouse Cloud 콘솔에서 PrivateLink를 통해 연결할 서비스를 연 다음 설정으로 이동합니다. 이전 단계에서 얻은 Resource ID를 입력합니다.

기존 PrivateLink connection의 액세스를 허용하려면 기존 endpoint 드롭다운 메뉴를 사용하십시오.

옵션 2: API

명령을 실행하기 전에 다음 환경 변수를 설정하세요:

PROVIDER=azure
KEY_ID=<Key ID>
KEY_SECRET=<Key secret>
ORG_ID=<set ClickHouse organization ID>
ENDPOINT_ID=<Private Endpoint Resource ID>
INSTANCE_ID=<Instance ID>

Private Link를 통해 사용할 수 있어야 하는 각 서비스에 대해 이 작업을 실행하십시오. 다음 명령을 실행하여 서비스의 허용 목록에 Private Endpoint를 추가하십시오:

cat <<EOF | tee pl_config.json
{
  "privateEndpointIds": {
    "add": [
      "${ENDPOINT_ID:?}"
    ]
  }
}
EOF

다음 명령을 실행하여 서비스 허용 목록에서 Private Endpoint를 제거할 수도 있습니다:

cat <<EOF | tee pl_config.json
{
  "privateEndpointIds": {
    "remove": [
      "${ENDPOINT_ID:?}"
    ]
  }
}
EOF

Private Endpoint를 서비스 허용 목록에 추가하거나 제거한 후, 이를 조직에 적용하려면 다음 명령을 실행하세요:

curl --silent --user "${KEY_ID:?}:${KEY_SECRET:?}" -X PATCH -H "Content-Type: application/json" "https://api.clickhouse.cloud/v1/organizations/${ORG_ID:?}/services/${INSTANCE_ID:?}" -d @pl_config.json | jq

Private Link를 사용하여 ClickHouse Cloud 서비스에 액세스하기

Private Link가 활성화된 각 서비스에는 퍼블릭 엔드포인트와 Private Endpoint가 있습니다. Private Link를 사용해 연결하려면 Private Link용 Azure connection alias 가져오기에서 확인한 privateDnsHostname^API 또는 DNS name^console에 해당하는 Private Endpoint를 사용해야 합니다.

Private DNS 호스트명 확인하기

옵션 1: ClickHouse Cloud 콘솔

ClickHouse Cloud 콘솔에서 설정으로 이동합니다. Set up private endpoint 버튼을 클릭합니다. 열리는 플라이아웃에서 DNS Name을 복사합니다.

옵션 2: API

명령을 실행하기 전에 다음 환경 변수를 설정하세요:

KEY_ID=<Key ID>
KEY_SECRET=<Key secret>
ORG_ID=<set ClickHouse organization ID>
INSTANCE_ID=<Instance ID>

다음 명령을 실행하세요:

curl --silent --user "${KEY_ID:?}:${KEY_SECRET:?}" "https://api.clickhouse.cloud/v1/organizations/${ORG_ID:?}/services/${INSTANCE_ID:?}/privateEndpointConfig" | jq  .result

다음과 비슷한 응답이 반환됩니다:

{
  ...
  "privateDnsHostname": "xxxxxxx.<region code>.privatelink.azure.clickhouse.cloud"
}

이 예시에서는 xxxxxxx.region_code.privatelink.azure.clickhouse.cloud 호스트명으로의 연결이 Private Link로 라우팅됩니다. 반면 xxxxxxx.region_code.azure.clickhouse.cloud는 인터넷을 통해 라우팅됩니다. privateDnsHostname을 사용하여 Private Link를 통해 ClickHouse Cloud 서비스에 연결하세요.

문제 해결

DNS 설정 확인

다음 명령을 실행하세요:

nslookup <dns name>

여기서 “dns name”은 Private Link용 Azure connection alias 가져오기에 있는 privateDnsHostname^API 또는 DNS name^console입니다. 다음과 같은 응답이 반환되어야 합니다:

Non-authoritative answer:
Name: <dns name>
Address: 10.0.0.4

상대편에서 연결을 재설정함

대개 서비스의 허용 목록에 Private Endpoint Resource ID가 추가되지 않았기 때문입니다. 서비스 허용 목록에 Private Endpoint Resource ID 추가 단계를 다시 확인하십시오.

Private Endpoint가 대기 상태입니다

대개 서비스 허용 목록에 Private Endpoint Resource ID가 추가되지 않았기 때문입니다. 서비스 허용 목록에 Private Endpoint Resource ID 추가 단계를 다시 확인하십시오.

연결 테스트

Private Link를 사용한 연결에 문제가 있으면 openssl로 연결 상태를 확인하십시오. Private Link endpoint status가 Accepted 상태인지 확인하십시오. OpenSSL로 연결할 수 있어야 합니다(출력에 CONNECTED가 표시됨). errno=104는 정상적으로 예상되는 값입니다.

openssl s_client -connect abcd.westus3.privatelink.azure.clickhouse.cloud:9440

CONNECTED(00000003)
write:errno=104
---
no peer certificate available
---
No client certificate CA names sent
---
SSL handshake has read 0 bytes and written 335 bytes
Verification: OK
---
New, (NONE), Cipher is (NONE)
Secure Renegotiation IS NOT supported
Compression: NONE
Expansion: NONE
No ALPN negotiated
Early data was not sent
Verify return code: 0 (ok)

Private Endpoint 필터 확인

명령을 실행하기 전에 다음 환경 변수를 설정하십시오:

KEY_ID=<Key ID>
KEY_SECRET=<Key secret>
ORG_ID=<ClickHouse 조직 ID를 설정하세요>
INSTANCE_ID=<Instance ID>

다음 명령을 실행하여 Private Endpoint 필터를 확인하세요:

curl --silent --user "${KEY_ID:?}:${KEY_SECRET:?}" -X GET -H "Content-Type: application/json" "https://api.clickhouse.cloud/v1/organizations/${ORG_ID:?}/services/${INSTANCE_ID:?}" | jq .result.privateEndpointIds

추가 정보

Azure Private Link에 관한 자세한 내용은 azure.microsoft.com/en-us/products/private-link를 참조하십시오.

​주의

​Private Link용 Azure connection alias 가져오기

​옵션 1: ClickHouse Cloud 콘솔

​옵션 2: API

​Azure에서 Private Endpoint 생성

​옵션 1: Azure Portal을 사용하여 Azure에서 Private Endpoint 만들기

​옵션 2: Terraform을 사용해 Azure에서 Private Endpoint 생성하기

​Private Endpoint Resource ID 가져오기

​Private Link용 DNS 설정

​Private DNS 존 생성

​와일드카드 DNS 레코드 만들기

​가상 네트워크 링크 생성

​DNS 설정 확인

​ClickHouse Cloud 조직에 Private Endpoint Resource ID를 추가합니다

​옵션 1: ClickHouse Cloud 콘솔

​옵션 2: API

​서비스의 허용 목록에 Private Endpoint Resource ID 추가

​옵션 1: ClickHouse Cloud 콘솔

​옵션 2: API

​Private Link를 사용하여 ClickHouse Cloud 서비스에 액세스하기

​Private DNS 호스트명 확인하기

​옵션 1: ClickHouse Cloud 콘솔

​옵션 2: API

​문제 해결

​DNS 설정 확인

​상대편에서 연결을 재설정함

​Private Endpoint가 대기 상태입니다

​연결 테스트

​Private Endpoint 필터 확인

​추가 정보

주의

Private Link용 Azure connection alias 가져오기

옵션 1: ClickHouse Cloud 콘솔

옵션 2: API

Azure에서 Private Endpoint 생성

옵션 1: Azure Portal을 사용하여 Azure에서 Private Endpoint 만들기

옵션 2: Terraform을 사용해 Azure에서 Private Endpoint 생성하기

Private Endpoint Resource ID 가져오기

Private Link용 DNS 설정

Private DNS 존 생성

와일드카드 DNS 레코드 만들기

가상 네트워크 링크 생성

DNS 설정 확인

ClickHouse Cloud 조직에 Private Endpoint Resource ID를 추가합니다

옵션 1: ClickHouse Cloud 콘솔

옵션 2: API

서비스의 허용 목록에 Private Endpoint Resource ID 추가

옵션 1: ClickHouse Cloud 콘솔

옵션 2: API

Private Link를 사용하여 ClickHouse Cloud 서비스에 액세스하기

Private DNS 호스트명 확인하기

옵션 1: ClickHouse Cloud 콘솔

옵션 2: API

문제 해결

DNS 설정 확인

상대편에서 연결을 재설정함

Private Endpoint가 대기 상태입니다

연결 테스트

Private Endpoint 필터 확인

추가 정보