cargo.ayedo.cloud/ayedo/k8s/traefik

Deploys Traefik Proxy v3 als Ingress Controller und/oder Gateway API Controller via dem offiziellen Helm-Chart.

Unterstützt klassische Kubernetes Ingress-Ressourcen, Traefik-eigene IngressRoute CRDs und optional den Kubernetes Gateway API Standard.

Minor Migrations (v3.7): https://doc.traefik.io/traefik/v3.7/migrate/v3/#v371

Konfiguration

Alle Optionen liegen unter config.* im Block oder in der workspace.poly.

Minimal (Ingress Controller, 1 Replica)

- name: traefik
  from: cargo.ayedo.cloud/ayedo/k8s/traefik
  config:
    namespace: traefik
    replicas: 1
    ingressclass:
      isdefaultclass: true

Produktiv (HA, Hetzner LB, Custom Resources)

- name: traefik
  from: cargo.ayedo.cloud/ayedo/k8s/traefik
  config:
    namespace: traefik
    replicas: 3
    resources:
      requests:
        cpu: 200m
        memory: 256Mi
      limits:
        cpu: 1000m
        memory: 512Mi
    ingressclass:
      enabled: true
      isdefaultclass: true
      name: traefik
    service:
      type: LoadBalancer
      annotations:
        load-balancer.hetzner.cloud/location: nbg1
        load-balancer.hetzner.cloud/name: traefik-prod
        load-balancer.hetzner.cloud/use-private-ip: "true"
    log:
      level: INFO
      access:
        enabled: true
        format: json
    metrics:
      enabled: true
      vmservicescrape:
        enabled: true
        namespace: victoria-metrics-stack

Mit Gateway API

Voraussetzung: Gateway API CRDs müssen im Cluster installiert sein. Entweder gateway_api.install_crds: true setzen (Block installiert sie automatisch), oder die CRDs manuell vorab installieren:
kubectl apply --server-side -f \
  https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.3.0/standard-install.yaml

- name: traefik
  from: cargo.ayedo.cloud/ayedo/k8s/traefik:0.1.0
  config:
    namespace: traefik
    replicas: 2
    ingressclass:
      enabled: true
      isdefaultclass: false
      name: traefik
    gateway_api:
      enabled: true
      install_crds: true          # CRDs automatisch installieren
      crds_version: "v1.3.0"
      create_gatewayclass: true   # GatewayClass "traefik" erstellen
      create_gateway: true        # Standard-Gateway erstellen
      experimental_channel: false # true = TCPRoute, TLSRoute aktivieren

Konfigurationsreferenz

Schlüssel	Standard	Beschreibung
`namespace`	`traefik`	Kubernetes Namespace
`create_namespace`	`true`	Namespace automatisch anlegen
`replicas`	`1`	Anzahl Traefik Pods
`resources`	`{}`	CPU/Memory Requests und Limits
`ingressclass.enabled`	`true`	IngressClass deployen
`ingressclass.isdefaultclass`	`false`	Als Cluster-Standard-IngressClass setzen
`ingressclass.name`	`traefik`	Name der IngressClass
`service.type`	`LoadBalancer`	Service-Typ
`service.annotations`	`{}`	Annotations auf dem LB Service Object
`service.externalips`	`[]`	Feste externe IPs
`gateway_api.enabled`	`false`	Gateway API Provider aktivieren
`gateway_api.experimental_channel`	`false`	TCPRoute/TLSRoute aktivieren
`gateway_api.install_crds`	`false`	Gateway API CRDs automatisch installieren
`gateway_api.crds_version`	`v1.3.0`	Version der Gateway API CRDs
`gateway_api.create_gatewayclass`	`true`	Standard-GatewayClass deployen
`gateway_api.create_gateway`	`true`	Standard-Gateway deployen
`gateway_api.gateway_namespace`	`""`	Namespace des Gateways (leer = Traefik-Namespace)
`log.level`	`INFO`	Log-Level: `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL`, `PANIC`
`log.format`	`""`	Log-Format: `json` oder leer (common)
`log.access.enabled`	`false`	HTTP Access Logs aktivieren
`log.access.format`	`""`	Access Log Format: `json` oder leer
`providers.kubernetes_crd.enabled`	`true`	Traefik IngressRoute CRD Provider
`providers.kubernetes_crd.allow_cross_namespace`	`false`	Namespaces-übergreifende IngressRoutes erlauben
`providers.kubernetes_ingress.enabled`	`true`	Standard Kubernetes Ingress Provider
`dashboard.enabled`	`false`	Traefik Dashboard IngressRoute deployen
`metrics.enabled`	`false`	Dedizierten Metrics Service deployen (Port 9100)
`metrics.vmservicescrape.enabled`	`false`	VMServiceScrape für VictoriaMetrics deployen
`metrics.vmservicescrape.namespace`	`victoria-metrics-stack`	Namespace des VMServiceScrape
`certmanager.enabled`	`false`	cert-manager Integration aktivieren (Traefik verwaltet keine Certs selbst)
`certmanager.clusterissuer`	`letsencrypt-production`	ClusterIssuer-Annotation auf dem shared Gateway (nur bei `gateway_api.enabled: true`)
`certmanager.gateway_tls_secret`	`traefik-gateway-tls`	Secret-Name, in den cert-manager das Gateway-Zertifikat schreibt

Installation

poly run traefik install

Deinstallation

poly run traefik uninstall

Status

poly run traefik status

Hinweise

Service Annotations (LoadBalancer)

Die service.annotations werden direkt auf das LoadBalancer Service Object von Traefik gesetzt. Damit lassen sich Cloud-Provider-spezifische LB-Features konfigurieren.

Hetzner Cloud Beispiele:

service:
  annotations:
    load-balancer.hetzner.cloud/location: nbg1
    load-balancer.hetzner.cloud/type: lb11
    load-balancer.hetzner.cloud/name: my-cluster-lb
    load-balancer.hetzner.cloud/use-private-ip: "true"
    load-balancer.hetzner.cloud/disable-private-ingress: "true"
    load-balancer.hetzner.cloud/ipv6-disabled: "false"

Gateway API vs. Ingress

Traefik unterstützt beide Modi parallel. Es ist möglich, providers.kubernetes_ingress.enabled: true und gateway_api.enabled: true gleichzeitig zu betreiben.

Ingress (klassisch)

App-Team erstellt ein Ingress-Objekt
  → enthält: Routing-Regeln + tls.secretName + cert-manager Annotation
  → cert-manager sieht die Annotation, stellt das Zertifikat aus, schreibt ins Secret
  → Traefik liest das Ingress-Objekt und terminiert TLS

Routing, TLS-Konfiguration und Cert-Management liegen vollständig im Ingress-Objekt. Jede App besitzt ihre Konfiguration selbst.

Gateway API

Gateway API trennt Infrastructure-Verantwortung und App-Verantwortung explizit in drei Ressourcentypen:

GatewayClass  →  definiert die Implementierung ("traefik") — cluster-weit, Ops-Verantwortung
     ↓
Gateway       →  definiert Listener-Infrastruktur (Port, Protokoll, TLS) — Ops-Verantwortung
     ↓
HTTPRoute     →  definiert Routing-Regeln (Host/Path → Service) — App-Team-Verantwortung

Es gibt einen shared Gateway pro Cluster, nicht einen pro App oder Host. Der Gateway ist Infrastruktur — vergleichbar mit dem LoadBalancer Service des nginx-ingress Controllers: alle Apps nutzen denselben, und erstellen nur ihre eigenen Routing-Regeln.

App-Teams erstellen HTTPRoute-Objekte. Gateways werden nie von App-Teams erstellt.

	Ingress	Gateway API
Routing-Objekt (App)	`Ingress`	`HTTPRoute`
Infrastruktur (Ops)	implizit	`Gateway` (explizit, shared)
TLS-Konfiguration	pro Ingress-Objekt	am Gateway-Listener
Cert-Manager Trigger	Annotation pro Ingress	Annotation am shared Gateway

cert-manager + Gateway API

cert-manager >= v1.17 unterstützt Gateway API nativ (GA, kein Feature Gate nötig).

Wenn certmanager.enabled: true gesetzt ist, wird die cert-manager.io/cluster-issuer-Annotation auf den shared Gateway geschrieben. cert-manager scannt dann alle am Gateway angehängten HTTPRoute-Objekte, extrahiert daraus die Hostnamen, und stellt pro Hostname automatisch ein Zertifikat aus — genau wie bei der per-Ingress-Annotation, nur eine Ebene höher.

# So sieht ein App-Team-Objekt im Gateway API Modell aus:
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: my-app
  namespace: my-app
spec:
  parentRefs:
    - name: traefik          # referenziert den shared Gateway
      namespace: traefik
  hostnames:
    - my-app.example.com     # cert-manager stellt für diesen Host automatisch ein Cert aus
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: my-app-service
          port: 8080

Dashboard

Das Dashboard ist standardmäßig deaktiviert. Bei Aktivierung über dashboard.enabled: true wird eine IngressRoute erstellt, die nur über den internen traefik Entrypoint erreichbar ist. Für externen Zugriff muss eine separate IngressRoute mit Auth-Middleware erstellt werden.

PodDisruptionBudget

Bei replicas > 1 wird automatisch ein PodDisruptionBudget mit maxUnavailable: 1 erstellt.