Kubernetes IngressClass 怎样选择控制器

在 Kubernetes 中选择 Ingress 控制器，真正要对齐的不是“我想用 NGINX 还是 Traefik”这句产品名，而是三个字段之间的关系：Ingress 的 spec.ingressClassName 指向哪个 IngressClass.metadata.name，以及这个 IngressClass 的 spec.controller 是否正好是目标控制器监听的值。最稳妥的做法是给每个控制器建立清晰的 IngressClass，并在每个 Ingress 上显式写出 ingressClassName。

官方地址：https://kubernetes.io/docs/concepts/services-networking/ingress/

选择控制器时先查控制器文档中的 controller value，再决定 IngressClass 的名称；名称负责被 Ingress 引用，controller value 负责让控制器决定是否接管。多个控制器并存时，不要依赖“谁先发现资源”，也不要把旧 annotation 当成新配置的替代品。

先分清三个名字分别负责什么

IngressClass 是集群级资源。它的 metadata.name 是给 Ingress 引用的类名，例如 public-nginx；spec.controller 则是控制器用来认领这类资源的标识。Ingress 只保存类名，不直接把某个 Deployment 的名字写进去。

因此，下面三段关系不能混用：

• Ingress.spec.ingressClassName：当前路由对象选择的 IngressClass 名称。
• IngressClass.metadata.name：集群中被引用的类名，可以按流量边界或环境命名。
• IngressClass.spec.controller：控制器实现声明并监听的值，必须和控制器配置对得上。

例如，IngressClass 叫 public-nginx 并不意味着它的 controller value 一定是 public-nginx。前者是资源引用名，后者要以具体控制器的文档、Helm values 或启动参数为准。把两个值写成一样有时只是命名习惯，不能当成 Kubernetes 的强制规则。

先查 controller value，再创建 IngressClass

以 ingress-nginx 为例，控制器的 --controller-class 决定它满足哪个 IngressClass 的 spec.controller。官方示例的默认值是 k8s.io/ingress-nginx；如果部署第二个实例，通常要为它设置不同的 controller value、IngressClass 名称，以及必要时不同的选主标识。

下面的清单表达的是“公网控制器负责 public-nginx 这一类”，不是所有控制器都应照抄的通用值：

apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: public-nginx # 这是 Ingress.spec.ingressClassName 要引用的资源名
spec:
  controller: k8s.io/ingress-nginx # 必须与目标控制器的 controller-class 对齐

如果使用 Traefik，则应以其部署配置和官方文档为准；常见的 IngressClass controller value 是 traefik.io/ingress-controller。不要因为类名叫 traefik，就把 spec.controller 也随意写成 traefik。控制器是否处理对象，取决于它的实现和配置。

多控制器场景优先使用显式绑定

当集群里只有一个控制器时，无类 Ingress 可能因为默认 IngressClass 而正常工作；一旦同时运行公网和内网两个控制器，隐式选择就会变成风险。应用团队只需要在 Ingress 上填写类名，控制器之间就可以按类边界分工。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: checkout-public # 这个对象只声明公网路由
  namespace: shop
spec:
  ingressClassName: public-nginx # 显式指向上面的 IngressClass
  rules:
    - host: checkout.example.com
      http:
        paths:
          - path: /
            pathType: Prefix # Prefix 让根路径覆盖其子路径
            backend:
              service:
                name: checkout
                port:
                  number: 8080 # 后端 Service 的端口，不是控制器端口

这里的成功条件不是 YAML 被 API Server 接受，而是目标控制器能看到并处理它。应用的部署模板应把 ingressClassName 作为明确配置，而不是让不同环境靠默认值“碰巧工作”。如果公网与内网控制器都部署了，应该各自使用不同的 IngressClass 名称和互不混淆的 controller value。

默认类只解决无类对象，不替代显式选择

可以在一个 IngressClass 上增加 ingressclass.kubernetes.io/is-default-class: "true"，让没有指定类的 Ingress 获得默认类。这个设置适合单控制器集群，或者组织已经明确规定“未写类名的对象都归某个入口层”的场景。

apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: public-nginx
  annotations:
    ingressclass.kubernetes.io/is-default-class: "true" # 只保留一个明确默认类
spec:
  controller: k8s.io/ingress-nginx # 仍然要与控制器监听值一致

不要把默认类当成多控制器路由规则。Kubernetes 文档指出，如果集群中恰好有一个默认 IngressClass，无类 Ingress 才能获得这个默认选择；同时标记多个默认类会让结果不再清晰。多控制器场景仍建议显式填写 ingressClassName，这样代码审查和迁移时都能看见真实归属。

旧 annotation 迁移时要避免两套配置互相打架

kubernetes.io/ingress.class 是旧的选择方式，新的 Ingress API 推荐使用 spec.ingressClassName。迁移旧清单时，不要只把字段追加上去就结束；还要检查旧 annotation 是否仍存在、控制器版本如何处理两者同时出现，以及是否有模板默认值覆盖了新字段。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: legacy-shop
  annotations:
    # 旧资源可先保留用于兼容，但新模板不要继续依赖它
    kubernetes.io/ingress.class: public-nginx
spec:
  ingressClassName: public-nginx # 迁移后的明确绑定字段
  rules: [] # 示例只展示类选择，业务路由按实际服务补全

对新建对象，优先只保留 spec.ingressClassName。对存量对象，先按控制器文档确认兼容行为，再分批修改，并把“类名、控制器值、是否默认”放进同一份部署记录。这样排查时能区分是对象没有选择类，还是类选择了但没有控制器认领。

用资源字段和控制器日志核对选择结果

发布后先核对资源关系，再看控制器日志。下面的命令只做配置观察，不依赖访问业务域名：

# 列出所有 IngressClass，确认名称、默认标记和 controller value
kubectl get ingressclass -o custom-columns=NAME:.metadata.name,CONTROLLER:.spec.controller,DEFAULT:.metadata.annotations.ingressclass\.kubernetes\.io/is-default-class

# 查看目标 Ingress 实际引用了哪个类
kubectl get ingress checkout-public -n shop -o jsonpath='{.spec.ingressClassName}{"\n"}'

# 查看控制器是否为该对象生成了状态或事件
kubectl describe ingress checkout-public -n shop

核对时可以按这个顺序判断：

1. Ingress 的 ingressClassName 是否拼写成现有 IngressClass 的 metadata.name。
2. 该 IngressClass 的 spec.controller 是否与目标控制器的监听配置完全一致。
3. 控制器是否在自己的命名空间或日志中看到该对象，并产生对应事件或状态变化。
4. 如果对象没有类名，集群是否只有一个明确默认 IngressClass。
5. 如果同时存在旧 annotation，是否按照当前控制器文档处理，而不是凭经验推断优先级。

把选择结果写成一张小决策表

最终可以把规则压缩成一句话：用 IngressClass 名称表达“应用选择谁”，用 spec.controller 表达“谁会认领它”，用 ingressClassName 把两者明确连接起来。如果集群只有一个控制器，默认类是兼容手段；如果集群有多个控制器，显式类名才是长期可维护的配置。

常见问题

IngressClass 的 name 和 spec.controller 应该写成同一个值吗？

不要求相同。name 是 Ingress 引用的资源名，controller 是实现识别的标识；只要 IngressClass 被目标控制器支持且两边配置一致即可。

为什么 Ingress 已经创建，却没有控制器处理？

优先检查 ingressClassName 是否引用了不存在的类、IngressClass 的 spec.controller 是否与控制器监听值不一致，以及旧 annotation 是否造成了实现差异。

两个 IngressClass 都能用，能不能都标记为默认？

不建议。默认类应保持唯一，否则无类 Ingress 的归属不清；需要在多个控制器之间选择时，应在对象上显式写 ingressClassName。

只部署一个控制器还需要写 ingressClassName 吗？

生产模板仍建议写。显式字段让资源的归属可读，也能降低未来引入第二个控制器或迁移入口层时的改动范围。

官方参考

• Kubernetes Ingress Controllers：https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/
• Kubernetes IngressClass API：https://kubernetes.io/docs/reference/kubernetes-api/networking/ingress-class-v1/
• Ingress-NGINX Multiple Ingress Controllers：https://kubernetes.github.io/ingress-nginx/user-guide/multiple-ingress/
• Ingress-NGINX CLI Arguments：https://kubernetes.github.io/ingress-nginx/user-guide/cli-arguments/
• Traefik Kubernetes Ingress：https://doc.traefik.io/traefik/providers/kubernetes-ingress/