Deploy-Laboratory/docs/03-09-k3s-gitops-集群配置管理.md

03-09-k3s-gitops-集群配置管理（框架草案）

本文先给出 GitOps 管理 k3s 集群的大致框架，后续可以按需要再细化成完整实践。 目标：在 01-05 自动装好 k3s 之后，由 GitOps 工具（Argo CD / Flux）自动把 Traefik、监控、应用等 YAML 下发到集群。

契约与真源

• 本仓库示意：ansible/files/03-09/argocd-namespace.example.yaml（极简 Namespace；正式安装请用 Argo CD 官方 install.yaml 或 Helm），索引见 ansible/files/03-09/README.md。
• 主真源：独立 GitOps 仓库（见下文「仓库结构建议」）；本目录仅与文档对齐的辅助文件。
• 手动 / 自动：kubectl apply -f ansible/files/03-09/argocd-namespace.example.yaml 可与 ./ansible/bin/verify.sh run 03-09 共用同一路径，避免文档与仓库脱节。

TL;DR

• 自动化验收：./ansible/bin/verify.sh run 03-09
• 关键前置：按本文「前置条件」准备环境变量/Secret/入口 IP
• 成功判据：达到本文「预期」且 playbook 断言通过
• 排障：见本文「排障」

1. 选型与边界

• GitOps 工具二选一：
  • Argo CD：UI 友好、概念清晰，适合个人实验；
  • Flux：更轻量，完全 Git 驱动，命令行为主。
• 建议先选其中一个，不要在同一集群同时跑两套 GitOps。

2. 仓库结构建议（与本仓库的关系）

建议将「集群声明性配置」与本仓库代码/文档区分开，形成一个专门的 GitOps 仓库，例如：

homelab-k3s-gitops/
  clusters/
    ylc-k3s-01/
      kustomization.yaml
  apps/
    traefik/
    monitoring/
    homer/
    openlist/
    gitlab/

本仓库依然作为「文档 + 脚本 + ansible playbook」的入口，GitOps 仓库只存 K8s 清单。

3. 最小 Argo CD 部署思路（示意）

如果未来你决定使用 Argo CD，可以按以下思路展开（这里不给出完整清单，仅做导航）：

1. 在 k3s 集群中安装 Argo CD（官方 install.yaml 或 Helm）；
2. 暴露 Argo CD Server（通过 Traefik IngressRoute 或 NodePort）；
3. 在 Argo CD 中创建一个 Application，指向 GitOps 仓库的 clusters/ylc-k3s-01；
4. 在 clusters/ylc-k3s-01/kustomization.yaml 中列出：
   • Traefik 扩展配置；
   • Prometheus+Grafana；
   • Homer、openlist、GitLab 等应用的 Kustomize/Helm 目录。

4. 与现有文档的衔接

• 01-05-节点初始化-ansible-实践.md：负责从「可 SSH 裸机」到「k3s 就绪」；
• 本篇 03-09：负责从「k3s 就绪」到「配置由 Git 驱动下发」；
• 其他 02-**、04-**、05-** 文档中的部署命令，可以逐步迁移为 GitOps 仓库中的 YAML/Kustomize/Helm 定义。

5. 后续可以补充的内容（TODO）

• 针对 Argo CD 或 Flux 选定一个具体方案，写出：
  • 详细安装步骤；
  • GitOps 仓库的完整示例结构；
  • 与 Cloudflare Tunnel、监控、openlist 等现有专题的映射关系。

排障

• 先看 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。