When teams need ClickHouse encryption at rest
This page explains how to configure ClickHouse encrypted disks with AES-CTR keys on local or S3 storage, and what that encryption does and does not cover. Teams usually reach for it when a policy, an auditor or a customer contract requires event, log or telemetry data to be encrypted on disk in a self-managed cluster. Encryption at rest protects against stolen or copied storage media and against unauthorized reads of the data files on disk or in a bucket. It does not stop a user who has valid database credentials from querying rows they should not see, and it does not replace access control, row policies or network controls. Those controls are covered in their own sections of this guide.
Before you choose a version, check the supported release lines in the ClickHouse security policy. The policy lists 26.9, 26.8, 26.7 and 26.3 as currently supported with security updates, and all other versions as unsupported. A cluster on an unsupported line should be upgraded before encryption is added, because a key configuration built on an unpatched server inherits any unfixed vulnerabilities. Confirm the line your organization will run, and record which lines your change process allows, so the encryption work is not undone by a later version change.
Ask the team that owns the requirement three questions before any configuration starts: which data sets fall under it, where the copies live (local disks, S3-compatible buckets, backups), and who is expected to hold the keys. An encrypted disk protects the files it writes, but a backup written to an unencrypted location or a log file that echoes sensitive values will still expose data. Plan for key custody and rotation as an operational task with an owner, not a one-time setting. Agree with your auditor in writing which evidence will show the control works, and check that evidence against your own environment with a test restore before go-live.
Choosing local or S3 storage for an encrypted disk
This table compares local disks and S3-compatible object storage as the layer beneath an encrypted ClickHouse disk. Read each row as a question to settle before build: where ciphertext sits, what restore and replica sync depend on, and which key handling fits. The main takeaway is that the storage choice also decides who owns the key lifecycle and how backups must be verified.
| Consideration | Local disk | S3-compatible object storage |
|---|---|---|
| Where ciphertext lives | On the server's own volumes, so each replica holds encrypted parts on its own hosts | In the bucket, with the encrypted disk writing parts there, so the bucket and its replication settings matter as much as the hosts |
| Replica sync and recovery | A recovered replica pulls missing data from a healthy replica, so the encryption key must be available on the rebuilt host | Replicas can share a bucket, so the key must be identical across nodes or data written by one node may not read on another; confirm this in the docs for your version |
| Restore path | Restores depend on local volumes and any BACKUP destination you configure, which must also be encrypted or protected | Restores depend on bucket access, object versioning and lifecycle rules, and on whether the backup destination uses the same key |
| Key sources that fit | Key files or values on the host, or an external key source if your version supports it; protect the key file with host permissions | The same key sources apply, but a bucket outage or misconfigured credentials can block reads even when the key is correct |
| Key rotation work | Rotation means changing configuration on every node and checking that older parts remain readable | Rotation touches every node and any tooling that writes to the bucket; confirm how existing objects are handled |
| What operators manage | Disk capacity, volume health, file permissions on key material and host backups | Bucket policies, credentials, endpoint TLS, object lifecycle, versioning and cross-site copies of objects |
| Failure modes to test | Host loss, failed volume and a replica rebuilt without its key | Credential expiry, lost bucket access, accidental object deletion and a key mismatch between nodes |
| What to confirm | Supported key sources and cipher modes for your ClickHouse version in its encrypted disk documentation | Supported key sources and cipher modes for your version, and whether your S3-compatible provider handles object encryption on top |
Setting up an encrypted disk step by step
This sequence takes a self-managed ClickHouse cluster from an unencrypted storage layout to an encrypted disk that holds table data, with checks at each stage that show the encryption is active and the data is recoverable. It is meant to be run in a non-production cluster first, then repeated in production under change control.
Confirm the ClickHouse version and storage target
Record the exact ClickHouse version running on every node and confirm the support status of that line in the project's security policy before you change storage. Decide whether the encrypted disk will sit on local disks or on S3-compatible object storage, and note which paths or buckets each node will use. Check the version with a query against the server and compare it with the supported lines listed in the ClickHouse security policy. The step is complete when the version, storage target and owner of each node are written into the change record.
Generate the encryption key and store it outside the data directory
Generate the AES-CTR key using a method your security team approves, and store it in a secrets manager or hardware-backed store that is separate from the ClickHouse data directory and from its configuration backups. Record who can read the key, how it is copied to each node, and where the recovery copy lives. Do not place the key in SQL text, in query logs or in a file that ships with the server package. The check is a documented key location, a named key custodian and a test showing that the key can be read by the ClickHouse service account and by no other standard account.
Define the encrypted disk in server configuration
Add an encrypted disk definition to the server configuration, pointing it at the underlying local or S3 disk and referencing the key source. Config keys and their exact names differ between releases, so take every key from the ClickHouse documentation for the version you confirmed in the first step, not from older examples or forum posts. Apply the file on one test node first and restart it. The check is that the server starts without errors in its log and that the disk appears in the system disks table with the expected type.
Create a storage policy that uses the encrypted disk
Define a storage policy that routes table data to the encrypted disk, and assign it to a test table or a new table created for the test. Keep the policy name and volume layout in version control with the rest of the configuration. Tables that already exist will not move on their own, so plan how existing data will be copied or rebuilt in a later step. The check is that the policy is listed in the storage policies system table and that the test table reports the encrypted disk in the parts or disks view after a small insert.
Test on a non-production cluster with representative data
Load a copy of representative tables, with realistic column types, partition layout and volume, into the non-production cluster, then run the queries and inserts your workloads depend on. Measure query and insert behavior before and after encryption, and check background merges and replica synchronization on replicated tables. Restart each node and confirm that the data reads back correctly. The check is a written comparison of row counts and sample query results, plus a clean restart record for every node in the test cluster.
Verify that raw disk files are unreadable
Inspect the underlying storage path or bucket directly, outside ClickHouse, and confirm that the data files do not contain recognizable plaintext values from the test table. Use a known test string in the inserted rows so the search is unambiguous. Also confirm that a read through the raw path without the key fails or returns no usable data. The check is a short written result showing the test string was not found in the raw files and that unauthorized reads did not expose the values. Repeat this check after each key change.
Restart, read back and document the production rollout
Once the test passes, plan the production change with a rollout order that keeps replicas available, and record the expected behavior at each node restart. For existing data, copy or rebuild tables onto the encrypted policy using the method your team validated in testing, and keep the original data until the copy is verified. After each node is changed, confirm the policy in the system tables and read a known test row back after the restart. The step is complete when every production node reports the encrypted disk, the test rows read back correctly and the rollout record is filed with the key rotation procedure.
Key handling and operational controls that protect the encryption
An encrypted disk is only as protected as the key that opens it. The six controls below cover where the key lives, who can read it, how configuration is locked down, how changes are recorded, how keys travel with backups and replicas, and what happens when a key is lost. Each one should be decided and written down before the first encrypted table is loaded.
Key storage and access
Decide where the AES-CTR key material is held and which principals can read it. A key stored in the same configuration file or on the same volume as the data defeats the purpose of encrypting it, because anyone who copies the disk gets the key too. Prefer a source that is separate from the server host, such as a secrets manager or an HSM-backed service your organization already runs, and confirm with your ClickHouse version how the key is supplied at startup and whether it can be read back through SQL or system tables.
File permissions on configuration
Encrypted disk definitions, key settings and any files that reference key material live in the server configuration directory. Restrict read access on those files to the ClickHouse service account and the configuration management tooling, and keep them out of world-readable container images and shared repositories. Check permissions on every node, since a single host with a looser file mode can expose the key for the whole replica set. Treat changes to these files as privileged changes.
Separating key custody from administrators
The people who administer ClickHouse should not be the only people who can recover or replace the key. Assign key custody to a separate role, ideally with two-person control for export or rotation, so that a database administrator cannot read the data and the key alone. Document who holds each custody role, how access is requested and removed, and how this is reviewed. Confirm that your identity provider and secrets platform can enforce the split.
Logging and change control
Record every change to encryption configuration, including new disks, key identifiers, rotations and policy updates that move data onto encrypted storage. Ship these records to a log store that ClickHouse administrators cannot edit. Tie each change to a ticket or approval, and compare the running configuration against the approved version on a schedule. Ask your team which events in the server and query logs reveal a configuration change, since that determines what you can prove after an incident.
Keys in backups and replicas
A backup of encrypted data is only restorable if the matching key is available to the restoring cluster. Plan where backup copies of the key live, and keep them separate from the backup bucket that holds the data. Replicas also need the key to read their parts, so confirm that every node in a ReplicatedMergeTree set gets the key through the same controlled path. Note that replication does not protect against deletion or corruption, so backups remain necessary. Test a restore on a spare cluster using only the documented key recovery steps.
What happens if a key is lost
If the only copy of a key is lost, the encrypted data cannot be read, and no vendor or service provider can recover it from ClickHouse. Write a key loss runbook that names the escrow copy, the custody owners and the steps to rebuild a disk from backup. Rehearse that runbook as part of regular restore tests, because a backup that has never been restored will probably not restore properly when it is needed. Ask whether your compliance scope requires documented key escrow or key destruction procedures.
Rotating encryption keys without losing access to existing data
Key rotation is where encrypted disks most often fail in practice. Keys change on a schedule or after a suspected exposure, but parts already written under an old key must stay readable during and after the change, or queries break and restores fail. Before any rotation, the team needs to confirm from the documentation for its exact ClickHouse version whether rotating a key re-encrypts existing data parts or only applies to new writes. Those are different operations with different risk profiles, and the answer determines how long old key material must remain available on every node and in every backup set.
The planning questions are specific. Confirm how old keys are retained in the configuration until every part written under them has been merged or rewritten, and who is responsible for proving that point has been reached. Confirm how the rotation is applied across replicas of a ReplicatedMergeTree table, so that one node does not hold a key the others have not received, and how the change interacts with backup and restore, since a backup taken mid-rotation must still be restorable with the keys it references. Keys belong in your key management system, with an owner, an audit trail and a documented recovery path if the key store itself is lost.
Rehearse the full rotation on a spare cluster before touching production. Restore a recent backup onto that cluster, rotate the key using the documented procedure, and then run row counts, checksums on representative tables and a read of data written before the rotation. Repeat the restore check afterward, because a backup that was never test-restored will probably not restore properly when needed. Record the steps, timings and any errors so the production runbook reflects what actually happened. Ask your deployment partner or vendor to confirm which rotation behaviors apply to your chosen release line.
Performance impact by storage type and workload
On a local encrypted disk, the main added cost is CPU spent encrypting data as parts are written and decrypting blocks as they are read. Because the cipher runs on the same hosts that run merges and queries, the effect shows up most in CPU-bound stages rather than in raw disk throughput. Reads from the page cache may be affected less than cold reads, since decryption happens on the way from disk into memory.
- Write path: Inserts and background merges both produce new encrypted parts, so the CPU cost recurs for every merge, not only for the first write.
- Read path: Queries that scan many columns over large parts decrypt more data, so wide scans tend to show the impact more than narrow, indexed lookups.
- Hardware support: Confirm whether your CPUs expose AES acceleration to the ClickHouse build you run, because this strongly affects the per-byte cost.
- Part size and compression: Larger compressed parts mean fewer, bigger encryption operations, while heavy compression shifts work between CPU stages that you must measure together.
- Measure before and after: Record insert throughput, merge duration from system tables, and p95 query latency on a copy of production data with the same hardware.
Before you approve a rollout, check that merge duration and CPU saturation on your busiest nodes stay within the headroom your operations team expects.
On S3-compatible storage, encryption adds CPU work on the ClickHouse servers, but the larger variable is often the object storage round trips that dominate latency. Parts are read in units that the cache layer may or may not hold, so the amount of data fetched over the network can change how visible the cipher cost is. Measure the network traffic to the object store along with CPU, because the two effects can offset or compound.
- Network traffic: Compare bytes transferred to and from the bucket before and after enabling encryption, since encrypted disk configuration itself should not multiply requests, but cache behavior may change.
- Cache sizing: A warm local cache reduces object reads and makes the decryption cost on hot data more noticeable relative to fetch time.
- Merge duration: Merges that read and rewrite many small parts from object storage can be dominated by request latency, so encryption may be a minor share of total time.
- Part sizing: Fewer, larger parts reduce request counts, which usually matters more than the cipher on this storage type.
- Provider behavior: Ask your storage team how the S3-compatible service throttles requests and what egress costs apply in your environment, since these are outside ClickHouse.
After the test run, confirm that request counts, merge duration and query latency all moved in the direction you expected, not only CPU utilization.
Ingestion-heavy workloads, such as log or telemetry pipelines, feel encryption through every insert and the merges that follow. Because ClickHouse writes many small parts and merges them continuously, the cipher runs repeatedly over the same data. The effect on ingest throughput depends on how far the cluster sits from its CPU and disk limits before encryption is added.
- Insert throughput: Measure rows per second at the batch sizes your pipeline actually uses, since very small batches add overhead that can hide or inflate the cipher cost.
- Merge backlog: Watch the count of active parts and merge queue depth, because a growing backlog is an early sign that background work is falling behind.
- Batch and part size: Larger insert batches produce fewer parts, so the same data is encrypted with less per-part overhead.
- Replication traffic: On replicated tables, each insert is also replicated, so benchmark with your replication topology, not a single node.
- Peak load: Test with your highest expected ingest rate, not an average, to see whether the cluster keeps up during bursts.
Before sign-off, check that the merge backlog returns to a steady level after your peak test instead of growing across the run.
Query-heavy workloads, such as dashboards and investigation tools, feel encryption on reads of data that is not already cached in memory. The impact is highest for queries that scan many columns across large ranges and lowest for queries that answer from primary key ranges, skip indexes or cached data. Test with your real query mix, because a small set of expensive reports can determine the result.
- Scan width: Wide scans that read many columns decrypt more data per query, so include your most column-heavy dashboards in the benchmark.
- Index selectivity: Queries that prune most parts through the primary key or skip indexes read less encrypted data and show less impact.
- Concurrency: Run tests at your real concurrent user count, since decryption competes with other CPU work under load.
- Caching: Compare cold and warm runs, because the page cache can hide the cipher cost on repeated queries.
- Latency percentiles: Compare p50 and p95 or p99 query latency, since tail latency often reveals contention that averages hide.
Before you approve the change, confirm that your most important dashboards still meet the latency targets your analysts depend on, using the same query set before and after.
A fair comparison needs the same hardware, data, schema, settings and query set before and after encryption is enabled. Run the test on a pre-production cluster loaded with a representative copy of your data, because synthetic data often has compression ratios and part layouts that differ from production. Record results in a table that your engineers and security reviewers can both read.
- Baseline first: Capture metrics on the unencrypted configuration before changing anything, including insert throughput, merge duration, query latency and CPU use.
- Same workload: Replay the same ingestion and query traffic so that differences come from the storage change rather than from load variation.
- Metrics source: Use ClickHouse system tables and your monitoring stack, such as Prometheus metrics, to gather numbers consistently.
- Repeat runs: Run each scenario more than once to separate real differences from noise on shared hosts.
- Documented results: Keep the raw numbers and the hardware description with the change record, so the performance decision can be reviewed later.
Before you publish any figure internally, confirm that it came from your own environment and workload, not from a vendor example or a general rule of thumb.
Limits to confirm before you commit to encrypted disks
Encrypted disks add a layer that touches cipher support, table engines, storage policies, external tooling and vendor support. Each item below is a question to settle with the ClickHouse documentation and your own tests before the design is locked.
Cipher modes and key sources
Confirm which cipher modes and key sources your chosen ClickHouse version supports for encrypted disks, and whether the key can come from the configuration file or another source. The encrypted disk design in this topic relies on AES-CTR keys, so check the exact key options in the version you plan to run. Record the supported options in your design document, since a later version may change them. Test a key rotation on a staging cluster before production.
Table engine and storage policy fit
Verify that encrypted disks work with every table engine and storage policy you plan to use, including replicated tables, Distributed tables and any tiering across local and object storage. Build a test table for each combination, insert representative data, merge parts, and run a query and a restore. Gaps found here are cheaper to fix in design than after data is loaded.
Changing storage policies on existing tables
Ask whether a table can move from an unencrypted storage policy to an encrypted one without a rebuild, and what happens to existing parts. If the answer requires a copy, plan the migration window, disk space and validation steps. Confirm the same behavior for moving between disks inside a policy, since tiering rules may depend on it.
Third-party tools that read files
Encrypted parts are not readable by tools that open data files directly, such as file-level backup agents, antivirus scanners, forensic utilities or custom scripts. Inventory every tool that touches ClickHouse data directories or object storage buckets and confirm each one works through ClickHouse or is excluded. Document which tools are approved, because a direct read may silently return unusable bytes.
Security fix coverage for the release line
Check that the release line you choose receives security updates under the ClickHouse security policy before you commit to it. The policy lists the supported versions, and any version not listed is unsupported. Put that check in your upgrade calendar so an encrypted deployment does not stay on an unsupported line. Confirm the policy again before each planned upgrade.
How encryption at rest maps to PCI DSS and HIPAA requirements
An encrypted ClickHouse disk does not satisfy PCI DSS or the HIPAA Security Rule on its own. Both frameworks expect stored sensitive data to be protected, but they judge the control by the surrounding evidence: who manages the keys, who can reach the data, how changes are recorded and whether the protection has been tested. For PCI DSS, the relevant version is v4.0.1, the only active version of the standard. For HIPAA, the relevant text is the Security Rule at 45 CFR Part 164 Subpart C. Treat the encrypted disk as one input to those requirements, and map it to the specific requirements your assessor or compliance lead has in scope, rather than to the word encryption in general.
In practice, the encrypted disk should come with a small body of evidence. Document how the AES-CTR keys for the encrypted disk are generated, stored, rotated and retired, and name the people or service accounts allowed to change the key configuration. Restrict access to the server configuration files that hold key material, and keep change records for every key rotation and disk configuration change. Most important, run restore tests from backups taken on the encrypted disks, because ClickHouse backups are only useful if they restore into a working cluster. Confirm with your assessor which of these artifacts they will ask for, and confirm which layer (ClickHouse or the storage platform underneath) owns each control, since the evidence for each layer will differ.
The HIPAA Security Rule treats encryption as an addressable implementation specification, not a required one. For an addressable specification, the covered entity or business associate must assess whether it is reasonable and appropriate, and if it is not implemented as written, document the reason and implement an equivalent alternative measure where that is reasonable and appropriate (45 CFR 164.306(d)). Record that decision explicitly for each ClickHouse deployment that holds electronic protected health information. Neither the PCI SSC nor HHS certifies products or endorses certifications, so no vendor label on the encryption feature will settle the question. Ask your assessor or compliance lead to decide how the control is evidenced, and ask them to review the written justification before the environment goes into scope.
Encrypting ClickHouse data at rest: questions buyers ask
What does encrypting ClickHouse data at rest cost, and what drives the price?
The cost is set by the written scope, not by a list price. DeployOpen does not publish prices, and no researched figure for this work is available to quote here. The main components are planning the storage layout, configuring encrypted disks for each storage type in use (local disks, S3-compatible or other object storage), key custody design, re-encrypting or migrating existing data, testing on a spare cluster, and documentation with evidence for your assessors. Cost rises with the number of clusters and nodes, the number of storage types, how much data must be rewritten, and how much performance testing you require. Ask for a quote that lists each component separately, states which items are one-time and which recur (such as key rotation runs and retainer support), and names who holds the key material.
How long does planning and rolling out encryption at rest take?
Duration depends on how many clusters and disks are involved, whether data must be moved into encrypted disks, and how much change control your organization requires. Planning covers an inventory of current storage paths, a key design, and a test plan. Rollout is usually staged: first a pre-production cluster with representative data, then production one node or replica at a time, with checks that queries and inserts behave as expected. Ask for a timeline in the written scope with explicit milestones and the change windows it depends on. Any duration you are given should be tied to these inputs rather than accepted as a fixed promise.
What do we need to provide for the work?
Expect to supply access and decisions that only your organization can make. You need to provide read and write access to the storage targets involved, including local data paths and any S3-compatible bucket, and the ability to create or restrict service identities used by ClickHouse. Key custody is a decision for your security team: whether keys live in a dedicated key management service, a secrets manager you already run, or files on the host, and who may read them. You also need a spare or staging cluster for restore and performance tests, and change windows for rolling restarts. Confirm these items with your platform and security leads before the scope is signed.
Can our internal team set up encryption at rest without outside help?
Often yes, if your team already operates ClickHouse and has experience with storage configuration, secrets handling and rolling restarts. The configuration itself is documented, but the risky parts are key handling, verifying that every storage path is covered, and proving that backups and restores still work with encrypted disks. A self-review usually starts with a list of every disk, table storage policy and backup destination, then a test on a non-production cluster. If your team lacks capacity or has no spare cluster, an external partner can take on planning, implementation and evidence under a fixed written scope, while your staff keep ownership of keys and day-to-day operations.
Does encryption at rest alone make our ClickHouse system compliant?
No. Encryption at rest is one control among several. Compliance frameworks such as PCI DSS and HIPAA's Security Rule expect a set of safeguards covering access control, network protection, logging, backup, risk assessment and documented policies. Encryption at rest also does not protect data from users who have legitimate query access, so role design, row policies and audit logs still matter. DeployOpen prepares systems, controls and evidence for compliance assessments, but it does not issue audit reports, attestations or certifications. Those come from independent auditors and certification bodies. Ask your assessor early which requirements your environment must meet and how they expect encryption evidence to be presented.
How is key rotation handled, and does it require re-encrypting all data?
Key rotation is a planned procedure with its own test. Confirm with the ClickHouse documentation for your version how encrypted disks reference keys and whether a new key can be introduced without rewriting existing parts. If rotation requires re-encryption, the cost and downtime scale with the data volume and the number of replicas. Your written scope should define the rotation trigger (scheduled or after a suspected exposure), who approves it, where the old and new keys are stored during the transition, how backups made under the old key are restored, and how the result is verified on a spare cluster. Ask for a rotation runbook as a deliverable.
What performance impact should we expect from encrypted disks?
The impact depends on hardware, storage type, query mix and how much data is read or written, so no general figure applies. Encryption adds CPU work on reads and writes, and object storage paths may behave differently from local disks. Measure before and after on a pre-production cluster with data and queries that match production, including merge-heavy ingestion and your slowest dashboards. Ask any vendor or partner to show the test method, the metrics captured and the hardware used, and to report results per storage type rather than as a single average.
How DeployOpen scopes and delivers ClickHouse encryption at rest
DeployOpen plans encrypted disk design as part of the wider ClickHouse build, inside infrastructure you control. The work starts with a written scope that names the storage targets, key handling and evidence your assessors will ask for, then moves through a tested build, a handover pack and optional ongoing support.
How we scope
- Inventory which tables, partitions and storage targets hold regulated or sensitive data and need encryption at rest.
- Confirm whether data sits on local disks, S3-compatible storage or both, since each path needs its own encrypted disk definition.
- Agree key custody, rotation expectations and the evidence your auditors or assessors will request before work starts.
How we build
- Configure encrypted disks in the server configuration and wire them into the storage policies used by your tables.
- Test write, read, merge and restore paths on a pre-production cluster with representative data before any production change.
- Measure query and insert performance against an agreed baseline and record the results in the build notes.
How we hand over
- Deliver the written configuration, key handling procedure, rotation runbook and a record of the tests that were run.
- Document which controls the encryption design supports, and which remain with your organization or your assessor to confirm.
- Walk your operators through key rotation and restore steps so the team can run them without us.
How we support
- Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
- Ongoing support, upgrades and continuous testing are available as a retainer if you want help after handover.
- Re-test encrypted disks after ClickHouse upgrades, since release changes should be checked against the changelog first.
