从 Ingress NGINX Controller 迁移到 Traefik¶

如何以零停机方式从 Ingress NGINX Controller 迁移到 Traefik。

迁移后的结果¶

完成迁移后，现有 Ingress 资源无需修改就能由 Traefik 提供服务。Traefik Kubernetes Ingress NGINX 提供者会自动将 NGINX 注解转换为 Traefik 配置：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: myapp
  annotations:
    # These NGINX annotations are automatically translated by Traefik
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
    nginx.ingress.kubernetes.io/force-ssl-redirect: "true"
    nginx.ingress.kubernetes.io/enable-cors: "true"
    nginx.ingress.kubernetes.io/cors-allow-origin: "https://example.com"
    nginx.ingress.kubernetes.io/affinity: "cookie"
    nginx.ingress.kubernetes.io/session-cookie-name: "route"
spec:
  ingressClassName: nginx  # ← Traefik will watch this class
  rules:
    - host: myapp.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: whoami
                port:
                  number: 80

apiVersion: apps/v1
kind: Deployment
metadata:
  name: whoami
spec:
  replicas: 2
  selector:
    matchLabels:
      app: whoami
  template:
    metadata:
      labels:
        app: whoami
    spec:
      containers:
        - name: whoami
          image: traefik/whoami
          ports:
            - containerPort: 80

---
apiVersion: v1
kind: Service
metadata:
  name: whoami
spec:
  selector:
    app: whoami
  ports:
    - protocol: TCP
      port: 80
      targetPort: 80

完整的注解支持列表和行为差异，请参阅 Ingress NGINX 路由配置文档。

前置条件¶

开始迁移前，确保具备：

• Kubernetes 集群中正在运行的现有 Ingress NGINX Controller
• 已配置 kubectl 的 Kubernetes 集群访问能力
• 集群支持多个 LoadBalancer 服务同时监听 80/443 端口
• Helm
• 可创建 RBAC 资源的集群管理员权限
• 关键配置备份，包括 Ingress 资源、ConfigMap 和 Secret

# Export all Ingress resources
kubectl get ingress --all-namespaces -o yaml > ingress-backup.yaml

# Export NGINX ConfigMaps
kubectl get configmap --all-namespaces -l app.kubernetes.io/name=ingress-nginx -o yaml > nginx-configmaps.yaml

迁移策略概览¶

本迁移通过让 Traefik 与 NGINX 并行运行实现零停机。两个控制器同时为相同的 Ingress 资源提供服务，因此可以逐步切换流量，再移除 NGINX。

Current:     DNS → LoadBalancer → NGINX → Your Services

Migration:   DNS → LoadBalancer → NGINX  → Your Services
                 → LoadBalancer → Traefik → Your Services

Final:       DNS → LoadBalancer → Traefik → Your Services

迁移流程：

• 步骤 0：检查 ingress-nginx ConfigMap，将集群级默认值转换为 Traefik 配置
• 步骤 1：在 NGINX 旁部署 Traefik
• 步骤 2：验证 Traefik 正确处理流量
• 步骤 3：逐步将流量从 NGINX 切换至 Traefik
• 步骤 4：从 DNS 移除 NGINX，保留 IngressClass，然后卸载

步骤 0：迁移全局 ConfigMap 设置¶

安装 Traefik 前，检查当前 ingress-nginx ConfigMap 中设置的全局默认值。 在 ingress-nginx 中，控制器 ConfigMap 是集群级配置层。 在 Traefik 中，相同行为分布在以下位置：

• providers.kubernetesIngressNGINX 静态配置，提供 ingress-nginx 兼容性默认值
• 入口点，控制 HTTP 到 HTTPS 重定向、PROXY 协议等监听器行为
• 动态 tls.options 和 HTTP 中间件，控制 TLS 策略、HSTS 及其他 HTTP 头行为
• Traefik 访问日志配置，记录请求日志

先导出现有 ConfigMap，并检查自定义过的键：

kubectl get configmap --all-namespaces -l app.kubernetes.io/name=ingress-nginx,app.kubernetes.io/component=controller -o yaml

无论安装 ingress-nginx 时使用什么命名空间或发布名称，该标签选择器都可以定位控制器 ConfigMap。

ConfigMap 到 Traefik 的映射¶

没有直接对应项的 ConfigMap 键¶

部分 ingress-nginx ConfigMap 键专属于 NGINX，在迁移时可以移除，因为 Traefik 不暴露原始 NGINX 内部配置。 常见例子包括：

• worker-processes、worker-cpu-affinity 和 Lua 共享字典设置等工作进程调优项
• main-snippet、http-snippet、server-snippet、location-snippet 和 stream-snippet 等片段类键
• 超出 Traefik 内置访问日志格式的自定义 NGINX 日志模板

遇到这类键时，应转换它们想达到的目的，而不是逐字复制指令。

参考页面¶

• Kubernetes Ingress NGINX 提供者配置
• Traefik TLS 选项
• Traefik Headers 中间件
• Traefik 入口点配置
• ingress-nginx ConfigMap 参考

步骤 1：在 NGINX 旁安装 Traefik¶

helm upgrade --install ingress-nginx ingress-nginx \
  --repo https://kubernetes.github.io/ingress-nginx \
  --namespace ingress-nginx --create-namespace

启用 Kubernetes Ingress NGINX 提供者并安装 Traefik。两个控制器将同时为相同的 Ingress 资源提供服务。

添加 Traefik Helm 仓库¶

helm repo add traefik https://traefik.github.io/charts
helm repo update

安装 Traefik¶

helm upgrade --install traefik traefik/traefik \
  --namespace traefik --create-namespace \
  --set providers.kubernetesIngressNGINX.enabled=true

也可以通过 values 文件进行更多配置：

...
providers:
  kubernetesIngressNGINX:
    enabled: true
 ...

helm upgrade --install traefik traefik/traefik \
  --namespace traefik --create-namespace \
  --values traefik-values.yaml

确认两个控制器均在运行¶

# Check NGINX pods
kubectl get pods -n ingress-nginx

# Check Traefik pods
kubectl get pods -n traefik

# Check both services have LoadBalancer IPs
kubectl get svc -n ingress-nginx ingress-nginx-controller
kubectl get svc -n traefik traefik

此时 NGINX 和 Traefik 都已运行，能够为相同 Ingress 资源提供服务。但由于 DNS 仍指向 NGINX LoadBalancer，流量仍只经过 NGINX。

步骤 2：验证 Traefik 正确处理流量¶

将 Traefik 加入 DNS 前，先确认它能够正确服务现有 Ingress 资源。

通过 Traefik 的 LoadBalancer IP 测试¶

获取 Traefik 的 LoadBalancer IP，并使用 --resolve 测试，无需修改 DNS：

# Get LoadBalancer IPs
NGINX_IP=$(kubectl get svc -n ingress-nginx ingress-nginx-controller -o go-template='{{ $ing := index .status.loadBalancer.ingress 0 }}{{ if $ing.ip }}{{ $ing.ip }}{{ else }}{{ $ing.hostname }}{{ end }}')
TRAEFIK_IP=$(kubectl get svc -n traefik traefik -o go-template='{{ $ing := index .status.loadBalancer.ingress 0 }}{{ if $ing.ip }}{{ $ing.ip }}{{ else }}{{ $ing.hostname }}{{ end }}')
echo -e "Nginx IP: $NGINX_IP\nTraefik IP: $TRAEFIK_IP"

# Test HTTP for both
FQDN=myapp.example.com
# Observe HTTPS redirections:
curl --connect-to "${FQDN}:80:${NGINX_IP}:80" "http://${FQDN}" -D -
curl --connect-to "${FQDN}:80:${TRAEFIK_IP}:80" "http://${FQDN}" -D - # note X-Forwarded-Server which should be traefik

# Test HTTPS
curl --connect-to "${FQDN}:443:${NGINX_IP}:443" "https://${FQDN}"
curl --connect-to "${FQDN}:443:${TRAEFIK_IP}:443" "https://${FQDN}"

确认 Ingress 发现¶

检查 Traefik 日志，确认已发现现有 Ingress 资源：

kubectl logs -n traefik deployment/traefik | grep -i "ingress"

步骤 3：将流量切换到 Traefik¶

确认两个控制器均在运行且验证通过后，逐步将流量从 NGINX 切换到 Traefik。

方案 A：基于 DNS 的迁移¶

将 Traefik LoadBalancer IP 与 NGINX 地址一起加入 DNS 记录，让两个控制器都可以接收流量。

获取 LoadBalancer 地址：

# NGINX LoadBalancer
echo $(kubectl get svc -n ingress-nginx ingress-nginx-controller -o go-template='{{ $ing := index .status.loadBalancer.ingress 0 }}{{ if $ing.ip }}{{ $ing.ip }}{{ else }}{{ $ing.hostname }}{{ end }}')

# Traefik LoadBalancer
echo $(kubectl get svc -n traefik traefik -o go-template='{{ $ing := index .status.loadBalancer.ingress 0 }}{{ if $ing.ip }}{{ $ing.ip }}{{ else }}{{ $ing.hostname }}{{ end }}')

逐步迁移 DNS：

1. 将 Traefik 加入 DNS：把 Traefik LoadBalancer IP 加入 DNS 记录，此时两个 IP 通过轮询接收流量。
2. 监控：观察两个控制器上的流量模式。
3. 从 DNS 移除 NGINX：确认无误后，移除 NGINX LoadBalancer IP。
4. 等待 DNS 传播：留出时间让 DNS 缓存过期。
5. 卸载 NGINX：进入步骤 4。

方案 B：使用外部负载均衡器分配加权流量¶

如需更精确地控制流量分配，可以在两个 Kubernetes LoadBalancer 前放置外部负载均衡器，例如 Traefik、Cloudflare、AWS ALB 或专用负载均衡器。

配置步骤：

1. 创建指向 NGINX Kubernetes LoadBalancer 的外部负载均衡器。
2. 更新 DNS，使其指向外部负载均衡器。
3. 将 Traefik Kubernetes LoadBalancer 以较低权重（例如 10%）加入外部负载均衡器。
4. 逐渐增加 Traefik 权重，同时降低 NGINX 权重。
5. NGINX 不再接收流量后，将其卸载。

权重调整示例：

保留 LoadBalancer IP¶

如果希望 Traefik 最终使用与 NGINX 相同的 LoadBalancer IP，以简化 DNS 管理，可以在迁移后转移 IP。由于 Traefik 已经使用自己的 LoadBalancer 运行，这一过程可以实现零停机。

零停机 IP 转移流程：

1. Traefik 已使用自己的 LoadBalancer IP 运行（来自步骤 1）。
2. 将 Traefik LoadBalancer IP 加入 DNS，此时流量同时到达 NGINX 和 Traefik。
3. 从 DNS 移除 NGINX IP，等待传播。
4. 删除 NGINX LoadBalancer 服务以释放 IP。
5. 升级 Traefik，申请已释放的 IP。
6. 新 IP 生效后，可选地从 DNS 移除 Traefik 的旧 IP。

这样在 IP 转移期间，流量始终能够到达 Traefik。

获取当前 NGINX LoadBalancer IP：

kubectl get svc -n ingress-nginx ingress-nginx-controller -o go-template='{{ $ing := index .status.loadBalancer.ingress 0 }}{{ if $ing.ip }}{{ $ing.ip }}{{ else }}{{ $ing.hostname }}{{ end }}'

aws ec2 allocate-address --domain vpc --region <your-region>
# Note the AllocationId (eipalloc-xxx) for each EIP

service:
  type: LoadBalancer
  loadBalancerClass: service.k8s.aws/nlb  # Requires AWS Load Balancer Controller
  annotations:
    service.beta.kubernetes.io/aws-load-balancer-type: "external"
    service.beta.kubernetes.io/aws-load-balancer-nlb-target-type: "ip"
    service.beta.kubernetes.io/aws-load-balancer-eip-allocations: "eipalloc-xxx,eipalloc-yyy"

az network public-ip list --resource-group <your-resource-group> \
  --query "[?ipAddress=='<your-ip>'].name" -o tsv

service:
  type: LoadBalancer
  annotations:
    # Only needed if the public IP is in a different resource group than the AKS cluster
    service.beta.kubernetes.io/azure-load-balancer-resource-group: "<public-ip-resource-group>"
  spec:
    loadBalancerIP: "<your-existing-ip>"

# List existing static IPs
gcloud compute addresses list

# Or reserve a new regional static IP (must be in the same region as your GKE cluster)
gcloud compute addresses create traefik-ip --region <your-cluster-region>

service:
  type: LoadBalancer
  spec:
    loadBalancerIP: "<your-static-ip>"

NGINX_IP=$(kubectl get svc -n ingress-nginx ingress-nginx-controller \
  -o go-template='{{ $ing := index .status.loadBalancer.ingress 0 }}{{ if $ing.ip }}{{ $ing.ip }}{{ else }}{{ $ing.hostname }}{{ end }}')

echo "NGINX IP: $NGINX_IP"

kubectl annotate svc my-lb-svc loadbalancer.openstack.org/keep-floatingip=true

service:
  type: LoadBalancer
  spec:
    loadBalancerIP: "<your-existing-floating-ip>"

转移 IP：

DNS 已指向 Traefik，且 values 已配置目标 IP 后：

# Ensure Traefik is already receiving traffic via its current LoadBalancer
kubectl get svc -n traefik traefik

# Delete NGINX LoadBalancer service to release the IP
kubectl delete svc -n ingress-nginx ingress-nginx-controller

# Upgrade Traefik to claim the released IP
helm upgrade traefik traefik/traefik \
  --namespace traefik \
  --values traefik-values.yaml

# Verify Traefik now has the old NGINX IP
kubectl get svc -n traefik traefik

# In traefik-values.yaml
deployment:
  replicas: 2

# Spread pods across nodes to survive node failures
affinity:
  podAntiAffinity:
    requiredDuringSchedulingIgnoredDuringExecution:
      - labelSelector:
          matchLabels:
            app.kubernetes.io/name: traefik
            app.kubernetes.io/instance: traefik
        topologyKey: kubernetes.io/hostname

# Ensure at least one pod is always available during disruptions
podDisruptionBudget:
  enabled: true
  minAvailable: 1

步骤 4：卸载 Ingress NGINX Controller¶

NGINX 不再接收流量后，将其从集群移除。卸载前，必须确保保留 nginx IngressClass，Traefik 需要它继续发现现有 Ingress。

保留 IngressClass¶

# Add the required annotation
helm upgrade ingress-nginx ingress-nginx \
  --repo https://kubernetes.github.io/ingress-nginx \
  --namespace ingress-nginx \
  --reuse-values \
  --set-json 'controller.ingressClassResource.annotations={"helm.sh/resource-policy": "keep"}'
# Check that the annotation is really here
kubectl describe ingressclass nginx

# ingressclass.yaml
apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: nginx
spec:
  controller: k8s.io/ingress-nginx

kubectl apply -f - <<EOF
apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: nginx
spec:
  controller: k8s.io/ingress-nginx
EOF

删除 NGINX 准入 Webhook¶

应删除准入 Webhook，避免 NGINX 移除后修改 Ingress 时出现问题：

kubectl delete validatingwebhookconfiguration ingress-nginx-admission
kubectl delete mutatingwebhookconfiguration ingress-nginx-admission --ignore-not-found

卸载 NGINX¶

helm uninstall ingress-nginx -n ingress-nginx

如果已添加 helm.sh/resource-policy: keep 注解，应看到：

These resources were kept due to the resource policy:
[IngressClass] nginx

release "ingress-nginx" uninstalled

确认 IngressClass 存在¶

kubectl get ingressclass nginx

如果 IngressClass 意外被删除，可以使用保留 IngressClass一节中的命令重新创建。

清理 NGINX 命名空间¶

kubectl delete namespace ingress-nginx

故障排查¶

Traefik 提供仪表盘，可帮助了解运行情况。 参阅专门文档启用仪表盘。

# Verify IngressClass exists
kubectl get ingressclass nginx

# Check Traefik provider configuration
kubectl logs -n traefik deployment/traefik | grep -i "nginx\|ingress"

# Verify Ingress has correct ingressClassName
kubectl get ingress <name> -o yaml | grep ingressClassName

    # Verify TLS secret exists in the same namespace as Ingress
kubectl get secrets -n <namespace>

    # Check secret format
kubectl get secret <tls-secret-name> -n <namespace> -o yaml

  # Check service status
  kubectl describe svc -n traefik traefik

  # Check for events
  kubectl get events -n traefik --sort-by='.lastTimestamp'

后续步骤¶

进一步了解 Traefik：

• Kubernetes Ingress NGINX 安装配置：详细的提供者配置。
• Kubernetes Ingress NGINX 路由配置：路由规则与注解支持。
• HTTP 中间件：扩展 NGINX 注解之外的功能。
• TLS 配置：高级 TLS 与证书管理。

增强部署：

• 启用指标和追踪。
• 配置访问日志，提高可观测性。
• 探索 Traefik 中间件，实现高级流量管理。
• 从基于 Nginx 的配置迁移到 Traefik IngressRoute 或 Kubernetes Gateway API。
• 考虑使用 Traefik Hub，获取 AI 与 API 网关、API 管理和高级安全等企业功能。

反馈与支持¶

如果迁移中遇到问题，或对本指南有改进建议：

• 报告问题： GitHub Issues
• 社区支持： Traefik 社区论坛
• 企业支持： Traefik Labs 商业支持

欢迎为本迁移指南贡献改进。开始前请阅读贡献指南。