Ingress NGINX Controller v1.12.6 发布解析：路径校验、Auth TLS 重定向与可靠性修复

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：

生产环境建议始终通过 digest（@sha256:）而不是 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：允许命名重定向（#13820）

auth-tls-error-page注解用于指定客户端证书校验失败时的跳转地址。v1.12.6 之前，该注解的取值校验正则不接受@named_location形式的 Nginx 命名位置引用；本次变更扩展了该校验，允许在注解中直接引用 Nginx 命名重定向。

校验正则定义在 internal/ingress/annotations/authtls/main.go：

var ( 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 配置中的命名 location：

location @auth-error { return 302 /login?reason=client-cert-invalid; }

2.3 Metrics：修复nginx_ingress_controller_config_last_reload_successful（#13859）

该指标用于标识"最后一次配置 reload 是否成功"，是监控 Ingress 控制器健康状态的核心信号。v1.12.6 修复了该指标在某些失败场景下上报不准确的问题。

指标定义位于 internal/ingress/metric/collectors/controller.go：

configSuccess: 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：布尔语义 Gauge，1表示最近一次 reload 成功，0表示失败；
• config_last_reload_successful_timestamp_seconds：最近一次成功 reload 的 Unix 时间戳，用于计算"距上次成功 reload 的时长"，判断控制器是否长期处于配置失败状态。

同文件还定义了配套的 reload 计数指标nginx_ingress_controller_success、nginx_ingress_controller_errors（controller.go）以及语法检查计数nginx_ingress_controller_check_success、nginx_ingress_controller_check_errors（controller.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" 为前缀，属于安全加固类变更，涉及两个方面：

1. 加固 socket 创建：收紧控制器进程创建 socket（主要面向 TCP/UDP 代理与健康检查端口监听）时的权限与行为，降低被利用面；
2. 校验错误码输入：对接受外部输入的错误码（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.1（1.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.0）；
• Test Runner 基础镜像升级到 v1.4.2（#13843），对应 images/test-runner 目录；
• GitHub Actions 依赖组升级（#13826），并将actions/checkout从 4.3.0 升级到 5.0.0（#13797）；
• CI 集群升级到 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 为权威配置参考的原则；
• 替换文档中的不换行空格（U+A0）（#13814）与镜像版本刷新（#13857）等收尾工作。

六、依赖更新一览

除代码变更外，v1.12.6 还包含以下自动化依赖更新：

七、升级建议与验证清单

1. 镜像引用：升级时将controller与controller-chroot镜像 tag 或 digest 更新为第一节所列的 v1.12.6 版本，生产环境优先使用 digest；
2. 关注路径语义：若此前因Exact/Prefix路径含.被校验拦截，升级后可直接生效；若仍被拦截，检查是否误用了strict-validate-path-type与ImplementationSpecific的边界（参考 internal/ingress/inspector/inspector_test.go 的测试用例）；
3. 验证指标采集：确认--enable-metrics已开启，升级后观察nginx_ingress_controller_config_last_reload_successful与nginx_ingress_controller_config_last_reload_successful_timestamp_seconds是否如实反映 reload 状态；
4. 回归测试：重点回归 AuthTLS 双向认证链路（auth-tls-error-page指向命名 location 时）、TCP/UDP 代理 socket 监听以及控制器滚动升级期间的优雅退出；
5. Chart 一致性：使用 Helm 部署时，确认kube-webhook-certgen升级后准入 Webhook 证书能够正常生成与轮换。

v1.12.6 作为维护版本不引入破坏性变更，但其中路径校验与指标修复直接影响生产路由与可观测性行为，建议在非生产环境先行验证后再滚动升级。

【免费下载链接】ingress-nginxIngress NGINX Controller for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/in/ingress-nginx