Azure Private Link

Este guia mostra como usar o Azure Private Link para fornecer conectividade privada por meio de uma rede virtual entre o Azure (incluindo serviços de propriedade do cliente e de parceiros da Microsoft) e o ClickHouse Cloud. O Azure Private Link simplifica a arquitetura de rede e protege a conexão entre endpoints no Azure ao eliminar a exposição de dados à internet pública.

O Azure oferece suporte à conectividade entre regiões por meio do Private Link. Isso permite estabelecer conexões entre VNets localizadas em diferentes regiões onde você tem serviços do ClickHouse implantados.

Conclua as etapas a seguir para habilitar o Azure Private Link:

1. Obtenha o alias de conexão do Azure para o Private Link
2. Crie um Private Endpoint no Azure
3. Adicione o Private Endpoint Resource ID à sua organização do ClickHouse Cloud
4. Adicione o Private Endpoint Resource ID à lista de permissões dos seus serviços
5. Acesse seu serviço do ClickHouse Cloud usando o Private Link

O ClickHouse tenta agrupar seus serviços para reutilizar o mesmo serviço de Private Link publicado na região do Azure. No entanto, esse agrupamento não é garantido, especialmente se você distribuir seus serviços entre várias organizações do ClickHouse. Se você já tiver o Private Link configurado para outros serviços na sua organização do ClickHouse, muitas vezes poderá pular a maior parte das etapas devido a esse agrupamento e seguir diretamente para a etapa final: Adicionar o Private Endpoint Resource ID à lista de permissões dos seus serviços.

Encontre exemplos de Terraform no repositório do Terraform provider do ClickHouse.

No console do ClickHouse Cloud, abra o serviço ao qual você deseja se conectar via PrivateLink e, em seguida, abra o menu Settings. Clique no botão Set up private endpoint. Anote o Service name e o DNS name, que serão usados para configurar o Private Link.

Anote o Service name e o DNS name; eles serão necessários nas próximas etapas.

Antes de começar, você precisará de uma API key do ClickHouse Cloud. Você pode criar uma nova chave ou usar uma existente.

Depois de obter sua API key, defina as seguintes variáveis de ambiente antes de executar qualquer comando:

REGION=<código da região, use o formato Azure, por exemplo: westus3>
PROVIDER=azure
KEY_ID=<ID da chave>
KEY_SECRET=<Segredo da chave>
ORG_ID=<defina o ID da organização do ClickHouse>
SERVICE_NAME=<Nome do seu serviço ClickHouse>

Obtenha o INSTANCE_ID da sua instância do ClickHouse filtrando por região, provedor e nome do serviço:

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)

Obtenha o alias de conexão do Azure e o hostname do DNS privado para o Private Link:

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

Anote o endpointServiceId. Você vai usá-lo na próxima etapa.

Nesta seção, vamos criar um Private Endpoint no Azure. Você pode usar o Azure Portal ou o Terraform.

No Azure Portal, abra Private Link Center → Private Endpoints.

Abra a caixa de diálogo de criação do Private Endpoint clicando no botão Create.

Na tela a seguir, especifique as opções abaixo:

• Subscription / Resource Group: escolha a assinatura do Azure e o grupo de recursos do Private Endpoint.
• Name: defina um nome para o Private Endpoint.
• Region: escolha a região em que está a VNet implantada que será conectada ao ClickHouse Cloud via Private Link.

Depois de concluir as etapas acima, clique no botão Next: Resource.

Selecione a opção Connect to an Azure resource by resource ID or alias.

Em Resource ID or alias, use o endpointServiceId obtido na etapa Obtain Azure connection alias for Private Link.

Clique no botão Next: Virtual Network.

• Virtual network: escolha a VNet que você quer conectar ao ClickHouse Cloud usando Private Link
• Subnet: escolha a sub-rede em que o Private Endpoint será criado

Opcional:

• Application security group: você pode anexar um ASG ao Private Endpoint e usá-lo em Network Security Groups para filtrar o tráfego de rede de/para o Private Endpoint.

Clique no botão Next: DNS.

Clique no botão Next: Tags.

Opcionalmente, você pode adicionar tags ao Private Endpoint.

Clique no botão Next: Review + create.

Por fim, clique no botão Create.

O Connection status do Private Endpoint criado ficará no estado Pending. Ele mudará para Approved assim que você adicionar esse Private Endpoint à lista de permissões do serviço.

Abra a interface de rede associada ao Private Endpoint e copie o Private IPv4 address (10.0.0.4 neste exemplo); você precisará dessa informação nas próximas etapas.

Use o modelo abaixo para criar um Private Endpoint com o Terraform:

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
  }
}

Para usar o Private Link, você precisa adicionar o Resource ID da conexão do Private Endpoint à lista de permissões do seu serviço.

O Private Endpoint Resource ID é exibido no Azure Portal. Abra o Private Endpoint criado na etapa anterior e clique em JSON View:

Copie o campo id de nível superior (o Resource ID do endpoint privado, no formato /subscriptions/.../providers/Microsoft.Network/privateEndpoints/<name>) — não use os campos id aninhados dentro do objeto properties:

Método preferido: usando o Resource ID

Método legado: usando resourceGUID Você ainda pode usar o resourceGUID por compatibilidade com versões anteriores. Localize o campo resourceGuid e copie esse valor:

Você precisará criar uma zona DNS privada (${location_code}.privatelink.azure.clickhouse.cloud) e vinculá-la à sua VNet para acessar os recursos via Private Link.

Opção 1: Usando o Azure Portal

Siga este guia para criar uma zona DNS privada no Azure usando o Azure Portal.

Opção 2: Usando o Terraform

Use o template do Terraform a seguir para criar uma zona DNS privada:

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

Crie um registro curinga apontando para o seu Private Endpoint:

Opção 1: Usando Azure Portal

1. Abra o grupo de recursos MyAzureResourceGroup e selecione a zona privada ${region_code}.privatelink.azure.clickhouse.cloud.
2. Selecione + Conjunto de registros.
3. Em Name, digite *.
4. Em IP Address, digite o endereço IP exibido para o Private Endpoint.
5. Selecione OK.

Opção 2: Usando Terraform

Use o seguinte modelo do Terraform para criar um registro DNS curinga:

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

Para vincular a zona DNS privada a uma rede virtual, você precisará criar um link de rede virtual.

Opção 1: Usando o Azure Portal

Siga este guia para vincular a rede virtual à sua zona DNS privada.

Opção 2: Usando Terraform

Você precisa apontar o "DNS name", obtido na etapa Obter o connection alias do Azure para Private Link, para o endereço IP do Private Endpoint. Isso garante que os serviços/componentes dentro da sua VPC/rede consigam resolvê-lo corretamente.

O domínio xxxxxxxxxx.westus3.privatelink.azure.clickhouse.cloud deve apontar para o IP do Private Endpoint (10.0.0.4 neste exemplo).

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

Para adicionar um endpoint à organização, prossiga para a etapa Adicionar o Private Endpoint Resource ID à lista de permissões dos seus serviços. Ao adicionar o Private Endpoint Resource ID à lista de permissões dos serviços pelo console do ClickHouse Cloud, ele é automaticamente adicionado à organização.

Para remover um endpoint, abra Organization details -> Private Endpoints e clique no botão de excluir para remover o endpoint.

Defina as seguintes variáveis de ambiente antes de executar qualquer comando:

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>

Defina a variável de ambiente ENDPOINT_ID usando os dados da etapa Como obter o ID do recurso do Private Endpoint.

Execute o comando a seguir para adicionar o Private Endpoint:

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

Você também pode executar o comando a seguir para remover um Private Endpoint:

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

Após adicionar ou remover um Private Endpoint, execute o comando a seguir para aplicar a alteração à sua organização:

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

Por padrão, um serviço do ClickHouse Cloud não fica disponível por meio de uma conexão Private Link, mesmo que essa conexão esteja aprovada e estabelecida. Você precisa adicionar explicitamente o Private Endpoint Resource ID de cada serviço que deve ficar disponível usando o Private Link.

No console do ClickHouse Cloud, abra o serviço ao qual deseja se conectar via PrivateLink e, em seguida, vá para Settings. Insira o Resource ID obtido na etapa anterior.

Defina estas variáveis de ambiente antes de executar qualquer comando:

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>

Faça isso para cada serviço que deve estar disponível por meio do Private Link.

Execute o comando a seguir para adicionar o Private Endpoint à lista de permissões dos serviços:

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

Você também pode executar o comando a seguir para remover um Private Endpoint da lista de permissões dos serviços:

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

Após adicionar ou remover um Private Endpoint da lista de permissões de serviços, execute o comando a seguir para aplicar essa alteração à sua organização:

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

Cada serviço com Private Link habilitado tem um endpoint público e outro privado. Para se conectar usando Private Link, você precisa usar o endpoint privado, que será privateDnsHostname^API ou DNS name^console, obtido em Obter o alias de conexão do Azure para Private Link.

No console do ClickHouse Cloud, vá para Settings. Clique no botão Set up private endpoint. No painel lateral aberto, copie o DNS Name.

Defina as seguintes variáveis de ambiente antes de executar os comandos:

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

Execute o seguinte comando:

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

Você deve receber uma resposta semelhante à seguinte:

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

Neste exemplo, a conexão com o hostname xxxxxxx.region_code.privatelink.azure.clickhouse.cloud será encaminhada via Private Link. Enquanto isso, xxxxxxx.region_code.azure.clickhouse.cloud será encaminhado pela internet.

Use o privateDnsHostname para se conectar ao seu serviço do ClickHouse Cloud usando Private Link.

Execute o seguinte comando:

nslookup <dns name>

em que "DNS name" é o privateDnsHostname^API ou DNS name^console em Obter alias de conexão do Azure para Private Link

Você deverá receber a seguinte resposta:

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

É bem provável que o Private Endpoint Resource ID não tenha sido adicionado à lista de permissões do serviço. Revise a etapa Adicionar o Private Endpoint Resource ID à lista de permissões dos seus serviços.

Muito provavelmente, o Private Endpoint Resource ID não foi adicionado à lista de permissões do service. Revise a etapa Adicionar o Private Endpoint Resource ID à lista de permissões dos seus services.

Se você tiver problemas para se conectar usando o Private Link, verifique a conectividade com openssl. Certifique-se de que o status do endpoint do Private Link esteja como Accepted.

O OpenSSL deve conseguir se conectar (veja CONNECTED na saída). errno=104 é o esperado.

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)

Defina as seguintes variáveis de ambiente antes de executar qualquer comando:

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

Execute o seguinte comando para verificar os filtros do 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

Para obter mais informações sobre o Azure Private Link, visite azure.microsoft.com/en-us/products/private-link.