Ingress NGINX Controller v1.12.6 发布解析路径校验、Auth TLS 重定向与可靠性修复【免费下载链接】ingress-nginxIngress NGINX Controller for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/in/ingress-nginx导读本文基于 changelog/controller-1.12.6.md 展开系统梳理 Ingress NGINX Controller v1.12.6含配套 Helm Chart v4.12.6这一补丁版本的完整变更清单并结合仓库源码深入解读三项对生产环境有直接影响的修复Exact/Prefix路径中允许.字符、AuthTLS 注解支持命名重定向、以及nginx_ingress_controller_config_last_reload_successful指标的可靠性修复。读完本文你将掌握 v1.12.6 的镜像清单、核心变更的底层实现原理以及升级评估要点。一、版本概况与镜像清单v1.12.6 是 ingress-nginx 在 v1.12 稳定分支上的一个维护补丁版本主要包含依赖升级、CI/测试基础镜像刷新、文档修正与若干针对性修复不包含破坏性变更无⚠️标记条目。发布时提供两个官方镜像均托管在 Kubernetes 官方镜像仓库registry.k8s.io镜像完整引用标准控制器registry.k8s.io/ingress-nginx/controller:v1.12.6sha256:c371fbf42b4f23584ce879d99303463131f4f31612f0875482b983354eeca7e6chroot 控制器registry.k8s.io/ingress-nginx/controller-chroot:v1.12.6sha256:7ff9cdb081b18f9431b84d4c3ccd3db9d921ed5f5b7682a45f6a351bfc4ceed4生产环境建议始终通过 digestsha256:而不是 tag 引用镜像保证升级的可复现性与供应链可追溯性。其中controller-chroot镜像对应仓库根目录 rootfs/Dockerfile-chroot 与 rootfs/chroot.sh 所描述的运行方式将控制器进程置于 chroot 环境中以隔离文件系统访问。二、功能修复详解2.1 Ingresses允许Exact与Prefix路径中包含.#13800这是 v1.12.6 中对路由行为影响最直接的变更。在严格路径校验strict-validate-path-type开启后控制器会对PathType为Exact或Prefix的路径执行格式校验而此前的校验规则不允许路径中出现.字符。该校验的实现位于 internal/ingress/inspector/rules.go// validPathType enforces alphanumeric, -, _ , . and / characters. // The field (?i) turns this regex case-insensitive // The remaining regex says that the string must start with a / (^/) // the group [[:alnum:]\_\-\/\.]* says that any amount of characters (A-Za-z0-9), _, - , . and / // are accepted until the end of the line // Nothing else is accepted. validPathType regexp.MustCompile((?i)^/[[:alnum:]._\-/]*$)可以看到 v1.12.6 使用的正则(?i)^/[[:alnum:]._\-/]*$已经显式将.纳入允许字符集合[[:alnum:]._\-/]。该校验在 internal/ingress/inspector/inspector.go 的ValidatePathType函数中执行遍历Ingress.Spec.Rules下所有 HTTP 路径对PathType为Exact或Prefix的路径逐一匹配路径必须以/开头且只能包含字母数字、.、_、-、/ImplementationSpecific类型不受该正则约束因为该类型允许使用 Nginx 正则表达式如 rewrite 场景。本次变更的实际意义像/api/v1.2/status、/assets/app.min.js这类带点号的真实业务路径在使用Exact/Prefix语义时不再被误拦截。控制器在 internal/ingress/controller/controller.go 中依据cfg.StrictValidatePathType开关调用该校验。需要注意strict-validate-path-type的默认值为true见 internal/ingress/controller/config/config.go 与 config.go 的默认值定义因此绝大多数默认部署都会受此修复影响。若你需要在Exact/Prefix路径中使用正则等特殊语义应改用ImplementationSpecific类型。2.2 Annotations/AuthTLS允许命名重定向#13820auth-tls-error-page注解用于指定客户端证书校验失败时的跳转地址。v1.12.6 之前该注解的取值校验正则不接受named_location形式的 Nginx 命名位置引用本次变更扩展了该校验允许在注解中直接引用 Nginx 命名重定向。校验正则定义在 internal/ingress/annotations/authtls/main.govar ( authVerifyClientRegex regexp.MustCompile(^(on|off|optional|optional_no_ca)$) redirectRegex regexp.MustCompile(^([A-Za-z0-9_-]|((https?://)?[A-Za-z0-9\-.](:\d)?)?(/[A-Za-z0-9\-_.])*/?)$) )redirectRegex第一分支[A-Za-z0-9_-]即本次新增的命名重定向支持。该正则的校验语义为named_location直接引用 Nginx server 块内定义的命名 location如maintenance完整的 URL 或路径https?://host:port/path/协议、端口均为可选项。与校验配套AuthTLS 注解组在 internal/ingress/annotations/authtls/main.go 中统一登记包含auth-tls-secret、auth-tls-verify-client取值on|off|optional|optional_no_ca、auth-tls-verify-depth默认深度 1见 main.go、auth-tls-error-page、auth-tls-pass-certificate-to-upstream、auth-tls-match-cn。其中auth-tls-error-page的风险等级被标记为High因为其取值会影响重定向目标需要管理员严格审核auth-tls-secret与auth-tls-verify-client为Medium其余为Low。Parse函数main.go在解析auth-tls-secret时会通过allow-cross-namespace-resources配置默认关闭限制跨命名空间引用 Secret。典型用法nginx.ingress.kubernetes.io/auth-tls-secret: default/ca-secret nginx.ingress.kubernetes.io/auth-tls-verify-client: on nginx.ingress.kubernetes.io/auth-tls-error-page: auth-error配合 Nginx 配置中的命名 locationlocation auth-error { return 302 /login?reasonclient-cert-invalid; }2.3 Metrics修复nginx_ingress_controller_config_last_reload_successful#13859该指标用于标识最后一次配置 reload 是否成功是监控 Ingress 控制器健康状态的核心信号。v1.12.6 修复了该指标在某些失败场景下上报不准确的问题。指标定义位于 internal/ingress/metric/collectors/controller.goconfigSuccess: prometheus.NewGauge( prometheus.GaugeOpts{ Namespace: PrometheusNamespace, Name: config_last_reload_successful, Help: Whether the last configuration reload attempt was successful, ConstLabels: constLabels, }), configSuccessTime: prometheus.NewGauge( prometheus.GaugeOpts{ Namespace: PrometheusNamespace, Name: config_last_reload_successful_timestamp_seconds, Help: Timestamp of the last successful configuration reload., ConstLabels: constLabels, }),config_last_reload_successful布尔语义 Gauge1表示最近一次 reload 成功0表示失败config_last_reload_successful_timestamp_seconds最近一次成功 reload 的 Unix 时间戳用于计算距上次成功 reload 的时长判断控制器是否长期处于配置失败状态。同文件还定义了配套的 reload 计数指标nginx_ingress_controller_success、nginx_ingress_controller_errorscontroller.go以及语法检查计数nginx_ingress_controller_check_success、nginx_ingress_controller_check_errorscontroller.go共同构成完整的 reload 健康观测体系。这些指标通过 PrometheusGauge语义暴露可用于配置告警当config_last_reload_successful 0且持续较长时间时触发告警结合config_last_reload_successful_timestamp_seconds判断是否属于长时间未成功。注意自 v1.12.0 起--enable-metrics参数默认被关闭见 changelog/controller-1.12.0.md如需采集上述指标须在控制器启动参数中显式开启。指标采集与告警的整体用法可参考 docs/user-guide/monitoring.md 和 Grafana 面板 deploy/grafana/dashboards/nginx.json。三、安全与稳健性改进3.1 加固 socket 创建并校验错误码输入#13786该 PR 以 Security 为前缀属于安全加固类变更涉及两个方面加固 socket 创建收紧控制器进程创建 socket主要面向 TCP/UDP 代理与健康检查端口监听时的权限与行为降低被利用面校验错误码输入对接受外部输入的错误码HTTP 状态码等增加校验避免非法值进入配置渲染路径。这与仓库整体的安全基线一致——从 v1.12.0 起控制器默认开启--enable-annotation-validation并将allow-cross-namespace-resources默认关闭、annotations-risk-level默认降为High、strict-validate-path-type默认开启见 changelog/controller-1.12.0.md。升级到 v1.12.6 即继承上述默认安全策略。3.2 将废弃的wait.Poll*迁移为 context-aware 版本#13782作为 Chores 类技术债清理该变更将k8s.io/apimachinery中已废弃的wait.Poll、wait.PollImmediate等轮询函数迁移到wait.PollUntilContextTimeout、wait.PollUntilContextCancel等支持context.Context的等价实现。该迁移的意义在于新 API 在 Pod 终止、控制器关闭时能够通过 context 取消及时退出轮询避免 goroutine 泄漏与关闭延迟——这与仓库 internal/task/queue.go 中基于 context 的优雅退出机制相互配合。四、镜像、依赖与工具链升级4.1 NGINX 基础镜像v1.3.2#13837本次将 NGINX 基础镜像从 v1.3.11.12.5 引入升级到 v1.3.2。NGINX 基础镜像的构建配置位于 images/nginx/rootfs/Dockerfile版本号记录在 images/nginx/TAG。需要说明的是这里的版本号是 ingress-nginx 项目自定义的 NGINX 镜像发布序列与上游 Nginx 主版本号并不一一对应它承载控制器运行所需的 Nginx 运行时及其补丁补丁列表见 images/nginx/rootfs/patches。4.2 Helm Chart升级 Kube Webhook CertGen#13858配套 Chart 将准入 Webhook 证书生成工具kube-webhook-certgen升级到新版本该工具源码位于 images/kube-webhook-certgen/rootfs。它用于在控制器部署时自动生成与轮换 admission webhook 所需的 TLS 证书。在 Helm 部署中如需自定义证书生成行为可参考 Chart 的 charts/ingress-nginx/values.yaml 中controller.admissionWebhooks相关配置段。4.3 Go 依赖与工具链Go 依赖批量更新#13829、#13779与 v1.12.5 的 Go 1.24.6 工具链GOLANG_VERSION保持兼容的模块级升级测试框架 Ginkgo 升级到 v2.25.1#13817此前在 v1.12.5 周期已历经 v2.24.0 → v2.25.0Test Runner 基础镜像升级到 v1.4.2#13843对应 images/test-runner 目录GitHub Actions 依赖组升级#13826并将actions/checkout从 4.3.0 升级到 5.0.0#13797CI 集群升级到 Kubernetes v1.33.4#13777。这些升级共同保障了控制器二进制与 e2e 测试套件见 test/e2e在较新的 Kubernetes 版本与 Go 工具链下通过验证。五、测试与文档类变更启用 default backend 访问日志测试#13789在 e2e 套件中启用此前跳过的 default backend 访问日志断言default backend 相关实现可参考 charts/ingress-nginx/templates/default-backend-deployment.yaml增强 SSL Proxy e2e 测试#13784扩充 SSL 代理场景的覆盖移除datadogConfigMap 选项文档#13852同步清理文档中已不存在的配置项避免误导该变更印证了以 docs/user-guide/nginx-configuration/configmap.md 为权威配置参考的原则替换文档中的不换行空格UA0#13814与镜像版本刷新#13857等收尾工作。六、依赖更新一览除代码变更外v1.12.6 还包含以下自动化依赖更新PR内容#13826actions group 批量更新3 项#13797actions/checkout4.3.0 → 5.0.0#13795actions group 批量更新2 项七、升级建议与验证清单镜像引用升级时将controller与controller-chroot镜像 tag 或 digest 更新为第一节所列的 v1.12.6 版本生产环境优先使用 digest关注路径语义若此前因Exact/Prefix路径含.被校验拦截升级后可直接生效若仍被拦截检查是否误用了strict-validate-path-type与ImplementationSpecific的边界参考 internal/ingress/inspector/inspector_test.go 的测试用例验证指标采集确认--enable-metrics已开启升级后观察nginx_ingress_controller_config_last_reload_successful与nginx_ingress_controller_config_last_reload_successful_timestamp_seconds是否如实反映 reload 状态回归测试重点回归 AuthTLS 双向认证链路auth-tls-error-page指向命名 location 时、TCP/UDP 代理 socket 监听以及控制器滚动升级期间的优雅退出Chart 一致性使用 Helm 部署时确认kube-webhook-certgen升级后准入 Webhook 证书能够正常生成与轮换。v1.12.6 作为维护版本不引入破坏性变更但其中路径校验与指标修复直接影响生产路由与可观测性行为建议在非生产环境先行验证后再滚动升级。【免费下载链接】ingress-nginxIngress NGINX Controller for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/in/ingress-nginx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考