• A standalone or imported RKE2 cluster that is using Ingress NGINX as the ingress controller. The local cluster, where Rancher deployed, is included in this category.
  一个独立或导入的 RKE2 集群，使用 Ingress NGINX 作为入口控制器。Rancher 部署的本地集群也包含在这一类别中。
• RKE2 v1.32 >= v1.32.11+rke2r1, v1.33 >= v1.33.7+rke2r1, v1.34 >= v1.34.3+rke2r1, or >= v1.35.0+rke2r1
  RKE2 v1.32 >= v1.32.11+rke2r1， v1.33 >= v1.33.7+rke2r1， v1.34 >= v1.34.3+rke2r1， or >= v1.35.0+rke2r1

N.B. For Rancher-provisioned RKE2 clusters, a separate KB will be created, once support for Traefik is enabled in the RKE2 cluster provisioning UIs.
注意： 对于 Rancher 配置的 RKE2 集群，一旦在 RKE2 集群配置界面中启用 Traefik 支持，将创建一个独立的知识库。

Situation  地理位置

You’ve likely seen the announcement that Ingress NGINX will be retired after March 2026. For organizations that do not want to migrate ingress controller in the near term, SUSE will help you stabilize what you have. RKE2 v1.35 will give SUSE Rancher Prime LTS customers support through November 2027. That means hardened baselines and continuous CVE monitoring on Ingress NGINX, with documented mitigations.
你很可能已经看到过 Ingress NGINX 将在 2026 年 3 月后退役的公告。对于近期不打算迁移入口控制器的组织，SUSE 将帮助你稳定现有设备。RKE2 v1.35 将为 SUSE Rancher Prime LTS 客户提供支持 至 2027 年 11 月。这意味着在 Ingress NGINX 上必须有更强的基线和持续的 CVE 监控，并有文档化的缓解措施。

For organizations ready to move, SUSE offers a path to Traefik. Where your configuration fits common patterns, it is possible to lean on Traefik’s nginx-compatibility approach to reduce changes and risk during the cutover. Where you’ve accumulated bespoke annotations or advanced behaviours - for example, TLS passthrough, mutual TLS, rate limiting, custom authentication - our consulting services team can help you scope the differences, pilot safely and stage a controlled cutover. 
对于准备搬迁的组织，SUSE 为通往 Traefik 提供了一条路径。当配置符合常见模式时，可以依赖 Traefik 的 nginx 兼容性方法来减少切换过程中的变化和风险。如果您积累了定制注释或高级行为——例如 TLS 直通、互助 TLS、速率限制、自定义认证——我们的咨询服务团队可以帮助您界定差异，安全试飞并实现受控切换。

For more information, check our blog post.
欲了解更多信息，请查看我们的博客文章 。

This article explains the supported migration plan to Traefik.
本文解释了支持的迁徙计划，前往特雷菲克。

Important considerations  重要考虑

Before starting the migration, please review the following technical requirements and limitations:
在开始迁移前，请先审查以下技术要求和限制：

• Annotation compatibility: While Traefik includes a "shim layer" to interpret NGINX annotations, compatibility is not 1/1.
  注释兼容性 ：虽然 Traefik 包含一个“垫层”用于解释 NGINX 注释，但兼容性并非一举可行。

  • Action: Review the official Traefik annotations list to identify unsupported annotations.
    动作场面： 请查看官方 Traefik 注释列表以识别无支持的注释。

  • Tooling: Use the Traefik-provided discovery tool to automatically highlight unsupported annotations within your cluster.
    工具： 使用 Traefik 提供的发现工具 ，自动高亮集群中不支持的注释。

  • Support: If your environment relies on unsupported annotations, our consulting services team can assist with scoping, pilot testing, and staging a controlled cutover.
    支持： 如果您的环境依赖无支持的注释，我们的咨询服务团队可以协助范围界定、试点测试并进行受控切换。

• General limitations: The Traefik documentation depicts some limitations of the current implementation that you will need to take into account.
  一般限制： Traefik 文档展示了当前实现的一些限制，你需要考虑这些限制。

Requirements  要求

Before starting the migration from Ingress NGINX to Traefik make sure that you comply with the requirements:
在开始从 Ingress NGINX 迁移到 Traefik 之前，请确保您满足以下要求：

• One of the following RKE2 versions, or above:
  以下 RKE2 版本之一或更高版本：

  • v1.35.0+rke2r1

  • v1.34.3+rke2r1

  • v1.33.7+rke2r1

  • v1.32.11+rke2r1 

• Verify the Ingress NGINX annotations are supported.
  确认 Ingress NGINX 注释是否支持 。

• Verify if you are impacted by the above mentioned limitations.
  请确认您是否受到上述限制的影响。

• Backup of critical configurations (Ingress resources, ConfigMaps, Secrets).
  备份关键配置（入口资源、配置映射、秘密）。

If an older version of RKE2 is run, an upgrade to any of those minors is needed.
如果运行的是较旧版本的 RKE2，则需要升级到这些小项目中的任意一个。

If you are hit by any limitation or using an unsupported annotation, please contact the SUSE team.
如果您遇到任何限制或使用了不支持的注释，请联系 SUSE 团队。

Migration  迁徙

The migration process involves four main phases on your RKE2 cluster:
迁移过程包括 RKE2 集群的四个主要阶段：

1. Phase 1: Dual ingress controller setup - Enable Traefik alongside Ingress NGINX, using temporary non-conflicting ports for Traefik.
   第一阶段：双入口控制器设置 ——启用 Traefik 与 Ingress NGINX，使用临时且不冲突的端口支持 Traefik。

2. Phase 2: Parallel migration and validation - Replicating the ingress objects, they can be exposed by both Ingress NGINX and Traefik. We can use this phase to verify that Traefik can handle the existing ingress objects without disruption.
   第二阶段：并行迁移与验证 ——通过复制入口对象，它们可以被 Ingress NGINX 和 Traefik 同时暴露。我们可以利用这一阶段验证 Traefik 能否在不中断的情况下处理现有的入口对象。

3. Phase 3: Final switchover and port reassignment  - Once the testing is complete using Traefik, this phase will remove Ingress NGINX.
   第三阶段：最终切换和端口重新分配  ——一旦使用 Traefik 测试完成，这一阶段将移除 Ingress NGINX。

4. Phase 4: Cleanup - Remove the duplicated ingress resources 
   第四阶段：清理 ——移除重复的入口资源 

Pre-requisites  先决条件

• Access to RKE2 Server Node: You must be able to modify the RKE2 configuration file (/etc/rancher/rke2/config.yaml), stage new manifest files on the server node and restart the rke2 control plane nodes.
  访问 RKE2 服务器节点： 你必须能够修改 RKE2 配置文件（/etc/rancher/rke2/config.yaml），在服务器节点上设置新的清单文件，并重启 RKE2 控制平面节点。

• Existing Ingress NGINX Setup: Your cluster is currently running Ingress NGINX as the ingress controller.
  现有的 Ingress NGINX 设置： 你的集群目前运行的是 Ingress NGINX 作为入口控制器。

Phase 1: Dual ingress controller setup (Coexistence)
第一阶段：双输入控制器设置（共存）

In this phase, you enable Traefik as a secondary Ingress Controller and configure it to use temporary ports to avoid conflict with the existing Ingress NGINX controller. You also enable the Ingress NGINX provider that allows Traefik to interpret Ingress NGINX annotations.
在此阶段，启用 Traefik 作为次级入口控制器，并配置其使用临时端口以避免与现有入口 NGINX 控制器冲突。你还启用了 Ingress NGINX 提供者，允许 Traefik 解释 Ingress NGINX 注释。

1. Assign ingressClassName: nginx to existing ingresses
1. 将 ingressClassName： nginx 分配给现有入口

First, ensure all existing Ingress resources are explicitly bound to the Ingress NGINX controller to prevent any race conditions when Traefik is deployed.
首先，确保所有现有的 Ingress 资源都明确绑定到 Ingress NGINX 控制器，以防止 Traefik 部署时出现任何竞争条件。

<span style="color:#000000"><span style="background-color:#ffffff"><span style="background-color:#efefef"><code># This command finds all Ingress resources across all namespaces and patches them
# to set the ingressClassName to 'nginx'.

kubectl get ingress --all-namespaces -o custom-columns='NAMESPACE:.metadata.namespace,NAME:.<a data-cke-saved-href="http://metadata.name/" href="http://metadata.name/">metadata.name</a>' --no-headers | while read NS NAME; do
    echo "Patching Ingress: $NS/$NAME"
    kubectl patch ingress "$NAME" -n "$NS" --type=merge -p '{"spec": {"ingressClassName": "nginx"}}'
done
</code></span></span></span>

1.1. Verification: confirm IngressClass assignment
1.1. 验证：确认 IngressClass 赋值

Run this command to quickly verify that all your Ingress resources now have their ingressClassName explicitly set to nginx.
执行此命令，快速验证所有 Ingress 资源的 ingressClassName 是否已显式设置为 nginx。

<span style="color:#000000"><span style="background-color:#ffffff"><span style="background-color:#efefef"><code># This command lists all Ingresses and their assigned Ingress Class Name (ICLASS).
# Check the output: the ICLASS column should show 'nginx' for all your resources.
kubectl get ingress --all-namespaces -o custom-columns='NAMESPACE:.metadata.namespace,NAME:.<a data-cke-saved-href="http://metadata.name/" href="http://metadata.name/">metadata.name</a>,ICLASS:.spec.ingressClassName'
</code></span></span></span>

If any Ingress resource shows <none> or a different class in the ICLASS column, you must investigate and manually patch those resources before proceeding to the next step.
如果任何 Ingress 资源在 ICLASS 列显示 <none> 或其他类别，您必须先调查并手动修补这些资源，才能进入下一步。

2. Update RKE2 configuration
2. 更新 RKE2 配置

Edit the RKE2 server configuration file (/etc/rancher/rke2/config.yaml) to enable both controllers:
编辑 RKE2 服务器配置文件（/etc/rancher/rke2/config.yaml）以启用两个控制器：

<span style="color:#000000"><span style="background-color:#ffffff"><span style="background-color:#efefef"><code># /etc/rancher/rke2/config.yaml
ingress-controller:
- ingress-nginx
- traefik</code></span></span></span>

⚠️ For airgap installations: If you are using the Image Tarball, note that Traefik is not included in the default rke2-images.linux-amd64.tar.zst asset (example assuming amd64), and you will need to download the additional rke2-images-traefik.linux-amd64.tar.zst tarball, and place it in the corresponding folder on the airgap node.
⚠️ 关于 Airgap 安装：如果你使用 Image Tarball，请注意 Traefik 不包含在默认的 rke2-images.linux-amd64.tar.zst 资产中（例如假设 amd64），你需要下载额外的 rke2-images-traefik.linux-amd64.tar.zst tarball，并将其放在 airgap 节点对应的文件夹中。

3. Configure Traefik ports and compatibility settings
3. 配置 Traefik 端口及兼容性设置

Create the HelmChartConfig manifest on your server node (e.g., /var/lib/rancher/rke2/server/manifests/rke2-traefik-config.yaml). This manifest now performs three functions:
在你的服务器节点上创建 HelmChartConfig 清单（例如， /var/lib/rancher/rke2/server/manifests/rke2-traefik-config.yaml ）。该清单现在承担三项功能：

1. Sets Traefik to use non-conflicting ports (8000 and 8443).
   设置 Traefik 使用非冲突端口（8000 和 8443）。

2. Enables Ingress NGINX compatibility mode for annotations (--providers.kubernetesIngressNGINX).
   启用 NGINX 对注释的兼容性模式（ --providers.kubernetesIngressNGINX ）。

3. Disables the published service to avoid race conditions with Ingress NGINX.
   禁用已发布的服务以避免与 Ingress NGINX 的竞赛条件。

<span style="color:#000000"><span style="background-color:#ffffff"><span style="background-color:#efefef"><code># rke2-traefik-config.yaml

apiVersion: <a data-cke-saved-href="http://helm.cattle.io/v1" href="http://helm.cattle.io/v1">helm.cattle.io/v1</a>
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"</code></span></span></span>

4. Restart RKE2  4. 重启 RKE2

Restart the rke2-server service in all CP nodes to apply the configuration changes:
在所有 CP 节点重启 rke2-server 服务以应用配置更改：

<span style="color:#000000"><span style="background-color:#ffffff"><span style="background-color:#efefef"><code>sudo systemctl restart rke2-server</code></span></span></span>

Wait for the cluster to become ready. Verify that both rke2-ingress-nginx-controller and rke2-traefik DaemonSets must be running:
等集群准备好。验证 rke2-ingress-nginx-controller 和 rke2-traefik DaemonSets 都必须同时运行：

<span style="color:#000000"><span style="background-color:#ffffff"><span style="background-color:#efefef"><code>kubectl get daemonset -n kube-system</code></span></span></span>

5. Verify Functionality  5. 验证功能

• Existing Ingress NGINX Ingresses: Verify that your existing Ingresses are still reachable on the standard ports (80/443).
  现有的 NGINX 入口： 确认你现有的入口端口在标准端口（80/443）上仍然可访问。

• New Traefik Ingresses (Testing): You can now deploy new Ingress resources specifying the traefik class to test your new controller, using the temporary ports (8000/8443) for access.
  新特拉菲克入口（测试）： 你现在可以部署新的 Ingress 资源，指定 traefik 类来测试你的新控制器，并使用临时端口（8000/8443）进行访问。

• Verify Traefik DaemonSet manifest: The DaemonSet includes hostPort: 8000, and hostPort: 8443.
  Verify Traefik DaemonSet manifest： 守护进程集包括 hostPort： 8000 和 hostPort： 8443。

• New IngressClass: There is a new ingressClass with name “rke2-ingress-nginx-migration”.
  新入门职业：  有一个名为“rke2-ingress-nginx-migration”的新 ingressClass。

• IngressNginx provider: Verify that the Ingressnginx provider is started. In the traefik logs:
  IngressNginx 提供商： 确认 Ingressnginx 的服务提供者已经启动。在 traefik 日志中：

<span style="color:#000000"><span style="background-color:#ffffff"><span style="background-color:#efefef"><code>INF Starting provider *ingressnginx.Provider</code></span></span></span>

Phase 2: Parallel migration and validation
第二阶段：并行迁移与验证

The goal is to validate that Traefik can correctly handle traffic and NGINX annotations by processing duplicated Ingress resources.
目标是验证 Traefik 是否能通过处理重复的 Ingress 资源，正确处理流量和 NGINX 注释。

⚠️ When migrating a Rancher local cluster, which includes the Rancher Ingress resource, specific steps are required. In this case, follow the guide: How to migrate the Rancher Ingress to Traefik in an RKE2 cluster.
⚠️ 在迁移包括牧场主入站资源的牧场主本地集群时，需要采取特定步骤。在这种情况下，请按照指南作： 如何在 RKE2 集群中将牧场主入口迁移到 Traefik。

1. Duplicate and reclassify Ingresses
1. 重复并重新分类入口

For every critical Ingress resource (currently using ingressClassName: nginx), create a copy of the manifest with only one change: set the class name to rke2-ingress-nginx-migration.
对于每个关键的 Ingress 资源（目前使用 ingressClassName： nginx），创建一个仅做一改动的清单副本：将类名 设置为 rke2-ingress-nginx-migration。

Apply these new, duplicated Ingress manifests. You can click here to download SCRIPT1 for a suggested way to achieve this.
应用这些新的、重复的入门清单。你可以点击这里下载 SCRIPT1，获取一些建议的实现方法。

2. Test services via both controllers
2. 通过两个控制器测试服务

Your services are now accessible via two separate routes (hostPorts):
您的服务现在可以通过两条不同的路径（hostPorts）访问：

• Ingress NGINX access (Original/Stable): http://<Node_IP>; (on ports 80/443)
  NGINX 入口访问（原始/稳定）：http：//<Node_IP>;（端口 80/443）

• Traefik access (Testing/Duplicated): http://<Node_IP>:8000 (on ports 8000/8443)
  Traefik 访问（测试/复制）：http：//<Node_IP>：8000（端口 8000/8443）

Note that Traefik provides also a ClusterIP service by default.
注意，Traefik 默认也提供 ClusterIP 服务。

Thoroughly test all services accessed via the Traefik port (8000/8443), ensuring all Nginx-specific features (annotations) are handled correctly by Traefik's compatibility layer.
彻底测试通过 Traefik 端口（8000/8443）访问的所有服务，确保所有 Nginx 专属的功能（注释）被 Traefik 的兼容层正确处理。

3. (Optional) Configure external load balancer
3. （可选）配置外部负载均衡器

If you use an external load balancer (LB) to route traffic to your Kubernetes cluster, add Traefik as a backend using the Traefik node route (http://<Node_IP>:8000).
如果你使用外部负载均衡器（LB）将流量路由到 Kubernetes 集群，建议通过 Traefik 节点路由（http：<Node_IP>：8000）添加 Traefik 作为后端。

Refer to the Traefik Migration Guide for either DNS-Based migration or External Load Balancer with Weighted Traffic strategies. Take into account that the guide expects both ingresses to include a service with a LoadBalancer address but this guide is assuming node ports are used
请参阅 Traefik 迁移指南 ，了解基于 DNS 的迁移或带加权流量的外部负载均衡器。请注意，指南期望两个入口都包含带有负载均衡器地址的服务，但本指南假设使用节点端口

⚠️ Health Check Warning!
⚠️  健康检查警告！

Ingress NGINX and Traefik use different health check endpoints. Ensure your LB configuration is updated accordingly:
Ingress NGINX 和 Traefik 使用不同的健康检查端点。确保你的线卫配置相应地更新：

• Ingress NGINX: /healthz
  Ingress NGINX： /healthz

• Traefik: /ping  Traefik： /ping

Phase 3: Final switchover and port reassignment 
第三阶段：最终切换及端口重新分配

Once validation is complete, you will uninstall Ingress NGINX and switch Traefik to the standard ports. Note that uninstalling Ingress NGINX might take a while because of how Kubernetes handles the teardown of resources and webhooks. If downtime is very important for you, you should consider splitting this phase in two: first uninstall Ingress NGINX while keeping Traefik listening on the 8000/8443 ports and then, once Ingress NGINX is removed, change Traefik ports.
验证完成后，你将卸载 Ingress NGINX，并将 Traefik 切换到标准端口。注意卸载 Ingress NGINX 可能需要一段时间，因为 Kubernetes 处理资源和 webhook 的处理方式不同。如果停机时间对你很重要，建议把这个阶段分成两部分：先卸载 Ingress NGINX，同时让 Traefik 监听 8000/8443 端口;然后在 Ingress NGINX 移除后，再更换 Traefik 端口。

1. Uninstall Ingress NGINX
1. 卸载 Ingress NGINX

Edit the RKE2 server configuration file (/etc/rancher/rke2/config.yaml) to set Traefik as the only Ingress Controller:
编辑 RKE2 服务器配置文件（/etc/rancher/rke2/config.yaml），将 Traefik 设置为唯一的入口控制器：

<span style="color:#000000"><span style="background-color:#ffffff"><span style="background-color:#efefef"><code># /etc/rancher/rke2/config.yaml
ingress-controller: 
- traefik</code></span></span></span>

If downtime is important and you’d like to split this phase, you should restart RKE2 at this point and don’t move to the next step (configure Traefik for Standard Ports) until Ingress NGINX is completely removed.
如果停机时间很重要，并且你想分阶段进行，应该在此时重启 RKE2，并且在完全移除 Ingress NGINX 之前，不要进入下一步（配置 Traefik 为标准端口）。

2. Configure Traefik for Standard Ports
2. 配置 Traefik 为标准端口

Update the HelmChartConfig manifest (/var/lib/rancher/rke2/server/manifests/rke2-traefik-config.yaml) to remove the custom port configuration.
更新 HelmChartConfig 列表（ /var/lib/rancher/rke2/server/manifests/rke2-traefik-config.yaml ）以移除自定义端口配置。

<span style="color:#000000"><span style="background-color:#ffffff"><span style="background-color:#efefef"><code># rke2-traefik-config.yaml

apiVersion: <a data-cke-saved-href="http://helm.cattle.io/v1" href="http://helm.cattle.io/v1">helm.cattle.io/v1</a>
kind: HelmChartConfig
metadata:
  name: rke2-traefik
  namespace: kube-system
spec:
  valuesContent: |-
    providers:
      kubernetesIngressNginx:
        enabled: true
        ingressClass: "rke2-ingress-nginx-migration"
        controllerClass: "rke2.​cattle.​io/ingress-nginx-migration"</code></span></span></span>

3. Restart RKE2  3. 重启 RKE2

Restart the rke2-server service in all CP nodes:
在所有 CP 节点重启 rke2-server 服务：

<span style="color:#000000"><span style="background-color:#ffffff"><span style="background-color:#efefef"><code>sudo systemctl restart rke2-server</code></span></span></span>

After a few seconds, helm-controller will detect the new configurations for both Ingress NGINX controller (remove) and Traefik (redeploy).
几秒钟后，舵控制器将检测到入口 NGINX 控制器（移除）和 Traefik（重新部署）的新配置。

4. Final verification (standard ports)
4. 最终验证（标准端口）

• Verify that the Ingress NGINX DaemonSet is gone.
  确认 Ingress NGINX 守护进程组是否已消失。

• Verify that your services are now accessible via the duplicated Traefik Ingresses on the standard ports (80/443).
  确认你的服务现在可以通过标准端口（80/443） 上的复制 Traefik 入口访问。

 

Phase 4: Cleanup   第四阶段：清理

1. Remove Ingress NGINX Objects
1. 移除入口 NGINX 对象

Delete the legacy Ingress objects that were bound to ingressClassName: nginx. For example, you can use the following script which removes all ingress objects which do not include the word traefik in their class
删除绑定到 ingressClassName： nginx 的遗留 Ingress 对象。例如，你可以使用以下脚本，去除所有不包含 traefik 一词的入口对象

<span style="color:#000000"><span style="background-color:#ffffff"><span style="background-color:#efefef"><code># Finds and deletes all original Ingresses explicitly bound to Ingress NGINX
kubectl get ingress --all-namespaces -o custom-columns='NAMESPACE:.metadata.namespace,NAME:.<a data-cke-saved-href="http://metadata.name/" href="http://metadata.name/">metadata.name</a>,ICLASS:.spec.ingressClassName' --no-headers | awk '$3 == "nginx" {print; exit}' | while read NS NAME ICLASS; do
    echo "Deleting legacy Ingress: $NS/$NAME"
    kubectl delete ingress "$NAME" -n "$NS"
done
</code></span></span></span>

Notes  注释

• By default the Ingress NGINX provider reads ingressClassName = nginx. We decided to change this and use a “bridge” ingressClass (rke2-ingress-nginx-migration) to avoid two problems:
  默认情况下，Ingress NGINX 提供者读取 ingressClassName = nginx。我们决定改变这一点，使用“桥接”ingressClass（rke2-ingress-nginx-migration）以避免两个问题：

  • 1 - Potential race conditions as both ingress controllers would read the same ingress resource and could try to update the status at the same time.
    1 - 潜在的竞争条件，因为两个入口控制器会读取同一个入口资源，并可能同时尝试更新状态。

  • 2 - The ingressClass nginx gets removed automatically when Ingress NGINX is uninstalled in phase 3.
    2 - 当 Ingress NGINX 在第三阶段卸载时，nginx 类 nginx 会自动移除。

• While preparing this document, we have detected a couple of bugs in some annotations. In general, it seems the Traefik Ingress NGINX provider is not super well tested with each and every annotation. If something weird is found, please contact us. We have a direct channel with Traefik engineers.
  在准备本文档时，我们在一些注释中发现了一些漏洞。总体来说，Traefik Ingress NGINX 供应商的每一个注释测试都不够充分。如果发现异常情况，请联系我们。我们与 Traefik 工程师有直接联系。

• Ingress NGINX might take a long time to be removed.
  Ingress NGINX 可能需要很长时间才能被移除。