Modes of Operation
Standalone (default)
Keeper runs as a separate process using the dedicatedclickhouse-keeper image. It has its own lifecycle and image tag. This is the default configuration.
Server-embedded
Keeper runs inside aclickhouse-server process. Keeper pods use the clickhouse-server image rather than the clickhouse-keeper image.
Server-embedded mode is the intended long-term default.
Why Use Server-Embedded Mode
The main reasons to switch:- Unified image supply chain: in server-embedded mode, both Server and Keeper pods pull from the same
clickhouse-serverimage repository, reducing the number of images you need to manage and mirror. - Future compatibility: new configuration capabilities and operational features are being added to server-embedded Keeper first.
- HTTPS metrics for Keeper: the
clickhouse-keeperimage does not expose port8443. Port8443is part of the ClickHouse Server HTTP stack, so it is only available when Keeper runs inside a server process. This is required to scrape Keeper metrics over TLS with Prometheus.
Image Registry Considerations
In standalone mode your registry needs two distinct images:
In server-embedded mode, Keeper pods switch to the
clickhouse-server image. Keeper and Server can run at different tags — keeper.image.tag is independent of server.image.tag — so your registry must contain the clickhouse-server image at each tag in use:
<keeper-server-tag> may equal 26.2.1.704 or be a different build. ClickHouse Private publishes a validated clickhouse-server build for each Keeper release — see the versions reference for the tag to use. Mirror both tags to your private registry before enabling this mode.
Enabling Server-Embedded Mode
Setkeeper.featureFlags.runKeeperInServer: true in your cluster Helm values
Related How-To Guides
- Expose Keeper Metrics over HTTPS — step-by-step instructions to enable the HTTPS metrics endpoint using server-embedded mode