ClickHouse ACME certificates: automatic TLS setup

ClickHouse ACME certificates: when automatic TLS fits

Let ClickHouse request and renew its own certificates only when the server can prove control of a public DNS name and your team accepts an experimental client in the certificate path. ACME is a good fit for a publicly reachable HTTPS or native TLS endpoint that needs a publicly trusted certificate from Let's Encrypt or ZeroSSL, and it is a poor fit for internal-only services that should chain to your own certificate authority. The ACME client built into ClickHouse can obtain and renew certificates from these providers, but the feature is experimental, so confirm its current status, supported settings and release notes in the ClickHouse documentation for the version you run before you depend on it.

ACME automates three things: issuance, renewal and the domain validation a public certificate authority requires before it signs. The validation step is the part teams most often underestimate. The ACME server must reach your endpoint or your DNS zone during validation, so the cluster needs a path for that challenge, and the named hosts must resolve to the nodes that hold the certificate. ACME does not cover private trust chains, client certificate issuance for mutual TLS, certificate policy decisions, or key custody. Those stay with your team, along with the question of where the private key is stored and who can read it on each replica.

Before choosing ACME, ask four questions. Does every node in the cluster need the same public name? Can you keep ports reachable for the validation method you select? Who monitors renewal failures and alerts before expiry? And does the security policy for your environment allow a public CA to issue certificates for these hostnames? If the answer to any of these is no, an external certificate manager, such as your existing internal CA or a secrets platform issuing certificates to files that ClickHouse reads, is usually the safer choice. For the manual OpenSSL setup that this approach replaces, see the sibling topic on configuring TLS for ClickHouse.

Which certificate source to use for ClickHouse

This table compares the built-in ACME client, an external certificate manager, and OpenSSL certificates issued from an internal CA across ownership, public validation, internal hostnames, reloads and fit. Read each row against your own hostnames and renewal process, and treat the main takeaway as a starting point to confirm with your team and the ClickHouse documentation for your version.

Question	Built-in ACME client	External certificate manager	Manual OpenSSL certificates from internal CA
Who owns issuance and renewal	ClickHouse server, once configured, requests and renews the certificate itself	Certificate manager issues and renews, then pushes or mounts files into ClickHouse	Your team issues each certificate with OpenSSL and replaces files by hand or by script
What public validation requires	Public DNS name and an HTTP or TLS challenge reachable from the internet from the ACME CA	Depends on the manager's challenge method, often DNS-based, so the hostname must be publicly resolvable	Not required; the internal CA signs names that never need public validation
Private or internal hostnames	Generally unsuited, because public CAs cannot validate names that only resolve inside your network	Works for internal names when the manager uses a private CA or DNS challenge you control	Well suited, since you choose the CA, the subject names and the trust chain clients install
How reloads reach the server	Confirm in your version's documentation how renewed material is loaded and whether a restart is needed	Usually a file update followed by a configuration reload or restart, handled by a sidecar or operator	Operator replaces files and triggers a reload or restart; the step is easy to forget without a runbook
Renewal failure visibility	Depends on the built-in client's logging and alerting, which you must test and monitor	Managers typically provide their own expiry alerts and renewal history	Only as good as your calendar, scripts and monitoring of certificate expiry dates
Ongoing effort for your team	Low routine effort once working, but the feature is experimental and needs close testing on each upgrade	Moderate: you run the manager, its access policies and the delivery path into ClickHouse	Highest manual effort unless you automate issuance and rotation for every node
Best fit	Public-facing endpoints with public DNS names, a small team and tolerance for an experimental feature	Mixed public and internal names, several services sharing one certificate platform, or formal renewal evidence	Internal clusters, restricted networks and clients you control, where an internal CA already exists

ClickHouse ACME certificates setup, step by step

This sequence moves a self-managed ClickHouse cluster from plaintext or manually issued certificates to ACME-issued certificates that renew on their own, with each step confirmed before the next one starts.

Confirm version and support line
The platform or security lead confirms the ClickHouse version on every node, checking that it sits on a line listed as supported in the ClickHouse security policy. Then they check the release notes and documentation for that exact version to confirm the experimental ACME client is included and which settings it accepts. Nodes on mixed versions should be aligned first. The step is done when a written record lists the version, the support status and the ACME features confirmed for that build.
Choose the certificate authority and account
The security lead selects Let's Encrypt or ZeroSSL, based on the CA terms, issuance limits and support model confirmed in each provider's current documentation. They register an ACME account under a monitored operations mailbox, not an individual's address, and record who holds access to the account key. Ask the CA which account and rate limits apply to your domain volume. The step is done when the account is registered, the contact address is confirmed and the key storage location is documented.
Prepare DNS and the validation path
The network team points each public hostname for ClickHouse endpoints at the correct load balancer or node addresses, then chooses a validation method the CA supports for that version. HTTP validation requires the challenge path to be reachable from the CA over the public internet, while DNS validation requires controlled API access to the zone. Confirm the chosen method with the version documentation before opening any firewall rule. The step is done when a test request for the challenge path or DNS record resolves from outside your network.
Enable the ACME client on each node
The platform engineer adds the ACME settings documented for the confirmed version to a configuration file under config.d, applying the same settings to every node in the cluster. The account key file gets restricted file permissions owned by the ClickHouse service user. Each node's hostnames must match its certificate subject or SAN entries. Restart or reload according to the version's documentation. The step is done when the server log shows the ACME order completing and the certificate and key files appear in the configured location.
Bind the certificate to HTTPS and native TLS
The engineer points the HTTPS interface and the native secure TCP interface at the issued certificate and private key, keeping the certificate chain complete. They confirm the served chain with openssl s_client against each port, checking that the hostname matches, the intermediate certificate is present and the expiry date is in the expected window. Repeat this on every node. The step is done when both secure listeners present the expected chain and each node reports the same certificate issuer and validity dates.
Verify verified client connections
The engineer connects with clickhouse-client using secure mode and a CA configuration that trusts the issuing chain, then confirms a query succeeds. They also run a test connection with a deliberately wrong CA file to confirm the client refuses to connect, which proves verification is active rather than assumed. Application service accounts should be tested the same way. The step is done when the trusted client succeeds, the untrusted client fails, and the results are recorded in the change ticket.
Disable plaintext ports where policy requires
Where the security policy requires encrypted transport only, the engineer removes or disables the plaintext HTTP and native TCP listeners in configuration, then restarts or reloads each node. Before changing ports, they confirm which internal tools, dashboards and load balancers still depend on them. Port exposure should be reviewed against the network port guidance for the deployment. The step is done when ss -tlnp on each node shows no plaintext listeners on ClickHouse ports and all dependent services connect over TLS.
Rehearse renewal in a non-production environment
Before relying on automation in production, the platform team runs a full issuance and renewal cycle in a non-production cluster that mirrors the production hostnames and validation path. They confirm the version reloads the new certificate without a restart, or they document the restart window if it does not, and they check that expiry monitoring and alerts fire before the current certificate runs out. Ask the vendor or documentation which renewal behavior applies to your version. The step is done when a forced renewal completes, the new certificate serves correctly and the alert test is logged.

Security risks of automated certificate issuance on ClickHouse

Automated issuance removes manual steps, and each removed step was also a checkpoint. The cards below cover the places where an ACME setup can expose names, keys or validation paths without anyone noticing, and the checks and controls that keep them contained.

Hostnames exposed through public logs

Public certificate authorities record issued certificates in certificate transparency logs, so any hostname you request becomes publicly searchable, including internal-looking names such as ch-admin-prod or analytics-restore-test. Before requesting anything, list the names that would appear in a certificate and remove those that reveal architecture or environments. Use a public name for the HTTPS endpoint only, and keep internal node names on a private CA or a wildcard you have decided to accept.

ACME account key access

The ACME account key authenticates your server to the certificate authority and lets its holder request, renew and revoke certificates for your names. Whoever reads that key can impersonate your renewal process. Check which OS user the ClickHouse process runs as, confirm that the account key file is readable only by that user and root, and confirm that backups of the configuration directory do not capture it in a broadly readable archive.

Validation endpoint left open

HTTP-01 validation requires a port 80 path that the certificate authority can reach, and that path stays reachable between renewals. Keeping it open longer than needed widens the surface of the server and of any service sharing that port. Confirm which addresses the validation listener accepts, whether it serves only the challenge path, and whether it is closed or restricted when issuance is not running. Where the validation can be done through DNS, compare the trade-off in your own environment.

Renewal failures that stay silent

Automated renewal fails quietly when DNS changes, a firewall rule drifts, a rate limit is hit or the process is stopped by a configuration error. The certificate keeps working until its expiry date, and the first visible sign is a client rejecting the connection. Set an alert on the remaining validity of the served certificate, not only on the renewal job, and test a renewal in a non-production environment after each change to network or DNS rules.

One host holding key and issuance authority

When the ClickHouse server both holds the private key and runs the process that requests new certificates, a compromise of that host gives an attacker the key, the account and the ability to obtain fresh certificates for the same names. Review whether the server should hold only the leaf key while a separate job or certificate manager performs issuance. For a regulated environment, document this separation as a deliberate decision with its owner and review date.

Private keys with weak file permissions

Certificate private keys are often copied between directories during renewal, and each copy can keep permissive default modes. Check the owner, group and mode of every key file, including temporary and renewed copies, and confirm that ClickHouse reads them under a dedicated account. Verify with a listing of the directory after each renewal, and include the key directories in your file integrity or configuration review.

Choosing ACME or an external certificate manager by environment

When clients outside your organization connect to ClickHouse, the certificate must be trusted by public clients without a private root, so a publicly trusted provider is the usual path. The built-in ACME client is reasonable when the host serves one public hostname, the challenge path is reachable through your firewall, and your team can test renewal on the release you run. The feature is marked experimental, so confirm its status and supported challenge types in your version before you rely on it.

When the built-in client fits: a single public hostname, a predictable challenge path and a team willing to verify renewal on a test host first.
When an external manager is safer: a load balancer or CDN already terminates TLS, or several services share one certificate lifecycle and need one owner.
Renewal failure visibility: a blocked challenge can fail renewal silently, so decide who receives expiry alerts and how a failed renewal is detected before clients are affected.
Key storage and access: confirm where the account and certificate private keys are written, their file permissions and who can read them from the host.
Provider terms: check the provider's rate limits and terms for your hostnames before scheduling frequent renewals.

Check that public DNS, inbound ports and the hostname in your client configuration all match what the chosen provider will validate.

Operating renewals, reloads and rotation without outages

The first issuance is the easy part. The operating risk is the renewal loop that follows, and it needs an owner, a monitor and a rehearsed procedure before the first certificate reaches its renewal window. Start by confirming in the ClickHouse documentation for your exact version how the ACME client schedules renewals, where it writes the new certificate and key, and whether the server picks them up without a restart. Do not assume a reload behavior from another product. Record the answer per version, because the experimental feature may change between releases, and tie the check to your upgrade process so that a version change re-triggers the question.

Monitor the outcome, not the schedule. Track the expiry date of the certificate each node actually presents on its secure ports, not the date stored in a file, and raise an alert well before expiry so that a failed renewal leaves time to act. Also alert on failed renewal attempts in the server logs, since a silent failure is the usual cause of expiry incidents. Whatever threshold you choose, document who receives the page and what the first response is. For a replicated cluster, the ReplicatedMergeTree replicas and their Keeper nodes all use TLS, so a certificate problem on one node can isolate it from its peers. Check the replication status after every rotation.

Rehearse every change on a non-production cluster that mirrors your topology, including the same number of replicas, the same listening ports and the same client trust configuration. Stagger renewal across nodes so that no two replicas, and no Keeper quorum member, change certificates at the same moment. If the ACME client renews on its own timer on each node, confirm whether the nodes' clocks and renewal windows are offset enough to avoid overlap, and if not, plan a controlled rollout. Keep the previous certificate and key available until the new one is verified, and keep a tested rollback. Ask your implementation partner or your own team to write the runbook, and ask the vendor to confirm the behavior of each step for the version you run.

Limits to confirm before relying on the experimental client

ClickHouse's ACME client is marked experimental, so each card below is a question to answer with the vendor or in a pre-production test before any certificate it issues reaches a production listener. Together they decide whether the client fits your trust model, your naming scheme and your cluster layout.

Is the client stable across releases?

An experimental feature can change its flags, defaults or renewal behavior between releases, and a change that goes unnoticed can break renewal after an upgrade. Ask the vendor which release lines carry the client as supported, read the changelog for each planned upgrade, and run a renewal cycle in a pre-production cluster on the exact version you intend to deploy. Record the version and configuration that passed.

Which CAs and challenge types work?

Confirm which certificate authorities the client can use, whether Let's Encrypt and ZeroSSL are both supported, and which challenge types it implements. The challenge type decides what your network must allow: HTTP validation needs inbound reachability on port 80 from the CA, while DNS validation needs API access to your zone. Check these against your firewall and DNS policy before you commit to a design.

Can it issue wildcard or internal names?

Public CAs issue wildcard certificates only through DNS validation, and they cannot issue for internal-only hostnames such as single-label names or private zones. Ask whether the client can request wildcard names at all, and whether your ClickHouse endpoints, Keeper hosts and inter-node names resolve to public domains. If internal names are required, plan an internal CA instead and verify that the client does not attempt to issue for them.

Where account keys and certificates live

The ACME account key and the issued private keys are sensitive material. Confirm where the client writes them, which file permissions it applies, and whether the server process must be able to read them in plaintext. Check whether keys are included in backups, configuration management output or container images, and who can read them on each host. Document the answer so your key custody review covers the ACME path too.

How renewal behaves on multi-node clusters

Each replica and Keeper node that terminates TLS needs a valid certificate, and renewal must not reload every node at the same moment. Ask whether each node runs its own ACME order, how the nodes avoid competing for the same challenge, and whether a failed renewal on one node raises an alert. Test a rolling renewal across the replicas of one shard in a pre-production cluster and confirm that queries keep succeeding during the reload.

Is the version on the supported list?

The security policy lists the versions that receive security updates, and anything outside that list is unsupported. Confirm that the release you plan to run appears on that list and that your upgrade path stays inside supported versions. An experimental client on an unsupported release leaves you without fixes for the server and for the TLS code paths that the client relies on.

ClickHouse ACME certificates cost and effort: what buyers ask

What drives the cost of setting up ACME certificates for ClickHouse?

The cost is mostly the time of the engineers doing the work, and it rises with the number of nodes, listening ports and client types that need certificates. Effort goes up when the cluster has many replicas, when Keeper and inter-node traffic also need TLS, when DNS and firewall changes must pass change control, and when applications pin a specific certificate authority. Effort goes down when the hostnames are stable, DNS is automated, and a test cluster already exists. Ask any quote to list each node and port in scope, who performs the DNS and firewall changes, how renewal is tested, and whether the work is one-time or includes ongoing support. Renewal is recurring, so ask who watches it after handover.

How long does a first ACME setup for ClickHouse take?

No duration figure is fixed for this work, so the timeline depends on the environment. The main variables are the number of servers, how quickly your team can grant DNS records and open the HTTP or DNS challenge path, how many change windows you need, and how much testing you require on a non-production cluster. A single test node with working DNS can move quickly, while a replicated production cluster with several change approvals takes longer. Ask for a written timeline that separates the test rollout, the production cutover and the first observed renewal, since the first real renewal is the step most teams never rehearse.

What does our team need to provide for ACME certificates?

Plan to provide the following before any hands-on work starts:

DNS control for each hostname, including the ability to create records or update zones if you use DNS validation
Network paths from the certificate authority to the validation endpoint, or confirmed inbound access on the challenge port if you use HTTP validation
Firewall and listen-address decisions that match your network port plan
A change window for each production restart, plus a rollback plan
A non-production ClickHouse cluster with representative configuration so renewal can be tested before production
Named owners for the certificate, the ACME account and the monitoring alerts for expiry

Confirm with your network and security teams whether outbound access to the certificate authority is allowed from database hosts, since many restricted networks block it.

Can one engineer set up ACME certificates for ClickHouse without a partner?

Yes, a single engineer with Linux, DNS and ClickHouse configuration experience can usually do a test setup alone, provided the environment is small and the change process allows it. The risk is not the first issuance but the unattended renewal path, the reload behavior after renewal, and the handling of the experimental feature, which is documented as experimental and should be validated for your version. A second engineer should review the configuration and run a renewal drill. Consider a partner when many clusters need the same pattern, when the team lacks time to test renewal, or when the work must sit inside a documented change process with evidence for auditors.

When is an external certificate manager a better choice than ClickHouse's ACME client?

Choose an external certificate manager when your organization already issues certificates centrally, when the same certificates serve many systems, or when you need one inventory, approval workflow and expiry alerting across the estate. The built-in client is experimental, so teams that require a supported, documented renewal path for production databases often prefer a mature manager that delivers files or secrets to ClickHouse hosts. Also consider your internal certificate authority for private hostnames, since public ACME services only issue for names they can validate. Confirm in the ClickHouse documentation for your version whether the client is still experimental before you commit to it.

What does a fixed-scope ACME engagement cover at DeployOpen?

A fixed-scope engagement covers the work agreed in writing before it starts, such as reviewing the current TLS and listener configuration, designing the certificate pattern, implementing it on a named set of nodes, testing issuance and renewal on a test cluster, and documenting the runbook for your team. It can also include the choice between the built-in client and an external manager, with the trade-offs recorded. Items outside the written scope, such as changes to Keeper TLS, client certificate policy or ongoing renewal monitoring, need their own scope or a retainer. DeployOpen prepares systems and evidence for compliance reviews but does not issue audit reports or certifications.

How do we check that ACME renewal will work before the first expiry?

Run a renewal test on a non-production cluster before the production cutover, then confirm the new certificate is loaded without a failed connection for existing clients. Check the certificate chain, the validity dates, the file ownership and the reload behavior on each node, and record the results. Add alerting on expiry time so a failed renewal is visible well before the certificate lapses. Ask any partner to show the test evidence and the alert rules as part of the deliverables, since a renewal that has never been exercised is the most common reason certificates expire unnoticed.

How DeployOpen scopes and delivers ClickHouse certificate work

DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure, and certificate automation for ClickHouse is handled the same way. We agree the scope in writing first, then build and test the certificate path on a non-production cluster before anything touches live listeners.

How we scope

Written scope names the ClickHouse nodes, listeners and clients that will use ACME-issued certificates
Scope states whether Let's Encrypt, ZeroSSL or an existing internal certificate manager issues the certificates
Scope lists the DNS and HTTP validation paths your network allows, and the firewall changes they require
Engagements are fixed-scope, with deliverables and timelines agreed before work starts

How we build

Configure the experimental ACME client on a staging cluster and confirm issuance and renewal end to end
Test each validation method against your real DNS and network rules, not only in a lab
Set reload behavior so renewed certificates apply without a full cluster outage, then verify client connections
Document the decision record comparing the built-in client with an external certificate manager for your environment

How we hand over

Runbook covering issuance, renewal checks, failed-renewal alerts and manual recovery steps
Configuration files, version pins and rollback steps for every node in the cluster
Test evidence showing renewal, reload and client verification results, kept for your change records
Knowledge transfer sessions with the engineers who will operate the certificate path after handover

How we support

Ongoing support, upgrades and continuous testing are available as retainers
Retainers can cover ClickHouse version changes that affect the ACME client or its experimental status
Ask your provider to confirm how renewal alerts reach your on-call team before go-live
Agree in the written scope who responds to a failed renewal and within which hours

ClickHouse ACME certificates: when automatic TLS fits your environment