从 Ingress NGINX 迁移到 Traefik

适用场景

希望使用 Traefik 的自动服务发现、中间件链、Gateway API 或更简单的证书管理。迁移难点在注解语义、重写规则、限流和灰度配置。

前置条件

• 现有 Ingress 清单和注解清单。
• Traefik 的 LoadBalancer 地址或域名。
• TLS 证书和 DNS 管理权限。
• 保留 Ingress NGINX 作为回滚路径。

步骤

1. 导出并梳理现有 Ingress：

kubectl get ingress -A -o yaml > ingress-all.yaml
grep -nE 'nginx.ingress.kubernetes.io|ingressClassName|host:|path:' ingress-all.yaml

2. 安装 Traefik：

helm repo add traefik https://traefik.github.io/charts
helm install traefik traefik/traefik \
  --namespace traefik --create-namespace \
  --set ingressClass.enabled=true \
  --set ingressClass.name=traefik
kubectl -n traefik get svc

3. 创建 IngressRoute：

kubectl apply -f - <<'EOF'
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: demo
  namespace: demo
spec:
  entryPoints: [websecure]
  routes:
  - match: Host(`demo.example.com`) && PathPrefix(`/api`)
    kind: Rule
    services:
    - name: api
      port: 8080
    middlewares:
    - name: strip-api
EOF

4. 配置重写和限流中间件：

kubectl apply -f - <<'EOF'
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: strip-api
  namespace: demo
spec:
  stripPrefix:
    prefixes: ["/api"]
---
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: ratelimit
  namespace: demo
spec:
  rateLimit:
    average: 100
    burst: 50
EOF

5. 配置 TLS：

kubectl -n demo create secret tls demo-tls --cert=fullchain.pem --key=privkey.pem

6. 测试新入口：

curl -k --resolve demo.example.com:443:$TRAEFIK_IP https://demo.example.com/api/health

验证

• 路由、重写、超时、限流和灰度与旧 Ingress 一致。
• TLS 证书正确加载。
• WebSocket/SSE 长连接正常。
• 访问日志和指标可观测。
• 旧 Ingress 流量降为 0 后再删除。

回滚

• 保留 Ingress NGINX 和原 LoadBalancer。
• DNS 切回旧入口。
• 不删除旧证书和 Secret，直到观察期结束。
• 记录注解到中间件的映射关系。

常见坑

• rewrite-target 与 stripPrefix 语义不同，路径拼接错误。
• 多个 Ingress 注解冲突，Traefik 中间件顺序不正确。
• ingressClassName 没有切换，流量仍走旧控制器。
• TLS Secret 命名空间或证书链不完整。
• 限流和超时默认值不同，行为变化。
• WebSocket 没有配置正确的 entryPoint 或超时。
• 旧 Ingress 和新 IngressRoute 同时匹配，流量随机分流。

相关命令

• kubectl — 管理 Ingress、IngressRoute、Middleware
• curl — 按 host 验证路由
• openssl — 检查证书
• traefik — 查看路由和中间件状态