企业官网建设流程全解析

Ingress NGINX Controller v1.12.1 版本解析：安全修复、镜像重构与关键功能增强

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

一、版本概览

controller-v1.12.1 是 ingress-nginx 项目在 v1.12.0 之后发布的一个维护版本，发布于 2025 年 4 月。该版本的核心特征是"稳定为主、修修补补"，包含控制器安全修复、镜像构建流程重构、多个第三方组件版本升级，以及若干功能增强。

官方发布镜像（两个）：

chroot 镜像对应仓库中的 rootfs/Dockerfile-chroot，用于在受限的 chroot 环境中运行控制器。

版本升级要点（重要）：本版本将 Go 语言从 1.23.x 一路升级到v1.24.1（PR #12942 记录的版本为registry.k8s.io/ingress-nginx/nginx:v2.2.8。同时将依赖的kubectl客户端更新至 v1.32.2（PR #12856），并将 CI 环境中的 Kubernetes 集群版本提升至 v1.32.3（PR #13025）。

镜像构建流程重构（重点）：本版本有一个重要变化——将镜像构建迁移到AR（阿里云容器镜像服务）。相关 PR 包括：

• PR #12846：镜像迁移到 AR（1/2）
• PR #12849：镜像迁移到 AR（2/2）
• PR #12809：文档迁移到 AR

这是项目对镜像分发基础设施的一次调整。

二、安全修复（Controller: Several security fixes）

本版本最重要的变化是Controller: Several security fixes（PR #13069）。虽然 changelog 未逐一列出修复的具体 CVE 编号，但结合同期合并的改动可以看出安全加固的方向：

1. 注解换行符拒绝（Annotations: Deny newlines）（PR #12667）：ingress-nginx 的注解中，configuration-snippet、server-snippet、auth-snippet等允许注入任意 NGINX 配置。如果用户能控制这些注解的内容，注入换行符可以拼出额外的配置指令，从而执行任意 Lua 代码或篡改 NGINX 配置。此改动在注解解析层面对换行符进行了拦截，防止通过注解进行配置注入攻击。

2. 依赖漏洞修复：本版本升级了大量 Go 依赖，包括golang.org/x/crypto（从 0.31.0 到 0.36.0）、google.golang.org/grpc（从 1.69.2 到 1.71.0）、github.com/prometheus/client_golang、github.com/opencontainers/runc等，其中部分升级是针对已公开的安全漏洞。

3. ModSecurity 更新：NGINX 侧同步更新了 ModSecurity（PR #12915），修复 Web 应用防火墙（WAF）引擎层面的已知问题。

建议：如果你在生产环境使用 v1.12.0 及以下版本，应尽快升级到 v1.12.1 以获取上述安全修复。升级前请先阅读 docs/deploy/upgrade.md 中的升级指南。

三、关键功能增强

3.1 ExternalName Service 的 DNS 问题修复

PR #12951 fix DNS issues with unresolvable backends with ExternalName是本版本值得关注的功能修复之一。

什么是 ExternalName Service

在 Kubernetes 中，Service的type: ExternalName会将 Service 映射到集群外部的 DNS 名称，而不是选择 Pod 作为后端。例如：

apiVersion: v1 kind: Service metadata: name: external-db namespace: default spec: type: ExternalName externalName: db.example.com ports: - port: 5432

修复的底层逻辑

从 internal/ingress/controller/endpointslices.go 的getEndpointsFromSlices函数可以看到，当 Service 类型为ExternalName时，控制器会直接将s.Spec.ExternalName作为上游服务器地址：

// ExternalName services if s.Spec.Type == corev1.ServiceTypeExternalName { if ip := net.ParseIP(s.Spec.ExternalName); s.Spec.ExternalName == "localhost" || (ip != nil && ip.IsLoopback()) { klog.Errorf("Invalid attempt to use localhost name %s in %q", s.Spec.ExternalName, svcKey) return upsServers } ... // if the externalName is not an IP address we need to validate is a valid FQDN if net.ParseIP(s.Spec.ExternalName) == nil { externalName := strings.TrimSuffix(s.Spec.ExternalName, ".") if errs := validation.IsDNS1123Subdomain(externalName); len(errs) > 0 { klog.Errorf("Invalid DNS name %s: %v", s.Spec.ExternalName, errs) return upsServers } } return append(upsServers, ingress.Endpoint{ Address: s.Spec.ExternalName, Port: fmt.Sprintf("%v", targetPort), }) }

可以看到，控制器对externalName做了两类校验：拒绝localhost和回环 IP，以及验证 DNS 名称是否为合法的 DNS-1123 子域（internal/ingress/controller/endpointslices.go）。

v1.12.1 修复的问题：当 ExternalName 指向的 DNS 名称无法解析（例如内部 DNS 记录被删除、或者外部域名的 DNS 解析暂时不可用）时，NGINX 无法解析后端地址，导致请求全部返回 502/504。此次修复调整了控制器对不可解析 ExternalName 后端的处理方式，避免因单个不可解析的后端拖垮整个 upstream 的健康状态。

另外需要说明的是，控制器提供了disable-service-external-name配置选项（对应源码中的DisableServiceExternalName字段，见 internal/ingress/controller/controller.go），当设置为true时，Ingress 引用的 ExternalName Service 会被直接拒绝：

// Ingress with an ExternalName Service and no port defined for that Service if svc.Spec.Type == apiv1.ServiceTypeExternalName { if n.cfg.DisableServiceExternalName { klog.Warningf("Service %q of type ExternalName not allowed due to Ingress configuration.", svcKey) return upstreams, nil } ... }

3.2 自定义错误页支持多种 MIME 类型

PR #13006 Custom Error Pages: Accept first of many MIME types改进了自定义错误页的行为。

自定义错误页是 ingress-nginx 的一项功能，通过custom-http-errors配置指定需要返回自定义错误页的 HTTP 状态码列表，当后端返回这些状态码时，由 images/custom-error-pages 镜像中的错误页服务接管响应。

从 images/custom-error-pages/rootfs/main.go 的源码可以看到，错误页服务会根据请求头中的Content-Type来决定返回 HTML、JSON 还是其他格式的错误页：

format := r.Header.Get(FormatHeader) if format == "" { format = defaultFormat log.Printf("format not specified. Using %v", format) } // if multiple formats are provided, use the first one index := strings.Index(format, ",") if index != -1 { format = format[:index] } cext, err := mime.ExtensionsByType(format) if err != nil { ... }

此修复解决的问题：当Content-Type请求头包含多个 MIME 类型（例如application/json, text/html）时，旧版本可能无法正确匹配到错误页文件；修复后错误页服务会接受并处理多种 MIME 类型中的第一个，从而更可靠地返回匹配格式的错误页。

3.3 全局外部认证注解文档修正

PR #12978 Docs: Useenable-global-authannotation instead of non-existing ConfigMap option是一个文档修正。

实际用法：当在 Ingress NGINX ConfigMap 中设置了global-auth-url（全局外部认证地址）时，控制器默认会将所有请求重定向到该认证服务。如果某个 Ingress 不希望启用全局认证，可以使用注解nginx.ingress.kubernetes.io/enable-global-auth: "false"单独关闭。

从源码 internal/ingress/annotations/authreqglobal/main.go 可以看到注解的默认值逻辑：

enableGlobalAuthAnnotation = "enable-global-auth" ... enableGlobalAuth, err := parser.GetBoolAnnotation(enableGlobalAuthAnnotation, ing, a.annotationConfig.Annotations) if err != nil { enableGlobalAuth = true // 默认值为 true }

即默认值为"true"，只有显式设置为"false"才会禁用。详细的注解说明可以查看 docs/user-guide/nginx-configuration/annotations.md 的 "Global External Authentication" 一节。

3.4 自定义头部变更触发配置重载

PR #12652 Annotations: Reload on custom header changes修复了一个配置同步问题：当通过注解（如proxy-set-headers、add-headers等）配置的自定义头部发生变化时，控制器能够正确触发 NGINX 配置重载，确保头部配置的修改能立即生效。

四、镜像构建与工具链升级

4.1 NGINX 基础镜像升级

本版本将NGINX_BASE从 v1.2.0 升级到v1.2.1（PR #13044 中记录的版本为registry.k8s.io/ingress-nginx/nginx:v2.2.8@sha256:1c31dc6ffa7427b7a2128ce66e356f3b0ff743b90494272612b1742c9326b8b2。

基础镜像的构建文件位于 images/nginx/rootfs/Dockerfile，其中包括 OpenTelemetry 模块升级（PR #12631）、ModSecurity 模块更新（PR #12915）以及引号对齐（PR #12673）等改动。

4.2 测试与开发工具链升级

• Test Runner升级到 v1.3.1（PR #13048 目录
• KIND集群镜像更新到 v1.32.3（PR #13029）
• kubectl客户端升级到 v1.32.2（PR #12856）
• Kube Webhook CertGen升级（PR #13066 目录

4.3 Go 依赖升级

本版本升级了大量 Go 依赖，主要涉及 go.mod。值得关注的升级包括：

• github.com/opencontainers/runc1.2.5 → 1.2.6（PR #13033）
• golang.org/x/crypto0.31.0 → 0.36.0
• google.golang.org/grpc1.69.2 → 1.71.0
• github.com/prometheus/client_golang1.20.5 → 1.21.0
• github.com/prometheus/common0.61.0 → 0.63.0
• sigs.k8s.io/controller-runtime0.19.4 → 0.20.1
• github.com/spf13/cobra1.8.1 → 1.9.1

其中golang.org/x/crypto、runc等的升级通常与安全公告相关。

五、文档与配置改进

• 限流语义澄清（PR #12715 的 Rate Limiting 章节中。

• 裸金属部署文档改进（PR #12744 的部署说明。

• values.yaml 链接更新（PR #12960 的链接。

• 文档代码复制按钮（PR #12805）：站点文档启用了代码复制按钮，提升阅读体验。

六、Helm Chart 同步说明

与控制器 v1.12.1 配套的 Helm Chart 版本为4.12.1，对应的变更记录见 charts/ingress-nginx/changelog/helm-chart-4.12.1.md。Chart 的配置模板位于 charts/ingress-nginx/templates，所有可配置项定义在 charts/ingress-nginx/values.yaml。

部署时可以通过以下命令指定版本：

helm upgrade --install ingress-nginx ingress-nginx \ --repo https://kubernetes.github.io/ingress-nginx \ --namespace ingress-nginx --create-namespace \ --version 4.12.1

七、升级建议与注意事项

1. 安全优先：如果当前使用 v1.12.0 或更早版本，建议尽快升级到 v1.12.1，以获得安全修复（注解换行符拦截、ModSecurity 更新、依赖漏洞修复）。
2. 镜像地址：v1.12.1 的官方镜像位于registry.k8s.io/ingress-nginx/，包含controller和controller-chroot两个变体，生产环境推荐使用带 digest 的固定引用方式。
3. ExternalName 用户注意：如果你的 Ingress 依赖 ExternalName Service 指向外部服务，v1.12.1 修复了不可解析后端的 DNS 问题，升级后应观察上游健康检查与错误率变化。
4. 限流配置复核：升级后请确认限流注解（limit-rps、limit-rpm、limit-connections等）的配置是否符合预期——这些限制是按副本计算的，多副本部署时实际生效的限流值会乘以副本数。
5. 完整变更对比：完整变更列表可查看 Changelog.md，或通过controller-v1.12.0...controller-v1.12.1的 compare 视图查看所有合并的 PR。

参考

• 版本变更记录：changelog/controller-1.12.1.md
• 控制器源码：internal/ingress/controller/controller.go、internal/ingress/controller/endpointslices.go
• 注解实现：internal/ingress/annotations/authreqglobal/main.go
• 自定义错误页：images/custom-error-pages/rootfs/main.go
• 注解与 ConfigMap 文档：docs/user-guide/nginx-configuration/annotations.md、docs/user-guide/nginx-configuration/configmap.md

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