Nginx 与 Ingress

这一课你将能做到

1. 把裸机 upstream / location / ssl_certificate 映射到 K8s 的 Service、Ingress path、TLS Secret
2. 读懂一份「双 path：/api → backend，/ → platform」的 Ingress 示意 YAML，并指出与 prod.conf.example 的对应关系
3. 说明单机 Nginx、Compose 入口、Ingress Controller 各自适合的阶段，以及注解如何复刻部分 Nginx 指令

为什么要学

集群里很少在每个节点手写 /etc/nginx/conf.d。更常见的是 Ingress Controller（大量实现基于 Nginx）监听 Ingress 资源，自动生成/热加载等价路由。
你已经会的 server_name、location /api/、证书路径，在声明式世界里换成 Host、path、Secret。
本课不做完整 K8s 教程，只搭「概念桥」，方便从 deploy/nginx/prod.conf.example 迁到 kubernetes-essentials。

先建立图像

裸机：
  DNS → 主机:443 Nginx → upstream → 本机进程

K8s：
  DNS → LB → Ingress Controller Pod
                → Service backend → Pod:8080
                → Service platform → Pod:3000

裸机 Nginx	Kubernetes
upstream backend	Service backend:8080
location /api/	Ingress path /api → backend
location /	Ingress path / → platform
ssl_certificate 文件	TLS Secret + 常配 cert-manager
nginx -t && reload	Controller reconcile（仍有 reload/热更）
proxy_set_header 等	注解或 Controller 全局 ConfigMap

人话：Ingress 是「用 YAML 描述的门岗规则」；真正干活的仍是一台（组）Nginx 兼容数据面。

跟着做

步骤 1：复习裸机双 path

口头复述 prod：

• Host：www.coderoadmap.cn
• /api/ → 8080（剥前缀与否在注解/rewrite 中表达）
• / → 3000

步骤 2：读 Ingress 示意

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: coderoadmap
  annotations:
    # 对应 client_max_body_size 20m
    nginx.ingress.kubernetes.io/proxy-body-size: "20m"
    # 若需剥 /api 前缀，常用 rewrite 类注解（按 Controller 文档核对）
    # nginx.ingress.kubernetes.io/rewrite-target: /$2
spec:
  ingressClassName: nginx
  tls:
    - hosts:
        - www.coderoadmap.cn
      secretName: coderoadmap-tls
  rules:
    - host: www.coderoadmap.cn
      http:
        paths:
          - path: /api
            pathType: Prefix
            backend:
              service:
                name: backend
                port:
                  number: 8080
          - path: /
            pathType: Prefix
            backend:
              service:
                name: platform
                port:
                  number: 3000

笔记：「path 长短与优先级仍关键；更具体的 /api 应压过 /。」具体前缀剥离要以你用的 Ingress-Nginx 版本注解为准，先查文档再抄。

步骤 3：对照 TLS

• 裸机：certbot 写文件，Nginx 读 pem
• K8s：cert-manager 申请并写入 Secret，Ingress tls 引用

相似点：都要续期与滚动；不同点：密钥在集群对象里，不在某台机 /etc/letsencrypt alone。

步骤 4：选型表写进笔记

阶段	推荐入口
单机 / 小团队	宿主机 Nginx + prod.conf.example
Compose 过渡	映射 443→Nginx 容器，挂载 conf
多副本滚动	Ingress + Service + readiness

Pod 内不必再为每个应用塞一个「迷你公网 Nginx sidecar」（除非 mesh/特殊需求）；入口收敛到 Controller。

步骤 5：应用部署要点

• backend Deployment：containerPort 8080，ClusterIP Service
• platform Deployment：containerPort 3000
• 浏览器仍打公网 Host；集群内服务间可用 Service DNS
• 本地调试可用 kubectl port-forward，类似临时直连 upstream

步骤 6：注解能复刻什么、不能什么

常见可配：超时、body 大小、部分 header、rewrite、亲和。
复杂 lua、任意第三方模块、与主机文件强耦合的路径，不一定能一对一搬。
策略：先保证 path/Host/TLS 正确，再逐项搬优化项。

讲清楚要点

1. 因为 Ingress 描述期望状态，所以改 YAML 即改路由，不必 SSH 改 conf——Controller 负责落地。
2. 因为 Service 稳定提供 DNS/端口，所以 Ingress 指 Service 而不是指 Pod IP——Pod 换了路由仍在。
3. 因为 TLS Secret 替代磁盘 pem，所以证书流程与 certbot 形异实同——都要续期——自动化工具不同。
4. 因为不同 Controller 注解不通用，所以文档必须对齐你安装的那一款——忌混用 Traefik/Nginx 注解。
5. 因为 readiness 决定 Endpoint，所以坏 Pod 不会进 Service 负载池——补了开源 Nginx 被动检查的短板。
6. 因为本站双栈模型不变，所以 K8s 里仍是 API 与页面两路——换的是载体不是产品拓扑。
7. 因为官方 K8s Ingress API 偏通用，所以高级 Nginx 能力靠实现特定注解扩展——先 API 后注解。

你可能会懵的地方

• Ingress 和 Service 谁做负载均衡？
  Service 在集群内把流量分到 Pod；Ingress 做 七层 Host/path 与 TLS。两者常一起出现。

• pathType Prefix 会不会吃掉错误路径？
  / 是兜底；务必把 /api 写清楚。更细规则可看 ImplementationSpecific。

• rewrite 剥前缀失败怎么办？
  表现与裸机 proxy_pass 尾斜杠错误类似：上游 404。对照 Spring 映射与注解，用临时调试 Ingress 验证。

• 是否还要学裸机 Nginx？
  要。配置语义、排错日志、本地预发仍常用；Ingress 是同构概念的声明式外壳。

错法对照

错法	问题	正解
Ingress 直接指 Pod IP	Pod 重建即失效	指 Service
混用不同 Controller 注解	静默无效	按实际 Controller 文档
只有 / 一条 path	API 进错服务	分 /api 与 /
忽略 readiness	流量打到未就绪 Pod	配探针与资源请求
以为上了 Ingress 就不用懂 proxy_pass	排错不会推演	保留裸机语义心智

自测三问

1. 裸机 location /api/ 在 Ingress 里大致对应什么？
2. TLS 文件与 TLS Secret 在流程上有何相似点？
3. 为什么说 readiness 补了开源 Nginx 健康检查的短板？

小结一句话

Ingress 是声明式的集群版路由；双 path 仍对应 API 8080 与 Next 3000，证书与探针换了载体。

官方延伸

• Kubernetes Ingress
• Ingress-Nginx（若选用该类 Controller）