本文在专栏中的位置#

前七篇已经从单机和虚拟机视角建立了一套完整的 Nginx 入口能力：

1. 确定 Nginx 在后端架构中的位置；
2. 理解配置模型与请求匹配；
3. 完成反向代理、Header、超时、缓冲和流式传输；
4. 完成多实例负载均衡、重试和高可用；
5. 完成 HTTPS、证书和安全入口；
6. 完成静态资源、缓存、压缩和 CDN 协作；
7. 完成限流、结构化日志、Trace ID 和故障排查。

第八篇把这些能力放入容器和 Kubernetes 后，重点回答以下问题：

• Nginx 进入容器后，为什么必须前台运行？
• PID 1、信号、优雅退出和只读文件系统之间有什么关系？
• Docker Compose 中为什么可以用服务名访问后端？
• 环境变量为什么不能直接写进任意 nginx.conf？
• Kubernetes 中 Nginx 可以以哪些形态存在？
• Service、EndpointSlice、Pod Readiness 如何共同决定流量去向？
• Ingress 与 Ingress Controller 到底谁负责转发？
• 社区 ingress-nginx、F5 NGINX Ingress Controller 和 NGINX Gateway Fabric 有什么区别？
• ingress-nginx 退役后，现有系统和新项目分别应该怎么办？
• Gateway API 的 GatewayClass、Gateway、HTTPRoute 和 ReferenceGrant 如何协作？
• 配置变更怎样经过 Controller Reconcile 转换为 Nginx 配置？
• 热更新是否真的可以做到完全无损？
• 如何通过权重、Header、Cookie 和域名完成灰度发布？
• TLS Secret 与 cert-manager 如何完成自动签发和续期？
• 如何系统排查 Gateway Accepted 但请求仍然失败的问题？

这也是整个专栏从“会写 Nginx 配置”走向“理解云原生入口控制面与数据面”的收官篇。

学习目标#

完成本文后，你应当能够：

1. 解释 Nginx 容器为什么需要使用 daemon off;；
2. 说明 Nginx Master 作为 PID 1 时如何接收 HUP、QUIT、TERM；
3. 为容器设计只读配置、可写缓存目录和日志输出；
4. 使用固定版本或镜像摘要，而不是生产环境直接使用 latest；
5. 使用 Docker Compose 网络和服务名 DNS 连接后端；
6. 区分 depends_on、healthcheck 和运行期健康治理；
7. 使用官方镜像模板目录和 envsubst 生成简单配置；
8. 说明环境变量、ConfigMap、Secret 和配置中心的职责边界；
9. 区分普通 Nginx Deployment、应用前置代理、Sidecar、Ingress Controller 和 Gateway API 实现；
10. 解释 Service、ClusterIP、EndpointSlice 和 Pod Readiness 的关系；
11. 解释 Nginx 访问 Service 与直接访问 Pod Endpoint 的差异；
12. 区分 Ingress、IngressClass 和 Ingress Controller；
13. 区分社区 ingress-nginx、F5 NGINX Ingress Controller 和 NGINX Gateway Fabric；
14. 说明社区 ingress-nginx 退役对现有部署和新项目的影响；
15. 解释 Ingress API 冻结与 Controller 退役不是同一件事；
16. 使用 GatewayClass、Gateway 和 HTTPRoute 暴露 Spring Boot 服务；
17. 使用 allowedRoutes 和 ReferenceGrant 管理跨 Namespace 权限；
18. 使用 backendRefs.weight 实现权重灰度；
19. 理解 Header、Cookie、域名和路径灰度的标准能力与实现差异；
20. 解释 Controller 的 Watch、Reconcile、配置生成、校验和 Reload 流程；
21. 说明 ConfigMap 文件更新不等于 Nginx 已自动 Reload；
22. 设计 Readiness、PreStop、终止宽限期和连接排空流程；
23. 使用 Gateway Listener 和 TLS Secret 配置 HTTPS；
24. 使用 cert-manager 管理 Gateway 证书；
25. 通过 Conditions、事件、Controller 日志、数据平面日志、Service 和 EndpointSlice 排查问题；
26. 为新项目选择 Ingress、Gateway API、API Gateway 或 Service Mesh。

1.1 前台运行#

官方镜像的启动命令等价于：

1
nginx -g "daemon off;"

如果 Nginx 进入后台，而容器入口脚本退出，容器运行时会认为主进程已经结束，并停止容器。

容器内不需要 systemd 再管理一层 Nginx。容器运行时本身负责：

• 启动；
• 重启；
• 资源限制；
• 日志收集；
• 健康状态；
• 停止信号；
• 编排。

1.2 PID 1 与信号#

Nginx Master 作为容器 PID 1，需要正确接收停止和重载信号。

常见信号：

容器停止时，不应直接依赖强制 SIGKILL。应预留足够时间：

1
从负载均衡摘除
2
→ 停止接收新请求
3
→ 处理已有连接
4
→ Nginx 优雅退出
5
→ 超时后才强制终止

1.3 日志输出#

容器环境通常将：

1
Access Log → stdout
2
Error Log  → stderr

交给 Docker 或 Kubernetes 日志系统收集。

不要把日志永久写在容器可写层而不做轮转。容器删除后本地文件会消失，日志也可能占满节点磁盘。

1.4 文件系统与权限#

生产容器常采用：

• 只读根文件系统；
• 非 Root 用户；
• 禁止权限提升；
• 删除不必要 Capability；
• 高位监听端口；
• 临时目录使用 emptyDir；
• Secret 和 ConfigMap 只读挂载。

需要注意：Nginx 即使配置文件只读，仍可能需要写入：

• PID 文件；
• 客户端请求体临时文件；
• Proxy 临时文件；
• FastCGI 临时文件；
• Cache；
• 日志文件；
• Unix Socket。

如果使用：

1
readOnlyRootFilesystem: true

必须为实际需要写入的路径提供可写 Volume，或者调整配置关闭相关写入。

2.1 固定镜像版本#

开发环境可以临时使用：

1
image: nginx:1.30.3

生产环境最好进一步固定摘要：

1
image: nginx:1.30.3@sha256:<digest>

固定 Tag 可以避免大版本漂移；固定 Digest 可以保证实际镜像内容完全一致。

不要默认使用：

1
image: nginx:latest

原因包括：

• 无法从部署文件判断实际版本；
• 重新拉取时内容可能变化；
• 回滚难以复现；
• 安全审计无法确定基线。

2.2 最小 Dockerfile#

1
FROM nginx:1.30.3
2

3
COPY nginx.conf /etc/nginx/nginx.conf
4
COPY conf.d/ /etc/nginx/conf.d/
5
COPY html/ /usr/share/nginx/html/
6

7
RUN nginx -t

构建阶段执行 nginx -t 可以提前发现基础语法问题，但它不能验证：

• 运行时 DNS；
• Secret 是否存在；
• 后端是否可访问；
• TLS 证书和私钥是否匹配；
• 动态模板渲染结果；
• Kubernetes 资源引用是否有效。

2.3 非 Root 运行#

让 Nginx 完全以非 Root 用户运行时，需要：

1. 使用 1024 以上端口，例如 8080；
2. 确保配置和静态文件可读；
3. 确保 PID、Cache 和临时目录可写；
4. 删除或调整 user 指令；
5. 确保容器安全上下文一致。

示例：

1
pid /tmp/nginx.pid;
2

3
events {}
4

5
http {
6
    client_body_temp_path /tmp/client_temp;
7
    proxy_temp_path       /tmp/proxy_temp;
8

9
    server {
10
        listen 8080;
11
        location / {
12
            return 200 "nginx container\n";
13
        }
14
    }
15
}

不要仅添加：

1
runAsNonRoot: true

然后假设镜像自动兼容。权限、端口和目录必须一起调整。

3.1 Compose 网络#

同一个 Compose Project 的服务通常加入同一用户定义网络。服务可以通过服务名解析：

1
upstream backend {
2
    server backend:8080;
3
}

这里的 backend 不是宿主机 DNS，而是 Compose 网络中的服务名。

容器 IP 可能在重建后变化，所以不要手工写死容器 IP：

1
server 172.20.0.5:8080;

3.2 depends_on 不代表服务已经可用#

基础写法：

1
depends_on:
2
  - backend

只保证启动顺序，不保证 Spring Boot 已经完成：

• JVM 启动；
• Spring Context 初始化；
• 数据库连接；
• 缓存预热；
• 迁移脚本；
• 健康检查。

使用 healthcheck：

1
backend:
2
  healthcheck:
3
    test:
4
      - CMD
5
      - wget
6
      - -qO-
7
      - http://localhost:8080/actuator/health/readiness
8
    interval: 5s
9
    timeout: 2s
10
    retries: 20
11

12
nginx:
13
  depends_on:
14
    backend:
15
      condition: service_healthy

这只能改善初次启动。运行过程中后端异常时，仍需依赖：

• Nginx 超时；
• 被动故障判断；
• 多实例；
• 容器重启策略；
• 应用健康检查；
• 日志与告警。

3.3 完整 Compose 示例#

1
services:
2
  nginx:
3
    image: nginx:1.30.3
4
    ports:
5
      - "8088:8080"
6
    volumes:
7
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
8
      - ./nginx/conf.d:/etc/nginx/conf.d:ro
9
    depends_on:
10
      backend:
11
        condition: service_healthy
12
    networks:
13
      - nginx-lab
14

15
  backend:
16
    build:
17
      context: ./backend
18
    expose:
19
      - "8080"
20
    healthcheck:
21
      test:
22
        - CMD
23
        - wget
24
        - -qO-
25
        - http://localhost:8080/actuator/health
26
      interval: 5s
27
      timeout: 2s
28
      retries: 20
29
    networks:
30
      - nginx-lab
31

32
networks:
33
  nginx-lab:
34
    driver: bridge

4.1 Nginx 配置不会自动展开任意环境变量#

下面的写法并不会因为容器中存在 BACKEND_HOST 就自动工作：

1
proxy_pass http://${BACKEND_HOST}:8080;

Nginx 配置语法中的变量和操作系统环境变量不是同一个系统。

4.2 官方镜像模板机制#

官方 Docker 镜像入口脚本会执行 /docker-entrypoint.d/ 中的脚本。可以将模板放在：

1
/etc/nginx/templates/*.template

例如：

1
server {
2
    listen 8080;
3

4
    location / {
5
        proxy_pass http://${BACKEND_HOST}:${BACKEND_PORT};
6
    }
7
}

容器启动时渲染到：

1
/etc/nginx/conf.d/

Compose：

1
services:
2
  nginx:
3
    image: nginx:1.30.3
4
    environment:
5
      BACKEND_HOST: backend
6
      BACKEND_PORT: "8080"
7
    volumes:
8
      - ./templates:/etc/nginx/templates:ro

4.3 模板适合什么#

适合：

• 后端主机名；
• 端口；
• 域名；
• 简单开关；
• 环境差异较小的参数。

不适合：

• 大量嵌套条件；
• 复杂动态 upstream；
• 直接拼接用户输入；
• 保存私钥和 Token；
• 频繁变更的业务规则；
• 需要事务和版本治理的配置。

4.4 敏感配置#

不要把 Secret 放在普通 ConfigMap。Kubernetes Secret 也不意味着数据天然不可被读取，它只是提供专门资源类型和访问边界。

生产环境还应考虑：

• RBAC；
• etcd 静态加密；
• Secret Store CSI Driver；
• 外部密钥系统；
• 审计日志；
• Secret 轮换；
• Namespace 隔离。

5.1 普通 Deployment#

Nginx 作为普通应用部署：

1
Service
2
→ Nginx Deployment
3
→ 后端 Service

适用于：

• 应用独占入口；
• 自定义静态站点；
• 内部反向代理；
• 特殊协议转换；
• 团队希望完全控制 Nginx 配置。

缺点：

• 每个团队自行维护；
• 配置重复；
• TLS、监控和升级分散；
• 多租户治理困难。

5.2 应用前置代理#

Nginx 与应用分别部署，但只服务某个应用：

1
Nginx Deployment
2
→ Spring Boot Service

适用于：

• 静态资源和 API 分离；
• 独立缓存策略；
• 兼容旧系统；
• 应用级代理逻辑。

5.3 Sidecar#

Nginx 与应用在同一 Pod：

1
Pod
2
├── Nginx
3
└── Spring Boot

优点：

• 通过 localhost 通信；
• 生命周期一致；
• 可以封装应用专属代理逻辑。

缺点：

• 每个 Pod 都运行 Nginx；
• 资源开销重复；
• 任一容器异常会影响整个 Pod；
• 配置发布与应用发布耦合；
• 不能天然替代集群统一入口。

不要因为“Sidecar 很云原生”就默认使用。除非代理逻辑确实与每个应用实例绑定。

5.4 Ingress Controller 或 Gateway API 实现#

Controller 监听 Kubernetes API 资源并管理共享入口。

1
声明式资源
2
→ Controller
3
→ Nginx 数据平面
4
→ Service
5
→ Pod

这时，应用团队通常不直接编辑 Nginx 配置，而是提交：

• Ingress；
• Gateway；
• HTTPRoute；
• 实现相关 Policy 或 CRD。

6.1 Pod IP 不稳定#

Pod 被重新调度后 IP 可能变化。直接配置 Pod IP：

1
upstream backend {
2
    server 10.244.1.12:8080;
3
}

会导致配置很快过期。

Kubernetes 使用 Service 提供稳定入口：

1
apiVersion: v1
2
kind: Service
3
metadata:
4
  name: backend
5
spec:
6
  selector:
7
    app: backend
8
  ports:
9
    - port: 80
10
      targetPort: 8080

集群 DNS：

1
backend.default.svc.cluster.local

6.2 EndpointSlice#

Service Selector 持续选择 Pod。控制器将可用后端地址写入 EndpointSlice。

EndpointSlice 包含：

• IP；
• 端口；
• Ready 状态；
• Serving 状态；
• Terminating 状态；
• 拓扑信息。

旧的 Endpoints API 已被弃用方向替代，不应继续围绕单个 Endpoints 对象设计新的控制器。

6.3 Readiness 决定是否接收正常流量#

Deployment：

1
readinessProbe:
2
  httpGet:
3
    path: /actuator/health/readiness
4
    port: 8080
5
  initialDelaySeconds: 5
6
  periodSeconds: 5

Pod 未 Ready 时通常不会作为 Service 正常流量后端。

Readiness 不是 Liveness：

• Readiness 失败：临时从流量中摘除；
• Liveness 失败：Kubelet 重启容器；
• Startup Probe：保护慢启动应用，避免过早执行 Liveness。

不要用会被外部依赖轻微抖动触发的探针频繁重启整个应用。

6.4 Nginx 访问 Service 与直接发现 Pod#

1
proxy_pass http://backend.default.svc.cluster.local;

7.1 Ingress 只是 API 资源#

Ingress 示例：

1
apiVersion: networking.k8s.io/v1
2
kind: Ingress
3
metadata:
4
  name: backend
5
spec:
6
  ingressClassName: example
7
  rules:
8
    - host: api.example.com
9
      http:
10
        paths:
11
          - path: /
12
            pathType: Prefix
13
            backend:
14
              service:
15
                name: backend
16
                port:
17
                  number: 80

创建 Ingress 不会凭空出现代理。集群必须安装匹配的 Ingress Controller。

7.2 IngressClass#

1
apiVersion: networking.k8s.io/v1
2
kind: IngressClass
3
metadata:
4
  name: example
5
spec:
6
  controller: example.com/ingress-controller

Controller 根据：

• ingressClassName；
• Controller Name；
• 监听范围；
• Namespace 策略；

决定是否接管某个 Ingress。

7.3 Ingress API 已冻结#

Ingress API 仍然是 GA，Kubernetes 没有计划直接删除它。但是它已经冻结：

• API 不再增加新能力；
• 新的标准流量治理方向是 Gateway API；
• 复杂能力长期依赖 Controller Annotation 或 CRD；
• 不同 Controller 的 Annotation 很难迁移。

“冻结”不等于“立即不可用”。已有系统不必因为 Ingress 冻结就在一天内全部重写，但新项目应认真评估 Gateway API。

8.1 社区 ingress-nginx#

项目：

1
kubernetes/ingress-nginx

它由 Kubernetes 社区维护，使用 Nginx 作为数据平面。

截至 2026 年 3 月 24 日，该项目已经退役：

• 仓库和制品仍可供参考；
• 已有部署不会自动停止；
• 不再发布功能更新；
• 不再修复 Bug；
• 不再发布安全更新。

因此：

• 不应在新项目中继续默认安装；
• 现有系统应建立迁移计划；
• 不能因为当前仍然工作就忽略未来安全风险；
• 迁移前必须盘点 Annotation、Snippet、默认行为和定制模板。

8.2 F5 NGINX Ingress Controller#

这是 F5 NGINX 维护的独立项目，不等于社区 ingress-nginx。

它具有自己的：

• 发布节奏；
• Helm Chart；
• CRD；
• Annotation；
• NGINX Open Source / NGINX Plus 能力；
• 商业支持。

社区项目退役不代表 F5 NGINX Ingress Controller 同时退役。

8.3 NGINX Gateway Fabric#

NGINX Gateway Fabric 是 F5 NGINX 的 Gateway API 实现，以 Nginx 作为数据平面。

它主要监听：

• GatewayClass；
• Gateway；
• HTTPRoute；
• GRPCRoute；
• TLSRoute / TCPRoute 等受支持资源；
• NginxProxy 和其他实现扩展。

不要将它称为“新版 ingress-nginx”。二者 API、控制模型、资源角色和迁移方式不同。

8.4 迁移不是简单改 Kind#

Ingress：

1
kind: Ingress

不能机械替换为：

1
kind: HTTPRoute

还需要处理：

• Controller 特定 Annotation；
• Regex Path 行为；
• Rewrite；
• Snippet；
• 默认 Backend；
• TLS Secret；
• 跨 Namespace；
• 外部鉴权；
• Sticky Session；
• Rate Limit；
• Canary；
• 自定义 Header；
• Error Page；
• Source IP；
• 日志格式；
• Timeout 和 Retry。

迁移工具可以生成初始资源，但不能替代行为验证。

9.1 GatewayClass#

由基础设施提供者或集群管理员管理：

1
apiVersion: gateway.networking.k8s.io/v1
2
kind: GatewayClass
3
metadata:
4
  name: nginx
5
spec:
6
  controllerName: gateway.nginx.org/nginx-gateway-controller

它描述：

• 哪个 Controller 接管；
• 一类 Gateway 的实现；
• 可选基础设施参数。

通常应用团队不应随意创建 GatewayClass。

9.2 Gateway#

由平台或集群团队管理：

1
apiVersion: gateway.networking.k8s.io/v1
2
kind: Gateway
3
metadata:
4
  name: public-gateway
5
  namespace: gateway-system
6
spec:
7
  gatewayClassName: nginx
8
  listeners:
9
    - name: http
10
      protocol: HTTP
11
      port: 80
12
      hostname: "*.example.com"

Gateway 描述：

• 网络入口；
• Listener；
• 端口；
• 协议；
• Hostname；
• TLS；
• 允许哪些 Namespace 和 Route 挂载。

9.3 HTTPRoute#

由应用团队管理：

1
apiVersion: gateway.networking.k8s.io/v1
2
kind: HTTPRoute
3
metadata:
4
  name: backend
5
  namespace: app
6
spec:
7
  parentRefs:
8
    - name: public-gateway
9
      namespace: gateway-system
10
  hostnames:
11
    - api.example.com
12
  rules:
13
    - matches:
14
        - path:
15
            type: PathPrefix
16
            value: /api
17
      backendRefs:
18
        - name: backend
19
          port: 80

HTTPRoute 描述：

• 连接哪个 Gateway；
• Host；
• Path；
• Header；
• Query Parameter；
• Method；
• Filter；
• Backend Service；
• 权重。

独立插图 09：Gateway API 资源链路
对应文件：09-gateway-api-resource-chain.png

9.4 ReferenceGrant#

Route 跨 Namespace 引用 Service 时，需要后端 Namespace 显式授权：

1
apiVersion: gateway.networking.k8s.io/v1beta1
2
kind: ReferenceGrant
3
metadata:
4
  name: allow-app-route
5
  namespace: backend
6
spec:
7
  from:
8
    - group: gateway.networking.k8s.io
9
      kind: HTTPRoute
10
      namespace: app
11
  to:
12
    - group: ""
13
      kind: Service

这可以防止某个 Namespace 未经允许将其他团队的 Service 暴露到公网。

9.5 Conditions 是一等诊断入口#

不要只运行：

1
kubectl apply -f route.yaml

然后假设资源生效。

检查：

1
kubectl describe gateway public-gateway -n gateway-system
2
kubectl describe httproute backend -n app

关注：

• Accepted；
• Programmed；
• ResolvedRefs；
• Conflicted；
• UnsupportedProtocol；
• InvalidRouteKinds；
• NoMatchingParent。

10.1 实验目录#

1
nginx-column-08/
2
├── backend/
3
│   ├── Dockerfile
4
│   ├── pom.xml
5
│   └── src/main/java/com/example/demo/
6
│       ├── DemoApplication.java
7
│       └── DemoController.java
8
├── docker/
9
│   ├── compose.yaml
10
│   └── nginx/
11
│       └── templates/
12
│           └── default.conf.template
13
├── kind/
14
│   └── cluster.yaml
15
└── kubernetes/
16
    ├── namespace.yaml
17
    ├── backend-v1.yaml
18
    ├── backend-v2.yaml
19
    ├── gateway.yaml
20
    ├── route.yaml
21
    ├── canary-route.yaml
22
    └── tls/
23
        ├── secret.yaml
24
        └── gateway-https.yaml

10.2 Spring Boot 接口#

1
package com.example.demo;
2

3
import org.springframework.beans.factory.annotation.Value;
4
import org.springframework.web.bind.annotation.GetMapping;
5
import org.springframework.web.bind.annotation.RestController;
6

7
import java.time.Instant;
8
import java.util.Map;
9

10
@RestController
11
public class DemoController {
12

13
    @Value("${APP_VERSION:unknown}")
14
    private String version;
15

16
    @GetMapping("/api/instance")
17
    public Map<String, Object> instance() {
18
        return Map.of(
19
                "version", version,
20
                "time", Instant.now().toString()
21
        );
22
    }
23

24
    @GetMapping("/actuator-ready")
25
    public Map<String, String> ready() {
26
        return Map.of("status", "UP");
27
    }
28
}

10.3 Dockerfile#

1
FROM maven:3.9.11-eclipse-temurin-21 AS build
2
WORKDIR /workspace
3
COPY pom.xml .
4
RUN mvn -q -DskipTests dependency:go-offline
5
COPY src ./src
6
RUN mvn -q -DskipTests package
7

8
FROM eclipse-temurin:21-jre
9
WORKDIR /app
10
COPY --from=build /workspace/target/*.jar /app/app.jar
11

12
EXPOSE 8080
13
ENTRYPOINT ["java", "-jar", "/app/app.jar"]

10.4 kind 集群#

1
kind: Cluster
2
apiVersion: kind.x-k8s.io/v1alpha4
3
nodes:
4
  - role: control-plane
5
  - role: worker
6
  - role: worker

创建：

1
kind create cluster \
2
  --name nginx-column-08 \
3
  --config kind/cluster.yaml

10.5 构建并加载后端镜像#

1
docker build \
2
  -t nginx-column-backend:1.0.0 \
3
  ./backend
4

5
kind load docker-image \
6
  nginx-column-backend:1.0.0 \
7
  --name nginx-column-08

10.6 安装 NGINX Gateway Fabric#

为了保证可重复性，固定版本：

1
kubectl kustomize \
2
  "https://github.com/nginx/nginx-gateway-fabric/config/crd/gateway-api/standard?ref=v2.6.6" \
3
  | kubectl apply -f -

安装：

1
helm install ngf \
2
  oci://ghcr.io/nginx/charts/nginx-gateway-fabric \
3
  --version 2.6.6 \
4
  --create-namespace \
5
  --namespace nginx-gateway \
6
  --wait

检查：

1
kubectl get gatewayclass
2
kubectl get pods -n nginx-gateway

GatewayClass 应包含：

1
nginx

具体版本和受支持 Gateway API Bundle 必须以对应 Controller 的兼容性矩阵为准，不能独立升级 CRD 而忽略 Controller 支持范围。

10.7 Namespace#

1
apiVersion: v1
2
kind: Namespace
3
metadata:
4
  name: nginx-column

10.8 v1 Deployment 与 Service#

1
apiVersion: apps/v1
2
kind: Deployment
3
metadata:
4
  name: backend-v1
5
  namespace: nginx-column
6
spec:
7
  replicas: 2
8
  selector:
9
    matchLabels:
10
      app: backend
11
      version: v1
12
  template:
13
    metadata:
14
      labels:
15
        app: backend
16
        version: v1
17
    spec:
18
      terminationGracePeriodSeconds: 30
19
      containers:
20
        - name: backend
21
          image: nginx-column-backend:1.0.0
22
          imagePullPolicy: IfNotPresent
23
          env:
24
            - name: APP_VERSION
25
              value: v1
26
          ports:
27
            - containerPort: 8080
28
          readinessProbe:
29
            httpGet:
30
              path: /actuator-ready
31
              port: 8080
32
            periodSeconds: 5
33
          livenessProbe:
34
            httpGet:
35
              path: /actuator-ready
36
              port: 8080
37
            initialDelaySeconds: 20
38
            periodSeconds: 10
39
          resources:
40
            requests:
41
              cpu: 100m
42
              memory: 128Mi
43
            limits:
44
              cpu: "1"
45
              memory: 512Mi
46
---
47
apiVersion: v1
48
kind: Service
49
metadata:
50
  name: backend-v1
51
  namespace: nginx-column
52
spec:
53
  selector:
54
    app: backend
55
    version: v1
56
  ports:
57
    - port: 80
58
      targetPort: 8080

10.9 v2 Deployment 与 Service#

1
apiVersion: apps/v1
2
kind: Deployment
3
metadata:
4
  name: backend-v2
5
  namespace: nginx-column
6
spec:
7
  replicas: 1
8
  selector:
9
    matchLabels:
10
      app: backend
11
      version: v2
12
  template:
13
    metadata:
14
      labels:
15
        app: backend
16
        version: v2
17
    spec:
18
      containers:
19
        - name: backend
20
          image: nginx-column-backend:1.0.0
21
          imagePullPolicy: IfNotPresent
22
          env:
23
            - name: APP_VERSION
24
              value: v2
25
          ports:
26
            - containerPort: 8080
27
          readinessProbe:
28
            httpGet:
29
              path: /actuator-ready
30
              port: 8080
31
---
32
apiVersion: v1
33
kind: Service
34
metadata:
35
  name: backend-v2
36
  namespace: nginx-column
37
spec:
38
  selector:
39
    app: backend
40
    version: v2
41
  ports:
42
    - port: 80
43
      targetPort: 8080

10.10 Gateway#

1
apiVersion: gateway.networking.k8s.io/v1
2
kind: Gateway
3
metadata:
4
  name: nginx-column
5
  namespace: nginx-column
6
spec:
7
  gatewayClassName: nginx
8
  listeners:
9
    - name: http
10
      protocol: HTTP
11
      port: 80
12
      hostname: nginx-column.example.com
13
      allowedRoutes:
14
        namespaces:
15
          from: Same

10.11 HTTPRoute#

1
apiVersion: gateway.networking.k8s.io/v1
2
kind: HTTPRoute
3
metadata:
4
  name: backend
5
  namespace: nginx-column
6
spec:
7
  parentRefs:
8
    - name: nginx-column
9
      sectionName: http
10
  hostnames:
11
    - nginx-column.example.com
12
  rules:
13
    - matches:
14
        - path:
15
            type: PathPrefix
16
            value: /api
17
      backendRefs:
18
        - name: backend-v1
19
          port: 80

应用：

1
kubectl apply -f kubernetes/namespace.yaml
2
kubectl apply -f kubernetes/backend-v1.yaml
3
kubectl apply -f kubernetes/backend-v2.yaml
4
kubectl apply -f kubernetes/gateway.yaml
5
kubectl apply -f kubernetes/route.yaml

检查：

1
kubectl get gateway,httproute -n nginx-column
2
kubectl describe gateway nginx-column -n nginx-column
3
kubectl describe httproute backend -n nginx-column
4
kubectl get pods,svc,endpointslices -n nginx-column

10.12 本地访问#

NGINX Gateway Fabric 会为 Gateway 创建数据平面 Deployment 和 Service。检查：

1
kubectl get deployment,service \
2
  -n nginx-column

默认生成名称通常与 Gateway 相关，例如：

1
nginx-column-nginx

实际名称应以：

1
kubectl get svc -n nginx-column

为准。

端口转发：

1
kubectl port-forward \
2
  -n nginx-column \
3
  service/nginx-column-nginx \
4
  8088:80

测试：

1
curl \
2
  -H "Host: nginx-column.example.com" \
3
  http://127.0.0.1:8088/api/instance

11.1 声明式变更不是直接修改配置文件#

执行：

1
kubectl apply -f route.yaml

后通常经历：

1. API Server 保存资源；
2. Controller Watch 到资源变化；
3. 将相关 Gateway、Route、Service、Secret、EndpointSlice 加入队列；
4. Reconcile 读取期望状态；
5. 校验引用和实现能力；
6. 生成数据平面配置；
7. 执行配置检查；
8. Reload 或动态更新 Nginx；
9. 回写 Conditions；
10. 记录事件和指标。

11.2 ConfigMap 更新不等于自动 Reload#

普通 Nginx Deployment 使用 ConfigMap Volume：

1
volumes:
2
  - name: config
3
    configMap:
4
      name: nginx-config

ConfigMap 文件内容可能在一段时间后更新到 Pod，但 Nginx 不会因为磁盘文件变化自动执行：

1
nginx -s reload

需要额外机制：

• Sidecar 监听文件并 Reload；
• Controller；
• Reloader 触发 Deployment Rollout；
• GitOps 更新 Pod Template Annotation；
• 应用发布新版本 ConfigMap 并滚动替换 Pod。

使用 subPath 挂载单文件时，ConfigMap 后续更新通常不会自动反映到现有挂载，尤其需要注意。

11.3 Nginx Reload#

Reload 时：

1
Master 读取新配置
2
→ 校验成功
3
→ 创建新 Worker
4
→ 新 Worker 接收新连接
5
→ 旧 Worker 停止接收新连接
6
→ 处理完已有请求后退出

如果配置无效，旧 Worker 和旧配置继续运行。

11.4 热更新仍可能失败#

可能的问题：

• 配置生成错误；
• 引用 Secret 不存在；
• 端口冲突；
• Controller 快速重复 Reload；
• 大量 Route 导致配置生成慢；
• 长 WebSocket/SSE 使旧 Worker 长期存在；
• Worker Shutdown Timeout 不足；
• Pod 同时滚动更新；
• 上游 Endpoint 快速抖动；
• Reload 后缓存和连接池重新建立。

12.1 Pod 终止基本流程#

Kubernetes 删除 Pod 时：

1. Pod 标记为 Terminating；
2. Endpoint 状态开始变化；
3. 执行 preStop；
4. 容器运行时向 PID 1 发送停止信号；
5. 等待 terminationGracePeriodSeconds；
6. 到期后强制 SIGKILL。

默认终止宽限期通常是 30 秒。

12.2 PreStop 与宽限期#

示例：

1
spec:
2
  terminationGracePeriodSeconds: 60
3
  containers:
4
    - name: nginx
5
      lifecycle:
6
        preStop:
7
          exec:
8
            command:
9
              - /bin/sh
10
              - -c
11
              - sleep 5 && nginx -s quit

需要注意：

• PreStop 使用同一个宽限期预算；
• PreStop 执行 55 秒后只剩 5 秒供 Nginx 退出；
• Hook 卡住仍会在宽限期结束后被强制杀死；
• 不应无依据地增加固定 Sleep；
• 必须根据 Service 摘流延迟、最长请求和连接类型设计。

12.3 长连接#

对于：

• WebSocket；
• SSE；
• gRPC Stream；
• 大文件下载；
• 长轮询；

旧连接可能持续很久。必须明确：

• 发布时是否允许中断；
• 客户端是否自动重连；
• 是否携带恢复游标；
• Worker Shutdown Timeout；
• 最大连接生命周期；
• PodDisruptionBudget；
• 滚动更新并发度。

13.1 权重拆分#

1
apiVersion: gateway.networking.k8s.io/v1
2
kind: HTTPRoute
3
metadata:
4
  name: backend
5
  namespace: nginx-column
6
spec:
7
  parentRefs:
8
    - name: nginx-column
9
  hostnames:
10
    - nginx-column.example.com
11
  rules:
12
    - matches:
13
        - path:
14
            type: PathPrefix
15
            value: /api
16
      backendRefs:
17
        - name: backend-v1
18
          port: 80
19
          weight: 90
20
        - name: backend-v2
21
          port: 80
22
          weight: 10

权重是相对值：

1
90 : 10
2
等价于
3
9 : 1

它不是保证每连续 10 个请求恰好有 1 个进入 v2。

13.2 Header 灰度#

1
rules:
2
  - matches:
3
      - headers:
4
          - name: X-Canary
5
            value: "true"
6
    backendRefs:
7
      - name: backend-v2
8
        port: 80
9
  - backendRefs:
10
      - name: backend-v1
11
        port: 80

适用于：

• 测试人员；
• 内部流量；
• 特定客户端；
• 自动化验证。

公网用户可伪造 Header，因此不能把它作为权限控制。

13.3 Cookie 灰度#

Gateway API 标准 Header 匹配可以匹配整个 Cookie Header，但对 Cookie 键值进行结构化匹配的能力可能依赖具体实现或扩展。

需要验证：

• Controller 是否支持；
• 匹配语义；
• 正则引擎；
• 多 Cookie 顺序；
• 大小写；
• 安全边界。

13.4 域名和路径灰度#

域名：

1
canary.example.com → v2
2
api.example.com    → v1

路径：

1
/api/v2 → v2
2
/api    → v1

优点是路由可预测，缺点是用户路径或域名发生变化。

13.5 长连接与会话保持#

权重是连接或请求选择策略的输入。对于长连接：

• WebSocket 一旦建立会长期固定在某个后端；
• 小流量样本比例可能偏差很大；
• Session Persistence 可能覆盖权重效果；
• 客户端重试可能放大某个版本；
• HPA 扩缩容会改变实际后端集合。

灰度验收必须观察：

• 业务成功率；
• P95/P99；
• 5xx；
• 重试；
• 连接数；
• 版本分布；
• 下游影响。

13.6 回滚#

回滚不应依赖人工临时编辑：

1
backendRefs:
2
  - name: backend-v1
3
    port: 80
4
    weight: 100
5
  - name: backend-v2
6
    port: 80
7
    weight: 0

应使用：

• GitOps Commit；
• 发布平台；
• 自动指标门禁；
• 审计记录；
• 一键恢复稳定配置。

14.1 TLS Secret#

1
apiVersion: v1
2
kind: Secret
3
metadata:
4
  name: nginx-column-tls
5
  namespace: nginx-column
6
type: kubernetes.io/tls
7
data:
8
  tls.crt: <base64>
9
  tls.key: <base64>

Gateway：

1
apiVersion: gateway.networking.k8s.io/v1
2
kind: Gateway
3
metadata:
4
  name: nginx-column
5
  namespace: nginx-column
6
spec:
7
  gatewayClassName: nginx
8
  listeners:
9
    - name: https
10
      protocol: HTTPS
11
      port: 443
12
      hostname: nginx-column.example.com
13
      tls:
14
        mode: Terminate
15
        certificateRefs:
16
          - kind: Secret
17
            name: nginx-column-tls

14.2 Secret Namespace#

Listener 的 Secret 通常需要位于 Gateway Namespace。

如果实现支持跨 Namespace 引用，应通过 ReferenceGrant 显式授权，不能假设任意 Namespace Secret 都可读取。

14.3 cert-manager#

cert-manager 可以：

• 创建 Certificate；
• 调用 ACME 或内部 CA；
• 写入 TLS Secret；
• 在到期前续期；
• 失败时回写状态和事件。

Gateway API 集成应核对：

• cert-manager 版本；
• Gateway API 版本；
• Controller 是否启用 Gateway API；
• HTTP-01 Route 是否能够挂载；
• allowedRoutes；
• DNS 是否指向入口；
• Challenge 是否可从公网访问。

14.4 多租户 TLS#

Ingress 时代常见模式是应用团队自己创建 Ingress 和 TLS Secret。

Gateway API 将 Gateway 和 Route 角色分开后，多租户 Listener 和证书管理需要重新设计：

• 平台集中管理 Gateway Listener；
• 应用团队只管理 HTTPRoute；
• 使用 ListenerSet 等受支持能力扩展；
• 建立证书申请流程；
• 严格限制跨 Namespace Secret。

不要假设 Ingress 的证书自服务方式可以无修改迁移。

15.1 Controller#

观察：

• Reconcile 次数；
• Reconcile 错误；
• 队列长度；
• 配置生成失败；
• Reload 成功率；
• Gateway 和 Route Conditions；
• Leader Election；
• API Server 错误；
• RBAC 拒绝。

15.2 数据平面#

观察：

• 连接数；
• 请求数；
• 4xx/5xx；
• upstream 状态；
• upstream 延迟；
• 活跃 Worker；
• Reload；
• Access Log；
• Error Log；
• TLS 握手；
• 长连接。

NGINX Gateway Fabric 的 Prometheus 指标端点和具体指标取决于安装配置与版本，应通过官方文档核验。

15.3 Kubernetes 资源#

1
kubectl get gatewayclass
2
kubectl get gateway,httproute -A
3
kubectl get pod,svc,endpointslice -A
4
kubectl get events -A --sort-by=.lastTimestamp
5
kubectl describe gateway <name>
6
kubectl describe httproute <name>

15.4 应用层#

即使 Gateway 和 Nginx 都健康，也可能存在：

• 应用 500；
• 数据库慢；
• 线程池满；
• 下游超时；
• 业务错误；
• 错误版本；
• 配置中心异常。

应继续使用前一篇的 Request ID 和 Trace 体系。

16.1 Gateway 没有地址#

检查：

1
kubectl describe gateway nginx-column -n nginx-column
2
kubectl get gatewayclass nginx -o yaml
3
kubectl logs -n nginx-gateway \
4
  deployment/ngf-nginx-gateway-fabric

可能原因：

• GatewayClass 不存在；
• Controller Name 不匹配；
• Controller 未运行；
• RBAC 不足；
• 数据平面 Service 创建失败；
• 云环境 LoadBalancer 无实现；
• NginxProxy 配置无效。

16.2 HTTPRoute 未 Accepted#

检查 ParentRefs：

• Gateway Name；
• Namespace；
• Section Name；
• Hostname；
• allowedRoutes；
• Route Kind；
• Listener Protocol。

16.3 ResolvedRefs=False#

常见原因：

• Service 不存在；
• Port 不存在；
• 跨 Namespace 缺少 ReferenceGrant；
• Secret 不存在；
• Backend 协议不支持；
• Controller 不支持该 Filter。

16.4 返回 404#

先区分：

• 请求 Host 不匹配；
• Path 不匹配；
• Route 未挂载；
• Controller 默认 404；
• 后端应用 404。

检查：

1
curl -v \
2
  -H "Host: nginx-column.example.com" \
3
  http://127.0.0.1:8088/api/instance

16.5 返回 502 / 504#

检查：

1
kubectl get svc,endpointslice -n nginx-column
2
kubectl get pods -n nginx-column -o wide
3
kubectl logs deployment/nginx-column-nginx -n nginx-column
4
kubectl exec deployment/nginx-column-nginx \
5
  -n nginx-column \
6
  -- nginx -T

从数据平面容器测试：

1
kubectl exec deployment/nginx-column-nginx \
2
  -n nginx-column \
3
  -- curl -v http://backend-v1/api/instance

实际镜像可能不包含 curl。生产镜像不应为了排障长期安装大量工具，可以使用临时 Debug Pod：

1
kubectl run net-debug \
2
  --rm -it \
3
  --image=curlimages/curl \
4
  -- sh

16.6 Pod Ready 但请求失败#

Readiness 只验证探针，不一定覆盖真实业务链路。

检查：

• 探针是否过于简单；
• Service targetPort；
• 应用监听地址；
• NetworkPolicy；
• mTLS；
• Host Header；
• Context Path；
• 资源耗尽；
• 数据库；
• 下游依赖。

16.7 ConfigMap 已更新但配置未生效#

检查：

• Pod 内文件是否变化；
• 是否使用 subPath；
• 是否执行 Reload；
• Reload 是否通过 nginx -t；
• Controller 是否接管该配置；
• 是否更新了错误 Namespace；
• 是否存在多个 Controller。

16.8 灰度比例不准确#

检查：

• 样本量；
• 长连接；
• Session Persistence；
• 客户端重试；
• 是否多个 Gateway 副本；
• Service Endpoint 数量；
• HPA；
• Controller 对权重的具体实现；
• 是否存在缓存。

17.1 第一阶段：本地 Docker Compose#

目标：

• 固定 Nginx 镜像；
• 配置模板；
• healthcheck；
• stdout/stderr；
• 非 Root；
• nginx -t；
• 自动化请求验证。

17.2 第二阶段：普通 Kubernetes Deployment#

目标：

• ConfigMap；
• Secret；
• Readiness；
• Resource Requests/Limits；
• SecurityContext；
• NetworkPolicy；
• Rolling Update；
• PodDisruptionBudget；
• 日志和指标。

17.3 第三阶段：共享入口 Controller#

目标：

• 统一 TLS；
• Namespace 权限；
• 路由资源规范；
• Controller 高可用；
• 数据平面副本；
• 发布和回滚；
• 审计；
• 配置规模测试。

17.4 第四阶段：Gateway API#

目标：

• 基础设施与应用角色分离；
• 标准 Route；
• Conditions；
• ReferenceGrant；
• 权重灰度；
• TLS；
• 实现 Conformance；
• 从 Annotation 迁移到结构化字段或 Policy。

17.5 第五阶段：平台化#

目标：

• GitOps；
• Policy as Code；
• 自动证书；
• 自动灰度；
• 指标门禁；
• 多集群；
• 多区域；
• API Gateway；
• WAF；
• 成本与容量治理。

18.1 使用 latest#

18.2 把 Nginx 容器当虚拟机#

18.3 配置只读但临时目录不可写#

18.4 认为 depends_on 等于运行期健康检查#

18.5 在 Nginx 配置中直接写 ${ENV}#

18.6 手工写 Pod IP#

18.7 认为 Ingress 自己会转发#

18.8 将 ingress-nginx 和 NGINX Ingress Controller 混为一谈#

18.9 新项目继续安装已退役 ingress-nginx#

18.10 认为 Ingress API 已被删除#

18.11 迁移时只转换 YAML#

18.12 ConfigMap 更新后不 Reload#

18.13 Reload 前不校验#

18.14 所有 Namespace 都能挂载 Gateway#

18.15 用灰度权重代替业务兼容性验证#

20.1 核心问题#

20.2 场景题#

20.3 配置排错题#

1
kind: HTTPRoute
2
spec:
3
  parentRefs:
4
    - name: public-gateway

1
namespace: gateway-system

1
backendRefs:
2
  - name: payment
3
    namespace: payment
4
    port: 80

1
image: nginx:latest
2
imagePullPolicy: Always

内容完整性#

• 覆盖 Nginx 容器前台运行和 PID 1；
• 覆盖信号与优雅退出；
• 覆盖非 Root 和只读文件系统；
• 覆盖 Docker Compose 网络和健康检查；
• 覆盖 envsubst 模板；
• 覆盖 Kubernetes 中多种 Nginx 形态；
• 覆盖 Service 和 EndpointSlice；
• 覆盖 Readiness；
• 覆盖 Ingress 与 Controller；
• 覆盖项目命名和维护状态；
• 覆盖 Gateway API；
• 覆盖 ReferenceGrant；
• 覆盖 Reconcile 和 Reload；
• 覆盖优雅终止；
• 覆盖权重和 Header 灰度；
• 覆盖 TLS Secret 和 cert-manager；
• 覆盖可观测性和排障；
• 提供 kind + NGF + Spring Boot 完整实验；
• 提供常见错误、面试题和选择矩阵。

技术边界#

• 区分 Ingress API 与 Controller；
• 区分 ingress-nginx、F5 NGINX Ingress Controller 和 NGINX Gateway Fabric；
• 标明社区 ingress-nginx 已退役；
• 没有把 Annotation 能力写成 Gateway API 标准能力；
• 强调具体 Controller Conformance；
• 强调 Gateway API CRD 与 Controller 版本兼容；
• 说明 Secret 与 ConfigMap 安全边界；
• 说明多租户和跨 Namespace 授权；
• 说明热更新不等于绝对无损。

实验可执行性#

• 提供目录结构；
• 提供 Spring Boot 代码；
• 提供 Dockerfile；
• 提供 kind 配置；
• 提供固定版本 NGF 安装命令；
• 提供 Deployment 和 Service；
• 提供 Gateway 和 HTTPRoute；
• 提供权重灰度；
• 提供验证和排障命令；
• 提供资源清理思路。