ingress-nginx Helm Chart 4.3.0 版本解析迁移 EndpointSlices、参数化 Metrics 端口与关键变更详解【免费下载链接】ingress-nginxIngress NGINX Controller for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/in/ingress-nginx本文基于 ingress-nginx 仓库中的 Helm Chart 4.3.0 变更记录charts/ingress-nginx/changelog/helm-chart-4.3.0.md展开完整解读该版本的四项核心变更Kubernetes 版本支持范围的调整新增 v1.25、移除 v1.20/v1.21、控制器从 Endpoints 迁移到 EndpointSlices、metrics 端口名参数化、以及 admission webhook 多 annotations 的 YAML 格式修复并结合仓库源码与模板逐条给出实现证据帮助你理解这些变更背后的机制以及在升级该 Chart 时的注意点与验证方法。一、4.3.0 版本变更总览原变更记录列出如下要点引自 helm-chart-4.3.0.md新增对 Kubernetes v1.25.0 的支持同时引入对 EndpointSlices 的支持移除对 Kubernetes v1.20.0 与 v1.21.0 的支持迁移到 EndpointSlices对应 PR 8890kube-webhook-certgen 镜像 digest 更新对应 PR 9059Go 1.19.1 之后构建产物变化metrics 端口名参数化对应 PR 9046修复多个 annotations 场景下的 YAML 格式错误对应 PR 9104。这四条变更分别涉及「兼容性」「数据面正确性」「可观测性配置」「准入 Webhook 稳定性」下面逐条展开并在仓库中找到对应的源码与模板证据。二、Kubernetes 版本支持范围调整2.1 变更内容4.3.0 明确了两件事新增对 Kubernetes v1.25.0 的支持并伴随 EndpointSlices 能力EndpointSlices 自 Kubernetes 1.21 起稳定1.25 时代集群上已普遍可用这也是该版本把支持面推到 1.25 的基础移除对 v1.20.0 与 v1.21.0 的支持即低于这两个版本的老集群不再被该 Chart 覆盖。2.2 仓库中的证据当前仓库中 charts/ingress-nginx/Chart.yaml 声明了 Chart 对 Kubernetes 的最小版本约束apiVersion: v2 appVersion: 1.15.1 kubeVersion: 1.21.0-0 version: 4.15.1从源码结构看kubeVersion字段是 Helm 在安装/升级时对集群版本做前置校验的依据集群版本不满足约束时Helm 会在渲染前直接报错避免在低版本集群上安装一个依赖 EndpointSlices 等新 API 的 Chart。变更记录中「移除 v1.20/v1.21 支持」的表述与 Chart 的kubeVersion约束共同构成了版本兼容性的边界以当前仓库实际内容为准现行 Chart 的约束为1.21.0-0。实操提示升级到该版本前先确认集群kubectl version不低于 Chart 声明的最低版本若集群版本偏旧应选用与集群匹配的历史 Chart 版本而不是强行升级。三、迁移到 EndpointSlicesPR 8890这是 4.3.0 最重要的一项变更控制器获取 Service 后端端点的方式从传统的Endpoints对象迁移到了discovery.k8s.io/v1的EndpointSlice。3.1 为什么迁移Kubernetes 社区自 1.21 起将 EndpointSlices 作为 Endpoints 的演进替代方案规模优势单个 Endpoints 对象受对象大小限制大 Service 的端点必须拆分EndpointSlices 天然按分片组织每个分片有独立大小上限更适合大规模集群拓扑信息EndpointSlice 携带Hints.ForZones等拓扑提示为可用区级就近路由提供了数据基础。3.2 控制器侧的实现仓库中的核心实现在 internal/ingress/controller/endpointslices.go入口函数为getEndpointsFromSlices其处理逻辑可归纳为拉取分片通过getServiceEndpointsSlices(svcKey)按namespace/name获取该 Service 关联的全部 EndpointSlice端口匹配遍历每个分片的eps.Ports按协议reflect.DeepEqual(*epPort.Protocol, proto)与端口名port.Name *epPort.Name匹配出目标端口当分片未声明端口且 Service 的 targetPort 为数字时回退使用 Service 的TargetPort.IntVal拓扑感知过滤若存在 zone 提示且 Service 设置了trafficDistribution: PreferClose会检查每个端点的Hints.ForZones是否包含控制器所在 zone未包含的端点被跳过——只有当所有分片的端点都带 zone 提示时才启用该优化避免部分分片缺提示导致的路由偏差就绪过滤与去重ep.Conditions.Ready ! true的端点直接跳过用map[string]struct{}以host:port为键去重防止同一 Service 多个端口共享同一 targetPort 时产生重复 upstream。端点分片在控制器 store 层的存取实现于 internal/ingress/controller/store/endpointslice.goEndpointSliceLister.MatchByKey通过kubernetes.io/service-name标签过滤出属于目标 Service 的分片并处理了 Service 名过长导致分片名被截断前缀的匹配边界源码注释指向 issue 9240。store 接口中声明了对应的取数方法// GetServiceEndpointsSlices returns the EndpointSlices of a Service matching key. GetServiceEndpointsSlices(key string) ([]*discoveryv1.EndpointSlice, error)见 internal/ingress/controller/store/store.go 第 84-85 行配套的单测覆盖在 internal/ingress/controller/endpointslices_test.go包含多分片、端口名为空、数字 targetPort、zone 提示等场景store 层另有 internal/ingress/controller/store/endpointslice_test.go 验证按 Service 匹配分片的正确性。此外仓库还保留了 e2e 测试 test/e2e/endpointslices/ 用于真实集群验证。3.3 Chart 侧的 RBAC 配套迁移 EndpointSlices 必须同步放宽控制器的权限。当前仓库的模板中RBAC 已包含对discovery.k8s.io组下endpointslices资源list/watch/get的授权ClusterRolecharts/ingress-nginx/templates/clusterrole.yaml 第 92-99 行Rolenamespace 范围场景charts/ingress-nginx/templates/controller-role.yaml 第 86-93 行- apiGroups: - discovery.k8s.io resources: - endpointslices verbs: - list - watch - get升级要点从 4.2.x 升级到 4.3.0 时helm upgrade会更新 RBAC 对象若你使用了--set rbac.createfalse自管权限需要自行确认 ClusterRole/Role 中已加上discovery.k8s.io/endpointslices的读取权限否则控制器将无法发现后端端点Ingress 流量会异常。四、参数化 Metrics 端口名PR 90464.1 变更动机此前 Chart 中 metrics 端口的名称是写死的。参数化之后用户可以按自身环境例如某些平台对端口名的正则要求、或需要与既有监控体系的命名对齐自定义端口名而无需覆盖整个模板。4.2 配置项当前仓库的 charts/ingress-nginx/values.yaml 中定义如下约第 907-911 行metrics: port: 10254 portName: metrics # if this port is changed, change healthz-port: in extraArgs: accordingly enabled: false service:controller.metrics.port容器监听端口默认10254controller.metrics.portName容器端口/Service 端口的名称默认metrics本版本起可自定义注意注释中的提示若修改端口需同步调整extraArgs中的healthz-port。4.3 模板引用链portName在模板中被多处引用形成一条完整的引用链Deployment/DaemonSet 容器端口charts/ingress-nginx/templates/controller-deployment.yaml 与 charts/ingress-nginx/templates/controller-daemonset.yaml 中{{- if .Values.controller.metrics.enabled }} - name: {{ .Values.controller.metrics.portName }} containerPort: {{ .Values.controller.metrics.port }} protocol: TCP {{- end }}Metrics Servicecharts/ingress-nginx/templates/controller-service-metrics.yaml 中 Service 的port.name与targetPort均取portNametargetPort按名称指向容器端口这正是把名称参数化后仍能自洽的关键ServiceMonitorcharts/ingress-nginx/templates/controller-servicemonitor.yaml 中 Prometheus 抓取端点同样使用port: {{ .Values.controller.metrics.portName }}保证 Prometheus Operator 的抓取配置与端口名保持一致。使用示例helm install ingress-nginx ./charts/ingress-nginx \ --set controller.metrics.enabledtrue \ --set controller.metrics.portNameng-metrics安装后容器端口、Service 端口、ServiceMonitor 抓取端点都会统一使用ng-metrics。由于 Service 的targetPort与 ServiceMonitor 的port都按名称引用改名不会破坏链路。五、kube-webhook-certgen 镜像 digest 更新PR 90595.1 变更背景变更记录说明Go 1.19.1 之后kube-webhook-certgen镜像的构建产物发生了确定性变化原 digest 对应的产物不再适用因此需要更新 values 中固定镜像的 digest。该镜像用于 admission webhook 的证书自举Chart 在安装/升级时通过 Helm hook Job 运行kube-webhook-certgen create为ValidatingWebhookConfiguration生成 CA 与 TLS Secret。相关模板见 charts/ingress-nginx/templates/admission-webhooks/job-patch/job-createSecret.yaml其中容器参数为args: - create - --host{{ include ingress-nginx.controller.fullname . }}-admission,... - --namespace$(POD_NAMESPACE) - --secret-name{{ include ingress-nginx.admissionWebhooks.fullname . }}5.2 仓库证据当前 values 中的镜像配置位于 charts/ingress-nginx/values.yaml 第 852 行附近controller.admissionWebhooks.patch.image.image: ingress-nginx/kube-webhook-certgen并带 digest仓库内同时内置了该工具的源码与构建配置images/kube-webhook-certgen/含 README.md、构建 tag TAG 当前为v1.6.9以及 e2e 验证脚本 images/kube-webhook-certgen/hack/e2e.sh。实操提示digest 变化本身对用户透明helm upgrade会自动使用新 digest但若你的镜像源无法拉取新 digest 对应的产物离线/镜像仓库同步滞后createSecret hook Job 会失败进而影响 webhook 证书注入。遇到安装卡在 pre-install/pre-upgrade hook 时可优先检查该 Job 的日志。六、修复多 Annotations 的 YAML 格式错误PR 91046.1 问题4.3.0 之前当controller.admissionWebhooks.annotations配置了多个annotation 键值时渲染出的 YAML 存在格式错误可能导致helm install渲染失败或资源创建异常。6.2 修复方式修复后的模板采用「条件包裹 toYaml整体序列化 nindent统一缩进」的规范写法。以当前仓库的 charts/ingress-nginx/templates/admission-webhooks/job-patch/job-createSecret.yaml 第 7-12 行为例annotations: helm.sh/hook: pre-install,pre-upgrade helm.sh/hook-delete-policy: before-hook-creation,hook-succeeded {{- with .Values.controller.admissionWebhooks.annotations }} {{- toYaml . | nindent 4 }} {{- end }}同样的模式也出现在 charts/ingress-nginx/templates/admission-webhooks/validating-webhook.yaml 第 12-14 行等模板中。toYaml | nindent的组合保证了单条、多条 annotations 都能正确序列化键值中包含特殊字符时由 YAML 编码器处理引号与转义不再因手写拼接产生格式错误。验证方法本地渲染检查即可确认helm template test ./charts/ingress-nginx \ --set-json controller.admissionWebhooks.annotations{a:1,b:2,c:3} \ | yq select(.kind Job)渲染出的annotations块应为合法的 YAML 映射。七、升级与验证建议结合上述变更从 4.2.x 升级到 4.3.0或更新版本时的建议动作检查集群版本确认满足 Chart 的kubeVersion约束当前 Chart.yaml 为1.21.0-0且不落在已声明移除支持的版本上确认 RBAC 已包含 endpointslices 权限默认由 Chart 模板管理时helm upgrade自动生效自管 RBAC 时手动补充discovery.k8s.io/endpointslices的list/watch/get观察控制器日志升级后关注控制器日志中 EndpointSlices 相关的 Info/Warning如Getting Endpoints from endpointSlices for Service ...见 endpointslices.go 中的 klog 输出确认端点正常发现验证 Ingress 路由对关键 Ingress 执行kubectl get endpointslices -l kubernetes.io/service-namesvc与业务探活确认 upstream 端点符合预期若使用 metrics确认controller.metrics.portName修改后 Service 与 ServiceMonitor 渲染一致可用helm template预览若使用 admission webhook关注 createSecret/patchWebhook 两个 hook Job 是否正常完成。八、参考文件索引主题路径4.3.0 变更记录charts/ingress-nginx/changelog/helm-chart-4.3.0.mdChart 版本与 kubeVersion 约束charts/ingress-nginx/Chart.yamlEndpointSlices 端点解析internal/ingress/controller/endpointslices.goEndpointSlice store 层internal/ingress/controller/store/endpointslice.gostore 接口定义internal/ingress/controller/store/store.go见第 84-85 行GetServiceEndpointsSlicesEndpointSlices 单测internal/ingress/controller/endpointslices_test.goRBACClusterRole / Rolecharts/ingress-nginx/templates/clusterrole.yaml、charts/ingress-nginx/templates/controller-role.yamlmetrics 端口配置charts/ingress-nginx/values.yamlcontroller.metrics.port/portNamemetrics 模板引用charts/ingress-nginx/templates/controller-service-metrics.yaml、charts/ingress-nginx/templates/controller-servicemonitor.yamlwebhook 证书 Jobcharts/ingress-nginx/templates/admission-webhooks/job-patch/job-createSecret.yamlkube-webhook-certgen 工具源码images/kube-webhook-certgen/【免费下载链接】ingress-nginxIngress NGINX Controller for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/in/ingress-nginx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考