4.3 Ingress：庄园大门与路牌

4.3 Ingress：庄园大门与路牌

本节摘要：Ingress 是七层（HTTP 与 HTTPS）的入口规则对象，按域名与路径把外部流量路由到不同 Service；它自己只是"路牌规则"，真正开门的是必须单独部署的 Ingress Controller。本节为绿荫书屋配置正式域名入口，讲解 Controller 的角色、TLS 证书挂载要点与 Ingress 和 Service 的分工边界。

大门为什么不能用水闸凑合

到上一节为止，外部访客想看书屋网页，只能敲"某个节点的 IP 冒号 30080"。这种入口给测试用还行，正式营业有三个过不去的地方：地址不好看（谁家官网带端口号）、一张证书都不配（明文走网线）、所有服务各开一个洞（洞多了管不过来）。生产需要的是一扇正经大门：一个固定域名、统一证书、按路径分流的入口。

这就是 Ingress 的岗位，手册里叫大门与路牌。与水闸的关键区别在层次：Service 工作在四层（IP 与端口层面搬运水流），Ingress 工作在七层（读得懂 HTTP 请求里的域名与路径）。能读懂请求，才做得到"看牌分流"：greenlib.example.com 归网页组，斜杠 api 开头的请求转给接口组。

图：一扇大门后的路牌系统

一个容易忽略的角色：Controller

新手最常在这里迷惑：apply 了一份 Ingress，访问却 404。原因几乎总是——没装 Ingress Controller。Ingress 对象本质只是一份路牌规则躺在台账里，得有人守门执行它才行。Controller（常见选型有 Ingress-NGINX、Traefik 等）自己也是集群里的一个部署，通常经由一个 LoadBalancer 或 NodePort 型 Service 对外露面。比喻到位：Ingress 是路牌，Controller 是照牌放行的门卫，门卫不上岗，立再多牌子也没人看。

第九章的试验田教程里会提到装 Controller 的办法（minikube 的 addons 一条命令）。此处假设门卫已在岗，专心立牌子。

给书屋立路牌

# 大门路牌：域名加路径双维度分流
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: greenlib-entry
  namespace: greenlib-prod
spec:
  ingressClassName: nginx          # 交给哪队门卫执行
  tls:                             # 这扇门走 HTTPS
    - hosts:
        - greenlib.example.com
      secretName: greenlib-tls     # 证书存放在第 5 章的农药柜里
  rules:
    - host: greenlib.example.com   # 第一维度：看域名
      http:
        paths:
          - path: /                # 第二维度：看路径
            pathType: Prefix
            backend:
              service:
                name: greenlib-web # 指向水闸（不是苗！）
                port:
                  number: 80
          - path: /api
            pathType: Prefix
            backend:
              service:
                name: greenlib-api
                port:
                  number: 80
​

kubectl apply -f greenlib-ingress.yaml
# ingress.networking.k8s.io/greenlib-entry created

kubectl describe ingress greenlib-entry -n greenlib-prod
# 输出节选：
# Rules:
#   Host                    Path  Backends
#   greenlib.example.com    /     greenlib-web:80 (10.24.0.31:8080,10.24.1.17:8080)
#                           /api  greenlib-api:80 (10.24.2.9:8080)
# 观察点：Backends 直接列出了苗地址，说明门卫已经把路牌翻译成了水管

# 本地验证（把域名临时指到门卫地址）
curl -H "Host: greenlib.example.com" http://<门卫地址>/
# 返回书屋首页 HTML，分流成功
​

describe 的输出里藏着门卫的工作证据：规则表已把每条路牌落到了具体苗地址。再次看到熟悉的模式——规则（Ingress）与执行（Controller）分离，中间靠台账撮合。

TLS 与边界

HTTPS 的证书以 Secret 形式挂给 Controller（清单里的 secretName: greenlib-tls），证书更新时换 Secret 即可，路牌不用动。Secret 的具体保管方式是下一章农药柜的正题。

最后把整条水路串起来收束本章：访客敲域名，DNS（公网的）找到门卫；门卫查路牌，把请求转给对应水闸；水闸按名单分给某株苗。三层里任何一层变化都不影响其他层：换苗不动水闸、换水闸不动路牌、加服务只加一块牌。这条完整水路图值得画在笔记本第一页，它是你此后排查一切"访问不通"问题的地图。

⚠️ 常见坑：路牌的 backend 指向 Service 名与端口，不是 Pod，也不是苗的端口。写成 targetPort（8080）会直接报错；记住牌子上写的是水闸编号（port），闸到苗的换算归水闸管。

大门的排错清单

外部访问不通时，沿水路逆推最有效率：

1. 门卫在岗吗：查 Ingress Controller 的苗，四开头的状态多半是门卫缺席或没装
2. 路牌翻译了吗：describe ingress 看 Rules 表是否已落到具体苗地址
3. 证书配对吗：tls 段引用的 Secret 是否存在、证书与私钥是否成对
4. 水闸有水吗：backend 指向的 Service 及其 Endpoints 是否正常
5. 域名指对吗：公网 DNS 是否解析到门卫的对外地址

五步走完，九成的"进不了门"都能定位。再留一个进阶钩子：路牌还支持按请求头、按权重的精细分流，金丝雀发布（新版先接一小成流量）就长在这些能力上，值得日后专门去翻文档。

本节要点回顾

• Ingress 是七层路牌，按域名与路径分流；Controller 是门卫，必须单独部署
• backend 指向 Service 的名字与 port，不指向苗
• TLS 证书放 Secret，换证书不动路牌
• 完整水路：公网 DNS 找门卫，门卫查牌，水闸分水，苗接水
• 章节收束：通水完毕；下一章把配置从镜像里解耦，ConfigMap 与 Secret 登场