Kubernetes

Run chmonitor on Kubernetes with the vendored Helm chart or raw kustomize manifests. Both use the same image (ghcr.io/chmonitor/chmonitor:vX.Y.Z), expose port 3000, run as the non-root app user (uid/gid 1001), and wire the same health probes.

Prerequisites

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

The chart is published in two registries:

Setup

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"

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

image:
  tag: "vX.Y.Z"   # use the latest release tag from 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

helm install my-chm oci://ghcr.io/chmonitor/chmonitor --version vX.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 vX.Y.Z --untar
helm show values ./chmonitor

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

# Apply
kubectl apply -k deploy/kubernetes/base

kubectl port-forward svc/chmonitor 3000:3000

# deploy/kubernetes/overlays/prod/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: monitoring
resources:
  - ../../base
images:
  - name: ghcr.io/chmonitor/chmonitor
    newTag: vX.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'

Health probes

• Liveness — GET /healthz — always 200 while the process runs.
• Readiness — GET /api/healthz — returns 503 when no ClickHouse host is reachable.

Autoscaling

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

The dashboard is stateless, so scaling out is safe. The readiness probe keeps traffic off pods until ClickHouse is reachable.

Secrets management

For GitOps workflows, do not commit real passwords. Use:

• External Secrets — sync from AWS Secrets Manager, GCP Secret Manager, Vault, etc.
• SOPS — encrypt secrets in Git.
• Sealed Secrets — encrypt for a specific cluster.

Upgrading

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

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

kubectl rollout status deployment/chmonitor

For breaking changes between major versions, see Migrating to v0.3.

Troubleshooting

Validate the chart and manifests before applying:

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

Related

Walkthrough: Deploy chmonitor on Kubernetes with Helm.