ClickHouse Replica-Aware Routing Architecture Diagram: Istio Envoy Sticky Sessions

ClickHouse Cloud’s replica-aware routing public beta (September 15, 2026) pins HTTP and native clients to the same replica via Istio Envoy L7 consistent hashing. Temporary tables and named sessions only exist on the replica that created them; without affinity, a follow-up query can land elsewhere and fail. This diagram shows clients → Envoy → affined replicas.

Affinity keys

Over HTTP, clients send the X-ClickHouse-Replica-Tag header (ClickHouse ignores it as a setting; Envoy hashes it). Over the native protocol, clients pass --tls-sni-override: the certificate still validates --host, while Envoy hashes the SNI value as the routing key. Same key → same replica, which supports same-replica temporary tables and named sessions, warm local caches (filesystem cache, decompressed blocks, primary keys/indexes, query cache), and read-after-write while replication catches up.

Control plane

Istio Pilot programs the proxies. Draw Pilot as a side control box, not on the data path. Envoy is the L7 data plane that reads the header or TLS SNI and hashes onto the replica ring.

Vendor caveats

Stickiness is best-effort, not a guarantee: upgrades, restarts, and scaling in or out can reshape the service, remap a routing key to a different replica, and drop temporary tables or session state (recreate them; SELECT hostName() shows where you landed). It is not workload isolation — the chosen replica still serves other traffic. The feature is Enterprise only, available on standard ClickHouse Cloud and BYOC when enabled via service settings (or support).

How subdomain sticky fits the story

ClickHouse’s first sticky-routing approach used URL-based subdomains. That method did not scale because of certificate-provider limits, so the team moved to L7 hashing on a header (HTTP) or SNI override (native) that reuses the existing regional certificate. The dashed box on the diagram contrasts that earlier internal approach with the current L7 path — it is not a retired customer-facing feature.

Diagram checklist

Clients → Envoy hash ring → Replica A/B/C; label HTTP X-ClickHouse-Replica-Tag and native --tls-sni-override; Pilot off the data path; call out best-effort remaps and Enterprise availability.

FAQ

What is replica-aware routing?

A ClickHouse Cloud public beta (Sep 15 2026) that uses Envoy L7 consistent hashing on the X-ClickHouse-Replica-Tag HTTP header or native --tls-sni-override (cert validates --host; SNI is the hash key) to pin clients to the same replica.

Why not URL-subdomain sticky?

ClickHouse’s first sticky-routing approach used URL-based subdomains; it did not scale due to certificate-provider limits. Header and SNI hashing reuse the existing cert while Envoy still hashes a routing key.

Who gets it?

Enterprise only. Available on standard ClickHouse Cloud and BYOC when enabled via service settings (or support).

Conclusion

Keep the diagram honest to the launch posture: Sep 15 2026 public beta — Envoy L7 hashing on X-ClickHouse-Replica-Tag / --tls-sni-override for replica affinity; stickiness is best-effort (upgrade/restart/scale can remap keys and drop temp/session state); not workload isolation; Enterprise only on standard ClickHouse Cloud and BYOC when enabled. Sources: ClickHouse blog — Replica-aware routing public beta (Sep 15 2026). Browse more architecture diagrams on the ByteDiagram blog.