> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-detect-table-modification.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuración del aprovisionamiento automático de TLS mediante ACME

> Esta guía proporciona una configuración sencilla y mínima para que ClickHouse use certificados OpenSSL para validar conexiones.

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>
            Funcionalidad experimental. <u><a href="/docs/beta-and-experimental-features#experimental-features">Más información.</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>;
};

<CloudNotSupportedBadge />

<Note>
  Esta página no se aplica a [ClickHouse Cloud](https://clickhouse.com/cloud). El procedimiento que se documenta aquí está automatizado en los servicios de ClickHouse Cloud.
</Note>

Esta guía describe cómo configurar ClickHouse para usar el protocolo [ACME](https://en.wikipedia.org/wiki/Automatic_Certificate_Management_Environment) (descrito en [RFC8555](https://www.rfc-editor.org/rfc/rfc8555)).
Con la compatibilidad con ACME, ClickHouse puede obtener y renovar certificados automáticamente de proveedores como [Let's Encrypt](https://letsencrypt.org/) o [ZeroSSL](https://zerossl.com/).
El cifrado TLS protege los datos en tránsito entre los clientes y los servidores de ClickHouse, evitando que se intercepten consultas y resultados confidenciales.

<div id="overview">
  ## Descripción general
</div>

El protocolo ACME define un proceso de renovación automática de certificados con servicios como [Let's Encrypt](https://letsencrypt.org/) o [ZeroSSL](https://zerossl.com/). En resumen, ClickHouse, como solicitante del certificado, debe confirmar el control del dominio mediante tipos de desafío predefinidos para obtener un certificado.

Para habilitar ACME, configure los puertos HTTP y HTTPS junto con el bloque `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>
```

El puerto HTTP atiende las solicitudes del desafío ACME `HTTP-01` (más información sobre los tipos de desafío [aquí](https://letsencrypt.org/docs/challenge-types/)) durante la validación del dominio. Una vez completada la validación y emitido el certificado, el puerto HTTPS sirve tráfico cifrado con el certificado obtenido.

El puerto HTTP no tiene que ser el 80 en el propio servidor; puede reasignarse con `nftables` o herramientas similares. Consulta la documentación de tu proveedor ACME para conocer los puertos aceptados para los desafíos `HTTP-01`.

En el bloque `acme`, definimos `email` para crear la cuenta y aceptamos los términos del servicio de ACME.
Después de eso, lo único que necesitamos es una lista de dominios.

<div id="current-limitations">
  ### Limitaciones actuales
</div>

* Solo se admite el tipo de desafío `HTTP-01`.
* Solo se admiten claves `RSA 2048`.
* No se admite la limitación de tasa.

<div id="configuration-parameters">
  ## Parámetros de configuración
</div>

Opciones de configuración disponibles en la sección `acme`:

| Parámetro                            | Valor predeterminado                             | Descripción                                                                                                                                                                               |
| ------------------------------------ | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `zookeeper_path`                     | `/clickhouse/acme`                               | Ruta de ZooKeeper utilizada para almacenar los datos de la cuenta ACME, los certificados y el estado de coordinación entre los nodos de ClickHouse.                                       |
| `directory_url`                      | `https://acme-v02.api.letsencrypt.org/directory` | Endpoint del directorio de ACME utilizado para la emisión de certificados. De forma predeterminada, usa el servidor de producción de Let’s Encrypt.                                       |
| `email`                              |                                                  | Dirección de correo electrónico utilizada para crear y administrar la cuenta ACME. Los proveedores de ACME pueden usarla para enviar avisos de vencimiento y actualizaciones importantes. |
| `terms_of_service_agreed`            | `false`                                          | Indica si se aceptan los Términos del servicio del proveedor de ACME. Debe establecerse en `true` para habilitar ACME.                                                                    |
| `domains`                            |                                                  | Lista de nombres de dominio para los que deben emitirse certificados TLS. Cada dominio se especifica como una entrada `<domain>`.                                                         |
| `refresh_certificates_before`        | `2592000` (un mes, en segundos)                  | Tiempo antes del vencimiento del certificado en el que ClickHouse intentará renovarlo.                                                                                                    |
| `refresh_certificates_task_interval` | `3600` (una hora, en segundos)                   | Intervalo con el que ClickHouse comprueba si es necesario renovar los certificados.                                                                                                       |

Ten en cuenta que la configuración usa de forma predeterminada el directorio de producción de Let's Encrypt. Para evitar alcanzar la cuota de solicitudes debido a una posible configuración incorrecta, se recomienda probar primero el proceso de emisión de certificados con el [directorio de staging](https://letsencrypt.org/docs/staging-environment/).

<div id="administration">
  # Administración
</div>

<div id="initial-deployment">
  ## Implementación inicial
</div>

Al habilitar el cliente ACME en un clúster con varias réplicas, hay que tener especial cuidado durante la emisión inicial del certificado.

La primera réplica que se inicie con ACME habilitado intentará de inmediato crear una orden de ACME y realizar la validación del desafío HTTP-01. Si en ese momento solo un subconjunto de réplicas está sirviendo tráfico, es probable que el desafío falle, ya que las demás réplicas no podrán responder a las solicitudes de validación.

Si es posible, se recomienda enrutar temporalmente el tráfico a una sola réplica (por ejemplo, ajustando los registros DNS) y dejar que complete la emisión inicial del certificado. Una vez que el certificado se haya emitido correctamente y se haya almacenado en Keeper, ACME puede habilitarse en las réplicas restantes. Estas reutilizarán automáticamente el certificado existente y participarán en futuras renovaciones.

Si no es factible enrutar el tráfico a una sola réplica, otra opción es cargar manualmente el certificado existente y la clave privada en Keeper antes de habilitar el cliente ACME. Esto evita el paso inicial de validación y permite que todas las réplicas se inicien con un certificado válido ya presente.

Una vez emitido o importado el certificado inicial, su renovación no requiere ningún tratamiento especial, ya que todas las réplicas ya estarán ejecutando el cliente ACME y compartiendo el estado a través de Keeper.

<div id="keeper-data-structure">
  ## Estructura de datos de Keeper
</div>

```text theme={null}
/clickhouse/acme
└── <acme-directory-host>
    ├── account_private_key          # Clave privada de cuenta ACME (PEM)
    ├── challenges                   # Estado activo del desafío HTTP-01
    └── domains
        └── <domain-name>
            ├── certificate          # Certificado TLS emitido (PEM)
            └── private_key          # Clave privada del dominio (PEM)
```

<div id="migrating-from-other-acme-clients">
  ## Migración desde otros clientes ACME
</div>

Es posible migrar el certificado TLS y la clave actuales a Keeper para simplificar el proceso.
Por el momento, el servidor solo admite claves `RSA 2048`.

Suponiendo que se migra desde `certbot` y se usa el directorio `/etc/letsencrypt/live`, se puede utilizar el siguiente 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)\""
```