基本框架

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

@@ -0,0 +1,112 @@
+# 02-00 Nginx 矩阵系列说明（节点 + Ingress / IngressRoute）
+
+> 目的：先把本系列（02-01~02-05）共用的“节点调度规则”和“Traefik 路由对象差异”讲清楚，后面的 02-01~02-04 分篇才能读得更快、更少踩坑。
+
+---
+
+## 1. 节点与调度（M1~M4 到底落在哪）
+
+本仓库的 nginx 矩阵里，4 个场景 M1~M4 的“落点”不同，主要通过 `nodeSelector` 控制。
+
+### 1.1 查看 `node-role` 与 `hostname`（用于排查 nodeSelector）
+
+```bash
+# 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 目录（一键清理同一个场景）：
+
+```bash
+kubectl delete -f ansible/files/nginx-matrix/ -R
+```
+
+或按具体文件删单个场景（见各分篇的 `## 删除` 小节）。
+
+---
+
+## 5. 推荐阅读顺序
+
+1. `02-00-nginx-系列说明.md`（本页）
+2. `02-01~02-04`（按你关心的节点落点/路由对象读）
+3. `02-05-nginx-验证矩阵-一键部署.md`（最终整合、一次验证 4 个场景）
+