Deploy-Laboratory/docs/02-00-nginx-系列说明.md

02-00 Nginx 矩阵系列说明（节点 + Ingress / IngressRoute）

目的：先把本系列（02-0102-05）共用的“节点调度规则”和“Traefik 路由对象差异”讲清楚，后面的 02-0102-04 分篇才能读得更快、减少常见误区。

TL;DR

• 自动化验收：本篇为系列说明页，不参与 verify.sh run-all/full
• 关键前置：按本文说明准备节点标签、路由对象与入口路径认知
• 成功判据：你能区分 M1~M4 的节点落点与 Ingress/IngressRoute 差异，并据此进入 02-01~02-05
• 排障：见本文「排障」

---

分课真源（02-01～02-04）

• ansible/files/02-01/～02-04/：各含与 ansible/files/02-05/ 对应课节同构的 YAML，专供分篇学习时解耦（复制到目标路径 → 改 nodeSelector/hostname → kubectl/bash）。
• 手动：以各课文档中的 ansible/files/02-XX/*.yaml 为准，不必使用 verify。
• 自动：分课 ./ansible/bin/verify.sh run 02-01 … 02-04；四场景一键仍用 02-05 与 verify.sh run 02-05。

---

1. 节点与调度（M1~M4 到底落在哪）

本仓库的 nginx 矩阵里，4 个场景 M1~M4 的“落点”不同，主要通过 nodeSelector 控制。

1.1 查看 node-role 与 hostname（用于排查 nodeSelector）

# 1) 最直观：查看所有节点的全部 labels
kubectl get nodes --show-labels

# 2) 检查 hostname label（用于 M2/M4）
kubectl get nodes -l kubernetes.io/hostname=<hostname> -o name

# 3) 检查 control-plane label（用于 M1）
kubectl get nodes -l node-role.kubernetes.io/control-plane -o name

# 4) 检查 worker label（用于 M3）
kubectl get nodes -l node-role.kubernetes.io/worker -o name

# 5) 最后：查看单节点全部信息（Labels / Taints / Events）
kubectl describe node <节点名>

提示：如果你在 M2/M4 里写的是 nodeSelector: kubernetes.io/hostname: ylc61，但该节点没有打上 kubernetes.io/hostname=ylc61 这个 label，则 M2/M4 会匹配不到。

1.2 M1 / M2：控制节点（control-plane）

• M1（Ingress）：用 nodeSelector: node-role.kubernetes.io/control-plane: "" + tolerations（允许调度到控制节点的 NoSchedule 污点）。
• M2（IngressRoute）：用 nodeSelector: kubernetes.io/hostname: ylc61（指定某一台控制节点）。

如果你看到 M1/M2 的 Pod 一直 Pending：

• 通常是控制节点缺少对应的 label（node-role.kubernetes.io/control-plane 或 hostname 不匹配）
• 或者存在 taint 没有匹配到 M1 的 toleration

1.3 M3 / M4：工作节点（worker）

• M3（Ingress）：nodeSelector: node-role.kubernetes.io/worker: ""，因此会“随机落在任意 worker”。
• M4（IngressRoute）：nodeSelector: kubernetes.io/hostname: ylc64，指定某一台 worker。

如果你看到 M3/M4 落不到目标节点：

• 确认 worker 节点带有 node-role.kubernetes.io/worker 标签（M3）
• 或 hostname 是否与你写入的 ylc64 一致（M4）

---

2. Ingress vs IngressRoute（Traefik 路由对象差异）

本项目使用 Traefik：

• Ingress：Kubernetes 原生对象 kind: Ingress（依赖 Ingress Controller 对接）
• IngressRoute：Traefik CRD 对象 kind: IngressRoute（需要 CRD 已启用）

在本系列中，它们还体现为两类“路由写法”：

2.1 Ingress（用于 M1 / M3）

• 采用 spec.rules.http.paths，典型写法是：
  • path: /demo-mx
  • pathType: Prefix
• 中间件挂载方式在本仓库的示例里使用 annotation：
  • traefik.ingress.kubernetes.io/router.middlewares: default-stripprefix-mx@kubernetescrd

2.2 IngressRoute（用于 M2 / M4）

• 采用 spec.entryPoints + spec.routes，并使用 match：
  • entryPoints: [web]
  • match: PathPrefix(\/demo-mx`)`
  • services 指向对应 Service
  • middlewares 在 CRD 内直接引用（name: stripprefix-mx）

---

3. /demo-mx 路由结构（为什么还要 Middleware）

每个 Mx 都有一个 Middleware（kind: Middleware）做 stripPrefix：

• 前缀例如 /demo-m1
• 去掉前缀后，nginx 才能把请求当成 / 来返回 index.html

因此在本系列里：

• 你访问 http://<入口节点IP>/demo-m1/ 会先经过 stripPrefix
• ngnix 最终拿到的是 /
• 页面中会显示本场景的标识（M1/M2/M3/M4），便于你确认落点与路由是否正确

---

4. 本系列的“共同资源”你应该知道怎么删/怎么验证

所有 M1~M4 都在同一个命名空间 default：

• Pod/Service：kubectl get pod,svc -n default ...
• Ingress/IngressRoute：分别 kubectl get ing -n default 或 kubectl get ingressroute -n default

通用删除建议使用 manifests 目录（一键清理同一个场景）：

kubectl delete -f ansible/files/02-05/ -R

或按具体文件删单个场景（见各分篇的 ## 删除 小节）。

---

5. 推荐阅读顺序

1. 02-00-nginx-系列说明.md（本页）
2. 02-01~02-04（按你关心的节点落点/路由对象读）
3. 02-05-nginx-验证矩阵-一键部署.md（最终整合、一次验证 4 个场景）

排障

• 先看 playbook 输出：失败时先定位是 deploy/wait/http_check 哪一步。
• 集群侧总览：kubectl get nodes -o wide、kubectl -n kube-system get pods -o wide。
• 事件与日志：kubectl -n <ns> describe ...、kubectl -n <ns> logs ... --tail=200。