2026-09-09 19:45:25 +00:00
8 changed files with 6187 additions and 14 deletions
@@ -30,6 +30,9 @@ What changed in this homelab, when, and why. Newest first.
 | identity | Declared the Samba AD `gitea-admins` group with `panxiao81` as its initial member. Gitea already maps this OIDC group to site administrators; the local `gitea_admin` account remains as break-glass access |
 | docs | Reconciled the redesign and CI status with reality: the Gitea remote, instance-scoped runner, OpenBao-projected registration token and green Stage 1 are live; Flux, off-site mirroring and recovery verification remain pending |
 | 协作规范 | 在 `AGENTS.md` 中明确：homelab 向 `git.ddupan.top` 提交的 commit message、PR、issue 与项目文档默认优先使用中文，同时保留必要的英文技术标识符 |
+| k3s | 在本机逐级从 `v1.33.6+k3s1` 升级到 `v1.33.13+k3s2`、`v1.34.11+k3s1`、`v1.35.8+k3s1`，最终到 `v1.36.4+k3s1`；每一级均建立 SQLite/server 冷备份并验证节点、工作负载、PVC、Gateway、DNS 与 Gitea。k3s 每次重启都会覆盖 CoreDNS 的手工 `serve_stale`，已按 `platform/k3s/Corefile.desired` 恢复 |
+| GitOps | 加入固定 Flux `v2.9.5` 的四个核心 controller、集群内只读 Gitea source 和 `prune: false` 的 root Kustomization，等待 PR 合并后从本机首次 bootstrap |
+| cleanup | 准备彻底删除集群内不再承载流量的 Contour provisioner、RBAC、GatewayClass 和 CRD；先把 `bao-acme` HTTP-01 solver 从已不存在的 Contour Gateway 改到 Envoy Gateway 的明文 listener |

 `Carried forward`: re-verify OpenBao/ESO recovery and remaining Secret inventory;
 configure an off-site Git mirror; plan the Gitea upgrade beyond 1.25.5;
@@ -1,15 +1,37 @@
-# Homelab cluster
+# Homelab 集群

-This directory will become the Flux reconciliation entrypoint for the homelab
-k3s cluster. It is intentionally documentation-only until a Git remote, CI
-checks and a low-risk bootstrap workload have been verified.
+这里是单节点 k3s 集群的 Flux reconciliation 入口。集群当前运行 Kubernetes
+`v1.36.4+k3s1`，Flux 固定为 `v2.9.5`。

-Planned reconciliation order:
+## 首次 bootstrap

-1. namespaces and CRDs;
-2. shared platform controllers;
-3. secret references and storage;
-4. applications.
+仓库经过 PR 审查并合并后，在本机从合并后的 `main` 执行：

-Do not enable pruning for a path until its live resources and field ownership
-have been audited.
+```bash
+sudo k3s kubectl apply -f clusters/homelab/flux-system/gotk-components.yaml
+sudo k3s kubectl apply -f clusters/homelab/flux-system/gotk-sync.yaml
+```
+
+`GitRepository/flux-system` 通过集群内 Gitea Service 读取公开仓库，不需要长期
+管理员 token，也不依赖 Cloudflare、公网 DNS 或 Envoy Gateway。Gitea 暂时不可用
+时，已经应用的资源继续运行，Flux 在 Gitea 恢复后重新同步。
+
+root Kustomization 从 `./clusters/homelab` 开始 reconciliation。初始设置
+`prune: false`；在逐项审计现有资源和 field ownership 之前不得开启全局 prune。
+
+计划中的 reconciliation 顺序：
+
+1. namespaces 和 CRD；
+2. platform controllers；
+3. secret references 和 storage；
+4. applications。
+
+首次部署后的最低验证：
+
+```bash
+sudo k3s kubectl -n flux-system get pods
+sudo k3s kubectl -n flux-system get gitrepositories,kustomizations
+```
+
+四个 controller、GitRepository 和 root Kustomization 都必须为 Ready，随后才能
+通过单独 PR 引入低风险 canary workload。
@@ -0,0 +1,20 @@
+# Contour 退役清理
+
+Envoy Gateway 已经承载全部现用 `Gateway` 和 `HTTPRoute`。Contour 在集群中仅剩
+gateway provisioner、RBAC、旧 `GatewayClass` 和没有实例的 CRD，不再承载流量。
+
+清理必须在本变更合并后进行，顺序如下：
+
+1. 应用更新后的 `platform/cert-manager/clusterissuer-bao-acme.yaml`，把 OpenBao
+   HTTP-01 solver 改到 `envoy-gateway-system/eg` 的 `http` listener；
+2. 确认 `Gateway/eg` 为 `Programmed=True`，所有现用 `HTTPRoute` 保持正常；
+3. 删除 `GatewayClass/contour`；
+4. 删除 `projectcontour` namespace；
+5. 删除名称包含 `contour` 的遗留 ClusterRole/ClusterRoleBinding；
+6. 在确认所有 Contour 自定义资源均为空后，删除 `projectcontour.io` 的五个 CRD；
+7. 复查 Envoy Gateway、证书、DNS 和现用入口。
+
+这些对象是 Flux 启用前留下的孤立资源，首次清理由本机 `kubectl` 完成。Flux 的
+root Kustomization 初始保持 `prune: false`，不会借 bootstrap 顺带删除 brownfield
+资源。
+
@@ -0,0 +1,27 @@
+---
+apiVersion: source.toolkit.fluxcd.io/v1
+kind: GitRepository
+metadata:
+  name: flux-system
+  namespace: flux-system
+spec:
+  interval: 1m
+  ref:
+    branch: main
+  timeout: 60s
+  url: http://gitea-http.gitea.svc.cluster.local:3000/panxiao81/homelab-infra.git
+---
+apiVersion: kustomize.toolkit.fluxcd.io/v1
+kind: Kustomization
+metadata:
+  name: flux-system
+  namespace: flux-system
+spec:
+  interval: 10m
+  path: ./clusters/homelab
+  prune: false
+  sourceRef:
+    kind: GitRepository
+    name: flux-system
+  timeout: 3m
+  wait: true
@@ -0,0 +1,5 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+resources:
+  - gotk-components.yaml
+  - gotk-sync.yaml
@@ -0,0 +1,4 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+resources:
+  - flux-system
@@ -32,12 +32,12 @@ spec:
      # http-01, not dns01: bao resolves ad.ddupan.top and can reach LAN hosts
      # directly (noted as verified in openbao/terraform/pki.tf), so it can fetch
      # the challenge over the LAN with no public exposure. cert-manager creates a
-      # temporary HTTPRoute on the shared Contour gateway to answer it.
+      # temporary HTTPRoute on the shared Envoy Gateway to answer it.
      - http01:
          gatewayHTTPRoute:
            parentRefs:
-              - name: contour-gateway
-                namespace: projectcontour
+              - name: eg
+                namespace: envoy-gateway-system
                kind: Gateway
                group: gateway.networking.k8s.io
                sectionName: http     # the plaintext :80 listener