Ingress NGINX Controller 迁移 Kubernetes 1.22 完全指南IngressClass 与networking.k8s.io/v1迁移实战【免费下载链接】ingress-nginxIngress NGINX Controller for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/in/ingress-nginx本文是一份面向 Ingress NGINX Controller 用户的 Kubernetes 1.22 迁移 FAQ 实战指南核心讲解 IngressClass 资源、.spec.ingressClassName字段、废弃的kubernetes.io/ingress.class注解以及--watch-ingress-without-class与--controller-class等关键启动参数在多控制器场景下的行为。读完本文你将能判断自己的集群属于哪一种迁移场景并据此完成 IngressClass 的创建、默认类的设置、旧 Ingress 对象的接管配置以及多控制器共存时的类名隔离方案。适用前提本文内容以当前仓库ingress-nginx controller 1.x的实现为准针对运行 Kubernetes 1.22 以下版本、计划升级到 1.22 且正在使用 Ingress 对象的用户。为什么 Kubernetes 1.22 迁移与 IngressClass 息息相关在 Kubernetes 1.22 之前默认安装的 ingress-nginx controller 并不强制要求存在 IngressClass 对象控制器可以仅凭注解即可工作。而从 ingress-nginx controller 1.0.0 版本起IngressClass 对象成为必需。在集群中存在多个 ingress-nginx controller 实例时所有 controller 实例都必须清楚自己负责处理哪些 Ingress 对象。Ingress 的ingressClassName字段正是让控制器得知这一归属关系的方式。简而言之IngressClass 是 Kubernetes 的一等资源用来声明一类 IngressIngress 通过spec.ingressClassName引用某个 IngressClassIngressClass 的spec.controller字段决定由哪个控制器实现该类 Ingresscontroller 通过--controller-class启动参数声明自己监听哪个 controller 类名两者必须完全一致才会被纳入处理。查看 IngressClass 资源的结构可以使用kubectl explain ingressclass输出概要如下以 Kubernetes 官方 API 文档描述为准KIND: IngressClass VERSION: networking.k8s.io/v1 DESCRIPTION: IngressClass represents the class of the Ingress, referenced by the Ingress Spec. The ingressclass.kubernetes.io/is-default-class annotation can be used to indicate that an IngressClass should be considered default. When a single IngressClass resource has this annotation set to true, new Ingress resources without a class specified will be assigned this default class. FIELDS: apiVersion string APIVersion defines the versioned schema of this representation of an object. kind string Kind is a string value representing the REST resource this object represents. metadata Object Standard objects metadata. spec Object Spec is the desired state of the IngressClass.其中spec对象包含controller控制器类名必填与可选的parameters关联的资源配置例如 ConfigMap 引用。是什么导致了这次行为变化主要有两个原因理解它们有助于判断迁移时可能遇到的现象。原因一废弃 Ingress API 版本的移除在 Kubernetes 1.21 及之前可以使用以下已废弃版本的 Ingress API 创建 Ingress 资源extensions/v1beta1networking.k8s.io/v1beta1此时虽然会收到弃用提示但 Ingress 资源仍能成功创建。从Kubernetes 1.22 起只能通过稳定版networking.k8s.io/v1API 访问 Ingress旧的 beta 版本 API 被彻底移除。这意味着任何仍以旧 apiVersion 编写的 Ingress 清单在 1.22 集群中都将无法通过 API Server 的校验。原因二升级后既有 Ingress 对象可能出现不符合预期的情况如果你已经运行着 ingress-nginx controller随后将 Kubernetes 升级到 1.22可能存在多种场景导致既有 Ingress 对象不再按预期工作。本文后续的 FAQ 小节正是按使用场景逐一给出的排查与修复方案请对照自己的使用场景处理。什么是ingressClassName字段ingressClassName是 Ingress 对象 spec 中的一个字段用于引用集群范围内的 IngressClass 资源。查看其定义kubectl explain ingress.spec.ingressClassNameKIND: Ingress VERSION: networking.k8s.io/v1 FIELD: ingressClassName string DESCRIPTION: IngressClassName is the name of the IngressClass cluster resource. The associated IngressClass defines which controller will implement the resource. This replaces the deprecated kubernetes.io/ingress.class annotation. For backwards compatibility, when that annotation is set, it must be given precedence over this field. The controller may emit a warning if the field and annotation have different values. Implementations of this API should ignore Ingresses without a class specified. An IngressClass resource may be marked as default, which can be used to set a default value for this field.需要特别强调.spec.ingressClassName字段的行为优先级高于已废弃的kubernetes.io/ingress.class注解。这不仅是 API 层面的约定也直接体现在当前仓库的实现中——internal/ingress/controller/store/store.go的GetIngressClass函数store.go正是按如下顺序判断 Ingress 归属若ing.Spec.IngressClassName非空则到 IngressClass lister 中按名称取出对应类返回其名称否则回退检查kubernetes.io/ingress.class注解若注解值与控制器配置的AnnotationValue默认nginx不一致则返回错误ingress class annotation is not equal to the expected by Ingress Controller否则若开启WatchWithoutClass则以保留的_通配名接受该 Ingress都不满足时返回错误ingress does not contain a valid IngressClass。场景一集群中只有一个 Ingress Controller如果你的集群中 ingress-nginx controller 是唯一的 Ingress 控制器应当在 IngressClass 上添加注解ingressclass.kubernetes.io/is-default-class这样任何新建的、未显式指定 class 的 Ingress 对象都会自动归属到这个默认 IngressClass。通过 Helm 启用默认类使用官方 Helm Chart 时在 values 文件中设置controller: ingressClassResource: enabled: true default: trueingressClassResource.default为true时模板会在生成的 IngressClass 上写入默认类注解相关逻辑见 charts/ingress-nginx/templates/controller-ingressclass.yamlingressclass.kubernetes.io/is-default-class: true。处理遗留的旧 Ingress 对象如果集群中还存在大量未设置 IngressClass 的旧 Ingress 对象可以从以下方案中选择一种或多种手动设置字段在自有 Ingress 资源清单中为每个 Ingress 显式写入.spec.ingressClassName字段重建接管先将 IngressClass 的ingressclass.kubernetes.io/is-default-class注解置为true再重新创建这些 Ingress 对象使其被自动指派默认类开启无类监听以--watch-ingress-without-classtrue启动 ingress-nginx controller让控制器同时监听未设置ingressClassName字段的 Ingress。使用 Helm 时对应配置为.controller.watchIngressWithoutClass: true。官方推荐的 IngressClass 创建示例如下--- apiVersion: networking.k8s.io/v1 kind: IngressClass metadata: labels: app.kubernetes.io/component: controller name: nginx annotations: ingressclass.kubernetes.io/is-default-class: true spec: controller: k8s.io/ingress-nginx然后在 Ingress 对象中补充spec.ingressClassName: nginx字段。示例中spec.controller取值为k8s.io/ingress-nginx这与仓库中定义的默认控制器类名常量完全一致见 ingressclass.go 中的DefaultControllerName k8s.io/ingress-nginx。场景二集群中有大量未配置 class 的 Ingress 对象如果集群中未配置 ingressClass 的 Ingress 对象数量很大逐一修改清单不现实此时可以直接以--watch-ingress-without-classtrue运行控制器。认识--watch-ingress-without-class标志这是传给nginx-ingress-controller可执行文件的启动参数。它在 Deployment 的容器参数中呈现如下# ... args: - /nginx-ingress-controller - --watch-ingress-without-classtrue - --controller-classk8s.io/ingress-nginx # ... # ...从源码看该标志在 pkg/flags/flags.go 中定义默认值为false语义为定义 Ingress Controller 是否也应该监听未指定 IngressClass 或注解的 Ingress。启用后控制器对既无ingressClassName又无kubernetes.io/ingress.class注解的 Ingress会以_通配名接受见 store.go。在 Helm Chart 中该标志由values.yaml的.controller.watchIngressWithoutClass控制默认false见 values.yaml并由 _params.tpl 注入到容器参数中controller: watchIngressWithoutClass: true仓库的 CI 配置 charts/ingress-nginx/ci/controller-ingressclass-values.yaml 也展示了该参数的组合用法可作参考。需要注意该标志默认关闭是因为同时开启会带来多控制器归属冲突的风险见场景四。场景三集群中已有多个 Controller 且正在使用旧注解如果集群中运行着多个 Ingress 控制器且你已经在使用kubernetes.io/ingress.class注解——这没有问题该机制仍然可以继续工作但我们强烈建议你先做测试验证。虽然kubernetes.io/ingress.class已废弃但 ingress-nginx controller 仍然理解这个注解。仓库中保留了该注解的常量定义IngressKey kubernetes.io/ingress.class见 ingressclass.go且GetIngressClass在未设置ingressClassName时会回退检查该注解。如果希望遵循良好实践仍建议逐步迁移到 IngressClass 与.spec.ingressClassName字段。场景四集群中有多个 Controller 且希望使用新 API在此场景下需要创建多个 IngressClass示例见场景一。请注意 IngressClass 的匹配机制非常精确必须让 IngressClass 的.spec.controller值与控制器启动参数--controller-class的值完全一致。假设集群中存在三个 IngressClassIngressClassingress-nginx-one.spec.controller为example.com/ingress-nginx1IngressClassingress-nginx-two.spec.controller为example.com/ingress-nginx2IngressClassingress-nginx-three.spec.controller为example.com/ingress-nginx1私有使用时也可以使用不含/的控制器名例如ingress-nginx1。部署多个 ingress 控制器时--controller-class参数需要相应调整Ingress-Nginx A配置使用控制器类名example.com/ingress-nginx1Ingress-Nginx B配置使用控制器类名example.com/ingress-nginx2当一个 Ingress 对象将ingressClassName设置为ingress-nginx-two时只有监听example.com/ingress-nginx2控制器类的控制器才会处理它。在上面的配置中Ingress-Nginx B 将负责服务该对象而 Ingress-Nginx A 会忽略它。请记住如果以--watch-ingress-without-classtrue启动 Ingress-Nginx B它将同时接管以下四类 Ingress未设置任何ingressClassName的 Ingress已废弃注解kubernetes.io/ingress.class的值与--ingress-class参数值匹配的 Ingress引用了任何spec.controller与--controller-class配置一致的 IngressClass 的 Ingress组合情形Ingress-Nginx B 以--watch-ingress-without-classtrue启动、Ingress-Nginx A 以--watch-ingress-without-classfalse启动属于受支持的配置反之如果同一集群的两个 ingress-nginx controller 都以--watch-ingress-without-classtrue运行极有可能产生归属冲突应避免。底层判断依据可在GetIngressClass的实现中看到它优先处理ingressClassName再回退注解最后才在WatchWithoutClass开启时以_通配名兜底接受store.go。而控制器在校验失败时会打印 Warning 并跳过该 Ingresscontroller.go这正是下面排查场景的源码入口。日志报错ingress class annotation is not equal to the expected by Ingress Controller如果你在控制器日志中看到该错误很可能同时会看到对应的 Ingress 资源名称。该错误通常出现在 Ingress 清单中使用了废弃注解kubernetes.io/ingress.class且其值不等于控制器通过--ingress-class参数期望的值默认nginx的情况下。从源码可以确认该错误消息正是GetIngressClass在注解值不匹配时返回的store.go随后控制器会记录ignoring ingress ... based on annotation ...的 Warning 日志并跳过该 Ingresscontroller.go。推荐做法改用 Ingress 资源的.spec.ingressClassName字段来指定该 Ingress 所属 IngressClass 的名称而非继续依赖废弃注解。相关参数速查以下是本次迁移涉及的关键控制器启动参数均可在 pkg/flags/flags.go 中找到定义完整参数表见 docs/user-guide/cli-arguments.md。参数默认值说明--controller-classk8s.io/ingress-nginx本控制器满足的 Ingress Class Controller 值。Ingress 通过ingressClassName字段引用 IngressClass其.spec.controller必须与此值一致才会被监听--ingress-classnginx本控制器满足的 ingress class 名称对应废弃注解kubernetes.io/ingress.class。该参数已进入弃用流程--controller-class优先--watch-ingress-without-classfalse是否同时监听未设置 IngressClass 或注解的 Ingress--ingress-class-by-namefalse是否在按spec.controller匹配的同时也按 IngressClass 的.metadata.name匹配对应的 Helm values 配置项见 charts/ingress-nginx/values.yaml.controller.watchIngressWithoutClass与.controller.ingressClassByName以及.controller.ingressClassResource下的enabled、name、default、controllerValue、parameters等字段用于控制 IngressClass 资源的生成。迁移自检清单集群 API 版本已确认仅剩networking.k8s.io/v1Kubernetes 1.22旧的extensions/v1beta1、networking.k8s.io/v1beta1清单已改写已创建至少一个 IngressClass且spec.controller与控制器--controller-class完全一致单控制器集群已在 IngressClass 上设置ingressclass.kubernetes.io/is-default-class: trueHelm 对应.controller.ingressClassResource.default: true旧 Ingress 对象已补充.spec.ingressClassName或已确认--watch-ingress-without-classtrue与多控制器配置不存在归属冲突多控制器集群中各控制器的--controller-class互不相同且不存在两个控制器同时开启--watch-ingress-without-classtrue的情形日志中不再出现ingress class annotation is not equal to the expected by Ingress ControllerIngress 已纳入对应控制器处理。【免费下载链接】ingress-nginxIngress NGINX Controller for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/in/ingress-nginx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考