TLS and private CAs

With TLS on the loader speaks HTTPS (clickhouse.protocol: http, usually 8443) or native TLS (native, usually 9440), and either verifies the server's certificate and host name against the container's system trust store. Native TLS trusts the system store only, not a compiled-in root bundle, so both protocols accept the same servers.

Turning TLS on

Setting	Effect
clickhouse.tls.enabled	HTTPS for the connection
clickhouse.tls absent	TLS turns on for a host on 8443 or 9440, or under clickhouse.cloud

The SNI name and the name checked against the certificate are the host in clickhouse.hosts, so connect by a name (or IP) the certificate lists.

Private / internal CAs

A private CA is trusted the way the system trusts it: add it to the image's trust store, or point SSL_CERT_FILE at a PEM bundle that holds it (SSL_CERT_DIR at a directory of them). Either variable replaces the platform store rather than adding to it, so a bundle that must also trust public CAs has to carry them too.

A trust store with no readable CA certificate fails the client at startup instead of connecting unverified.

What is deliberately not offered

clickhouse.tls.ca_cert_file, cert_file, key_file and skip_verify are refused at startup: no client reads them. There is no skip-verify mode, and client-certificate (mTLS) auth is out of scope today.

Example: private-CA cluster

clickhouse:
  protocol: http
  tls:
    enabled: true
  hosts:
    - clickhouse.example.internal:8443

SSL_CERT_FILE=/etc/dfe/ca-bundle.pem   # the private CA plus any public roots still needed

The CA bundle is non-secret and is distributed with the deployment. Keep the cluster password in a Secret, never in committed config. See ../configuration.md for the cascade and ../deployment/ for how secrets are supplied at runtime.