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 via legacy prod overlay, local, jls
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-04-17

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 load balancer Traefik overlays expose the Service as LoadBalancer and depend on a routable IP
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/prod, traefik/overlays/layer7, traefik/overlays/jls
Deployment model Kustomize
Namespace traefik
Workload kind Deployment, Service, PVC, 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/prod Legacy overlay name still used by Fleet bootstrap
local traefik/overlays/layer7 Service type LoadBalancer pinned to oci-arm via node.io/ingress=true; overlay dir pending rename to local
jls traefik/overlays/jls Uses Cloudflare origin certificate and dashboard host on mutana.site

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 Cloudflare-backed overlays yes
CF_API_EMAIL overlay secret cloudflare Cloudflare account context for ACME automation yes

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: Kustomize secretGenerator fed by local overlay files such as cloudflare-api-token.txt, do-api-token.txt, origin certificate files, and basic auth env files
  • Rotation trigger: DNS provider credential rotation, certificate renewal policy changes, or dashboard credential rotation
  • Recovery note: if the secretGenerator source files are wrong or missing, certificate issuance, dashboard access, and provider integration break immediately after reconciliation

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 and keep overlay source files for provider credentials and certificates under version control discipline.
  • 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: standardized base and overlay split with per-cluster LoadBalancer patches and DNS provider specific secret generation.
  • Rollback reference: revert the overlay revision that changed static config, middleware resources, or provider credentials, then reapply the previous overlay.