Nginx to Traefik migration Guide

nginx_traefik_guide.md

I'll look that up.I couldn't pull the KB by its number directly — the SUSE support KB (support.scc.suse.com) is auth-gated and the KB000022184 ID isn't publicly indexed, so I can't confirm which of the two articles that ID maps to. There are two Prime KB docs in this family:

• Migrating from Ingress NGINX to Traefik in a standalone RKE2 cluster
• How to migrate the Rancher Ingress to Traefik in an RKE2 cluster (for Rancher local clusters, which need extra care to avoid locking yourself out of the UI)

The good news is the standalone one has a public equivalent at documentation.suse.com/cloudnative/rke2/latest/en/reference/ingress_migration.html (mirrored at docs.rke2.io), and the SUSE doc explicitly points to the Prime KB as the "more detailed" version of the same procedure. Here's what it says.

Why

Ingress NGINX retired in March 2026, so RKE2 is switching to Traefik as the default ingress controller for new clusters starting with v1.36. Rancher Prime LTS gets critical/important CVE backports for ingress-nginx through December 2027 on RKE2 v1.35, so you have runway.

Prerequisites

You need v1.32.11+rke2r1, v1.33.7+rke2r1, v1.34.3+rke2r1, or anything above v1.35. Traefik's NGINX compatibility layer doesn't cover every annotation — Traefik Labs publishes an annotations discovery tool (github.com/traefik/ingress-nginx-migration) to find unsupported ones in your cluster before you start.

The four phases

Phase 1 — dual controllers. First pin every existing Ingress to ingressClassName: nginx explicitly (there's a kubectl patch loop for this) so nothing races when Traefik shows up. Then in /etc/rancher/rke2/config.yaml:

ingress-controller:
- ingress-nginx
- traefik

And a HelmChartConfig at /var/lib/rancher/rke2/server/manifests/rke2-traefik-config.yaml putting Traefik on temporary ports and enabling the NGINX-annotation provider:

apiVersion: helm.cattle.io/v1
kind: HelmChartConfig
metadata:
  name: rke2-traefik
  namespace: kube-system
spec:
  valuesContent: |-
    ports:
      web:
        hostPort: 8000
      websecure:
        hostPort: 8443
    providers:
      kubernetesIngressNGINX:
        enabled: true
        ingressClass: "rke2-ingress-nginx-migration"
        controllerClass: "rke2.cattle.io/ingress-nginx-migration"

Restart rke2-server on all control-plane nodes, confirm both DaemonSets are up and that Traefik logs Starting provider *ingressnginx.Provider.

Phase 2 — parallel validation. Duplicate each critical Ingress with the class changed to rke2-ingress-nginx-migration (the doc ships a jq script that strips status/resourceVersion/uid/managedFields, appends -traefik to the name, and re-applies). Now the same services answer on 80/443 via NGINX and 8000/8443 via Traefik — test annotation behavior side by side.

Phase 3 — switchover. Set ingress-controller: [traefik] only, drop the custom ports: block from the HelmChartConfig, restart. If downtime matters, split this: remove Ingress NGINX first while Traefik stays on 8000/8443, then move Traefik to standard ports once NGINX is fully gone — teardown of its webhooks and resources is slow.

Phase 4 — cleanup. Delete the leftover ingressClassName: nginx Ingresses.

Things worth flagging for your setup

• The bridge class is deliberate. They use rke2-ingress-nginx-migration rather than letting Traefik read nginx directly, because both controllers would fight over the Ingress status subresource, and the nginx IngressClass gets deleted automatically when Ingress NGINX is uninstalled in Phase 3.
• Provider name casing changed. As of the June releases (v1.36.2+rke2r1, v1.35.6+rke2r1, v1.34.9+rke2r1, v1.33.13+rke2r1), the Traefik chart renamed kubernetesIngressNginx → kubernetesIngressNGINX. Easy silent failure if you're on an older patch.
• Health check endpoints differ if you have an external LB: NGINX uses /healthz, Traefik uses /ping.
• Air-gap: Traefik isn't in the default rke2-images.linux-amd64.tar.zst — you need rke2-images-traefik.linux-amd64.tar.zst staged separately.
• Longhorn: no backend impact, but the Longhorn UI Ingress needs reconfiguring — there's a separate doc for basic-auth Ingress with Traefik.
• Rancher-provisioned downstream clusters skip all of this: Rancher v2.13.5+ and v2.14 expose a "Dual Mode" migration option right in the cluster config UI.

If you're specifically after the Rancher-local-cluster variant (the one that guards against locking yourself out of the Rancher Ingress), that's the second KB and it builds on these same phases — you'd need an SCC login to read it, or you can give me the article title from your portal and I'll work from that.