Configuring TLS for ClickHouse: when a self-managed cluster needs it
A self-managed ClickHouse cluster that carries event, log or telemetry data over networks shared with applications, analysts or other teams needs TLS to protect data in transit and to let clients verify the server they connect to. In regulated environments, encrypted connections are usually a prerequisite that auditors and security teams expect to see before they review anything else. Without TLS, query text, credentials and result sets travel in plaintext across every segment the traffic crosses, and a client has no reliable way to confirm it reached the intended server rather than an impostor on the same network.
ClickHouse server is open-source software under the Apache License 2.0 (*Apache-2.0*), so the TLS design, the certificate authority, the trust store and the decision to accept or reject client certificates all sit with your organization, not with a vendor. Scope the work to every path that carries data: HTTPS and the native protocol for clients, and, where relevant, the traffic between replicas and between replicas and ClickHouse Keeper. Each path has its own listener, certificate and verification settings, so an audit of one does not cover the others. Confirm with your security team which of these paths must be encrypted, and whether internal segments count as trusted under your policy.
Enabling TLS is a technical control, not a certification. No vendor certification, attestation or audit result follows from turning on HTTPS or the secure native port, and a compliance assessor will judge the full configuration, key handling and evidence. Before you start, decide who issues and rotates certificates, where private keys are stored, and whether plaintext ports will be closed once clients have migrated. The ClickHouse GitHub repository is the place to confirm the behavior of the release you run, and the sections that follow cover the configuration steps themselves.
Which TLS option fits each client path
This table compares HTTPS, native TLS, server-only verification, mutual TLS and plaintext listeners by client path. Read each row as a decision: find the client type you operate, then check what it must change and what certificate work it adds. The main takeaway is that mutual TLS gives the strongest client identity but carries the heaviest certificate distribution and rotation burden.
| Client path | When it fits | What clients must change | What it protects and main operational cost |
|---|---|---|---|
| HTTPS interface | Browser tools, BI platforms and applications that already call the HTTP interface | Use an https scheme and trust the internal CA; update connection strings in each application | Encrypts query traffic and credentials in transit. Cost: distributing the CA bundle and renewing the server certificate before expiry |
| Native TLS interface | Drivers and services that use the native protocol for high-throughput ingestion or queries | Enable TLS in the client driver and point it at the secure native port with the CA file | Encrypts native protocol traffic. Cost: confirming driver TLS support and certificate handling for each language stack |
| Server-only verification | Most internal applications where the server must prove its identity but clients authenticate with passwords or external authenticators | Clients verify the server certificate against the CA and send their usual credentials | Protects against impersonation of the server and credential interception. Cost: CA distribution and server certificate rotation; client identity is not proven by certificate |
| Mutual TLS with client certificates | Service-to-service paths, ingestion pipelines and admin access where client identity should be certificate-based | Each client holds its own certificate and key, and the server is configured to verify it | Proves client identity cryptographically and supports certificate-based access controls. Cost: issuing, storing, rotating and revoking a certificate for every client, and handling clients that cannot present one |
| Plaintext listeners disabled | Production clusters after all clients have been moved to TLS | Remove plaintext client connections and confirm no service still uses them | Prevents credentials and data crossing the network unencrypted. Cost: finding forgotten clients first, so inventory query logs before turning plaintext off |
| Plaintext listeners retained | Short migration windows or isolated networks with a documented compensating control | Clients keep existing settings until moved | Offers no transport protection. Cost: a standing exception that assessors will ask you to justify and track |
| Internal Keeper and replica traffic | Traffic between ClickHouse servers and ClickHouse Keeper nodes | Each node needs matching certificates and verification settings | Protects coordination and replication traffic. Cost: consistent certificate handling across every node, where one mismatch can break replication |
Setting up TLS for ClickHouse step by step
This sequence takes a self-managed ClickHouse deployment from an inventory of its connections to a verified, encrypted setup in which the server rejects untrusted certificates and plaintext listeners are closed or restricted. Each step ends with a check you can record as evidence.
Inventory every client and node connection
Before touching configuration, list every path that reaches a ClickHouse node: application clients, BI tools, ingestion pipelines, admin sessions, monitoring scrapers, load balancers, and replica-to-replica and Keeper traffic. Record the protocol and port each one uses today, and note which ones carry credentials or query results. Your network team and application owners should confirm the list. The step is done when every path is named, with an owner and a target protocol, and nothing is left as an unknown.
Create the certificate authority and key storage
Set up a private certificate authority (CA) for internal ClickHouse traffic, or confirm that your organization's existing internal CA will issue for it. Keep the CA private key offline or in a hardware-backed or secrets store with restricted access, and document who can sign certificates. Decide where server keys will live on each host. The step is done when you can issue a test certificate from the CA and the CA certificate is distributed to the hosts and clients that must trust it.
Issue server certificates with correct names
Generate a private key and certificate signing request for each ClickHouse node, with subject alternative names that match the exact hostnames or addresses clients use to connect, including any load balancer or service name. Sign each request with the internal CA using OpenSSL, and set an expiry date your rotation process can meet. Check each certificate with OpenSSL's inspection commands to confirm the names, validity dates and issuing CA. The step is done when every node certificate chains to your CA and lists the names clients will verify.
Place keys with restricted file ownership
Copy each node's private key and certificate to a directory that only the ClickHouse service account and administrators can read. Keys should not be readable by general users, should not sit in shared repositories, and should not be passed on the command line. Use file permissions and ownership on the host, and make sure configuration management or your secrets tool writes them the same way on every node. The step is done when a permission listing shows the key readable only by the intended accounts, and the ClickHouse process starts as that account.
Enable HTTPS and native TLS listeners
Add the TLS listener and certificate settings to the server configuration on one node first, then open the secure HTTP and secure native protocol ports you planned. Use the official configuration reference for the exact keys, port settings and certificate paths for your ClickHouse version, rather than copying settings from older examples. Restart or reload according to the documentation for the setting. The step is done when the server logs show the secure listeners starting without certificate errors and the ports are bound on the expected interface.
Set the verification mode for clients and peers
Decide how strictly the server and its clients check each other. Require the server to present a certificate that chains to your CA, and where the design allows, require client certificates or a verified client identity for connections that need it. Apply the same trust settings to replica-to-replica traffic and to clients such as the ClickHouse client tool. Read the configuration reference for the verification options in your version before choosing a mode. The step is done when the chosen mode is written in configuration and applied to every node in the cluster.
Test a verified connection with the CA
From a client host that holds the CA certificate, connect over the secure native port and over HTTPS, specifying the CA file and the server name you issued. Run a simple query such as selecting the server version and confirm that the handshake succeeds without disabling verification. Repeat the test against each node and against any load balancer endpoint. The step is done when every expected client path completes a verified connection and the session shows the encrypted protocol in use.
Confirm rejection of an untrusted certificate
Test the negative case on purpose. Attempt a connection from a client that uses a CA certificate that did not sign the server certificate, and attempt one with a server name that does not match the certificate. Both attempts should fail during the TLS handshake. Keep the output as evidence. The step is done when each invalid trust path is refused and the refusal is recorded, which shows the verification you configured is actually enforced.
Disable or restrict plaintext listeners
Remove the plaintext HTTP and native ports from the listener configuration where all clients now use TLS, or restrict them to a management interface that only approved administrators can reach. Then review the listening sockets on every node with a port scan or the host's socket listing, and compare the result with the inventory from the first step. Check firewall rules, load balancer health checks and monitoring scrapers so they use the secure endpoints or an approved exception. The step is done when the listening port review matches the plan, and any remaining plaintext port has a documented reason and a firewall rule.
Security controls TLS does not provide on its own
TLS protects data in transit and proves server identity, but it does not decide who can log in, which hosts can connect or whether the server still receives security fixes. The cards below cover the controls that sit alongside your TLS configuration and that a secure listener depends on.
Restrict the default user
ClickHouse ships with a default user that starts with all permissions. Encrypted connections do not limit what a valid login can do, so an unprotected default account remains a path to full access. Set a password or disable the account, then create named administrators through SQL-driven access control. Check the result with a query that lists users and their grants, and confirm that no application still connects as default.
Protect private keys
A certificate is only as trustworthy as its private key. Store server and CA keys outside the ClickHouse data directory, give the clickhouse service account read access to the key file alone, and restrict write and copy access to a small operator group. Confirm file permissions on every node after each rotation, and keep CA keys offline or in a dedicated secrets system.
Limit which hosts reach TLS listeners
An HTTPS or native TLS port open to every network segment exposes the login surface to hosts that have no business reaching it. Use listen_host settings to bind listeners to the interfaces you intend, and apply host firewall rules that allow only application subnets, load balancers and monitoring. Verify from an unapproved network segment that the TLS ports refuse connections.
Separate Keeper and replication traffic
TLS on client ports does not secure the coordination layer between replicas. ClickHouse Keeper handles metadata for ReplicatedMergeTree tables, and its client and Raft traffic need their own TLS settings, access control and host isolation. Treat Keeper as a separate security boundary, and confirm that its ports are reachable only from ClickHouse servers and approved administrators.
Stay on a supported release
A correctly configured TLS stack still inherits flaws in the server code. The ClickHouse security policy lists versions 26.9, 26.8, 26.7 and 26.3 as currently supported with security updates, and all other versions as unsupported. Record the running version on every node, map it against that list, and plan upgrades so that the cluster does not drift onto an unsupported line.
Keep TLS settings identical on every node
A cluster where one node accepts an old protocol, uses a different CA bundle or still listens on a plaintext port weakens every connection that might reach it. Configuration drift often appears after a node rebuild or a rotation that missed one host. Compare the listener, certificate and CA settings across all servers and Keeper nodes, and make the comparison part of each change record.
How to rotate ClickHouse certificates without an outage
Rotation is a routine you schedule, not an event you react to. Start with an inventory that lists every certificate ClickHouse presents or trusts: the HTTPS and native TLS server certificates on each node, any client certificates used by applications or replication, and the CA certificate each side validates against. For each entry, record the subject, issuer, serial number, expiry date and the files it is loaded from, such as the server certificate and key paths in the openSSL section of the server configuration. Set a reminder well before the earliest expiry. Issue the replacement from the same certificate authority so that clients already trusting that CA keep working, and do it before the old certificate expires, not after.
Roll the change one node at a time and verify before moving on. Replace the certificate files on a single node, then decide whether that node needs a configuration reload or a full restart. Confirm the reload behavior for your exact version in the official documentation, because not every TLS setting is picked up without a restart. After the change, run a client test against that node using the verification mode your clients use, for example a clickhouse-client connection over the secure port with certificate checking enabled, and confirm the presented certificate shows the new serial and expiry. Only then move to the next replica. Keep the old certificate in place during the overlap so a failed node can be rolled back quickly.
Confirm the chain during the overlap, then retire the old certificate. While both certificates are valid, check that every client, replica peer and monitoring agent still trusts the chain, including any clients that pin the CA bundle or that pin a specific intermediate. A common failure is a new certificate issued under an intermediate that some clients do not yet trust. Automated issuance through ClickHouse's experimental ACME client is covered in a sibling topic, but many teams find an external certificate manager the safer choice, since it centralizes expiry tracking and renewal across databases, proxies and other services. Whichever route you take, ask your certificate team to confirm which CA and renewal process they will use before the first rotation.
What to confirm in your environment before rollout
TLS for ClickHouse touches more than the server config file. The items below are the points where a plan built on general assumptions tends to break, so confirm each one against the exact ClickHouse version and the systems around it before any listener is switched off.
Exact keys and ports for your version
Configuration keys, certificate paths and default port numbers for HTTPS and native TLS are version-specific, so copy them from the documentation for the release you will run, not from older tutorials or blog posts. Check whether your build exposes the secure and plaintext listeners you expect, and confirm how each is enabled in the server configuration. Record the result in your change plan so the reviewer can compare it with the running node.
Client driver and tool support
Every application, BI tool, ingestion agent and CLI in your stack must support the verification mode you choose, including whether it validates the server certificate chain, checks the host name and accepts a custom certificate authority. Some clients only trust the system store or cannot present a client certificate. Test each one against a staging node with the chosen mode before cutover, and keep a list of clients that need a separate plan.
Replication and Keeper connections
TLS on the client listener does not secure traffic between replicas or between the servers and ClickHouse Keeper. Check whether inter-server replication and Keeper client and Raft traffic are encrypted in your design, and plan that work as its own item with its own certificates and rollout order. Confirm that a replica can still fetch parts and that Keeper quorum still forms after each change, because a mismatch there can stall replication rather than fail loudly.
Release line and support window
The release line you run decides which security updates you receive and how long a configuration can stay unchanged. Check the security policy for the versions currently supported, confirm whether you are on a stable or LTS line, and plan certificate and configuration changes so they survive your next scheduled upgrade. Read the changelog for the target release before you schedule it.
Load balancers and proxies
A load balancer, ingress controller or reverse proxy in front of ClickHouse may terminate TLS itself, which changes where encryption starts and where certificates must live. Confirm whether traffic between the proxy and the server is also encrypted, whether client certificate verification passes through, and which component logs the client address. Document the full path from client to storage so the security review covers every hop, not only the server.
Certificate authority and rotation owner
Confirm who issues, stores and renews server and client certificates, and how the certificate authority is trusted by each client and node. Decide who owns rotation, how expiry is monitored, and how a reload is verified without a restart window that breaks ingestion. Ask whether your certificate tooling can reach every node in the cluster, and test an expired or revoked certificate in staging so the failure mode is known before production.
Questions teams ask before enabling TLS on ClickHouse
How much effort does enabling TLS on ClickHouse take?
The effort depends mostly on how many clients connect, how many nodes need certificates, and how much of your PKI already exists. A small single-node setup with an internal certificate authority is a short configuration task. A multi-node cluster with ClickHouse Keeper, several application services, BI tools and monitoring agents adds a certificate per host, a trust chain every client must accept, and a test pass for each client library. Ask whether your certificate authority already issues server and client certificates, and which clients you must change. Each unknown in that list moves the estimate more than the ClickHouse settings themselves.
What sets the duration of a TLS rollout?
The duration is set by coordination, not by the configuration file. The main drivers are how quickly your PKI owners can issue certificates, how many application teams must update connection strings and drivers, and whether you can run a mixed period where plaintext and TLS ports both accept traffic. Replicated clusters add a step: each node and each Keeper member must be changed and verified without breaking replication. Ask for a schedule that lists the clients, the change windows and the rollback point for each stage.
What does the internal team need to provide for a TLS project?
Three groups of people usually decide whether the work goes smoothly. PKI owners approve the certificate authority, key lengths, validity periods and how certificates are issued. Network and application owners confirm which ports are reachable, which clients connect and when they can restart. A test environment with representative clients lets you prove that each driver, dashboard and ingestion job accepts the new certificates before production changes. Without a test environment, the first real verification happens in production, which is the riskiest place to find a trust chain error.
Can our own engineers enable TLS using the official documentation?
Yes, for a small and well-understood environment, an experienced ClickHouse team can work from the official documentation and the configuration reference for the version you run. The gaps tend to appear in the surrounding work: deciding how certificates are issued and renewed, testing every client library against the new trust chain, and proving that plaintext ports are closed. If your team has no one who owns PKI or has not tested TLS across the full client list, a fixed-scope engagement can cover the design, the rollout and the verification steps, with your team retaining ownership of the environment.
What recurs after TLS goes live?
TLS is not a one-time change. Certificates expire, so someone must monitor expiry dates on every server and client certificate and renew them before the deadline. Each renewal needs a reload or restart plan, and the new certificate must still chain to the authority that clients trust. New clients, new services and new library versions also need testing against your trust setup. Budget for these as an ongoing operations task, and ask any partner whether post-go-live rotation, expiry monitoring and client updates are included in the quote or offered as a separate retainer.
What should a quote for TLS work include?
A useful quote lists the scope in writing: the ClickHouse nodes and Keeper members in scope, the certificate authority model (existing or new), the client types and drivers to be tested, and whether plaintext ports will be disabled. It should name the deliverables, such as configuration, a rollout runbook, verification evidence and a rotation procedure, and state what is excluded, such as changes to client applications or PKI redesign. Ask how changes are handled after signing, what your team must provide and when, and whether post-go-live support is a separate retainer. DeployOpen does not publish a price list; a quote follows from the written scope.
Which ClickHouse version should we target when enabling TLS?
Confirm the version before you write the configuration, because TLS settings and supported releases change over time. The ClickHouse security policy lists the versions that currently receive security updates, and the production FAQ recommends stable releases for most production use with a pre-production environment that has representative data. Plan the TLS change on a supported version so that any security fix you need later arrives without a forced upgrade in the middle of the certificate work.
How DeployOpen works on this
DeployOpen plans, builds, documents and supports self-hosted ClickHouse TLS inside your own infrastructure, including the certificate authority, listener settings, client verification and rotation procedure. Each engagement starts from a written scope, so you know which ports, clients and certificate paths are covered before any change is made.
How we scope
- Inventory every HTTPS, native TLS and plaintext listener across ClickHouse and Keeper nodes before choosing changes
- Agree whether the certificate authority is internal, enterprise-managed or an external issuer, in writing
- Record which clients, drivers and BI tools must connect and whether they verify server certificates
- Confirm the target ClickHouse versions, since supported release lines determine which TLS options you can rely on
How we build
- Build the certificate authority and issue server and client certificates with the subject names your nodes actually use
- Configure server TLS listeners and client verification modes, then test each mode with real client connections
- Disable plaintext ports on a staged schedule, with a rollback path for clients that still depend on them
- Set up a documented rotation procedure and test certificate renewal on a non-production cluster first
How we hand over
- Deliver configuration files, the certificate inventory, expiry dates and the ownership record for each certificate
- Provide a verification runbook with the exact connection tests that prove TLS is enforced on every exposed port
- Document the rotation steps, the reload behavior and the checks to run after each renewal
- Walk your operations and security teams through failure cases such as expired certificates and unknown certificate authorities
How we support
- Scope ongoing certificate renewal, configuration review and upgrade testing as a retainer if you want continued help
- Re-verify TLS after each ClickHouse upgrade, since listener and client settings can change between releases
- Review new clients and integrations before they connect, so each new path is checked against your TLS policy
- Run periodic checks that confirm no plaintext port has been reopened and that certificate expiry dates are tracked
