Keeper-in-Server Mode

ClickHouse Keeper can run as a standalone process or embedded inside a ClickHouse Server process. This page explains what that means, why you might enable it, and what it implies for image management in an air-gapped environment.

Modes of Operation

Standalone (default)

Keeper runs as a separate process using the dedicated clickhouse-keeper image. It has its own lifecycle and image tag. This is the default configuration.

Server-embedded

Keeper runs inside a clickhouse-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-server image 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-keeper image does not expose port 8443. Port 8443 is 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

Set keeper.featureFlags.runKeeperInServer: true in your cluster Helm values

helm upgrade <release-name> \
  oci://<your-registry>/helm-charts/onprem-clickhouse-cluster \
  --version <version> \
  --namespace <namespace> \
  --reuse-values \
  --set "keeper.image.tag=<keeper-server-tag>" \
  --set "keeper.featureFlags.runKeeperInServer=true"

The operator rolls out Keeper pods one at a time, preserving quorum throughout the migration.

Related How-To Guides

• Expose Keeper Metrics over HTTPS — step-by-step instructions to enable the HTTPS metrics endpoint using server-embedded mode