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

# Configurando o Provisioning automático de TLS via ACME

> Este guia fornece configurações simples e mínimas para configurar o ClickHouse para usar certificados OpenSSL na validação de conexões.

export const ExperimentalBadge = () => {
  return <div className="experimentalBadge">
            <div className="experimentalIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path strokeWidth="1.25" d="M5.5 2H10.5" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.25" d="M9.50015 2V6.19625L13.4283 12.7425C13.4738 12.8183 13.4985 12.9049 13.4996 12.9934C13.5008 13.0818 13.4785 13.169 13.435 13.246C13.3914 13.323 13.3283 13.3871 13.2519 13.4317C13.1755 13.4764 13.0886 13.4999 13.0002 13.5H3.00015C2.91164 13.5 2.8247 13.4766 2.74822 13.432C2.67174 13.3874 2.60847 13.3233 2.56487 13.2463C2.52126 13.1693 2.49889 13.082 2.50004 12.9935C2.50119 12.905 2.52582 12.8184 2.5714 12.7425L6.50015 6.19625V2" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.25" d="M4.47656 9.56754C5.30344 9.41254 6.47656 9.47942 7.99969 10.25C10.0153 11.2707 11.4216 11.0569 12.2184 10.7282" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>
        </div>
            Recurso experimental. <u><a href="/docs/docs/beta-and-experimental-features#experimental-features">Saiba mais.</a></u>
        </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>;
};

export const CloudNotSupportedBadge = () => {
  return <div className="cloudNotSupportedBadge">
            <div className="cloudNotSupportedIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path strokeWidth="1.5" d="M6.33366 12.6666L12.3739 12.6667C13.6593 12.6667 14.7073 11.6187 14.7073 10.3334C14.7073 9.04804 13.6593 8.00003 12.3739 8.00003C12.3739 8.00003 12.3337 7.66659 12.0003 7.33325M10.667 5.33322C8.00033 2.33325 4.45395 4.78537 4.14195 6.68203C2.55728 6.7627 1.29395 8.06203 1.29395 9.6667C1.29395 11.3234 2.66699 12.6666 4.00033 12.6666" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.5" d="M2.66699 14L12.0003 4.66663" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>

        </div>
            Sem suporte no ClickHouse Cloud
        </div>;
};

<ExperimentalBadge />

<CloudNotSupportedBadge />

<Note>
  Esta página não se aplica ao [ClickHouse Cloud](https://clickhouse.com/cloud). O procedimento descrito aqui é automatizado nos serviços do ClickHouse Cloud.
</Note>

Este guia descreve como configurar o ClickHouse para usar o protocolo [ACME](https://en.wikipedia.org/wiki/Automatic_Certificate_Management_Environment) (descrito na [RFC8555](https://www.rfc-editor.org/rfc/rfc8555)).
Com suporte a ACME, o ClickHouse pode obter e renovar automaticamente certificados de provedores como [Let's Encrypt](https://letsencrypt.org/) ou [ZeroSSL](https://zerossl.com/).
A criptografia TLS protege os dados em trânsito entre clientes e servidores ClickHouse, impedindo a interceptação de consultas e resultados sensíveis.

<div id="overview">
  ## Visão geral
</div>

O protocolo ACME define um processo automático de atualização de certificados com serviços como [Let's Encrypt](https://letsencrypt.org/) ou [ZeroSSL](https://zerossl.com/). Em resumo, o ClickHouse, como solicitante do certificado, precisa comprovar o controle do domínio por meio de tipos de desafio predefinidos para obter um certificado.

Para habilitar o ACME, configure as portas HTTP e HTTPS junto com o bloco `acme`:

```xml theme={null}
<http_port>80</http_port>
<https_port>443</https_port>

<acme>
    <email>valid_email@example.com</email>
    <terms_of_service_agreed>true</terms_of_service_agreed>
    <domains>
        <domain>example.com</domain>
    </domains>
</acme>
```

A porta HTTP é usada para atender às solicitações do desafio ACME `HTTP-01` (saiba mais sobre tipos de desafio [aqui](https://letsencrypt.org/docs/challenge-types/)) durante a validação do domínio. Quando a validação é concluída e o certificado é emitido, a porta HTTPS passa a atender o tráfego criptografado usando o certificado obtido.

A porta HTTP não precisa ser 80 no próprio servidor; ela pode ser remapeada usando `nftables` ou ferramentas semelhantes. Consulte a documentação do seu provedor ACME para verificar quais portas são aceitas para desafios `HTTP-01`.

No bloco `acme`, definimos `email` para a criação da conta e aceitamos os termos de serviço do ACME.
Depois disso, a única coisa de que precisamos é uma lista de domínios.

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

* Somente o tipo de desafio `HTTP-01` é compatível.
* Somente chaves `RSA 2048` são compatíveis.
* O rate limiting não é tratado.

<div id="configuration-parameters">
  ## Parâmetros de configuração
</div>

Opções de configuração disponíveis na seção `acme`:

| Parâmetro                            | Valor padrão                                     | Descrição                                                                                                                                                 |
| ------------------------------------ | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `zookeeper_path`                     | `/clickhouse/acme`                               | Caminho do ZooKeeper usado para armazenar os dados da conta ACME, os certificados e o estado de coordenação entre os nós do ClickHouse.                   |
| `directory_url`                      | `https://acme-v02.api.letsencrypt.org/directory` | Endpoint do diretório ACME usado para emissão de certificados. Por padrão, aponta para o servidor de produção do Let’s Encrypt.                           |
| `email`                              |                                                  | Endereço de e-mail usado para criar e gerenciar a conta ACME. Os provedores ACME podem usá-lo para enviar avisos de expiração e atualizações importantes. |
| `terms_of_service_agreed`            | `false`                                          | Indica se os Termos de Serviço do provedor ACME foram aceitos. Deve ser definido como `true` para habilitar o ACME.                                       |
| `domains`                            |                                                  | Lista de nomes de domínio para os quais os certificados TLS devem ser emitidos. Cada domínio é especificado como uma entrada `<domain>`.                  |
| `refresh_certificates_before`        | `2592000` (um mês, em segundos)                  | Tempo antes da expiração do certificado em que o ClickHouse tentará renová-lo.                                                                            |
| `refresh_certificates_task_interval` | `3600` (uma hora, em segundos)                   | Intervalo em que o ClickHouse verifica se os certificados precisam ser renovados.                                                                         |

Observe que, por padrão, a configuração usa o diretório de produção do Let's Encrypt. Para evitar atingir o limite de solicitações devido a uma provável configuração incorreta, recomenda-se primeiro testar o processo de emissão de certificados com o [diretório de staging](https://letsencrypt.org/docs/staging-environment/).

<div id="administration">
  # Administração
</div>

<div id="initial-deployment">
  ## Implantação inicial
</div>

Ao habilitar o cliente ACME em um cluster com várias réplicas, é necessário ter cuidado redobrado durante a emissão inicial do certificado.

A primeira réplica iniciada com o ACME habilitado tentará imediatamente criar uma ordem ACME e realizar a validação do desafio HTTP-01. Se apenas um subconjunto das réplicas estiver recebendo tráfego naquele momento, é provável que o desafio falhe, pois as outras réplicas não conseguirão responder às solicitações de validação.

Se possível, recomenda-se rotear temporariamente o tráfego para uma única réplica (por exemplo, ajustando os registros DNS) e permitir que ela conclua a emissão inicial do certificado. Depois que o certificado for emitido com sucesso e armazenado no Keeper, o ACME poderá ser habilitado nas réplicas restantes. Elas reutilizarão automaticamente o certificado existente e participarão das próximas renovações.

Se não for viável rotear o tráfego para uma única réplica, uma abordagem alternativa é fazer o upload manual do certificado existente e da chave privada para o Keeper antes de habilitar o cliente ACME. Isso evita a etapa inicial de validação e permite que todas as réplicas sejam iniciadas com um certificado válido já disponível.

Depois que o certificado inicial tiver sido emitido ou importado, a renovação do certificado não exigirá tratamento especial, pois todas as réplicas já estarão executando o cliente ACME e compartilhando estado por meio do Keeper.

<div id="keeper-data-structure">
  ## Estrutura de dados do Keeper
</div>

```text theme={null}
/clickhouse/acme
└── <acme-directory-host>
    ├── account_private_key          # Chave privada da conta ACME (PEM)
    ├── challenges                   # Estado ativo do desafio HTTP-01
    └── domains
        └── <domain-name>
            ├── certificate          # Certificado TLS emitido (PEM)
            └── private_key          # Chave privada do domínio (PEM)
```

<div id="migrating-from-other-acme-clients">
  ## Migrando de outros clientes ACME
</div>

É possível migrar o certificado TLS e a chave atuais para o Keeper, facilitando a migração.
No momento, o servidor oferece suporte apenas a chaves `RSA 2048`.

Partindo do pressuposto de que estamos migrando do `certbot` e usando o diretório `/etc/letsencrypt/live`, é possível usar o seguinte conjunto de comandos:

```bash theme={null}
DOMAIN=example.com
CERT_DIR=/etc/letsencrypt/live/$DOMAIN
ZK_BASE=/clickhouse/acme/acme-v02.api.letsencrypt.org/domains/$DOMAIN

clickhouse keeper-client -q "create '/clickhouse' ''"
clickhouse keeper-client -q "create '/clickhouse/acme' ''"
clickhouse keeper-client -q "create '/clickhouse/acme/acme-v02.api.letsencrypt.org' ''"
clickhouse keeper-client -q "create '/clickhouse/acme/acme-v02.api.letsencrypt.org/domains' ''"
clickhouse keeper-client -q "create '$ZK_BASE' ''"

clickhouse keeper-client -q "create '$ZK_BASE/certificate' \"$(cat $CERT_DIR/fullchain.pem)\""
clickhouse keeper-client -q "set '$ZK_BASE/certificate' \"$(cat $CERT_DIR/fullchain.pem)\""

clickhouse keeper-client -q "create '$ZK_BASE/private_key' \"$(cat $CERT_DIR/privkey.pem)\""
clickhouse keeper-client -q "set '$ZK_BASE/private_key' \"$(cat $CERT_DIR/privkey.pem)\""
```