Skip to content

Traefik

Součást PiKube setupu na k3s.

Zdroje

Let's encrypt integrace

Traefik podporuje active24 out-of-the-box od verze v3.3.6 nebo v2.11.24 (pomocí go-acme/lego). Traefik Let's Encrypt docs.

Setup

Vytvořit kubernetes secret s API Key (Active24 API key je uložený v Bitwarden: Active24 API Key - cert-manager webhook): 

kubectl -n kube-system create secret generic active24-credentials --from-literal=ACTIVE24_API_KEY='your_api_key' --from-literal=ACTIVE24_SECRET='your_secret'

Note

Na ostatní control nody se obsah /var/lib/rancher/k3s/server/manifests/ synchronizuje automaticky, změny se monitorují a okamžitě se aplikují.

Na jakémkoliv master nodu vytvořit /var/lib/rancher/k3s/server/manifests/traefik-config.yaml: 

apiVersion: helm.cattle.io/v1
kind: HelmChartConfig
metadata:
  name: traefik
  namespace: kube-system
spec:
  valuesContent: |-
    additionalArguments:
      - "--certificatesresolvers.active24resolver.acme.dnschallenge.provider=active24"
      - "--certificatesresolvers.active24resolver.acme.email=admin@mixi.cz"
      - "--certificatesresolvers.active24resolver.acme.storage=/data/acme.json"
      - "--certificatesresolvers.active24resolver.acme.dnschallenge.delaybeforecheck=0"
    env:
      - name: ACTIVE24_API_KEY
        valueFrom:
          secretKeyRef:
            name: active24-credentials
            key: ACTIVE24_API_KEY
      - name: ACTIVE24_SECRET
        valueFrom:
          secretKeyRef:
            name: active24-credentials
            key: ACTIVE24_SECRET
    persistence:
      enabled: true
      accessMode: ReadWriteOnce
      size: 1Gi
      storageClass: local-path
      path: /data

Pro debug logování stačí přidat "--log.level=DEBUG" mezi argumenty.

Warning

Pozor na rate limits! Pro zprovoznění je lepší použít Let's Encrypt staging prostředí, které má výrazně vyšší rate limity.

Pro ověření proti Let's Encrypt staging prostředí přidat "--certificatesresolvers.active24resolver.acme.caserver=https://acme-staging-v02.api.letsencrypt.org/directory": 

additionalArguments:
  - "--certificatesresolvers.active24resolver.acme.caserver=https://acme-staging-v02.api.letsencrypt.org/directory"
  - "--certificatesresolvers.active24resolver.acme.dnschallenge.provider=active24"
  - "--certificatesresolvers.active24resolver.acme.email=admin@mixi.cz"
  - "--certificatesresolvers.active24resolver.acme.storage=/data/acme.json"
  - "--certificatesresolvers.active24resolver.acme.dnschallenge.delaybeforecheck=0"

Příklady dynamické konfigurace

Ukázkový ingress: 

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ingress-grafana
  annotations:
    spec.ingressClassName: traefik
    traefik.ingress.kubernetes.io/router.tls.certresolver: active24resolver
spec:
  rules:
    - host: grafana.mixi.cz
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: grafana
                port:
                  number: 80
  tls:
    - hosts:
        - grafana.mixi.cz

Případně multihost: 

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ingress-mkdocs-multi
  annotations:
    spec.ingressClassName: traefik
    traefik.ingress.kubernetes.io/router.tls.certresolver: active24resolver
spec:
  rules:
    - host: doc.mixi.cz
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: mkdocs
                port:
                  number: 80
    - host: wiki.mixi.cz
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: mkdocs
                port:
                  number: 80
  tls:
    - hosts:
        - doc.mixi.cz
        - wiki.mixi.cz

Řešení problémů

1. nefunguje active24 DNS provider: unrecognized DNS provider: active24

time="2025-05-23T21:37:24Z" level=error msg="Unable to obtain ACME certificate for domains \"test-tls.mixi.cz\": cannot get ACME client unrecognized DNS provider: active24" ACME CA="https://acme-staging-v02.api.letsencrypt.org/directory" routerName=websecure-default-ingress-test-tls-test-tls-mixi-cz@kubernetes rule="Host(`test-tls.mixi.cz`) && PathPrefix(`/`)" providerName=active24resolver.acme
řešení: upgrade k3s na v1.33.0+k3s1

První verze, která obsahuje podporu active24 pomocí LEGO knihovny:

Control nodes: 

curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION="v1.33.0+k3s1" sh -

Worker nodes (nahradit <token> za reálný token): 

time curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION="v1.33.0+k3s1" K3S_TOKEN=<token> sh -s - agent --server https://pikm01:6443

2. chyby v traefik logu secret XXX does not exist

ERR Error configuring TLS error="secret default/test-tls does not exist" ingress=ingress-test-tls namespace=default providerName=kubernetes
řešení – nadbytečné pole secretName

V tls sekci ingressu je pole secretName – smazat ho. Dodávají to tam buď hotové ingress manifesty, které předpokládají použití cert-manageru nebo rady od AI. V cert-manager setupu si z těchto secrets traefik vyčítá certifikáty a klíče, které tam cert-manager spravuje.

Podpora vytváření secrets v traefiku – toto se možná bude hodit v budoucnu

Danger

Nepoužívat, podpora secrets je v traefiku (v3.3.6) zatím pouze experimentální! Je to exkluzivní s ukládáním do souboru, lze nastavit pouze jeden způsob.

Práva na vytváření a správu secrets (zatím nejsou přiřazena automaticky, ale možná v budoucnu budou až bude stabilní podpora secrets v traefiku - zatím funguje jen čtení pokud je vytváří cert-manager): 

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: traefik-secret-manager-global
rules:
- apiGroups: [""]
  resources: ["secrets"]
  verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: traefik-secret-manager-global-binding
subjects:
- kind: ServiceAccount
  name: traefik                   # Zkontrolujte název ServiceAccountu Traefiku
  namespace: kube-system          # Namespace, kde Traefik běží
roleRef:
  kind: ClusterRole
  name: traefik-secret-manager-global
  apiGroup: rbac.authorization.k8s.io

Autentizace

Traefik v k3s clusteru poskytuje autentizaci prostřednictvím ForwardAuth middleware v kombinaci s Authelia SSO serverem.

Authelia Integration

Traefik je nakonfigurován k práci s Authelia SSO Authentication serverem jako identity provider. Authelia poskytuje:

  • ForwardAuth Middleware: Ověřuje uživatele před přístupem k chráněným službám
  • Network-based Access Control: Automatické obejití pro interní síť (192.168.0.0/22)
  • Multi-Factor Authentication: TOTP a WebAuthn/FIDO2 podpora pro externí přístup
  • OAuth2/OIDC Provider: Standardní protokoly pro integraci s aplikacemi

Required Traefik Configuration

IP Forwarding for Real Client Detection

Pro správné fungování Authelia je nutné nakonfigurovat Traefik tak, aby důvěřoval proxy headers od Apache reverse proxy:

# Patch Traefik deployment to trust forwarded headers
kubectl patch deployment traefik -n kube-system --type='json' -p='[
  {
    "op": "add",
    "path": "/spec/template/spec/containers/0/args/-",
    "value": "--entryPoints.websecure.forwardedHeaders.trustedIPs=192.168.0.0/22,10.42.0.0/16,10.43.0.0/16,127.0.0.0/8"
  },
  {
    "op": "add",
    "path": "/spec/template/spec/containers/0/args/-",
    "value": "--entryPoints.web.forwardedHeaders.trustedIPs=192.168.0.0/22,10.42.0.0/16,10.43.0.0/16,127.0.0.0/8"
  }
]'

Důvod: Bez této konfigurace Authelia vidí pouze k3s pod IP adresy (10.42.x.x) místo skutečných klientských IP adres, což znemožňuje network-based access control.

ForwardAuth Middleware Configuration

Úplná konfigurace Authelia ForwardAuth middleware je dokumentována v Authelia - Working Configuration Details.

Klíčové elementy pro Traefik integraci: - Cookie Header: Musí být v authRequestHeaders pro session persistence - Session Cookie: addAuthCookiesToResponse: ["authelia_session"] pro SSO funkcionalitu - Trust Headers: trustForwardHeader: true pro proxy chain

Using Authentication in Services

Standard Ingress with ForwardAuth

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: protected-service
  annotations:
    traefik.ingress.kubernetes.io/router.middlewares: authelia-authelia@kubernetescrd
spec:
  rules:
  - host: service.mixi.cz
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: my-service
            port:
              number: 80

IngressRoute with ForwardAuth

apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: protected-service
spec:
  entryPoints:
    - websecure
  routes:
    - match: Host(`service.mixi.cz`)
      kind: Rule
      services:
        - name: my-service
          port: 80
      middlewares:
        - name: authelia
          namespace: authelia
  tls:
    certResolver: active24resolver

Authentication Flow

Kompletní diagram authentication flow včetně detailního popisu je k dispozici v Authelia - Architecture.

Current Protected Services

  • grafana.mixi.cz: Grafana monitoring dashboard
  • ha.mixi.cz: Home Assistant automation platform
  • wiki.mixi.cz: mkdocs dokumentace

Troubleshooting Authentication Issues

Kompletní troubleshooting guide včetně všech debug commands je k dispozici v Authelia - Troubleshooting.

Traefik-specifické debug commands: 

# Monitor Traefik logs for ForwardAuth requests
kubectl logs -n kube-system -l app.kubernetes.io/name=traefik --follow | grep -i forward

# Verify IP forwarding configuration
kubectl get deployment traefik -n kube-system -o jsonpath='{.spec.template.spec.containers[0].args}' | grep forwardedHeaders

Security Notes

Detailní bezpečnostní informace jsou dokumentované v Authelia - Security Features.

Traefik-specifické bezpečnostní aspekty: - Trusted Proxy Configuration: Kritická konfigurace pro správné předávání klientských IP adres - ForwardAuth Headers: Důležité pro bezpečnou komunikaci mezi Traefik a Authelia - Middleware Chain: Správné pořadí middleware pro bezpečný authentication flow

References