From c6e3abbfc0f3624f4062ea31efaab451a7c650b2 Mon Sep 17 00:00:00 2001
From: panxiao81 <pan-xiao@live.cn>
Date: Thu, 10 Sep 2026 09:26:54 +0000
Subject: [PATCH] =?UTF-8?q?feat(flux):=20=E5=88=86=E9=98=B6=E6=AE=B5?=
 =?UTF-8?q?=E6=8E=A5=E7=AE=A1=20Envoy=20Gateway?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 clusters/homelab/README.md                 |  1 +
 clusters/homelab/apps/envoy-gateway.yaml   | 14 ++++++++++
 clusters/homelab/kustomization.yaml        |  1 +
 platform/envoy-gateway/README.md           | 13 +++++++++
 platform/envoy-gateway/helmrelease.yaml    | 32 ++++++++++++++++++++++
 platform/envoy-gateway/helmrepository.yaml |  9 ++++++
 platform/envoy-gateway/kustomization.yaml  |  6 ++++
 7 files changed, 76 insertions(+)
 create mode 100644 clusters/homelab/apps/envoy-gateway.yaml
 create mode 100644 platform/envoy-gateway/helmrelease.yaml
 create mode 100644 platform/envoy-gateway/helmrepository.yaml
 create mode 100644 platform/envoy-gateway/kustomization.yaml

diff --git a/clusters/homelab/README.md b/clusters/homelab/README.md
index a0c8089..d430e6f 100644
--- a/clusters/homelab/README.md
+++ b/clusters/homelab/README.md
@@ -45,5 +45,6 @@ sudo k3s kubectl -n flux-system get gitrepositories,kustomizations
 - `http-echo` 保持 `prune: true`，root 保持 `prune: false`；
 - `gitea-actions`、`gitea` 与 External Secrets 已由 Flux HelmRelease 接管，Gitea 已升级到 `1.27.3`；
 - cert-manager 已固定现有 `v1.21.0` 并完成分阶段 Flux HelmRelease 接管；
+- Envoy Gateway 已进入分阶段接管：固定现有 `v1.5.6`，HelmRelease 暂停等待零变更验证；
 - External Secrets Operator 已固定 chart `2.8.0` 并完成分阶段接管；
 - root Kustomization 与所有 brownfield 子 Kustomization 继续保持 `prune: false`。
diff --git a/clusters/homelab/apps/envoy-gateway.yaml b/clusters/homelab/apps/envoy-gateway.yaml
new file mode 100644
index 0000000..c7983b7
--- /dev/null
+++ b/clusters/homelab/apps/envoy-gateway.yaml
@@ -0,0 +1,14 @@
+apiVersion: kustomize.toolkit.fluxcd.io/v1
+kind: Kustomization
+metadata:
+  name: envoy-gateway
+  namespace: flux-system
+spec:
+  interval: 10m
+  path: ./platform/envoy-gateway
+  prune: false
+  sourceRef:
+    kind: GitRepository
+    name: flux-system
+  timeout: 3m
+  wait: false
diff --git a/clusters/homelab/kustomization.yaml b/clusters/homelab/kustomization.yaml
index 5574ebf..8d4dff0 100644
--- a/clusters/homelab/kustomization.yaml
+++ b/clusters/homelab/kustomization.yaml
@@ -4,6 +4,7 @@ resources:
   - flux-system
   - namespaces/gitops-canary.yaml
   - apps/cert-manager.yaml
+  - apps/envoy-gateway.yaml
   - apps/external-secrets.yaml
   - apps/gitea.yaml
   - apps/gitea-actions.yaml
diff --git a/platform/envoy-gateway/README.md b/platform/envoy-gateway/README.md
index f53dd34..6f833bc 100644
--- a/platform/envoy-gateway/README.md
+++ b/platform/envoy-gateway/README.md
@@ -79,6 +79,19 @@ unauthenticated requests to an app whose auth model is "trust the header".
 
 ## Install
 
+### Flux 接管状态
+
+现有 release 为 OCI chart/app `v1.5.6`，且没有 user-supplied values。Git 中固定
+同一版本，并先以 `suspend: true` 的 HelmRelease 登记；确认 OCI source Ready、Helm
+revision 与 controller/data-plane Pod UID 均未变化后，再通过独立 PR 解除暂停。
+
+`GatewayClass eg` 与 `Gateway eg` 随本目录 Kustomization 由 Flux 管理。接管期间保持
+`prune: false`；Gateway API 与 Envoy Gateway CRD 使用 `CreateReplace`，延续现有 Helm
+所有权且绝不通过删除 CRD 迁移。Gateway 的三个 `certificateRefs` 最初属于
+`kubectl-client-side-apply`；首次 reconcile 会以 Flux 默认 SSA `Override` 转移这些已在
+Git 中声明且值相同的字段所有权，不改变 listener spec。不得用 `force: true`，它用于
+不可变字段失败时删除重建资源。以下命令保留为 break-glass 手工恢复流程。
+
 ```bash
 # The Gateway API CRDs may already be owned by another tool's field manager (Contour's
 # quickstart used client-side apply), which makes Helm fail with
diff --git a/platform/envoy-gateway/helmrelease.yaml b/platform/envoy-gateway/helmrelease.yaml
new file mode 100644
index 0000000..dcfb312
--- /dev/null
+++ b/platform/envoy-gateway/helmrelease.yaml
@@ -0,0 +1,32 @@
+apiVersion: helm.toolkit.fluxcd.io/v2
+kind: HelmRelease
+metadata:
+  name: envoy-gateway
+  namespace: envoy-gateway-system
+spec:
+  # 第一阶段只登记现有 release；入口数据面必须在独立激活 PR 后才由 Flux reconcile。
+  suspend: true
+  chart:
+    spec:
+      chart: gateway-helm
+      interval: 1h
+      sourceRef:
+        kind: HelmRepository
+        name: envoy-gateway
+      version: v1.5.6
+  driftDetection:
+    mode: enabled
+  install:
+    crds: CreateReplace
+    strategy:
+      name: RetryOnFailure
+      retryInterval: 5m
+  interval: 30m
+  releaseName: envoy-gateway
+  targetNamespace: envoy-gateway-system
+  timeout: 10m
+  upgrade:
+    crds: CreateReplace
+    strategy:
+      name: RetryOnFailure
+      retryInterval: 5m
diff --git a/platform/envoy-gateway/helmrepository.yaml b/platform/envoy-gateway/helmrepository.yaml
new file mode 100644
index 0000000..aceb53d
--- /dev/null
+++ b/platform/envoy-gateway/helmrepository.yaml
@@ -0,0 +1,9 @@
+apiVersion: source.toolkit.fluxcd.io/v1
+kind: HelmRepository
+metadata:
+  name: envoy-gateway
+  namespace: envoy-gateway-system
+spec:
+  interval: 1h
+  type: oci
+  url: oci://docker.io/envoyproxy
diff --git a/platform/envoy-gateway/kustomization.yaml b/platform/envoy-gateway/kustomization.yaml
new file mode 100644
index 0000000..a2c534d
--- /dev/null
+++ b/platform/envoy-gateway/kustomization.yaml
@@ -0,0 +1,6 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+resources:
+  - helmrepository.yaml
+  - helmrelease.yaml
+  - gateway.yaml