> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# AWS PrivateLink

> Este documento descreve como se conectar ao ClickHouse Cloud por meio do AWS PrivateLink.

export const ScalePlanFeatureBadge = ({feature = 'Este recurso', linking_verb_are = false}) => {
  return <div className="scalePlanFeatureContainer">
            <div className="scalePlanFeatureBadge">
                Recurso do plano Scale
            </div>
            <div>
                <p>{feature} {linking_verb_are ? 'estão' : 'está'} disponível nos planos Scale e Enterprise. Para fazer upgrade, acesse a página de planos no Console do Cloud.</p>
            </div>
        </div>;
};

export const Image = ({img, alt, size = "lg"}) => {
  const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
  return <div className={`ch-image-${normalizedSize}`}>
      <Frame>
        <img src={img} alt={alt} />
      </Frame>
    </div>;
};

<ScalePlanFeatureBadge feature="AWS PrivateLink" />

Você pode usar o [AWS PrivateLink](https://aws.amazon.com/privatelink/) para estabelecer conectividade segura entre VPCs, serviços da AWS, seus sistemas on-premise e o ClickHouse Cloud sem expor o tráfego à internet pública. Este documento descreve as etapas para se conectar ao ClickHouse Cloud usando o AWS PrivateLink.

<Warning>
  O AWS PrivateLink oferece suporte apenas a conexões iniciadas da sua AWS VPC para o ClickHouse Cloud. Ele não pode ser usado para conexões iniciadas do ClickHouse Cloud para serviços na sua VPC, como um [banco de dados privado](#connecting-to-a-remote-database).
</Warning>

Para restringir o acesso aos seus serviços do ClickHouse Cloud exclusivamente por meio de endereços do AWS PrivateLink, siga as instruções fornecidas pelo ClickHouse Cloud em [IP Access Lists](/docs/pt-BR/products/cloud/guides/security/connectivity/setting-ip-filters).

<Note>
  O ClickHouse Cloud oferece suporte a [PrivateLink entre regiões](https://aws.amazon.com/about-aws/whats-new/2024/11/aws-privatelink-across-region-connectivity/) nas seguintes regiões:

  * sa-east-1
  * il-central-1
  * me-south-1
  * mx-central-1
  * eu-central-2
  * eu-north-1
  * eu-south-2
  * eu-west-3
  * eu-south-1
  * eu-west-2
  * eu-west-1
  * eu-central-1
  * ca-west-1
  * ca-central-1
  * ap-northeast-1
  * ap-southeast-2
  * ap-southeast-1
  * ap-northeast-2
  * ap-northeast-3
  * ap-south-1
  * ap-southeast-4
  * ap-southeast-3
  * ap-south-2
  * ap-east-1
  * af-south-1
  * us-west-2
  * us-west-1
  * us-east-2
  * us-east-1
    Considerações sobre preços: a AWS cobrará dos usuários pela transferência de dados entre regiões. Consulte os preços [aqui](https://aws.amazon.com/privatelink/pricing/).
</Note>

**Conclua as etapas a seguir para habilitar o AWS PrivateLink**:

1. Obtenha o "Service name" do Endpoint.
2. Crie o endpoint da AWS.
3. Adicione o "Endpoint ID" à organização do ClickHouse Cloud.
4. Adicione o "Endpoint ID" à lista de permissões do serviço do ClickHouse.

Encontre exemplos de Terraform [aqui](https://github.com/ClickHouse/terraform-provider-clickhouse/tree/main/examples/).

<div id="considerations">
  ## Considerações importantes
</div>

O ClickHouse tenta agrupar seus serviços para reutilizar o mesmo [endpoint de serviço](https://docs.aws.amazon.com/vpc/latest/privatelink/privatelink-share-your-services.html#endpoint-service-overview) publicado na mesma região da AWS. 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 PrivateLink configurado para outros serviços na sua organização do ClickHouse, muitas vezes poderá pular a maior parte das etapas graças a esse agrupamento e seguir diretamente para a etapa final: adicionar o "Endpoint ID" do ClickHouse à lista de permissões do serviço ClickHouse.

<div id="prerequisites">
  ## Pré-requisitos para este processo
</div>

Antes de começar, você precisará de:

1. Sua conta da AWS.
2. [Chave de API do ClickHouse](/docs/pt-BR/products/cloud/features/admin-features/api/openapi) com as permissões necessárias para criar e gerenciar endpoints privados no lado do ClickHouse.

<div id="steps">
  ## Passos
</div>

Siga estes passos para conectar seus serviços no ClickHouse Cloud por meio do AWS PrivateLink.

<div id="obtain-endpoint-service-info">
  ### Obtenha o endpoint "Service name"
</div>

<div id="option-1-clickhouse-cloud-console">
  #### Opção 1: console do ClickHouse Cloud
</div>

No console do ClickHouse Cloud, abra o serviço ao qual você deseja se conectar via PrivateLink e, em seguida, acesse o menu **Settings**.

<Image img="https://mintcdn.com/private-7c7dfe99/Ph2XgLY43sq6v4yO/images/cloud/security/aws-privatelink-pe-create.webp?fit=max&auto=format&n=Ph2XgLY43sq6v4yO&q=85&s=e7d64cc8197a102205cb3a9e78ad40fc" size="md" alt="Endpoints privados" border width="1556" height="740" data-path="images/cloud/security/aws-privatelink-pe-create.webp" />

Anote o `Service name` e o `DNS name` e siga para a [próxima etapa](#create-aws-endpoint).

<div id="option-2-api">
  #### Opção 2: API
</div>

Primeiro, defina as seguintes variáveis de ambiente antes de executar qualquer comando:

```shell theme={null}
REGION=<Your region code using the AWS format, for example: us-west-2>
PROVIDER=aws
KEY_ID=<Your ClickHouse key ID>
KEY_SECRET=<Your ClickHouse key secret>
ORG_ID=<Your ClickHouse organization ID>
SERVICE_NAME=<Your ClickHouse service name>
```

Obtenha o `INSTANCE_ID` do seu ClickHouse filtrando por região, provedor e nome do serviço:

```shell theme={null}
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 `endpointServiceId` e `privateDnsHostname` para sua configuração do PrivateLink:

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

Este comando deve retornar algo parecido com:

```result theme={null}
{
  "endpointServiceId": "com.amazonaws.vpce.us-west-2.vpce-svc-xxxxxxxxxxxxxxxxx",
  "privateDnsHostname": "xxxxxxxxxx.us-west-2.vpce.aws.clickhouse.cloud"
}
```

Anote o `endpointServiceId` e o `privateDnsHostname` [siga para a próxima etapa](#create-aws-endpoint).

<div id="create-aws-endpoint">
  ### Criar endpoint da AWS
</div>

<Warning>
  Esta seção aborda detalhes específicos do ClickHouse para configurar o ClickHouse por meio do AWS PrivateLink. As etapas específicas da AWS são fornecidas apenas como referência para indicar onde procurar, mas podem mudar ao longo do tempo sem aviso prévio da AWS. Considere a configuração da AWS de acordo com o seu caso de uso específico.

  Observe que o ClickHouse não é responsável por configurar os endpoints de VPC da AWS necessários, as regras de Security Group nem os registros DNS.

  Se você ativou anteriormente "private DNS names" ao configurar o PrivateLink e está enfrentando dificuldades para configurar novos serviços via PrivateLink, entre em contato com o suporte do ClickHouse. Para qualquer outro problema relacionado a tarefas de configuração da AWS, entre em contato diretamente com o suporte da AWS.
</Warning>

<div id="option-1-aws-console">
  #### Opção 1: Console da AWS
</div>

Abra o Console da AWS e vá para **VPC** → **Endpoints** → **Create endpoints**.

Selecione **Endpoint services that use NLBs and GWLBs** e use `Service name`<sup>console</sup> ou `endpointServiceId`<sup>API</sup> obtido na etapa [Obtain Endpoint "Service name" ](#obtain-endpoint-service-info), no campo **Service Name**. Clique em **Verify service**:

<Image img="https://mintcdn.com/private-7c7dfe99/Ph2XgLY43sq6v4yO/images/cloud/security/aws-privatelink-endpoint-settings.webp?fit=max&auto=format&n=Ph2XgLY43sq6v4yO&q=85&s=c3a3c3863e54d648841465850f25fb51" size="md" alt="Configurações do endpoint do AWS PrivateLink" border width="1304" height="721" data-path="images/cloud/security/aws-privatelink-endpoint-settings.webp" />

Se quiser estabelecer uma conexão entre regiões via PrivateLink, marque a caixa de seleção "Cross region endpoint" e especifique a região do serviço. A região do serviço é aquela em que a instância do ClickHouse está em execução.

Se você receber o erro "Service name couldn't be verified.", entre em contato com o Suporte ao Cliente para solicitar a adição de novas regiões à lista de regiões compatíveis.

Em seguida, selecione sua VPC e sub-redes:

<Image img="https://mintcdn.com/private-7c7dfe99/Ph2XgLY43sq6v4yO/images/cloud/security/aws-privatelink-select-vpc-and-subnets.webp?fit=max&auto=format&n=Ph2XgLY43sq6v4yO&q=85&s=b2dcc25f05281adfa0e69af1420014ff" size="md" alt="Selecione a VPC e as sub-redes" border width="1312" height="595" data-path="images/cloud/security/aws-privatelink-select-vpc-and-subnets.webp" />

Como etapa opcional, atribua Security groups/Tags:

<Note>
  Certifique-se de que as portas `443`, `8443`, `9440`, `3306` estejam liberadas no Security Group.
</Note>

Após criar o endpoint da VPC, anote o valor de `Endpoint ID`; você precisará dele em uma próxima etapa.

<Image img="https://mintcdn.com/private-7c7dfe99/Ph2XgLY43sq6v4yO/images/cloud/security/aws-privatelink-vpc-endpoint-id.webp?fit=max&auto=format&n=Ph2XgLY43sq6v4yO&q=85&s=34dc81507345ac1ce833100f731b065d" size="md" alt="ID do endpoint da VPC" border width="467" height="212" data-path="images/cloud/security/aws-privatelink-vpc-endpoint-id.webp" />

<div id="option-2-aws-cloudformation">
  #### Opção 2: AWS CloudFormation
</div>

Em seguida, você precisa criar um endpoint da VPC usando `Service name`<sup>console</sup> ou `endpointServiceId`<sup>API</sup> obtido na etapa [Obter endpoint "Service name" ](#obtain-endpoint-service-info).
Certifique-se de usar os IDs de sub-rede, os grupos de segurança e o ID da VPC corretos.

```response theme={null}
Resources:
  ClickHouseInterfaceEndpoint:
    Type: 'AWS::EC2::VPCEndpoint'
    Properties:
      VpcEndpointType: Interface
      PrivateDnsEnabled: false
      ServiceName: <Service name(endpointServiceId), pls see above>
      VpcId: vpc-vpc_id
      SubnetIds:
        - subnet-subnet_id1
        - subnet-subnet_id2
        - subnet-subnet_id3
      SecurityGroupIds:
        - sg-security_group_id1
        - sg-security_group_id2
        - sg-security_group_id3
```

Depois de criar o endpoint da VPC, anote o valor de `Endpoint ID`; você vai precisar dele em um próximo passo.

<div id="option-3-terraform">
  #### Opção 3: Terraform
</div>

`service_name` abaixo corresponde a `Service name`<sup>console</sup> ou `endpointServiceId`<sup>API</sup> obtido na etapa [Obter o endpoint "Service name" ](#obtain-endpoint-service-info)

```json theme={null}
resource "aws_vpc_endpoint" "this" {
  vpc_id            = var.vpc_id
  service_name      = "<pls see comment above>"
  vpc_endpoint_type = "Interface"
  security_group_ids = [
    Var.security_group_id1,var.security_group_id2, var.security_group_id3,
  ]
  subnet_ids          = [var.subnet_id1,var.subnet_id2,var.subnet_id3]
  private_dns_enabled = false
  service_region      = "(Optional) If specified, the VPC endpoint will connect to the service in the provided region. Define it for multi-regional PrivateLink connections."
}
```

Após criar o endpoint da VPC, anote o valor de `Endpoint ID`; você precisará dele em um próximo passo.

<div id="set-private-dns-name-for-endpoint">
  #### Defina o nome DNS privado do endpoint
</div>

<Note>
  Há várias formas de configurar o DNS. Configure-o de acordo com o seu caso de uso específico.
</Note>

Você precisa apontar o "DNS name", obtido na etapa [Obtain Endpoint "Service name" ](#obtain-endpoint-service-info), para as interfaces de rede do AWS Endpoint. Isso garante que os serviços/componentes dentro da sua VPC/rede consigam resolvê-lo corretamente.

<div id="add-endpoint-id-to-services-allow-list">
  ### Adicione o "Endpoint ID" à lista de permissões do serviço ClickHouse
</div>

<div id="option-1-clickhouse-cloud-console-2">
  #### Opção 1: console do ClickHouse Cloud
</div>

Para adicionar, navegue até o console do ClickHouse Cloud, abra o serviço ao qual você deseja se conectar via PrivateLink e depois vá para **Configurações**. Clique em **Set up private endpoint** para abrir as configurações de endpoints privados. Insira o `Endpoint ID` obtido na etapa [Create AWS Endpoint](#create-aws-endpoint). Clique em "Create endpoint".

<Note>
  Se você quiser permitir acesso a partir de uma conexão PrivateLink existente, use o menu suspenso de endpoint existente.
</Note>

<Image img="https://mintcdn.com/private-7c7dfe99/Ph2XgLY43sq6v4yO/images/cloud/security/aws-privatelink-pe-filters.webp?fit=max&auto=format&n=Ph2XgLY43sq6v4yO&q=85&s=97c06a393efae123ce1aca28415f0c68" size="md" alt="Filtro de endpoints privados" border width="1555" height="748" data-path="images/cloud/security/aws-privatelink-pe-filters.webp" />

Para remover, navegue até o console do ClickHouse Cloud, localize o serviço e depois vá para **Configurações** do serviço. Localize o endpoint que deseja remover. Remova-o da lista de endpoints.

<div id="option-2-api">
  #### Opção 2: API
</div>

Você precisa adicionar um Endpoint ID à lista de permissões de cada instância que deve ficar disponível via PrivateLink.

Defina a variável de ambiente `ENDPOINT_ID` usando os dados da etapa [Criar AWS Endpoint](#create-aws-endpoint).

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

```bash theme={null}
REGION=<Your region code using the AWS format, for example: us-west-2>
PROVIDER=aws
KEY_ID=<Your ClickHouse key ID>
KEY_SECRET=<Your ClickHouse key secret>
ORG_ID=<Your ClickHouse organization ID>
SERVICE_NAME=<Your ClickHouse service name>
```

Para adicionar um ID do endpoint a uma lista de permissões:

```bash theme={null}
cat <<EOF | tee pl_config.json
{
  "privateEndpointIds": {
    "add": [
      "${ENDPOINT_ID:?}"
    ]
  }
}
EOF

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

Para remover um ID de endpoint de uma lista de permissões:

```bash theme={null}
cat <<EOF | tee pl_config.json
{
  "privateEndpointIds": {
    "remove": [
      "${ENDPOINT_ID:?}"
    ]
  }
}
EOF

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

<div id="accessing-an-instance-using-privatelink">
  ### Acessando uma instância usando PrivateLink
</div>

Cada serviço com o Private Link habilitado tem um endpoint público e outro privado. Para se conectar via Private Link, você precisa usar um endpoint privado, que será `privateDnsHostname`<sup>API</sup> ou `DNS Name`<sup>console</sup>, obtido em [Obter endpoint "Service name"](#obtain-endpoint-service-info).

<div id="getting-private-dns-hostname">
  #### Como obter o hostname DNS privado
</div>

<div id="option-1-clickhouse-cloud-console-3">
  ##### Opção 1: console do ClickHouse Cloud
</div>

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

<Image img="https://mintcdn.com/private-7c7dfe99/Ph2XgLY43sq6v4yO/images/cloud/security/aws-privatelink-pe-dns-name.webp?fit=max&auto=format&n=Ph2XgLY43sq6v4yO&q=85&s=85c6a9a5f407b7007d9354d26fa90f0e" size="md" alt="Nome DNS do endpoint privado" border width="1551" height="740" data-path="images/cloud/security/aws-privatelink-pe-dns-name.webp" />

<div id="option-2-api-3">
  ##### Opção 2: API
</div>

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

```bash theme={null}
KEY_ID=<Your ClickHouse key ID>
KEY_SECRET=<Your ClickHouse key secret>
ORG_ID=<Your ClickHouse organization ID>
INSTANCE_ID=<Your ClickHouse service name>
```

Você pode obter `INSTANCE_ID` na [etapa](#option-2-api).

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

Isso deve retornar algo como:

```result theme={null}
{
  "endpointServiceId": "com.amazonaws.vpce.us-west-2.vpce-svc-xxxxxxxxxxxxxxxxx",
  "privateDnsHostname": "xxxxxxxxxx.us-west-2.vpce.aws.clickhouse.cloud"
}
```

Neste exemplo, a conexão usando o valor do nome de host `privateDnsHostname` será roteada pelo PrivateLink, mas a conexão usando o nome de host `endpointServiceId` será roteada pela Internet.

<div id="troubleshooting">
  ## Solução de problemas
</div>

<div id="multiple-privatelinks-in-one-region">
  ### Vários PrivateLinks em uma região
</div>

Na maioria dos casos, você só precisa criar um único serviço de endpoint para cada VPC. Esse endpoint pode encaminhar solicitações da VPC para vários serviços do ClickHouse Cloud.
Consulte [aqui](#considerations)

<div id="connection-to-private-endpoint-timed-out">
  ### A conexão com o endpoint privado expirou
</div>

* Anexe o Security Group ao endpoint da VPC.
* Verifique as regras de `inbound` no Security Group anexado ao Endpoint e libere as portas do ClickHouse.
* Verifique as regras de `outbound` no Security Group anexado à VM usada para o teste de conectividade e permita conexões às portas do ClickHouse.

<div id="private-hostname-not-found-address-of-host">
  ### Hostname privado: endereço do host não encontrado
</div>

* Verifique sua configuração de DNS

<div id="connection-reset-by-peer">
  ### Conexão redefinida pelo host remoto
</div>

* Muito provavelmente, o Endpoint ID não foi adicionado à lista de permissões do serviço; consulte o [passo](#add-endpoint-id-to-services-allow-list)

<div id="checking-endpoint-filters">
  ### Verificando os filtros de endpoint
</div>

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

```bash theme={null}
KEY_ID=<Key ID>
KEY_SECRET=<Key secret>
ORG_ID=<please set ClickHouse organization ID>
INSTANCE_ID=<Instance ID>
```

Você pode obter `INSTANCE_ID` na [etapa](#option-2-api).

```shell theme={null}
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
```

<div id="connecting-to-a-remote-database">
  ### Conectando-se a um banco de dados remoto
</div>

De acordo com a [documentação do AWS PrivateLink](https://docs.aws.amazon.com/whitepapers/latest/building-scalable-secure-multi-vpc-network-infrastructure/aws-privatelink.html):

> Use o AWS PrivateLink quando houver uma configuração cliente/servidor em que você queira permitir que uma ou mais VPCs consumidoras tenham acesso unidirecional a um serviço específico ou a um conjunto de instâncias na VPC do provedor de serviço. Somente os clientes na VPC consumidora podem iniciar uma conexão com o serviço na VPC do provedor de serviço.

Para conectar as funções de tabela [MySQL](/docs/pt-BR/reference/functions/table-functions/mysql) ou [PostgreSQL](/docs/pt-BR/reference/functions/table-functions/postgresql) no ClickHouse Cloud a um banco de dados hospedado na sua VPC da AWS, configure seus grupos de segurança da AWS para permitir conexões do ClickHouse Cloud. Consulte os [endereços IP de egress padrão das regiões do ClickHouse Cloud](/docs/pt-BR/products/cloud/guides/data-sources/cloud-endpoints-api), juntamente com os [endereços IP estáticos disponíveis](https://api.clickhouse.cloud/static-ips.json).