Agent Skills: Traefik Knowledge Patch

Traefik Knowledge Patch

Use this guide to identify behavior that affects a Traefik task, then open the matching topic reference before editing static configuration, dynamic configuration, Kubernetes resources, or deployment manifests.

Reference index

| Reference | Topics | | --- | --- | | Kubernetes and Gateway API | Gateway API, EndpointSlices, CRDs, Ingress, Ingress NGINX, Knative, and namespace controls | | Observability | OpenTelemetry, access logs, support dumps, API/dashboard paths, and dashboard features | | Providers and operations | Docker, Swarm, ECS, Nomad, HTTP, plugins, socket activation, proxy controls, and operational fixes | | Routing, middleware, and services | Router hierarchies, matching, retries, compression, mirroring, health checks, balancing, failover, and stickiness | | Security, TLS, and authentication | ACME, TLS, ForwardAuth, forwarded headers, IP strategy, secrets, and security maintenance |

Check compatibility before editing

• Upgrade Traefik CRDs and RBAC together. Gateway API installations also need the matching Gateway API CRDs, and Kubernetes providers discover backends through EndpointSlices.
• Revalidate custom resources after a CRD upgrade. CEL and regular-expression validation are stricter, and the schema no longer supplies a default load-balancing strategy.
• Retest Kubernetes Ingress Prefix routes because matching follows Kubernetes semantics rather than Traefik's earlier interpretation.
• Treat generated Kubernetes resource names as migration-sensitive, especially when automation depends on their exact form.
• Use path-only health-check paths; absolute URLs are rejected.
• Remove reliance on deprecated defaultRuleSyntax and ruleSyntax settings.
• Replace ForwardAuth configurations that depend on TrustForwardHeader, and set body-size limits explicitly when forwarding request or response bodies.
• Set trace verbosity explicitly when span detail matters; the default emits fewer spans.
• Treat ingress-nginx snippets as constrained translations. Traefik parses only supported, allowlisted directives and never inserts arbitrary raw NGINX.
• Audit plugin manifests before allowing unsafe interpreter operations or syscalls, since both enlarge the plugin's execution authority.
• On the 3.7 patch line, use 3.7.11 rather than an earlier patch to incorporate the accumulated HTTP, TLS, Kubernetes, and security corrections.

Read Kubernetes and Gateway API for controller and manifest migrations, Security, TLS, and authentication for trust-boundary changes, and Providers and operations before selecting a deployment image or enabling plugins.

Build multi-layer HTTP routing

Use parentRefs when a parent router must apply shared middleware or TLS and enrich a request before a child evaluates its own rule.

http:
  routers:
    api-parent:
      rule: "Host(`api.example.com`) && PathPrefix(`/`)"
      entryPoints:
        - websecure
      middlewares:
        - auth-with-tier
      tls: {}
    api-enterprise:
      rule: "HeaderRegexp(`X-Customer-Tier`, `(enterprise|business)`)"
      parentRefs:
        - api-parent
      service: stable-backend

Keep the hierarchy structural rules intact:

• Attach root routers to entry points and omit a service from them.
• Let intermediate routers have children.
• Put the selected service on leaf routers.
• Expect every request to traverse its parent before reaching a child.

Router rules also accept wildcard Host and HostSNI names. Set provider precedence when routes produced by different providers can compete. Review the encoded-character policy before combining router hierarchies with rewriting or prefix stripping.

Apply behavior at the service boundary

Attach middleware directly to an HTTP service when every router selecting that service must receive the same processing. This also lets Gateway API filters apply to HTTP backends.

http:
  services:
    api:
      loadBalancer:
        servers:
          - url: "http://api-backend:8080"
      middlewares:
        - rate-limit
        - auth

Use status-aware retries when retry policy depends on backend responses:

http:
  middlewares:
    smart-retry:
      retry:
        attempts: 3
        initialInterval: 100ms
        retryOn:
          statusCodes: [502, 503, 504]
        timeout: 2s

Opt in deliberately before retrying non-idempotent methods. For service-level failover, define the response-status ranges that should switch from the primary to the fallback. See Routing, middleware, and services for provider-specific balancing strategies and CRD failover syntax.

Choose health and balancing behavior

• Use native TCP health checks for non-HTTP backends.
• Use passive checks to infer health from live traffic.
• Set a distinct unhealthy interval when failed servers need a different probe cadence.
• Choose p2c, Least Time, or HighestRandomWeight only where the target provider supports it.
• Scope sticky cookies with both path and domain where the defaults are too broad.
• Treat condition-only EndpointSlice updates as backend-state changes.

Read the routing and services reference before translating file-provider services into Kubernetes CRDs; strategy availability differs by provider.

Configure Kubernetes integrations

The Gateway provider supports HTTP, gRPC, and TLS routes with method, query, destination-port, regular-expression path, rewrite, redirect, response-header, backend-protocol, backend-TLS, and reference-grant behavior. It also reports route validity and supported features.

For ingress-nginx migration, enable kubernetesIngressNginx as a normal provider and audit every annotation:

providers:
  kubernetesIngressNginx:
    enabled: true

Compatibility includes many common authentication, rewrite, timeout, buffering, affinity, canary, rate-limit, header, error, access-log, and entry-point cases, but it is not a raw NGINX execution layer.

For Knative workloads, enable the experimental integration and scope watched namespaces:

experimental:
  knative: true
providers:
  knative:
    namespaces:
      - serverless-apps
      - production

Read Kubernetes and Gateway API for exact API channels, status ownership, certificate references, safe naming, and cross-namespace controls.

Secure certificates and upstream TLS

Treat ACME settings as resolver-local: resolvers can have separate account email addresses and custom CA trust. Configure profiles, multiple contacts, challenge propagation, HTTP challenge delay, provider timeouts, certificate duration, OCSP, and certificate timeouts only where required.

TLS configuration can disable session tickets and default-option fallback, enable X25519MLKEM768, and restrict upstream cipher suites through ServersTransport. Router TLS replaces rather than merges with entry-point TLS. Read Security, TLS, and authentication before debugging SNI, shared SANs, fragmented ClientHello messages, or missing Secrets.

Preserve observability intent

• Set OTLP metrics service.name and resource attributes deliberately.
• Correlate access logs with traces using trace ID and entry-point span ID.
• Enable application-log and access-log OTLP export through the required experimental setting, and use stdio when a local stream is also needed.
• Apply metrics, tracing, and access-log controls at entry-point or router scope when global settings are too broad.
• Use the support-dump endpoint for diagnostic state and configure the API/dashboard base path when mounting the UI below a prefix.
• Inspect certificate and service details in the dashboard during TLS and balancing investigations.

Read Observability for Kubernetes resource detection, trace-context attributes, secret-file handling, and UI additions.

Validate the finished change

1. Validate static and dynamic configuration with the same provider mix used in the target environment.
2. Apply current CRDs before custom resources, then verify controller status, namespace boundaries, and EndpointSlice RBAC.
3. Exercise WebSocket, CONNECT, redirect, CORS, encoded-path, authentication, retry, mirroring, and health-check behavior when relevant.
4. Inspect access logs, traces, route status, and dashboard service/certificate details for the expected result.
5. Review patch-line security and compatibility fixes before choosing an image.