chmonitorTraefik
Put chmonitor behind Traefik as a reverse proxy on Kubernetes or Docker, with optional ForwardAuth for SSO via oauth2-proxy.
Run chmonitor behind Traefik as reverse proxy / ingress. Same pattern on Kubernetes (IngressRoute or Ingress) and Docker (container labels).
Traefik handles TLS, routing, and — with oauth2-proxy — authentication. chmonitor can stay on none and trust the forwarded identity.
Prerequisites
What you need
- A running Traefik instance (ingress controller or Docker provider)
- chmonitor via Helm or Docker
- For SSO: oauth2-proxy (Dex, Google, GitHub, …)
Setup
chmonitor listens on port 3000.
If you installed with the Helm chart, expose the Service with an IngressRoute:
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
name: chmonitor
namespace: monitoring
spec:
entryPoints:
- websecure
routes:
- match: Host(`chmonitor.example.com`)
kind: Rule
services:
- name: chmonitor # chart Service name
port: 3000 # service.port (default 3000)
tls:
certResolver: letsencrypt # or tls.secretNamePrefer standard Ingress? Enable it in the chart:
ingress:
enabled: true
className: traefik
hosts:
- host: chmonitor.example.com
paths:
- path: /
pathType: Prefix
tls:
- hosts: [chmonitor.example.com]
secretName: chmonitor-tlsWith Compose and Traefik watching Docker:
services:
chmonitor:
image: ghcr.io/chmonitor/chmonitor:latest
environment:
CLICKHOUSE_HOST: http://clickhouse:8123
CLICKHOUSE_USER: default
CLICKHOUSE_PASSWORD: ""
labels:
- traefik.enable=true
- traefik.http.routers.chmonitor.rule=Host(`chmonitor.example.com`)
- traefik.http.routers.chmonitor.entrypoints=websecure
- traefik.http.routers.chmonitor.tls.certresolver=letsencrypt
- traefik.http.services.chmonitor.loadbalancer.server.port=3000Authentication via ForwardAuth
Put chmonitor behind oauth2-proxy using Traefik ForwardAuth, and read identity with the trusted auth provider.
Define the ForwardAuth middleware
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: oauth2-proxy-auth
namespace: monitoring
spec:
forwardAuth:
address: http://oauth2-proxy.monitoring.svc.cluster.local/oauth2/auth
trustForwardHeader: true
authResponseHeaders:
- X-Auth-Request-User
- X-Auth-Request-Email
- X-Auth-Request-Preferred-Username
- X-Auth-Request-GroupsAttach the middleware to the route
Add middlewares: [{ name: oauth2-proxy-auth }] on the IngressRoute, or traefik.http.routers.chmonitor.middlewares=... on Docker.
Configure chmonitor's trusted provider
CHM_AUTH_PROVIDER=trusted
# oauth2-proxy forwards X-Auth-Request-* (not X-Forwarded-*)
CHM_TRUSTED_USER_HEADER=X-Auth-Request-User
CHM_TRUSTED_EMAIL_HEADER=X-Auth-Request-Email
CHM_TRUSTED_NAME_HEADER=X-Auth-Request-Preferred-Username
CHM_TRUSTED_GROUPS_HEADER=X-Auth-Request-Groups
# Restrict to Dex groups (optional)
CHM_TRUSTED_ALLOWED_GROUPS=sre,platform-adminsSee Trusted proxy for headers, shared-secret vs CHM_TRUSTED_ALLOW_INSECURE, and Dex/oauth2-proxy flags.
Verify
chmonitor exposes /healthz (liveness, static) and /api/healthz (readiness, ClickHouse-gated). Traefik can health-check:
services:
- name: chmonitor
port: 3000
healthCheck:
path: /healthz
intervalSeconds: 15Don't guard health endpoints with ForwardAuth
Do not put ForwardAuth on /healthz and /api/healthz, or probes redirect to login. Use a higher-priority router without auth, or the chart's Kubernetes probes (hit the pod, bypass Traefik).
Troubleshooting
Related
Kubernetes deployment
Install chmonitor with the Helm chart.
Docker deployment
Run the published container behind Traefik's Docker provider.
Trusted proxy authentication
Header reference, shared-secret tradeoff, and Dex/oauth2-proxy flags.
Authentication overview
Choose an auth provider for chmonitor.
Production checklist
Harden and validate before exposing to a team or the internet.