jack/Deploy-Laboratory
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

对齐文件规范

Browse Source
This commit is contained in:
Jack
2026-03-27 16:58:41 +08:00
parent 231b6713c4
commit 31709425e2
235 changed files with 5433 additions and 2850 deletions
Download Patch File Download Diff File Expand all files Collapse all files

47
docs/03-02-k3s-traefik-acme.md
View File

@@ -1,11 +1,19 @@
# 03-02-k3s Traefik ACME
> **状态：✅ 验证已完成**（2026-03，K3s 4 节点 ylc61～ylc64，Cloudflare DNS-01、Let’s Encrypt 证书、TLS 矩阵 `test01～test04.jackadam.top`，HTTPS 与 HTTP-only 各 16 目标均 200；Ansible `nginx-matrix-tls-deploy.yml` 已实机跑通。）
> **状态：✅ 验证已完成**（2026-03，K3s 4 节点 ylc61～ylc64，Cloudflare DNS-01、Let’s Encrypt 证书、TLS 矩阵 `test01～test04.jackadam.top`，HTTPS 与 HTTP-only 各 16 目标均 200；Ansible `03-02.yml -e nginx_matrix_tls_enable=true` 已实机跑通。）
> 为 Traefik 配置 ACME 自动证书（Let's Encrypt + Cloudflare DNS 验证），并部署 **TLS 矩阵**。
>
> **为 02-05 的升级版**：02-05 为 HTTP-only（节点 IP、无域名）；本页在其基础上增加 ACME 证书、域名、根路径 `/`，用于有域名时的学习或生产。
## TL;DR
- **自动化验收**：`./scripts/verify.sh run 03-02`
- **关键前置**：按本文「前置条件」准备环境变量/Secret/入口 IP
- **成功判据**：达到本文「预期」且 playbook 断言通过
- **排障**：见本文「排障」
---
## 前置条件
@@ -21,7 +29,7 @@
- **Pod / 部署**：ACME 配置通过 `HelmChartConfig` 注入到 **同一个 Traefik Deployment**。**副本数为 chart 默认值 1**（即 `deployment.replicas` 未在 values 里写时默认为 1），所以只有 1 个 Traefik Pod；与 03-01 的 Traefik 是同一套 Deployment，只是 values 里多了 ACME 参数与 env。
- **配置存在哪里**：`HelmChartConfig` 存在 **etcd**（控制节点）；K3s 的 chart 控制器据此更新 Traefik 的部署参数，Traefik 进程从 **Kubernetes API** 读取 Ingress/IngressRoute，无需多 Pod 间同步。
- **ACME 存储（证书与账户）**：`acme.storage` 指向容器内 **`/data/acme.json`**。未配 hostPath 时，K3s 默认会为 Traefik 挂载卷到 `/data`（如 emptyDir 或默认持久卷），**仅当前这一个 Traefik Pod 可写**，Pod 重建后若卷不持久则需重新申请证书。若在 values 里配置了 **hostPath**（见本页可选配置），则 `/data` 对应宿主机目录，证书写在物理机路径，便于备份与复用；Traefik 仍为 1 个 Pod，不存在多副本间同步 acme.json 的问题。**推荐**：Dashboard + ACME 场景直接用 **同一份** [`traefik-dashboard-acme.yaml`](../ansible/files/03-03-traefik-dashboard-acme/traefik-dashboard-acme.yaml)（已含 **`persistence`（local-path）+ ACME**），见 `03-05-k3s-local-path-pvc.md`。不要 Dashboard 时按该文件头注释删减。
- **ACME 存储（证书与账户）**：`acme.storage` 指向容器内 **`/data/acme.json`**。未配 hostPath 时，K3s 默认会为 Traefik 挂载卷到 `/data`（如 emptyDir 或默认持久卷），**仅当前这一个 Traefik Pod 可写**，Pod 重建后若卷不持久则需重新申请证书。若在 values 里配置了 **hostPath**（见本页可选配置），则 `/data` 对应宿主机目录，证书写在物理机路径，便于备份与复用；Traefik 仍为 1 个 Pod，不存在多副本间同步 acme.json 的问题。**推荐**：Dashboard + ACME 场景直接用 **同一份** [`traefik-dashboard-acme.yaml`](../ansible/files/03-03/traefik-dashboard-acme.yaml)（已含 **`persistence`（local-path）+ ACME**），见 `03-05-k3s-local-path-pvc.md`。不要 Dashboard 时按该文件头注释删减。
- **第一次部署随机节点、重启后怎么办**：Traefik 未指定 nodeSelector 时，首次会**随机调度**到某一节点。若使用了 **hostPath**，证书只存在于该节点的磁盘上；**Pod 被调度到其他节点**（重启、驱逐、缩容再扩容）时，新节点上的同名 hostPath 是另一块盘，**证书不会跟着走**，可能需重新申请。若希望重启或节点故障后仍保留证书，可：**① 把 Traefik 固定到某一节点**（在 HelmChartConfig 的 `deployment` 下配 `nodeSelector`，例如 `nodeSelector: { kubernetes.io/hostname: ylc61 }（节点名使用短主机名 ylc61～ylc64，便于配合 Cloudflare CDN）`），使 hostPath 始终落在同一台机；**② 或不用 hostPath**，依赖 K3s 默认持久卷（若为 local-path，则卷仍绑定某节点，Pod 重建到同节点可复用）；**③ 或改用 NFS 等共享存储**挂到 `/data`，多节点可读同一证书（需自行在 values 里配 PVC/volume）。
---
@@ -86,11 +94,11 @@ kubectl -n kube-system get secret cloudflare-api-token \
## 配置 HelmChartConfig
> **重要**：同一 chart 只能有一份 `HelmChartConfig`（如 `name: traefik`）。若已按 03-01 部署了 Dashboard，再单独 apply 本文件的配置会**覆盖**掉 03-01，Dashboard 会失效。此时应二选一：**要么**使用 `03-03-k3s-traefik-dashboard-acme.md` 中的合并 YAML（Dashboard + ACME 一份搞定），**要么**把本页的 ACME 配置合并进已有 03-01 的 `traefik-dashboard.yaml`，只保留一个 manifest 文件。
> **重要**：同一 chart 只能有一份 `HelmChartConfig`（如 `name: traefik`）。若已按 03-01 部署了 Dashboard，再单独 apply 本文件的配置会**覆盖**掉 03-01，Dashboard 会失效。此时应二选一：**要么**使用 `03-03-k3s-traefik-dashboard-acme.md` 中的合并 YAML（Dashboard + ACME 合并为单一清单），**要么**把本页的 ACME 配置合并进已有 03-01 的 `traefik-dashboard.yaml`，只保留一个 manifest 文件。
>
> **文件选择**：K3s 自带的 `traefik.yaml` 会被 K3s 覆盖，**不要修改**。所有自定义配置（ACME、nodeSelector、hostPath 以及其他扩展配置）都应写在 **`traefik-acme.yaml`** 这一份 HelmChartConfig 里，与默认 chart 合并生效。
1. 在控制节点创建 `traefik-acme.yaml`，推荐放入 K3s manifests 目录（路径同 03-01）。**完整配置见 `ansible/files/03-02-traefik-acme/traefik-acme.yaml`**（与 Ansible 共用），复制后替换 `<YOUR_REAL_EMAIL>` 等占位符即可。若走 **Dashboard + ACME** 且需 **证书落盘 local-path PVC**，直接用 [`traefik-dashboard-acme.yaml`](../ansible/files/03-03-traefik-dashboard-acme/traefik-dashboard-acme.yaml)（已内置 persistence，说明见 `03-05-k3s-local-path-pvc.md`）。**仅 ACME、无 Dashboard** 时仍可用本目录 [`traefik-acme.yaml`](../ansible/files/03-02-traefik-acme/traefik-acme.yaml)，并自行按 `03-05` 在 Helm values 中增加 `persistence` 块（与 `/data/acme.json` 一致）。
1. 在控制节点创建 `traefik-acme.yaml`，推荐放入 K3s manifests 目录（路径同 03-01）。**完整配置见 `ansible/files/03-02/traefik-acme.yaml`**（与 Ansible 共用），复制后替换 `<YOUR_REAL_EMAIL>` 等占位符即可。若走 **Dashboard + ACME** 且需 **证书落盘 local-path PVC**，直接用 [`traefik-dashboard-acme.yaml`](../ansible/files/03-03/traefik-dashboard-acme.yaml)（已内置 persistence，说明见 `03-05-k3s-local-path-pvc.md`）。**仅 ACME、无 Dashboard** 时仍可用本目录 [`traefik-acme.yaml`](../ansible/files/03-02/traefik-acme.yaml)，并自行按 `03-05` 在 Helm values 中增加 `persistence` 块（与 `/data/acme.json` 一致）。
> 将 `<YOUR_REAL_EMAIL>` 改为你的邮箱。`/data/acme.json` 为容器内路径；`caserver` 为测试服务器（staging），正式上线前删除该行即切回生产 CA。Traefik 在容器内监听 8000/8443，由 Service 和 svclb 映射到节点 80/443。
>
@@ -185,7 +193,7 @@ kubectl -n kube-system exec -it "$POD" -- nslookup acme-v02.api.letsigncrypt.org
## TLS 矩阵清单（02-05 升级版）
> **唯一真源**：[`ansible/files/03-02-nginx-matrix-tls/`](../../ansible/files/03-02-nginx-matrix-tls/)（`01-control-ingress.yaml`～`04-worker-ingressroute.yaml`），与 [`ansible/playbooks/nginx-matrix-tls-deploy.yml`](../../ansible/playbooks/nginx-matrix-tls-deploy.yml) 共用；**本文不再内联整份 YAML**。
> **唯一真源**：[`ansible/files/03-02/`](../../ansible/files/03-02/)（`01-control-ingress.yaml`～`04-worker-ingressroute.yaml`），与 [`ansible/playbooks/verify/03-02.yml`](../../ansible/playbooks/verify/03-02.yml) 共用；**本文不再内联整份 YAML**。
**相对 02-05 的差异摘要**：基于域名根路径 `/`；TLS 仅绑 `websecure`；含 HTTP-only（仅 `web`）路由；与 02-05 的 `/demo-mx` 为两套资源；M2/M4 节点名与域名请在清单内编辑。
@@ -197,12 +205,12 @@ kubectl -n kube-system exec -it "$POD" -- nslookup acme-v02.api.letsigncrypt.org
**方式一：使用仓库 YAML 目录（推荐与文档一致）**
1. 在仓库中编辑 [`ansible/files/03-02-nginx-matrix-tls/`](../../ansible/files/03-02-nginx-matrix-tls/) 内各文件（M2/M4 节点名、域名等）。
2. 按 k3s 存储方案可将整个目录复制到控制节点 manifests，或直接在仓库根执行 `kubectl apply -f ansible/files/03-02-nginx-matrix-tls/ -R`（与 `01-01-k3s-控制节点含traefik.md` 存储路径说明一致）。
1. 在仓库中编辑 [`ansible/files/03-02/`](../../ansible/files/03-02/) 内各文件（M2/M4 节点名、域名等）。
2. 按 k3s 存储方案可将整个目录复制到控制节点 manifests，或直接在仓库根执行 `kubectl apply -f ansible/files/03-02/ -R`（与 `01-01-k3s-控制节点含traefik.md` 存储路径说明一致）。
3. 清理示例（路径与 apply 时一致）：
```bash
kubectl delete -f ansible/files/03-02-nginx-matrix-tls/ -R --ignore-not-found=true
kubectl delete -f ansible/files/03-02/ -R --ignore-not-found=true
```
或沿用下文按资源名删除。
或按资源名删除（与路径无关）：
@@ -217,12 +225,12 @@ kubectl -n kube-system exec -it "$POD" -- nslookup acme-v02.api.letsigncrypt.org
- 直接使用仓库中已合并好的 4 个文件（每个 Mx 含 TLS + HTTP-only），在**仓库根目录**执行：
```bash
kubectl apply -f ansible/files/03-02-nginx-matrix-tls/ -R
kubectl apply -f ansible/files/03-02/ -R
```
需保证当前环境已设置 KUBECONFIG 或 `kubectl` 已指向目标集群（例如在控制节点上或已配置远程 kubeconfig）。
- 一键部署/清理推荐用 Playbook（会先删 02-05 残留、再 apply、并做就绪与 curl 验证）：
- 在 `ansible/` 目录下：`ansible-playbook -i inventory.ini playbooks/nginx-matrix-tls-deploy.yml`
- 在仓库根目录：`ansible-playbook -i ansible/inventory.ini ansible/playbooks/nginx-matrix-tls-deploy.yml`
- 在 `ansible/` 目录下：`ansible-playbook -i inventory.ini playbooks/verify/03-02.yml`
- 在仓库根目录：`ansible-playbook -i ansible/inventory.ini ansible/playbooks/verify/03-02.yml`
- 清理：同上命令后加 `-e mode=cleanup`。
验证 HTTP 与 HTTPS 是否正常（将 `192.168.2.61 … 192.168.2.64` 按实际入口节点 IP 修改）：
@@ -258,7 +266,7 @@ done
```bash
kubectl get ingress -n default nginx-m1 -o yaml | grep -A5 "tls:\|host:\|certresolver"
```
若无 `tls` / `host` / `certresolver`，说明当前是 02-05 的非 TLS Ingress，需执行 `kubectl apply -f ansible/files/03-02-nginx-matrix-tls/ -R`（或跑 Ansible playbook `nginx-matrix-tls-deploy.yml`）。
若无 `tls` / `host` / `certresolver`，说明当前是 02-05 的非 TLS Ingress，需执行 `kubectl apply -f ansible/files/03-02/ -R`（或跑 Ansible playbook `03-02.yml -e nginx_matrix_tls_enable=true`）。
2. **看 Traefik 是否尝试/成功申请证书**：
```bash
@@ -281,7 +289,7 @@ done
6. **日志出现 “service not found” / “kubernetes service not found: default/nginx-m2” / “middleware … does not exist”**：说明 Ingress/IngressRoute 已存在，但对应的 **Service 或 Middleware 缺失**（例如只 apply 了部分 TLS 矩阵，或先删后 apply 时 Traefik 在中间时刻读到不完整状态）。需**完整** apply TLS 矩阵，保证 M1～M4 的 Deployment、Service、Middleware、Ingress/IngressRoute 一起就绪：
```bash
kubectl apply -f ansible/files/03-02-nginx-matrix-tls/ -R
kubectl apply -f ansible/files/03-02/ -R
kubectl get svc,middleware -n default | grep -E "nginx-m|stripprefix"
```
确认 nginx-m1～m4 的 Service 与 stripprefix-m1～m4 的 Middleware 均存在后，Traefik 会重新同步路由；证书仍需按上一步确保 ACME 配置生效。
@@ -311,18 +319,18 @@ done
可使用 Ansible 自动部署 / 清理 TLS 矩阵（test01～test04.jackadam.top）并做 HTTPS 验证：
- **Playbook**：`ansible/playbooks/nginx-matrix-tls-deploy.yml`
- **Manifests**：`ansible/files/03-02-nginx-matrix-tls/`（M1～M4 带 TLS，域名为 test01～test04.jackadam.top；按实际修改 M2/M4 节点名 ylc61/ylc64）
- **Playbook**：`ansible/playbooks/verify/03-02.yml`
- **Manifests**：`ansible/files/03-02/`（M1～M4 带 TLS，域名为 test01～test04.jackadam.top；按实际修改 M2/M4 节点名 ylc61/ylc64）
- **前置**：已按本页完成 ACME 配置，且 test01～test04.jackadam.top 已解析到入口 IP
```bash
# 一键部署 TLS 矩阵
cd ansible
ansible-playbook -i inventory.ini playbooks/nginx-matrix-tls-deploy.yml -e mode=deploy
ansible-playbook -i inventory.ini playbooks/verify/03-02.yml -e mode=deploy
# 一键删除 TLS 矩阵
cd ansible
ansible-playbook -i inventory.ini playbooks/nginx-matrix-tls-deploy.yml -e mode=cleanup
ansible-playbook -i inventory.ini playbooks/verify/03-02.yml -e mode=cleanup
```
Playbook 在 `mode=deploy` 时会：拷贝 TLS manifests 到控制节点 → **若存在不含 TLS 的 nginx 矩阵（02-05），先按资源名删除**（deployments、svc、ingress、ingressroute、configmaps 共 M1～M4）→ `kubectl apply` TLS 矩阵 → 等待 Pod 就绪 → 对**所有 k3s_nodes 节点**做 HTTPS 验证（4 节点 × 4 域名 = 16 个目标，与 02-05 HTTP 矩阵一致，所有节点均为入口点）。`mode=cleanup` 时则按资源名删除 TLS 矩阵相关 Deployment/Service/Ingress/IngressRoute/ConfigMap，并清理 `/tmp/nginx-matrix-tls` 目录，恢复到未部署 TLS 矩阵前的状态。
@@ -382,3 +390,8 @@ sudo rm -f /storage/server/manifests/traefik-acme.yaml
- 返回 00-00-构建总览.md，按导航继续。
## 排障
- **先看 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`。