Skip to content

traefik

Metadata

Field Value
Service traefik
Purpose Shared ingress controller, TLS termination point, and edge routing layer for workloads exposed through LoadBalancer services
Criticality Tier 0
Owner Platform / Networking owner
Clusters homelab, local, cc-obs-kube (jls overlay), ozilab (Ozilab), cc-wrk-kube
Namespace traefik
Exposure Internal, LAN, VPN, and internet depending on cluster overlay
Stateful yes
Backup class PVC snapshot plus Git-backed configuration
RPO / RTO Low RPO for acme.json and origin certificates, 15 to 30 minutes to restore ingress service
Last reviewed 2026-07-28

1. Service Overview

Traefik is the north-south entry point for the homelab platform. It provides HTTP and TLS routing, dashboard access, middleware-based authentication, and edge exposure for selected external services. Multiple overlays tailor DNS challenge providers, dashboard hosts, and LoadBalancer behavior per cluster.

Summary

Without Traefik, internet-facing and many internal service routes stop working. It is also a dependency for observability flows because metrics are exported to the k8s-monitoring Alloy receiver and some overlays expose external services such as MinIO or Rancher through Traefik resources.

Dependencies

Dependency Type Why it matters
MetalLB or provider ingress load balancer LoadBalancer overlays require an allocated address; cc-obs-kube uses worker ports 80/443 and a ClusterIP Service
Authelia identity Dashboard and protected routes rely on forwardAuth middlewares
DNS challenge provider secrets secret ACME certificate issuance uses Cloudflare or DigitalOcean tokens depending on overlay
traefik-pvc storage ACME state and certificates are stored on a PVC mounted at /certs
k8s-monitoring Alloy receiver observability Static config forwards OTLP metrics to the monitoring stack

2. Architecture Diagram

[Client]
  -> [Cloudflare or direct LoadBalancer]
  -> [MetalLB-assigned IP]
  -> [Service traefik:80/443]
  -> [Traefik entrypoints and middlewares]
  -> [IngressRoute / TraefikService / backend service]

[Traefik metrics]
  -> [k8s-monitoring-alloy-receiver:4318]

3. Deployment Specifications

Item Value
Source path traefik/base plus traefik/overlays/cc-wrk-kube, traefik/overlays/homelab, traefik/overlays/local, traefik/overlays/jls, traefik/overlays/ozilab
Deployment model Kustomize; Fleet and manual kubectl use the same per-cluster overlay
Namespace traefik
Workload kind Deployment or DaemonSet by overlay, Service, PVC where enabled, CRDs, IngressRoute, Middleware, TLSOption, TLSStore
Chart or image version Traefik image v3.6 and upstream CRDs fetched from the Traefik v3.6 reference URLs
Config files base/traefik-deploy.yaml, base/traefik-service.yaml, overlays/*/kustomization.yaml, traefik-static-config.yaml, traefik-dynamic-config.yaml, traefik-resources.yaml

Cluster mapping

Cluster Overlay path Notes
homelab traefik/overlays/homelab Fleet target customization uses the standardized homelab overlay
local traefik/overlays/local Service type LoadBalancer pinned to the edge node via node.io/ingress=true; Cloudflare Origin certificate from the default TLSStore, no ACME resolvers and no DNS provider token
cc-obs-kube (jls) traefik/overlays/jls Host-network DaemonSet on untainted workers, ports 80/443; ClusterIP Service, Cloudflare Origin certificate, existing NFS certificate PVC retained
ozilab traefik/overlays/ozilab Ozilab overlay, selected by the dedicated GitRepo on branch dev
cc-wrk-kube traefik/overlays/cc-wrk-kube Host-network DaemonSet on the workers behind HAProxy 46.30.203.187; Cloudflare Origin certificate, no ACME or PVC; reached only through the local Traefik's priority-1 *.mutana.fr catch-all in overlays/local/cc-wrk-kube-backend.yaml (see traefik/README.md)

cc-obs-kube ingress path

Jelastic forwards traffic to worker IPs on ports 80/443, where the Traefik DaemonSet listens directly. Internal clients use the unchanged traefik Service name and ClusterIP. There is no LoadBalancer address to allocate. The control-plane node remains excluded by its existing taint.

The provider NFS volume mounts on all three workers. Current routes use the Cloudflare Origin certificate; none selects the declared ACME resolvers. The certificate PVC and Secret references are preserved. Before activating ACME, replace the shared-file multi-pod arrangement with a single-writer certificate design. Recheck storage access modes before changing the backend.

4. Configuration Guide

Traefik configuration is split between mounted static and dynamic config files, environment variables injected through overlay patches, and CRD resources declared in overlay resource files.

Environment variables

Variable Source Purpose Secret?
CF_DNS_API_TOKEN overlay secret cloudflare DNS-01 challenge for Let's Encrypt on the overlays that declare ACME resolvers (homelab, jls, ozilab) yes
CF_API_EMAIL overlay secret cloudflare Cloudflare account context for ACME automation on the same overlays yes

local and cc-wrk-kube inject neither variable: they declare no ACME resolvers, so Traefik there needs no DNS provider credentials.

ConfigMaps

Resource Path Purpose
traefik-config traefik/overlays/*/traefik-static-config.yaml and traefik-dynamic-config.yaml EntryPoints, providers, ACME resolvers, access logs, OTLP metrics, and dynamic middleware configuration

Secrets management

  • Secret names: cloudflare, cloudflare-origin-cert, do-auth-token, basic-auth-user
  • Source of truth: overlay-specific. Ozilab is migrating to out-of-band Kubernetes Secrets shared by Fleet and manual Kustomize; phase 1 retains the currently generated cloudflare and basic-auth-user Secrets before their tracked generator inputs are removed. Other overlays retain their existing Kustomize generator contracts.
  • Rotation trigger: DNS provider credential rotation, certificate renewal policy changes, or dashboard credential rotation
  • Recovery note: for Ozilab, create cloudflare and basic-auth-user in namespace traefik before the first Fleet reconciliation or manual apply on a rebuilt cluster. Missing Cloudflare keys prevent ACME DNS-01; missing basic auth keys break the corresponding dashboard middleware.

Notable runtime settings from the committed config:

  • Base readiness and liveness probes use /ping on port 80.
  • Metrics are exposed on port 8082 and forwarded by OTLP HTTP to the Alloy receiver.
  • LoadBalancer exposure is applied by overlay patches rather than in the shared base.
  • Scaling above a single replica should be reviewed carefully because ACME state is written to a single ReadWriteOnce PVC.

5. Access Protocols

Path URL or endpoint Audience Auth TLS terminates at
Internal traefik.traefik.svc.cluster.local on ports 80 and 443, metrics on 8082 Cluster workloads and operators Middleware- or backend-specific Traefik entrypoints
External traefik.mutana.fr for local, traefik.mutana.site for jls and legacy homelab Platform operators Authelia forwardAuth or basic auth depending on overlay Traefik with ACME or origin certificate strategy per overlay

6. Operations and Observability

  • Primary health indicators: Deployment available, Service has a LoadBalancer address, /ping succeeds, and dashboard routes answer through the expected middleware chain.
  • Dashboards or alerts: Traefik dashboard and OTLP-exported metrics consumed by k8s-monitoring.
  • Log locations: Container logs plus access.log mounted through the static configuration.
  • Known failure modes: missing external IP due to MetalLB, ACME failure caused by invalid provider secrets, dashboard auth loops when Authelia is unavailable, or stale CRDs after Traefik upgrades.

7. Backup and Recovery Notes

  • Backup method: snapshot or restore the traefik-pvc, keep Git-backed non-secret configuration, and back up provider credentials through the approved out-of-band secret process. Do not commit plaintext credentials.
  • Restore prerequisites: working MetalLB allocation, provider credentials, namespace traefik, and the overlay-specific resource files.
  • Related runbook: ../runbooks/traefik.md

8. Release and Change Notes

  • Current deployed app version: Traefik v3.6.
  • Current chart version: N/A, deployed from raw manifests and Kustomize overlays.
  • Last significant change: began the two-phase Ozilab handoff from Fleet-owned Kustomize-generated Secrets to out-of-band stable-name Secrets, while keeping one shared overlay for Fleet and manual deployment.
  • Rollback reference: revert the overlay revision that changed static config, middleware resources, or provider credentials, then reapply the previous overlay.