企业官网建设流程全解析

ingress-nginx controller v1.10.5 版本发布解读：镜像构建、多租户警告与关键指标修复全解析

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

导读

本文基于 ingress-nginx 官方仓库的 controller-v1.10.5 变更日志，系统解读该补丁版本的核心变更：包括多架构镜像构建策略（含 s390x 支持）、Go 与 NGINX 基础镜像版本升级、多租户安全警告、--watch-namespace使用说明，以及nginx_ingress_controller_ssl_expire_time_seconds指标的 namespace 修复。文章同时结合仓库源码（如 指标收集器实现、启动参数解析、Helm 模板）逐一印证各项变更的底层实现，帮助读者理解该版本在工程构建、测试与安全方面做了什么、为什么这么做。

说明：文中涉及的镜像 Digest、依赖版本均为 v1.10.5 发布时的快照；当前仓库已演进到更高版本（如NGINX_BASE已是 v2.2.8、Go 已是 1.26.1），引用当前源码仅用于印证 v1.10.5 所引入的机制与修复仍然存在且可验证。

一、版本定位与镜像产物

controller-v1.10.5 是 ingress-nginx v1.10.x 系列的一个补丁版本（patch release），发布于 Go 1.22 时代（该版本将 Go 升级到v1.22.8，PR #12093）。变更日志给出的官方镜像为：

registry.k8s.io/ingress-nginx/controller:v1.10.5@sha256:c84d11b1f7bd14ebbf49918a7f0dc01b31c0c6e757e0129520ea93453096315c registry.k8s.io/ingress-nginx/controller-chroot:v1.10.5@sha256:030a43bdd5f0212a7e135cc4da76b15a6706ef65a6824eb4cc401f87a81c2987

其中controller-chroot是 chroot 变体镜像，对应仓库根目录下的 rootfs/Dockerfile-chroot 与 chroot.sh。镜像的运行时版本信息由 version/version.go 中的RELEASE、COMMIT、REPO三个变量在构建期注入，控制器启动日志会输出形如NGINX Ingress controller / Release: v1.10.5 / Build: <commit>的信息，可通过kubectl logs快速核对部署的实际版本。

镜像的命名与归档规则由 magefiles/steps/release.go 中的发布流程生成，变更日志中的Images: Trigger ...条目即来自发布流水线中对各子镜像的构建触发。

二、多架构构建：s390x 的加入与回退

v1.10.5 的镜像构建变更记录了 s390x（IBM LinuxONE / Z 系列）架构的支持过程：

• Images: Build s390x controller.(#12128)：为 controller 镜像新增 s390x 架构构建；
• Images: Drop s390x.(#12139)：随后又移除了 s390x。

这一"加入又移除"的过程表明 s390x 支持在 CI 构建链中（cloudbuild.yaml 及子镜像目录中的构建配置）存在可用性问题而被回退。结合镜像定义可知，仓库通过 images/nginx/TAG 等 TAG 文件管理镜像版本，子镜像（e2e-test-echo、test-runner、custom-error-pages等）各自拥有独立的构建触发条目（如Images: Trigger e2e-test-echo build.#12142）。

对使用 s390x 架构集群的读者，这一点意味着：v1.10.5 最终发布产物不含 s390x 的 controller 镜像，部署前应通过docker manifest inspect registry.k8s.io/ingress-nginx/controller:v1.10.5确认目标架构的 manifest 是否可用。

三、版本升级：Go、NGINX 基础镜像与依赖

3.1 Go 工具链与 NGINX 基础镜像

• Go: Bump to v1.22.8.(#12093)：将编译 Go 工具链升级到 1.22.8，同时Go: Bump to v1.22.7.(#11969) 是更早的一次升级。注意当前仓库根目录的 GOLANG_VERSION 已为 1.26.1，这是仓库演进后的状态，v1.10.5 时代的工具链以 changelog 为准。
• Images: Bump NGINX_BASE to v0.1.0.(#12079) 与Images: Remove NGINX v1.21.(#12057)：NGINX_BASE指向 ingress-nginx 定制的 NGINX 基础镜像（仓库根目录的 NGINX_BASE 当前为 v2.2.8，对应 controller-v1.15.x 时代）。v1.10.5 将 NGINX 基础镜像升级到 v0.1.0 并移除 NGINX 1.21 分支，意味着 1.21 不再获得构建与测试覆盖，相关*.patch补丁从 images/nginx/rootfs/patches 体系中被淘汰。
• Images: Use latest Alpine 3.20 everywhere.(#11945)：各镜像的 rootfs 统一基于 Alpine 3.20，可从 rootfs/Dockerfile 及各子镜像 Dockerfile 验证。

3.2 主要依赖升级清单（节选）

此外还包括 kube-webhook-certgen（images/kube-webhook-certgen）的 Helm Chart 依赖升级（#12122）以及 OpenTelemetry C++ Contrib 的升级（#11950，与 docs/user-guide/third-party-addons/opentelemetry.md 描述的可观测性链路相关）。Dependabot 分组机制（actions group、go group、all group）的引入（#12037）使这类批量升级成为常规操作。

四、多租户安全警告：官方明确的使用边界

Docs: Add a multi-tenant warning.(#12098) 是本版本值得重点关注的文档变更。该警告的完整内容在 docs/deploy/hardening-guide.md 和 docs/faq.md 中均可找到原文：

Do not use in multi-tenant Kubernetes production installations. This project assumes that users that can create Ingress objects are administrators of the cluster.

其核心含义是：ingress-nginx 假设"能创建 Ingress 对象的用户"等同于集群管理员，因此不应在多租户生产集群中使用。理由在于控制面存在全局级与单 Ingress 级的配置项，一旦开启就可能跨租户越权。最典型的例子是 docs/user-guide/nginx-configuration/annotations.md 中关于nginx.ingress.kubernetes.io/auth-tls-secret类注解的说明：在多租户集群中，它可能让权限受限的用户读取集群内所有 Secret（参见 CVE-2021-25742）。

对运维者的实践指导：

• 若集群存在多个互不信任的租户，应评估其他隔离方案（如每租户独立 Ingress Controller + 独立命名空间，配合 RBAC 限制 Ingress 创建权限）；
• 对server-snippet、configuration-snippet、auth-tls-secret等高危注解，应通过 controller-configmap 中的allow-snippet-annotations: "false"等开关收紧。

五、--watch-namespace使用说明与参数互斥

Docs: Add note about --watch-namespace.(#11948) 补充了单命名空间监听模式的说明。该参数在源码 pkg/flags/flags.go 中定义：

watchNamespace = flags.String("watch-namespace", apiv1.NamespaceAll,

默认值为apiv1.NamespaceAll（即空字符串，监听全部命名空间）。与它配套的还有--watch-namespace-selector（pkg/flags/flags.go，按标签选择器监听命名空间）。关键约束在 pkg/flags/flags.go 中强制校验：

if *watchNamespace != "" && *watchNamespaceSelector != "" { return false, nil, fmt.Errorf("flags --watch-namespace and --watch-namespace-selector are mutually exclusive") } if *watchNamespaceSelector != "" { namespaceSelector, err = labels.Parse(*watchNamespaceSelector) ... }

即--watch-namespace与--watch-namespace-selector互斥，二者同时指定会直接报错退出。使用建议：

• 只想监听单个命名空间：--watch-namespace=my-app；
• 想按标签过滤多个命名空间：--watch-namespace-selector=environment=prod；
• 需要注意：监听范围缩小后，控制器不再处理范围外的 Ingress、Service 与 Secret，默认后端（default backend）等全局资源若位于范围外，可能影响其更新同步。

六、关键指标修复：ssl_expire_time_seconds的 namespace 修正

Metrics: Fix namespace in nginx_ingress_controller_ssl_expire_time_seconds.(#11985) 是本版本唯一直接的指标代码修复。该指标用于暴露证书过期时间（Unix 时间戳秒），其定义位于 internal/ingress/metric/collectors/controller.go：

sslExpireTime: prometheus.NewGaugeVec( prometheus.GaugeOpts{ Namespace: PrometheusNamespace, Name: "ssl_expire_time_seconds", Help: `Number of seconds since 1970 to the SSL Certificate expire. An example to check if this certificate will expire in 10 days is: "nginx_ingress_controller_ssl_expire_time_seconds < (time() + (10 * 24 * 3600))"`, }, sslLabelHost, ),

该指标带class、host、identifier、namespace、secret_name等标签（sslLabelHost标签集合），修复点在于标签中的namespace字段此前可能取错值，v1.10.5 将其修正为证书 Secret 所在的真实命名空间。测试用例 internal/ingress/metric/collectors/controller_test.go 中对该指标的期望输出为：

nginx_ingress_controller_ssl_expire_time_seconds{class="nginx",host="demo",identifier="abcd1234-100",namespace="secret-namespace",secret_name="secret-name"} 1.351807721e+09

运维告警示例（证书 10 天内过期告警）：

nginx_ingress_controller_ssl_expire_time_seconds < (time() + (10 * 24 * 3600))

使用该指标前请确认已通过 controller-configmap 开启证书指标采集（enable-ssl-chain-completion与 SSL 相关监听配置），并保证 Prometheus 拉取地址为控制器 metrics 端口（默认 10254，见 charts/ingress-nginx/README.md 的controller.metrics.service.servicePort）。

七、Helm Chart 改进与准入 Webhook 端口可配置

本版本 Chart 侧（对应 Helm Chart 3.26.0，见 charts/ingress-nginx/changelog/helm-chart-3.26.0.md）包含多项可验证的模板与测试改进：

7.1 新增controller.admissionWebhooks.service.servicePort

Chart: Implement controller.admissionWebhooks.service.servicePort.(#11933) 为准入 Webhook 的 Service 引入了可配置端口，模板实现在 charts/ingress-nginx/templates/admission-webhooks/validating-webhook.yaml：

port: {{ .Values.controller.admissionWebhooks.service.servicePort }}

该参数默认值为443（见 charts/ingress-nginx/README.md）。它解决了 Webhook Service 端口被写死为 443、导致在已占用 443 端口的环境无法安装的问题——现在可以在values.yaml中按需调整。

7.2 可用性测试与资源配置对齐

• Chart: Test controller.minAvailable & controller.maxUnavailable.(#12001)：为 controller-poddisruptionbudget.yaml 新增了针对 PDB 两个关键字段的单元测试；
• Chart: Align default backend PodDisruptionBudget.(#11998)：对齐默认后端（default-backend-deployment.yaml）的 PDB 行为；
• Chart: Improve default backend service account.(#11973)：完善默认后端 ServiceAccount 的模板与测试（default-backend-serviceaccount_test.yaml）；
• Chart: Add tests for PrometheusRule & ServiceMonitor.(#11888)：为 controller-prometheusrule.yaml 和 controller-servicemonitor.yaml 补齐测试；
• Chart: Extend image tests.(#12026) 与Chart: Improve CI.(#12029)：扩展镜像相关渲染测试并改进 Chart CI。

这些 Chart 测试均基于 Helm Chart 测试框架（charts/ingress-nginx/tests 下的*_test.yaml），渲染templates/*.yaml并对结果做断言。

八、注解解析与其余杂项修复

• Annotations: Allow commas in URLs.(#11886)：修复注解 URL 值中包含逗号时被错误拆分的问题。注解解析框架位于 internal/ingress/annotations/parser，所有注解（如auth-url、proxy-next-upstream等）经统一的Parser注册表处理，本修复保证带逗号参数的 URL 在进入 NGINX 配置模板前不被误截断。
• Docs: Add health check annotations for AWS.(#12021)：在 deploy/static/provider/aws 相关文档中补充 AWS 健康检查注解说明。
• Docs: Convert opentelemetry.md from CRLF to LF.(#12007)：修正 docs/user-guide/third-party-addons/opentelemetry.md 的行尾格式。
• Go: Sync go.work.sum.(#11876) 与Replace deprecated queue method.(#11858)：分别同步 Go workspace 校验和、替换已废弃的队列方法（internal/task/queue.go）。
• Auto-generate annotation docs.(#11835)：注解文档改为自动生成，对应 hack/update-annotation-doc.sh 与 hack/verify-annotation-docs.sh 的流水线，保证 docs/user-guide/nginx-configuration/annotations.md 与源码中的注解定义始终同步。
• Update maxmind post link about geolite2 license changes.(#11880)：更新 MaxMind GeoLite2 许可变更的参考链接（涉及 internal/nginx/maxmind.go 使用的 GeoIP 数据库说明）。
• CI: Grant checks write permissions to E2E Test Report.(#11884)、GitHub: Improve Dependabot.(#12037)：均为 CI/GitHub Actions 层面的工程化改进。

九、测试与构建基线的整体升级

v1.10.5 同步升级了 e2e 测试工具链镜像：

其中 e2e-test-echo 用于 e2e 测试中的回显服务（test/e2e 下大量用例依赖它验证请求头、路径重写等行为），test-runner 对应 images/test-runner（其 TAG 文件记录了当前版本）。e2e 测试的完整入口可见 test/e2e/e2e_test.go 与 test/e2e/run-e2e-suite.sh。

十、升级建议与总结

controller-v1.10.5 是一个以"构建与工程化"为主的补丁版本，无破坏性 API 变更，升级风险低。升级时建议：

1. 使用日志给出的固定 Digest 拉取镜像，保证供应链可复现：registry.k8s.io/ingress-nginx/controller:v1.10.5@sha256:c84d...；
2. 升级前确认集群 CPU 架构（x86_64 / arm64）在发布 manifest 覆盖范围内（s390x 已回退）；
3. 若部署环境 443 端口被占用，可利用本次新增的controller.admissionWebhooks.service.servicePort调整 Webhook 端口；
4. 升级后检查nginx_ingress_controller_ssl_expire_time_seconds的namespace标签是否符合预期，并核对 Prometheus 告警表达式；
5. 多租户集群务必阅读 docs/deploy/hardening-guide.md 的警告并评估隔离方案。

完整变更对比可见 changelog 中给出的 controller-v1.10.4 → controller-v1.10.5 的提交范围，以及本仓库根目录的 Changelog.md 与其他历史版本记录（changelog 目录）。对于希望跟进每个版本镜像、参数与修复细节的读者，changelog/controller.md.gotmpl 展示了该系列变更日志的生成模板，magefiles/utils/releasenote.go 则实现了自动化的发布说明组装逻辑。

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