Using GCS and Azure Blob Storage as ClickHouse disks: what it does and when to use it
If your self-managed ClickHouse cluster runs on Google Cloud or Azure and older data is filling expensive local disks, object storage can hold that data at a lower cost per terabyte. ClickHouse can keep MergeTree data on a Google Cloud Storage bucket. You declare the bucket as a disk in a configuration file under conf.d, add a cache section for that disk, and then reference the resulting storage policy in your table DDL. Azure Blob Storage is handled as a separate disk type with its own configuration, so the Azure path is not a variant of the GCS setup and needs its own design review, credentials model and test plan. Confirm the exact disk type names, parameters and supported options for your ClickHouse version in the GCS integration guide and the Azure section of the ClickHouse documentation before you write any configuration.
Object storage fits data that is written once or rarely changed, queried in batches, and tolerant of higher and more variable read latency, such as older partitions in a logs or telemetry table. It is a poor fit for the hot working set, for tables with frequent small merges, and for queries with tight latency targets, because every cold read depends on the network path to the bucket and on the local cache. Local NVMe or SSD disks remain the better choice for recent data and for any table where latency predictability matters more than storage cost. Plan for both paths: the same cluster often needs a local volume for recent partitions and an object storage volume for history, joined by TTL MOVE rules.
Before you commit, ask three questions of your own environment. Does your ClickHouse version support the disk type you intend to use, and does your team have a tested upgrade path for it? Which identity will the server use to reach the bucket or container, and can that identity be scoped to one bucket or container with no broader project or subscription rights? And have you run a restore from backup targeting the same storage, since ClickHouse's backup documentation lists Azure Blob Storage as a supported backup target and warns that a backup never test-restored will probably not restore when needed. Object storage is a place to keep data, not a backup strategy on its own.
Choosing between the GCS and Azure Blob disk paths
Google Cloud Storage is attached to ClickHouse by declaring a bucket as an S3-type disk with endpoint settings that point at the GCS interoperability endpoint. The ClickHouse GCS integration guide describes the disk, its cache and the storage policy referenced from DDL, and that guide is the authority for the exact keys. Teams should expect the configuration to live in a conf.d file on every replica, so that configuration drift is treated as a deployment defect.
- Credentials: Confirm which HMAC key type the guide expects for GCS interoperability access, and where the key material will be stored. Plan rotation before go-live, not after.
- Service account scope: Grant the service account object-level permissions on one bucket per cluster or environment, not project-wide roles.
- Config keys: Verify every endpoint, region and credential key against the current guide for your ClickHouse release, since key names change between versions.
- Identity model: If your organization uses Workload Identity Federation or short-lived tokens, confirm whether the interoperability path supports your pattern before designing around it.
- Network path: Decide whether nodes reach the bucket over private connectivity or the public endpoint, and document the egress cost of each choice.
Before committing, confirm each config key and credential type against the guide for the release you will run.
Azure Blob Storage has its own disk type in ClickHouse rather than sharing the S3 path, so the configuration, authentication options and storage object model follow Azure conventions. The choice here is usually driven by whether the organization already manages Azure identities centrally and whether storage accounts are governed by Azure policy. Teams should read the Azure disk section of the official ClickHouse documentation for the current keys before drafting any file.
- Authentication: Compare account keys, SAS tokens and Microsoft Entra ID based access as documented for the release in use, and pick the one your security team can rotate and audit.
- Storage account layout: Decide whether containers are separated per environment, and whether soft delete and versioning settings will interact with ClickHouse merges and deletions.
- Managed identity: If nodes run on Azure virtual machines or AKS, check whether managed identities can be used for the chosen access method before storing secrets on disk.
- Private endpoints: Plan private endpoints and DNS resolution early, because name resolution failures look like storage errors inside ClickHouse.
- Cache placement: Plan local cache directories on fast local disks, sized separately from the object store.
Confirm the authentication method, key names and private endpoint behavior against the Azure section of the official documentation for your ClickHouse version.
The cloud the data platform already runs in, and the identity system that governs it, usually settles this choice more than any technical difference between the two paths. A platform team that runs everything on Google Cloud with Google-managed identities will find the GCS path fits its existing audit trail, while a team standardized on Microsoft Entra ID will find the Azure path fits its existing controls. Mixed estates need an explicit decision about which cloud holds the data, not just where the compute runs.
- Data residency: Confirm which region and jurisdiction each bucket or container must sit in, and whether replicas in a second cloud are in scope.
- Secrets handling: Decide whether storage credentials live in a central secrets manager, and how ClickHouse nodes retrieve them at start-up.
- Audit alignment: Map storage access logs to the logging system your auditors already review.
- Multi-cloud replicas: Replicating ReplicatedMergeTree data across clouds raises cost and latency questions that a single-cloud design avoids.
- Exit path: Record how data would move if the bucket or account later changes, including the need to re-test restores.
Ask your cloud and security teams to sign off on the identity model before a configuration is drafted, and confirm any multi-cloud replication design against the replication guide.
Configuration options for object storage disks and when each fits
This table compares the decisions a team makes before configuring GCS or Azure Blob Storage as ClickHouse disks: disk type, authentication, cache placement, storage policy role and bucket layout. Read each row as a choice with a condition under which it fits and a cost it carries. The main takeaway is that identity and policy design matter more than the disk type itself, and cache sizing is covered separately in the filesystem cache topic.
| Decision | Option | Trade-off | When it fits |
|---|---|---|---|
| Disk type on GCS | s3 disk type pointed at the GCS S3-compatible endpoint | Uses the S3 disk code path with GCS-specific settings; confirm the endpoint and key format against the GCS integration guide for your ClickHouse version | Teams that want one disk definition pattern across clouds and have verified the GCS settings in a pre-production cluster |
| Disk type on Azure | Azure Blob Storage disk type | Azure-native configuration with its own credential and container settings; a separate pattern to test and maintain | Azure-hosted clusters where the team wants the native Blob Storage integration rather than an S3-style endpoint |
| Authentication on Google Cloud | Service account key stored in the server configuration | Long-lived key material that must be rotated, protected and kept out of images and version control | Short-lived pilots or environments where workload identity is not yet available to the platform team |
| Authentication on Google Cloud | Workload identity bound to the Kubernetes service account or VM | Removes stored keys but requires cluster identity setup and an IAM binding review | Self-managed clusters on GKE or VMs where the platform team controls identity bindings |
| Authentication on Azure | Managed identity assigned to the VM or node pool | No secret to store, but the identity's role assignments apply to every container it can reach | Clusters on Azure where the team can scope role assignments to specific containers |
| Authentication on Azure | Account key or shared access signature in configuration | Broad, long-lived credentials that are hard to scope and easy to leak through config files | Only as a documented exception with rotation and a named owner |
| Local cache placement | Cache on local NVMe or SSD attached to each replica | Fastest reads on repeated queries; capacity is lost if the node is replaced and the cache starts cold | Query patterns that reread recent object-stored data often |
| Local cache placement | Cache on network or shared volume | Easier to manage across nodes but adds latency and a shared failure domain | Rarely preferred; test carefully before choosing it |
| Storage policy role: cold volume | Object storage added as the last volume in a policy with TTL MOVE rules | Keeps hot data local and cuts local disk growth; queries against moved parts depend on object storage latency | Older data is queried occasionally and local disks are the constraint |
| Storage policy role: full tier | Object storage as the only or main volume for a table | Maximizes separation of storage and compute but makes object storage latency part of every query; replication behavior must be tested | Workloads that tolerate higher latency and where the team has validated replicated tables on object storage |
| Bucket or container layout | One bucket or container per cluster, with prefixes or per-table paths | Simpler IAM and cost tracking per environment; a shared bucket across clusters risks cross-cluster access and accidental deletion | Production, staging and test clusters that must not share data paths |
Setup sequence for a GCS or Azure Blob disk
This sequence takes a self-managed ClickHouse team from a confirmed server version to a verified remote disk, with each step closing on a check that shows the data actually lands in the bucket or container and can be restored.
Confirm the ClickHouse version and release line
Before anything is provisioned, the platform owner checks which ClickHouse release line will run in production. The ClickHouse security policy lists versions 26.9, 26.8, 26.7 and 26.3 as supported with security updates, and the production FAQ recommends stable releases for most production use. Confirm the exact build against the GitHub releases page and read the changelog for the disk and storage settings you plan to use. Done when the version, its support status and the changelog review are recorded in the change ticket.
Create the bucket or container and identity
In your own Google Cloud or Azure subscription, the cloud team creates the bucket or Blob container in the region your data policy requires, along with a dedicated service identity limited to that one storage target. Grant only the object read, write, list and delete rights ClickHouse needs, enable versioning or soft delete as your recovery design requires, and keep keys out of the configuration files. Confirm the identity and its permissions with a test upload and download from a ClickHouse host before continuing.
Write the conf.d disk and cache sections
The ClickHouse team adds a file under the server's conf.d directory that declares the remote disk, the local filesystem cache in front of it, and the storage policy that references them. For GCS, the disk is defined as an s3-compatible type using the Google Cloud Storage endpoint and HMAC keys, as described in the ClickHouse GCS integration guide. Azure Blob Storage uses its own disk type with the account, container and authentication settings. Store secrets through your secrets manager or environment substitution, and set the cache path and maximum size deliberately. Verify the file parses by restarting one test node and checking the server log for disk initialization errors.
Reference the policy in DDL on a test cluster
On a pre-production cluster with representative schemas, the DBA creates a MergeTree table with SETTINGS storage_policy pointing at the new policy. Confirm the table is using that policy by querying the system tables for the table's storage policy and the volumes it lists. Run the same DDL on each replica if the table is replicated, because the policy is applied per table definition. Done when the table's policy name matches the one in the configuration and no replica reports a missing disk.
Insert data and confirm parts land on the remote disk
Load a representative batch of rows, then run OPTIMIZE or wait for background merges so parts are written. Query the system parts table for the active parts, grouping by disk name, and confirm that the parts for the test table appear on the remote disk rather than the local default disk. Also check the system disks table for the remote disk's free space and the filesystem cache table for cache activity on reads. Done when the parts on the remote disk match the row counts you loaded and a query returns the same results as on local storage.
Confirm replication behavior across replicas
If the table uses ReplicatedMergeTree, confirm each replica sees the same parts and that a replica restarted during the test resyncs without manual steps, as the replication guide describes. Be aware that object-storage replication behavior is a separate design decision: check that your ClickHouse version and configuration support the replicated layout you chose, and do not assume zero-copy replication is appropriate. Done when all replicas report the same row count and the replication queue is empty.
Run a restore test to a spare cluster
Back up the test table with BACKUP to a separate destination, then RESTORE it to a spare cluster or a renamed database. The ClickHouse backup documentation warns that a backup never test-restored will probably not restore properly, so this step is required before the disk is used for real data. Compare row counts and a checksum-style query between source and restored copies, and confirm the restored parts are readable from the remote disk. Record the result and the commands used so the restore can be repeated on the production schedule.
Replication considerations when tables sit on object storage
Replicated tables on object storage need a deliberate replication design before go-live. A ReplicatedMergeTree table coordinates its replicas through ClickHouse Keeper, and placing its data on a GCS or Azure Blob disk changes what each replica has to fetch and where the stored parts live. Decide early whether each replica keeps its own copy of the parts on the object store or whether replicas share them, because that choice shapes cost, failure behavior and how much you rely on the bucket or container. Zero-copy replication on object storage is off by default and is not recommended for production, as the sibling topic on S3 storage explains, so the default per-replica model is the one to plan and test against. Confirm the setting your ClickHouse version uses in its documentation rather than assuming it.
Keeper stays on its own hardware. The replication guide recommends at least three Keeper nodes on dedicated hosts in production, with about 4 GB of RAM each, and that guidance does not change because the data disks are remote. Do not co-locate Keeper with the ClickHouse data nodes that also read and write object storage, since a storage-heavy node under load can slow Keeper and destabilize coordination for the whole cluster. Ask your team or partner to show where each Keeper node runs, what its failure domain is across the cloud zones or Azure availability zones you use, and how a lost Keeper quorum is recovered.
A recovered replica syncs missing data from a healthy replica without manual intervention, according to the replication guide. That automation is useful, but it is not a recovery plan for every failure. Replication copies mistakes too: a DROP TABLE, a bad ALTER, or a corrupted part is reproduced on every replica. Keep ClickHouse backup and restore to a separate target, such as an Azure Blob container or an S3-compatible bucket in a different account or region, with its own credentials and retention. Test restores on a spare cluster, because a backup that has never been restored may not restore when you need it.
Security controls for cloud credentials and bucket access
Storage disks give ClickHouse a standing path to your buckets and containers, so the same credential can expose far more data than a single table. The cards below cover the controls that limit that path, from the cloud side through the configuration files to the users who query ClickHouse. Check each one against your own cloud account and cluster before the disk goes into production.
Least-privilege bucket and container roles
Give the ClickHouse service identity access only to the one bucket or container that holds its MergeTree data, with the object permissions the disk needs to write, read and delete parts. Avoid project-wide or subscription-wide roles, which would let a compromised node reach unrelated storage. Ask your cloud team to confirm the exact permission set in writing, then test it by attempting a read from an unrelated bucket with the same identity. Review the role whenever you add a new disk or storage policy.
Keeping keys out of configuration and version control
Disk declarations in the conf.d files often need a key or secret, and it is easy to commit that value with the rest of the cluster configuration. Prefer workload identity or an instance identity where your platform supports it, so no long-lived secret is stored on disk at all. If a static key is unavoidable, load it from a secret store at deploy time and rotate it on a schedule your security team sets. Scan repositories for leaked keys before each merge.
Restricting network paths to storage endpoints
Decide whether ClickHouse nodes reach the storage endpoint over the public internet or over a private path such as a private endpoint or private Google access configured in your network. Restrict egress from the ClickHouse subnets so that only the storage service is reachable for this purpose. Confirm the path with a test from each node, including nodes in a second zone or region if you replicate. Document the allowed destinations so that network changes do not silently break disk access.
Encryption at rest in your own account
Storage services encrypt data at rest, but the key management model varies: provider-managed keys, customer-managed keys in your key service, or keys held outside the cloud. Decide which model your data classification requires, then confirm with your cloud provider which option applies to the bucket or container and whether it can be changed later. Make sure the ClickHouse service identity has permission to use any customer-managed key, and plan for key rotation and for what happens if the key is disabled.
Users, roles and the default user
The storage credential protects the bucket, but ClickHouse users decide who can query or change the tables on it. The access control documentation recommends the SQL-driven workflow of users, roles, row policies, settings profiles and quotas, and it recommends restricting the default user, which starts with all permissions. Create named users with roles that match analyst, writer and administrator duties, and confirm that default is disabled or limited before the cluster takes real traffic.
Authentication for ClickHouse clients
Decide how people and services authenticate to ClickHouse before they reach the disks. The external authenticators documentation covers LDAP, Kerberos, SSL X.509 certificates, an HTTP authenticator and JWT authentication, so you can connect ClickHouse to the directory your organization already runs. Pick one primary method for interactive users and one for service accounts, and confirm which methods your cluster version supports before you design around them.
Questions teams ask before using GCS or Azure Blob for ClickHouse
What does the work involve and who does it?
Configuring a GCS bucket or Azure Blob container as a ClickHouse disk is a defined piece of work: you declare the disk, its cache and a storage policy in configuration files, then reference that policy in table DDL. DeployOpen plans and implements this inside your cloud accounts, including credentials, cache layout, the storage policy, replication checks and restore tests. Your engineers keep ownership of the cluster and the cloud accounts. The GCS integration guide describes the GCS path as a MergeTree disk declared in a conf.d file with sections for the disk, its cache and the storage policy, which gives a clear starting point for scoping the build.
What drives the cost of running ClickHouse on GCS or Azure Blob?
Cost has four parts. Cloud providers bill for stored bytes and for read, write and list requests, and frequent small reads from merges and queries can add up. Local cache disks cost money to provision and must be sized for your working set. Engineering time covers design, configuration, testing and documentation, and is a one-time cost plus ongoing changes. Testing covers a pilot cluster and recurring restore tests. Ask any quote to separate one-time build effort from recurring support, and to state which cloud charges are estimated from your own data volumes, since DeployOpen does not set cloud prices.
How long does a pilot take and what changes the timeline?
The timeline depends on how many clusters and tables are involved, how many storage policies you need, whether replicated tables must sit on object storage, and how quickly your cloud accounts, identities and network paths are ready. A pilot with representative data and queries is the step that matters most, because it shows cache behavior and request volume before production. DeployOpen agrees a fixed scope and timeline in writing before work starts, so ask for the schedule to be tied to these named dependencies rather than a generic duration.
Can our in-house team set up GCS or Azure Blob disks without a partner?
Yes, if your team already runs ClickHouse in production, understands storage policies and has cloud IAM experience. The configuration itself is small. The harder parts are sizing the cache, choosing which tables belong on object storage, testing merges and failover, and writing a restore test that proves backups work. The ClickHouse production guidance recommends a pre-production environment with representative data and queries and reading the changelog before upgrades, so a team without that environment should plan to build one first. Many teams use a partner for the design review and the first pilot, then run the platform themselves.
What do we need to provide before the engagement starts?
Plan on providing:
- Cloud accounts or projects for GCS or Azure Blob, with permission to create buckets or containers, identities and network rules
- Named identities for ClickHouse to use, such as a service account or managed identity, and a process for rotating its credentials
- Representative test data and the queries your analysts run, so cache and latency tests reflect real use
- A spare ClickHouse cluster for restore tests, because the backup documentation advises regular restore tests on spare clusters
- Named owners for the cluster, the cloud accounts and the change process
Confirm each item with your cloud and platform teams before the quote is finalized.
Can DeployOpen run GCS or Azure Blob storage for ClickHouse on an ongoing basis?
DeployOpen offers ongoing support, upgrades and continuous testing as retainers. For this topic, a retainer could cover monitoring the disk and cache, reviewing storage costs, applying ClickHouse upgrades and running scheduled restore tests. Scope, service levels and the frequency of tests are set in the written agreement, so ask for them to be listed explicitly. Your team keeps the cloud accounts and data, and DeployOpen works inside your infrastructure.
Does replication still protect us if the disk is on object storage?
Not by itself. ClickHouse replicates ReplicatedMergeTree tables through ClickHouse Keeper, and a recovered replica syncs missing data from a healthy replica automatically. The backup documentation notes that replication alone does not protect against human error or corruption, so you still need BACKUP and RESTORE and tested restores. Replicated tables on object storage also need a deliberate design, because zero-copy replication on S3 is off by default and not recommended for production, so ask your engineers to review the supported options before relying on a shared bucket.
Does using cloud object storage change our security and access model?
It adds new credentials and trust paths. ClickHouse needs permission to read and write objects in the bucket or container, and those credentials must be stored and rotated like any other secret. Use a dedicated identity with the narrowest bucket rights, restrict the default ClickHouse user, and manage access through roles and settings profiles. Encryption, network paths and audit logging should be reviewed together with your security team. DeployOpen prepares these controls and the evidence for them, but independent auditors and certification bodies, not DeployOpen, decide on compliance.
How a fixed-scope disk engagement is agreed
DeployOpen agrees scope, deliverables and timelines in writing before any work starts, so the written scope is the document you will measure the engagement against. Because the work happens in your own cloud accounts, the scope also has to say whose project, service accounts, buckets, networks and Kubernetes or virtual machine hosts are in play, and who holds the keys to each. A scope that only says "configure object storage for ClickHouse" leaves too much open for either side to judge completion fairly.
The written scope should name the ClickHouse version and the release line you will run (for example, a stable line or an LTS line, checked against the current release listings before you commit), the disk types for each cluster, and the storage policy design, including which tables use which volumes and which TTL rules move or delete data. It should also name the cache plan: where the local cache sits, its maximum size, and how cold-cache behavior will be tested. Finally, it should include a restore test on a spare cluster with a defined pass condition, since a backup that has never been restored is not evidence of recovery. Ask for each of these items to appear as a named deliverable with an owner.
Ask for the scope to list what you provide and what you receive: bucket and credential decisions, network paths, a staging environment with representative data, and the change window for each cluster. Also confirm how changes after signing are handled, since a change to the disk design or the ClickHouse version usually means a revised written scope. Your own cloud and security teams should review the credential model and bucket policy before signature, not after go-live.
How DeployOpen works on this
DeployOpen plans, builds and documents ClickHouse storage on Google Cloud Storage or Azure Blob Storage inside your own cloud accounts. We start from the workloads, retention rules and replication design your team already has, then agree the work in writing before any configuration changes are made. Every step ends with tested evidence your operators can rerun.
How we scope
- Inventory which tables, partitions and retention rules will live on GCS or Azure Blob disks and which stay local.
- Confirm the bucket or container layout, identity model, region and network path each cluster will use.
- Document the cache placement, storage policy names and replication assumptions in a written scope before work starts.
- Agree deliverables and acceptance tests in writing; engagements are fixed-scope, with a quote following from that scope.
How we build
- Declare the GCS or Azure disk, its cache and the storage policy in the server configuration, then test the policy in a pre-production cluster.
- Set credentials through workload identity or managed identity where your platform supports it, and remove static keys from configuration files.
- Run representative inserts, merges, moves and queries against object storage to measure latency and cache behavior before go-live.
- Test replica recovery and a full BACKUP and RESTORE cycle on a spare cluster, since replication alone does not protect against human error.
How we hand over
- Deliver configuration files, storage policy definitions and DDL examples in version-controlled form your team can review.
- Provide a runbook covering cache sizing checks, move monitoring, credential rotation and bucket lifecycle settings.
- Walk your operators through restore tests and record the results so the evidence stays with your organization.
- Document open items and the version you ran, including a changelog review before any future ClickHouse upgrade.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers, scoped separately from the original build.
- Retainer work can include regular restore tests on spare clusters and review of storage policy changes before they reach production.
- Confirm with us which ClickHouse release lines your retainer covers and how upgrade testing is scheduled against the supported versions.
- Ask for the support boundary in writing, including who responds to cloud provider incidents and who owns bucket-level changes.
