Merge pull request '分阶段接管 External Secrets Helm release' (#32) from feat/external-secrets-adoption-stage into main

Reviewed-on: #32

clusters/homelab/README.md

@@ -43,6 +43,7 @@ sudo k3s kubectl -n flux-system get gitrepositories,kustomizations
 - `http-echo` 的专用测试 ConfigMap 已在 `prune: true` 生效后重新纳管，并由下一
   revision 自动删除；
 - `http-echo` 保持 `prune: true`，root 保持 `prune: false`；
-- `gitea-actions` 已由 Flux HelmRelease 接管且首次 reconcile 未触发 runner rollout；
+- `gitea-actions` 与 `gitea` 已由 Flux HelmRelease 接管，Gitea 已升级到 `1.27.3`；
-- 下一个接管对象是现有 `gitea` Helm release，先固定 chart `12.5.3` 并分两阶段完成
+- 当前接管对象是 External Secrets Operator：先固定现有 chart `2.8.0` 并以
-  零变化 adoption，再通过独立 PR 升级 Gitea。
+  `suspend: true` 登记，确认零变化后再独立激活；
+- root Kustomization 与所有 brownfield 子 Kustomization 继续保持 `prune: false`。

clusters/homelab/apps/external-secrets.yaml

@@ -0,0 +1,14 @@
+apiVersion: kustomize.toolkit.fluxcd.io/v1
+kind: Kustomization
+metadata:
+  name: external-secrets
+  namespace: flux-system
+spec:
+  interval: 10m
+  path: ./platform/external-secrets
+  prune: false
+  sourceRef:
+    kind: GitRepository
+    name: flux-system
+  timeout: 3m
+  wait: false

clusters/homelab/kustomization.yaml

@@ -3,6 +3,7 @@ kind: Kustomization
 resources:
   - flux-system
   - namespaces/gitops-canary.yaml
+  - apps/external-secrets.yaml
   - apps/gitea.yaml
   - apps/gitea-actions.yaml
   - apps/http-echo.yaml

docs/homelab-gitops-redesign.md

@@ -213,11 +213,10 @@ offline break-glass path. ESO-generated Secrets are projections, not backups.
 4. **Complete:** the reviewed Gitea Runner and Stage 1 CI are live. Flux deploys
    `http-echo`; automatic deployment, replica drift repair and scoped deletion
    were verified. Root prune remains disabled for brownfield safety.
-5. **Next:** adopt the existing `gitea-actions` Helm release with the same chart
+5. **In progress:** Gitea Actions and Gitea are managed by Flux. Adopt External
-   `0.1.1` and repository values before attempting an upgrade. Its live
+   Secrets Operator next with its existing chart `2.8.0` and repository values;
-   StatefulSet and Git both use regular DinD, while Helm's stored release values
+   register the suspended release first, then activate it in a separate PR after
-   still describe the failed rootless attempt. The first Flux reconciliation
+   proving the fixed render matches Helm's stored manifest.
-   must repair this stored-state drift without changing the live Pod spec.
 6. Move Tunnel origins to Envoy and consolidate split DNS through Blocky.
 7. Deploy Backstage read-only with Catalog, Kubernetes, Flux and TechDocs.
 8. Reconstruct the OCI root to a zero-change plan and add libvirt drift reports.

platform/external-secrets/README.md

@@ -0,0 +1,20 @@
+# External Secrets Operator
+
+External Secrets Operator（ESO）把 OpenBao `kv/k8s/*` 下的值投影为 Kubernetes
+Secret。`ClusterSecretStore/openbao` 使用 `external-secrets` ServiceAccount 的短期
+JWT 登录 OpenBao，不在 Git 中保存长期凭据。
+
+## Flux 接管
+
+现有 release 是 2026-07-28 手工安装的 chart `external-secrets` `2.8.0`，Helm
+revision 1。接管前审计确认：本目录 `values.yaml` 与 Helm stored user values 一致；
+用固定 chart 生成的 33,528 行 manifest 与 stored manifest 只有末尾空行差异。
+
+接管分两阶段：本阶段以 `suspend: true` 登记 HelmRepository、values ConfigMap 与
+HelmRelease，不执行 Helm action，不应重建三个 controller。合并后确认 source Ready、
+release 仍为 revision 1、三个 Pod UID/重启次数不变，再用独立 PR 移除 `suspend`。
+子 Kustomization 保持 `prune: false`。
+
+`clustersecretstore.yaml` 和 `externalsecrets.yaml` 是现有 secret delivery intent，
+本阶段故意不把它们加入该 Kustomization，避免在 Helm release 接管时同时扩大 Flux
+ownership。Helm 接管稳定后再单独审计、纳管这些对象。

platform/external-secrets/helmrelease.yaml

@@ -0,0 +1,32 @@
+apiVersion: helm.toolkit.fluxcd.io/v2
+kind: HelmRelease
+metadata:
+  name: external-secrets
+  namespace: external-secrets
+spec:
+  suspend: true
+  chart:
+    spec:
+      chart: external-secrets
+      interval: 1h
+      sourceRef:
+        kind: HelmRepository
+        name: external-secrets
+      version: 2.8.0
+  driftDetection:
+    mode: enabled
+  install:
+    strategy:
+      name: RetryOnFailure
+      retryInterval: 5m
+  interval: 30m
+  releaseName: external-secrets
+  targetNamespace: external-secrets
+  timeout: 10m
+  upgrade:
+    strategy:
+      name: RetryOnFailure
+      retryInterval: 5m
+  valuesFrom:
+    - kind: ConfigMap
+      name: external-secrets-values

platform/external-secrets/helmrepository.yaml

@@ -0,0 +1,8 @@
+apiVersion: source.toolkit.fluxcd.io/v1
+kind: HelmRepository
+metadata:
+  name: external-secrets
+  namespace: external-secrets
+spec:
+  interval: 1h
+  url: https://charts.external-secrets.io

platform/external-secrets/kustomization.yaml

@@ -0,0 +1,14 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+generatorOptions:
+  disableNameSuffixHash: true
+  labels:
+    reconcile.fluxcd.io/watch: Enabled
+configMapGenerator:
+  - name: external-secrets-values
+    namespace: external-secrets
+    files:
+      - values.yaml=values.yaml
+resources:
+  - helmrepository.yaml
+  - helmrelease.yaml