> ## 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.

> Estabeleça uma conexão segura entre o ClickPipes e uma fonte de dados hospedada no GCP usando o Private Service Connect (PSC).

# GCP Private Service Connect para ClickPipes

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

Você pode usar o GCP [Private Service Connect (PSC)](https://cloud.google.com/vpc/docs/private-service-connect) para estabelecer uma conexão segura entre o ClickPipes e uma fonte de dados hospedada no GCP. O ClickPipes cria um **endpoint privado reverso (RPE)** na sua VPC e o aponta para um serviço de endpoint privado publicado para a sua fonte de dados, garantindo que o tráfego nunca seja exposto à internet pública.

<Note>
  A conectividade por PSC do GCP está disponível apenas quando o serviço ClickPipes é implantado no GCP. Verifique a [lista de regiões do GCP que hospedam o ClickPipes](/docs/pt-BR/integrations/clickpipes/networking/static-ips#google-cloud-static-nat-ips) antes de começar.
</Note>

<div id="supported-patterns">
  ## Padrões compatíveis
</div>

| Padrão                           | Quando se aplica                                                                                                                                  | Anexo de serviço                                             |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| **PSC nativo**                   | Serviços gerenciados que publicam automaticamente um anexo de serviço PSC, como o AlloyDB.                                                        | Criado automaticamente quando você ativa o PSC na instância. |
| **PSC controlado pelo produtor** | Fontes de dados que não publicam um anexo de serviço, como o Postgres no Compute Engine ou um serviço gerenciado acessível apenas por IP privado. | Criado e gerenciado por você.                                |

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

* Um serviço do ClickHouse Cloud hospedado no GCP, em uma [região compatível com o ClickPipes](/docs/pt-BR/integrations/clickpipes/networking/static-ips#google-cloud-static-nat-ips).
* Permissões do IAM para habilitar o PSC na sua origem e gerenciar anexos de serviço do PSC (`roles/compute.networkAdmin`).
* O **projeto consumidor do ClickPipes** autorizado a se conectar ao seu anexo de serviço. Para o ClickPipes em produção, é `clickpipes-production`.
* A chave de API/Secret do ClickHouse Cloud da organização proprietária do serviço (necessário apenas se o provisionamento for feito pelo Terraform ou pela API).

<div id="create-rpe">
  ## Crie o endpoint privado reverso
</div>

Para criar um RPE, você precisa das seguintes informações sobre sua fonte de dados:

* **URI do anexo de serviço**: `projects/<PROJECT>/regions/<REGION>/serviceAttachments/<NAME>`, o
  endpoint PSC publicado em frente à sua fonte de dados.
* **Nome DNS privado**: o hostname ao qual seu pipe se conecta. Um endpoint PSC recebe um IP interno estático
  sem um nome DNS associado. Por isso, o ClickPipes resolve esse hostname para esse IP.

<Tabs>
  <Tab title="Interface do ClickPipes">
    1. No ClickHouse Cloud, abra seu serviço e acesse **Fontes de dados** > **ClickPipes**.
    2. Selecione a fonte de dados da qual deseja fazer a ingestão.
    3. Em **Configure sua conexão do ClickPipe**, ative **Usar conexão segura**, clique em **+ Endpoint privado reverso** e escolha **Anexo de serviço do GCP PSC**.
    4. Preencha o **URI do anexo de serviço**, o **Nome DNS privado** e uma **Descrição**.
    5. Clique em **Criar**. O endpoint passa pelos estados `Provisioning` → `Ready`. (O PSC nativo aceita automaticamente, portanto, você não verá `PendingAcceptance`.)
  </Tab>

  <Tab title="Terraform">
    Os mapeamentos personalizados de DNS privado não são um atributo de `clickhouse_clickpipes_reverse_private_endpoint` — eles são gerenciados pelo recurso separado `clickhouse_clickpipes_reverse_private_endpoint_custom_private_dns`, que recebe uma lista completa de mapeamentos para substituição e referencia o endpoint pelo ID:

    ```hcl theme={null}
    resource "clickhouse_clickpipes_reverse_private_endpoint" "gcp_psc" {
      service_id             = var.clickhouse_service_id
      description            = "GCP PSC endpoint"
      type                   = "GCP_PSC_SERVICE_ATTACHMENT"
      gcp_service_attachment = "projects/<PROJECT>/regions/<REGION>/serviceAttachments/<NAME>"
    }

    resource "clickhouse_clickpipes_reverse_private_endpoint_custom_private_dns" "gcp_psc" {
      service_id                  = var.clickhouse_service_id
      reverse_private_endpoint_id = clickhouse_clickpipes_reverse_private_endpoint.gcp_psc.id

      mapping = [
        { private_dns_name = "<PRIVATE_DNS_NAME>" }
      ]
    }
    ```
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    curl --silent --user $KEY_ID:$KEY_SECRET \
      -X POST -H "Content-Type: application/json" \
      https://api.clickhouse.cloud/v1/organizations/<ORG_ID>/services/<SERVICE_ID>/clickpipesReversePrivateEndpoints \
      -d '{
        "type": "GCP_PSC_SERVICE_ATTACHMENT",
        "description": "GCP PSC endpoint",
        "gcpServiceAttachment": "projects/<PROJECT>/regions/<REGION>/serviceAttachments/<NAME>",
        "customPrivateDnsMappings": [
          { "privateDnsName": "<PRIVATE_DNS_NAME>" }
        ]
      }'
    ```
  </Tab>
</Tabs>

<div id="custom-private-dns-rules">
  ### Nomes DNS privados personalizados
</div>

Como o GCP PSC não propaga DNS, um mapeamento personalizado de DNS privado é indispensável para cada endpoint PSC do GCP — é por meio dele que você sempre fornece o nome DNS privado da fonte, e o ClickPipes o resolve para o IP interno estático do endpoint.

Aplicam-se as [regras padrão de nomenclatura de DNS privado personalizado](/docs/pt-BR/integrations/clickpipes/networking/aws-privatelink#custom-private-dns) do ClickPipes — o suporte a curingas, a exclusividade entre os endpoints privados reversos de um serviço e as restrições a sufixos reservados são aplicados de forma idêntica por todos os provedores. Os curingas são especialmente úteis no GCP: um único mapeamento como `*.<cluster>.<region>.managedkafka.<project>.cloud.goog` abrange todos os brokers de um cluster Kafka gerenciado.

Para o GCP PSC, apenas o `privateDnsName` do mapeamento é usado. O campo `internalDNSName` não é compatível, pois um endpoint PSC expõe um IP estático sem nome DNS ao qual possa ser associado — os mapeamentos sempre são resolvidos para esse IP.

<div id="producer-owned">
  ## Aprovando conexões controladas pelo produtor
</div>

Para PSC controlado pelo produtor, adicione o projeto consumidor do ClickPipes à lista de aceitação automática do anexo de serviço para que a conexão seja aceita automaticamente. Caso contrário, o RPE permanecerá em `PendingAcceptance` até que você o aprove manualmente.

Para aceitar a conexão, a lista de aceitação de consumidores do anexo de serviço precisa do URI do endpoint baseado em ID numérico (`projects/<PROJECT>/regions/<REGION>/forwardingRules/<NUMERIC_ID>`). Esse valor é o `endpointWithId` da conexão pendente no anexo de serviço — descreva-o para localizá-lo:

```bash theme={null}
gcloud beta compute service-attachments describe <SERVICE_ATTACHMENT_NAME> \
  --region=<REGION> --project=<YOUR_PROJECT_ID> \
  --format='json(connectedEndpoints)'
```

Obtenha o `endpointWithId` da entrada cujo `status` é `PENDING`, remova o prefixo `https://www.googleapis.com/compute/beta/` e passe o resultado para `--consumer-accept-list`:

```bash theme={null}
gcloud beta compute service-attachments update <SERVICE_ATTACHMENT_NAME> \
  --region=<REGION> --project=<YOUR_PROJECT_ID> \
  --consumer-accept-list=projects/<PROJECT>/regions/<REGION>/forwardingRules/<NUMERIC_ID> \
  --reconcile-connections
```

<Warning>
  Não use aqui o `endpoint_id` da resposta da API/Terraform do ClickPipes — esse valor é o *nome* da regra de encaminhamento, não o ID numérico exigido pelo GCP. Portanto, a lista de aceitação não terá correspondência. Sempre obtenha o ID numérico no `endpointWithId` pendente do anexo de serviço.

  `--consumer-accept-list` também substitui a lista de aceitação, em vez de adicionar itens a ela. Se o anexo de serviço já aceitar outros projetos ou endpoints, inclua todos no mesmo comando; caso contrário, os que forem omitidos perderão o acesso.
</Warning>

<div id="managing-rpes">
  ## Gerenciamento de endpoints privados reversos
</div>

Você pode gerenciar endpoints privados reversos existentes nas configurações do serviço ClickHouse Cloud:

1. Na barra lateral, localize o botão `Settings` e clique nele.

   <Image img="https://mintcdn.com/private-7c7dfe99/KW34O4k4cC0oxlHH/images/integrations/data-ingestion/clickpipes/cp_rpe_settings0.webp?fit=max&auto=format&n=KW34O4k4cC0oxlHH&q=85&s=71e42e9eea9482ef95a7a0268daed9e2" alt="Configurações do ClickHouse Cloud" size="lg" border width="1120" height="928" data-path="images/integrations/data-ingestion/clickpipes/cp_rpe_settings0.webp" />

2. Clique em `Reverse private endpoints` na seção `ClickPipe reverse private endpoints`.

   <Image img="https://mintcdn.com/private-7c7dfe99/KW34O4k4cC0oxlHH/images/integrations/data-ingestion/clickpipes/cp_rpe_settings1.webp?fit=max&auto=format&n=KW34O4k4cC0oxlHH&q=85&s=085af9a759cfaa002abb814936c14600" alt="Configurações do ClickHouse Cloud" size="md" border width="579" height="705" data-path="images/integrations/data-ingestion/clickpipes/cp_rpe_settings1.webp" />

   Informações detalhadas sobre o endpoint privado reverso são exibidas no flyout.

   Esta visualização é somente leitura, exceto pela exclusão: clique no `×` de um endpoint e confirme a exclusão. A exclusão é permanente e interrompe qualquer ClickPipe que esteja usando esse endpoint.

   Para alterar os mapeamentos personalizados de DNS privado de um endpoint, use a API ou o Terraform. A atualização substitui toda a lista de mapeamentos, em vez de adicionar novos mapeamentos a ela.

Se um endpoint mostrar `Rejected` ou `Failed`, leia a mensagem exibida no status: ela diferencia uma conexão rejeitada pelo produtor de uma conexão encerrada ou que requer atenção. Ambos geralmente indicam que a lista de aceitação do anexo de serviço não inclui o projeto consumidor do ClickPipes. Para ver o status informado pelo GCP para o endpoint, descreva os `connectedEndpoints` do anexo de serviço.

<div id="limitations">
  ## Limitações
</div>

* O endpoint RPE e o anexo de serviço devem estar na **mesma região do GCP**. O PSC entre regiões via [acesso global](https://docs.cloud.google.com/vpc/docs/about-accessing-vpc-hosted-services-endpoints#global-access) ainda não é compatível. Use [túnel SSH](/docs/pt-BR/integrations/clickpipes/networking/index#ssh-tunneling) se sua fonte estiver em outra região.
* Um anexo de serviço do PSC só pode ser associado a um serviço do ClickHouse Cloud por vez; ele não pode ser reutilizado em vários serviços. Para mover um anexo de serviço para outro serviço, [entre em contato com o suporte do ClickHouse](https://clickhouse.com/support/program) para liberar a associação existente.