Kubernetes

Deploy chmonitor on Kubernetes with the vendored Helm chart or kustomize overlays, with health probes, autoscaling, and secrets management.

Run chmonitor on Kubernetes with the vendored Helm chart or raw kustomize manifests. Same image (ghcr.io/chmonitor/chmonitor:X.Y.Z), port 3000, non-root app user (uid/gid 1001), same health probes.

Loading diagram…

Prerequisites

A Kubernetes cluster and kubectl context.
Helm 3 (chart) or kubectl + kustomize (raw manifests).
A reachable ClickHouse endpoint with a monitoring user.

Registry	Install command
Helm repo (Cloudflare Pages)	`helm repo add chmonitor https://charts.chmonitor.dev`
OCI (GHCR)	`helm install my-chm oci://ghcr.io/chmonitor/chmonitor --version X.Y.Z`

Setup

Add the repo and install

helm repo add chmonitor https://charts.chmonitor.dev
helm repo update

helm install my-chm chmonitor/chmonitor \
  --set clickhouse.host="https://clickhouse.example.com:8443" \
  --set clickhouse.user="monitoring" \
  --set clickhouse.password="change-me"

Install with a values file (optional)

helm install my-chm chmonitor/chmonitor -f values.yaml

image:
  tag: "X.Y.Z"   # latest tag: https://github.com/chmonitor/chmonitor/releases

clickhouse:
  host: "https://clickhouse.example.com:8443"
  user: "monitoring"
  password: "change-me"

ingress:
  enabled: true
  className: nginx
  hosts:
    - host: chmonitor.example.com
      paths:
        - path: /
          pathType: Prefix

resources:
  requests:
    cpu: 100m
    memory: 256Mi
  limits:
    cpu: 500m
    memory: 512Mi

helm upgrade my-chm chmonitor/chmonitor -f values.yaml
helm uninstall my-chm

Replace X.Y.Z with the chart version from GitHub Releases.

helm install my-chm oci://ghcr.io/chmonitor/chmonitor --version X.Y.Z \
  --set clickhouse.host="https://clickhouse.example.com:8443" \
  --set clickhouse.user="monitoring" \
  --set clickhouse.password="change-me"

helm pull oci://ghcr.io/chmonitor/chmonitor --version X.Y.Z --untar
helm show values ./chmonitor

Clone and install the chart when you need to patch it first:

git clone https://github.com/chmonitor/chmonitor.git
cd chmonitor

helm install my-chm ./deploy/helm/chmonitor \
  --set clickhouse.host="https://clickhouse.example.com:8443" \
  --set clickhouse.user="monitoring" \
  --set clickhouse.password="change-me"

kubectl kustomize deploy/kubernetes/base
kubectl apply -k deploy/kubernetes/base
kubectl port-forward svc/chmonitor 3000:3000

Keep environment differences in an overlay:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: monitoring
resources:
  - ../../base
images:
  - name: ghcr.io/chmonitor/chmonitor
    newTag: X.Y.Z
replicas:
  - name: chmonitor
    count: 2

Verify

kubectl port-forward svc/my-chm-chmonitor 3000:3000
# open http://localhost:3000

Configure

Required: CLICKHOUSE_HOST, CLICKHOUSE_USER, CLICKHOUSE_PASSWORD (Secret, not ConfigMap).

Helm values.yaml clickhouse.* maps to those names. Extra flags: extraEnv — copy names from apps/dashboard/.env.example. Full list: Environment variables. Auth: Authentication.

kubectl create secret generic chmonitor-clickhouse \
  --from-literal=CLICKHOUSE_HOST='https://clickhouse.example.com:8443' \
  --from-literal=CLICKHOUSE_USER='monitoring' \
  --from-literal=CLICKHOUSE_PASSWORD='change-me'

Clerk / dual-surface flags

CHM_AUTH_PROVIDER and CHM_CLERK_PUBLISHABLE_KEY must be present at image build time. The published GHCR image is auth none.

Health probes

Probe	Path	Behavior
Liveness	`GET /healthz`	Always `200` while the process runs
Readiness	`GET /api/healthz`	`503` when no ClickHouse host is reachable

Autoscaling

autoscaling:
  enabled: true
  minReplicas: 2
  maxReplicas: 10
  targetCPUUtilizationPercentage: 80

The dashboard is stateless. Readiness keeps traffic off pods until ClickHouse is reachable.

Secrets management

Do not commit real passwords. Use:

External Secrets — AWS / GCP / Vault
SOPS — encrypt in Git
Sealed Secrets — encrypt for one cluster

Upgrading

Update the image tag

In values.yaml or the kustomize overlay.

Apply the change

# Helm
helm upgrade my-chm ./deploy/helm/chmonitor -f values.yaml

# kustomize
kubectl apply -k deploy/kubernetes/overlays/prod

Verify the rollout

kubectl rollout status deployment/chmonitor

For breaking changes, see Migrating to v0.3.

Troubleshooting

Validate before applying:

helm lint ./deploy/helm/chmonitor
helm template release ./deploy/helm/chmonitor | kubeconform -strict -summary
kubectl kustomize deploy/kubernetes/base | kubeconform -strict -summary

Production checklist

Harden and validate before going live.

Authentication

Configure none / clerk / proxy auth providers.

Docker

Single-container self-host on one server.

Migrating to v0.3

Breaking changes between major versions.

Walkthrough: Deploy chmonitor on Kubernetes with Helm.

Kubernetes

Production checklist

Authentication

Docker

Migrating to v0.3

On this page