Skip to content
chmonitor chmonitor

Traefik

Open as Markdown

Run chmonitor behind Traefik as your reverse proxy / ingress controller. Works the same on Kubernetes (IngressRoute CRD or the standard Ingress) and with plain Docker (container labels).

Traefik handles TLS, routing, and — combined with oauth2-proxy — authentication, so chmonitor itself can stay on the none provider and trust the forwarded identity.

Kubernetes (IngressRoute)

Section titled “Kubernetes (IngressRoute)”

If you installed chmonitor with the Helm chart, expose the Service with a Traefik 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          # matches the chart's Service name
          port: 3000               # service.port (default 3000)
  tls:
    certResolver: letsencrypt      # or a cert-manager-issued Secret via tls.secretName

Prefer the standard Ingress? Enable it in the chart and point the class at Traefik:

## values.yaml
ingress:
  enabled: true
  className: traefik
  hosts:
    - host: chmonitor.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - hosts: [chmonitor.example.com]
      secretName: chmonitor-tls

Docker (labels)

Section titled “Docker (labels)”

With docker compose and Traefik watching the Docker provider:

services:
  chmonitor:
    image: ghcr.io/duyet/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=3000

Authentication via ForwardAuth

Section titled “Authentication via ForwardAuth”

Put chmonitor behind oauth2-proxy (with Dex, Google, GitHub, …) using a Traefik ForwardAuth middleware, and have chmonitor read the forwarded identity with the trusted auth provider.

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
    # Copy oauth2-proxy's identity headers back onto the upstream request.
    authResponseHeaders:
      - X-Auth-Request-User
      - X-Auth-Request-Email
      - X-Auth-Request-Preferred-Username
      - X-Auth-Request-Groups

Attach the middleware to the route (middlewares: [{ name: oauth2-proxy-auth }] on the IngressRoute, or traefik.http.routers.chmonitor.middlewares=... on Docker), then configure chmonitor:

Terminal window
CHM_AUTH_PROVIDER=trusted
VITE_AUTH_PROVIDER=trusted
## oauth2-proxy forwards X-Auth-Request-* (not X-Forwarded-*) through ForwardAuth
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 specific Dex groups (optional)
CHM_TRUSTED_ALLOWED_GROUPS=sre,platform-admins

See Trusted proxy for the full header reference, the shared-secret vs CHM_TRUSTED_ALLOW_INSECURE tradeoff, and the Dex/oauth2-proxy flags.

Health checks

Section titled “Health checks”

chmonitor exposes /healthz (liveness, static) and /api/healthz (readiness, gated on ClickHouse). Traefik can health-check the service:

## IngressRoute service entry
services:
  - name: chmonitor
    port: 3000
    healthCheck:
      path: /healthz
      intervalSeconds: 15

Make sure your ForwardAuth middleware does not guard /healthz and /api/healthz, or probes will be redirected to the login flow. Route those paths without the auth middleware (a separate, higher-priority router rule), or rely on the chart’s Kubernetes probes which hit the pod directly and bypass Traefik.

Section titled “Related”