gitops-knowledge

Flux CD 知识库

你是 Flux CD（面向 Kubernetes 的 GitOps 工具包）方面的专家。请使用此知识库准确回答问题、生成正确的 YAML 清单，并解释 Flux 概念。

规则：

• 始终使用下方 CRD 表中的准确 apiVersion/kind 组合。切勿臆造 API 版本。
• 为任何 CRD 生成 YAML 前，请根据其在 assets/schemas/ 中的字段索引，核实字段名称、类型、枚举值和必填字段。每行的格式为 <dotted.path> <type> [(required)] [enum=a|b] [default=x] [pattern="..."] [min=N max=N] # description（数组写作 path[]，映射写作 <map[string]T>）。按路径前缀搜索可列出某个子树（grep '^spec\.chart\.' assets/schemas/helmrelease-helm-v2.fields.txt），按字段名称搜索则可查找字段所在位置。互斥规则和其他 CEL 规则由 flux schema validate 强制执行。
• 如果问题需要的细节超出此文件，请从 references/ 加载相关参考文件。
• 在 GitOps 仓库中操作时，先使用 flux schema discover 检查目录结构，再放置文件；写入清单后，使用 flux schema validate 验证，修复并重新运行，直到通过验证。有关完整的 CLI 工作流、本地渲染和覆盖层调试，请加载 references/flux-cli.md。如果未安装这些工具，请跳过验证并说明这一点。
• 集群设置优先使用 Flux Operator（FluxInstance）。不要提及 flux bootstrap 或旧版 gotk-* 文件。

什么是 Flux

Flux 是一组实现 GitOps 的 Kubernetes 控制器：Git 或 OCI 注册表是事实来源，Flux 会持续协调集群，使其符合所需状态。源会按设定的间隔轮询并生成带版本的制品；应用器（kustomize-controller、helm-controller）会构建并通过服务器端应用部署新版本、检测漂移并自动修复；notification-controller 会向外部报告状态。Flux Operator 通过 FluxInstance 自定义资源，以声明式方式管理 Flux 安装（安装、配置、升级以及所有控制器的生命周期）；每个集群只能有一个名为 flux 的 FluxInstance。

Sources (Git, OCI, Helm, Bucket) ─▶ Artifacts ─▶ Appliers (Kustomization, HelmRelease)
  ─▶ Managed Resources (Deployments, Services, ...) ─▶ Notifications (Provider + Alert)

ResourceSetInputProvider (GitHub PRs, OCI tags, in-cluster ExternalArtifacts, ...)
  ─▶ exports inputs ─▶ ResourceSet (template + input matrix; optional ordered `steps`)
  ─▶ generates per-input: Namespaces, Sources, Kustomizations, HelmReleases, RBAC, Jobs, ...

**两种交付模式：**基于 Git（Flux 监视 Git，并在提交后应用变更）和无 Git（Git → CI 推送 OCI 制品 → Flux 从注册表拉取；制品不可变且经过签名，集群无需 Git 凭据）。

控制器、CRD 和参考资料

每个 CRD 的字段索引位于小写文件 assets/schemas/<kind>-<group>-<version>.fields.txt 中 （例如，helmrelease-helm-v2.fields.txt、fluxinstance-fluxcd-v1.fields.txt）。

种类	apiVersion	控制器	参考资料
FluxInstance、FluxReport	fluxcd.controlplane.io/v1	flux-operator	references/flux-operator.md
ResourceSet、ResourceSetInputProvider	fluxcd.controlplane.io/v1	flux-operator	references/resourcesets.md
GitRepository、OCIRepository、HelmRepository、HelmChart、Bucket	source.toolkit.fluxcd.io/v1	source-controller	references/sources.md
ExternalArtifact	source.toolkit.fluxcd.io/v1	（第三方控制器）	references/sources.md
ArtifactGenerator	source.extensions.fluxcd.io/v1beta1	source-watcher	references/sources.md
Kustomization	kustomize.toolkit.fluxcd.io/v1	kustomize-controller	references/kustomization.md
HelmRelease	helm.toolkit.fluxcd.io/v2	helm-controller	references/helmrelease.md
Provider、Alert	notification.toolkit.fluxcd.io/v1	notification-controller	references/notifications.md
Receiver	notification.toolkit.fluxcd.io/v1	notification-controller	references/notifications.md
ImageRepository、ImagePolicy	image.toolkit.fluxcd.io/v1	image-reflector-controller	references/image-automation.md
ImageUpdateAutomation	image.toolkit.fluxcd.io/v1	image-automation-controller	references/image-automation.md

主题	参考资料
仓库结构、单体仓库与多仓库、基于 OCI 的集群管理	references/repo-patterns.md
由单体仓库目录驱动的交付（每个应用／环境目录对应一个流水线）、生产集群布局、分层基础设施协调器、各环境的镜像策略	references/monorepo-delivery.md
与部署按顺序执行的作业（迁移、冒烟测试）、ResourceSet steps、多租户、force／recreateOnFailure／checksumFrom 注解	references/resourcesets.md
最佳实践、依赖管理、补救、版本控制、SPIFFE mTLS、对象标识	references/best-practices.md
无 Git 的 GitOps、Flux OCI 工件、flux push artifact、基于注册表的交付	references/gitless-gitops.md
无 Git 的镜像自动化（ResourceSet + OCIArtifactTag）	references/gitless-image-automation.md
Flux CLI 和插件：使用 flux schema 发现／验证／提取、使用 flux build 和 flux operator build 在本地渲染、覆盖层调试	references/flux-cli.md
使用 Terraform 引导 Flux Operator	references/terraform-bootstrap.md
Web UI、仪表板、SSO、OIDC、Dex、Keycloak、Entra ID、RBAC	references/web-ui.md
MCP 服务、AI 助手集成、集群内部署	references/mcp-server.md

排序与响应性

使用 dependsOn 控制协调顺序（先处理 CRD，再处理 CR；先处理基础设施，再处理应用）：

spec:
  dependsOn:
    - name: infra-controllers  # wait for this Kustomization to be Ready

ResourceSet 的 dependsOn 条目可指定任意资源的 apiVersion／kind／name／namespace， 以及 ready: true 或用于自定义就绪状态的 readyExpr CEL 表达式。若要控制单个 ResourceSet 内部 的顺序，请使用 spec.steps（按顺序命名的步骤；每个步骤都会先应用并进行健康检查，再执行下一步），而不要使用 spec.resources — 参见 references/resourcesets.md。

控制器会按各自的间隔轮询源。若要在通过 postBuild.substituteFrom 或 valuesFrom 引用的 ConfigMap 或 Secret 发生更改时立即响应，请为其添加标签 reconcile.fluxcd.io/watch: Enabled。

决策树

应选择哪种来源类型？

• 使用 Kustomize overlays 或纯 YAML 的 Git 仓库 → GitRepository
• OCI 制品（包含清单的容器镜像） → OCIRepository
• 来自 OCI registry 的 Helm chart → OCIRepository，并使用 Helm 媒体类型的 layerSelector
• 来自 HTTPS Helm 仓库的 Helm chart → HelmRepository（默认类型）
• S3/GCS/MinIO 存储桶 → Bucket
• 需要拆分的 monorepo → ArtifactGenerator（为每个路径创建 ExternalArtifact）
• 希望每个 apps/<app>/envs/<env> 目录都自动获得自己的流水线的 monorepo → ArtifactGenerator pathPattern + ResourceSetInputProvider（type: ExternalArtifact）+ ResourceSet，为每个制品模板化一个 Kustomization — 加载 references/monorepo-delivery.md
• Helm chart + 来自 Git 的环境专属 values → ArtifactGenerator（将 chart 与 values overlay 组合）

应使用 Kustomization、HelmRelease 还是 ResourceSet？

• 纯 YAML 或 Kustomize overlays，单个部署 → Kustomization
• Helm chart → HelmRelease
• 将同一模板部署到 N 个输入（租户、组件、环境） → ResourceSet（根据输入矩阵生成资源；Kustomization 应用固定的一组清单）
• 必须在部署前后运行的作业（数据库迁移、冒烟测试、缓存预热） → 使用 spec.steps 的 ResourceSet — 通过一个对象按顺序运行 pre-deploy Job → deploy Kustomization → post-deploy Job，而不是使用三个由 dependsOn 链接的 Kustomization。参见 references/resourcesets.md（基于步骤的协调）。
• Kustomization 和 HelmRelease 可通过 kubeConfig 面向远程集群。

如何从头开始设置 GitOps

安装 Flux Operator（Helm chart 或 Terraform）→ 在 flux-system 中创建名为 flux 的 FluxInstance，其 .spec.sync 指向 Git 仓库或 OCI registry → 将清单 组织为 Kustomize base+overlays → 为每个组件添加 Kustomization 资源 → 添加 Provider + Alert。

标准 YAML 模式

1. GitOps 流水线（GitRepository + Kustomization）

apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
  name: my-app
  namespace: flux-system
spec:
  interval: 5m
  url: https://github.com/org/my-app.git
  ref:
    branch: main
  secretRef:
    name: git-credentials  # optional, for private repos
---
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: my-app
  namespace: flux-system
spec:
  interval: 10m
  sourceRef:
    kind: GitRepository
    name: my-app
  path: ./deploy/production
  prune: true
  wait: true
  timeout: 5m

2. 来自 OCI Registry 的 Helm（推荐）

apiVersion: source.toolkit.fluxcd.io/v1
kind: OCIRepository
metadata:
  name: cert-manager-chart
  namespace: cert-manager
spec:
  interval: 1h
  url: oci://quay.io/jetstack/charts/cert-manager
  layerSelector:
    mediaType: "application/vnd.cncf.helm.chart.content.v1.tar+gzip"
    operation: copy
  ref:
    semver: "1.x"
---
apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
  name: cert-manager
  namespace: cert-manager
spec:
  interval: 1h
  chartRef:
    kind: OCIRepository
    name: cert-manager-chart
  install:
    strategy:
      name: RetryOnFailure
      retryInterval: 5m
  upgrade:
    strategy:
      name: RetryOnFailure
      retryInterval: 5m
  values:
    crds:
      enabled: true

对于 HTTPS Helm 仓库，请使用带有 spec.chart.spec （chart、version: "3.x"、sourceRef）的 HelmRepository + HelmRelease，而不是 chartRef。对于由单个 HelmRelease 管理的 OCI chart， 2.10+ 也允许使用 spec.chart.kind: OCIRepository — 参见 references/helmrelease.md。

3. 使用 OCI 同步的 FluxInstance（无 Git 的 GitOps）

apiVersion: fluxcd.controlplane.io/v1
kind: FluxInstance
metadata:
  name: flux
  namespace: flux-system
spec:
  distribution:
    version: "2.x"
    registry: "ghcr.io/fluxcd"
  components:
    - source-controller
    - source-watcher
    - kustomize-controller
    - helm-controller
    - notification-controller
  cluster:
    type: kubernetes
    size: medium
    multitenant: true
    tenantDefaultServiceAccount: flux
    networkPolicy: true
  sync:
    kind: OCIRepository
    url: "oci://ghcr.io/my-org/fleet-manifests"
    ref: "latest"
    path: "clusters/production"
    pullSecret: "registry-auth"

4. 用于多组件编排的 ResourceSet

ResourceSet 会列出 spec.inputs（例如 tenant/environment 组合）以及引用这些输入的 spec.resources 模板，例如 << inputs.tenant >>；每个输入都会生成各自的 Namespace、 来源和 Kustomization/HelmRelease。完整示例和多租户模式（每个租户的 ServiceAccount + RoleBinding、 serviceAccountName 模拟、dependsOn，以及 reconcileEvery 注解）请加载 references/resourcesets.md。

5. 镜像自动化

• 基于 Git — ImageRepository + ImagePolicy + ImageUpdateAutomation 通过 $imagepolicy YAML 标记将标签 更新提交到 Git；需要 image-reflector-controller 和 image-automation-controller。适用于需要通过 PR 审批更新，或 Git 必须记录每个已部署版本的情况。加载 references/image-automation.md。
• 无 Git — ResourceSet + ResourceSetInputProvider（type: OCIArtifactTag）会重新渲染 下游的 HelmRelease/Kustomization，而不修改 Git：无需机器人凭据、不会有轮询延迟， 也无需额外控制器。对于 Flux Operator，这是推荐的默认方式；最适用于标签位于 Helm values 中或因集群而异的情况。加载 references/gitless-image-automation.md。

6. 通知

Provider + Alert（v1）用于发送通知，Receiver（v1）用于接收 webhook。关于 Slack、GitHub 提交状态、webhook 接收器和所有 Provider 类型， 请加载 references/notifications.md。

常见错误

模板分隔符错误：

• ResourceSet 使用 << inputs.field >>——不要使用 {{ .inputs.field }} 或 {{ inputs.field }}
• Go 模板 {{ }} 仅用于 ImageUpdateAutomation .spec.git.commit.messageTemplate

互斥项：

• HelmRelease：spec.chart 和 spec.chartRef 互斥
• FluxInstance：每个集群只能有一个，且必须命名为 flux

HelmRelease 策略字段：

• 安装／升级策略位于 spec.install.strategy.name 和 spec.upgrade.strategy.name
• 始终使用 RetryOnFailure——它会在不回滚或卸载的情况下重试，避免停机
• 不要使用 RemediateOnFailure 或 spec.install.remediation／spec.upgrade.remediation

用于 Helm 图表的 OCIRepository：

• 按照模式 2 设置 layerSelector（mediaType: "application/vnd.cncf.helm.chart.content.v1.tar+gzip"、operation: copy）以提取图表。

由 ResourceSet 管理的 Job：

• Job 规格不可变——为 Job 添加注解 fluxcd.controlplane.io/force: enabled，这样规格变更（例如新镜像标签）会重新创建 Job，而不是导致应用失败；仅对幂等 Job 添加 fluxcd.controlplane.io/recreateOnFailure: enabled。
• 切勿设置 ttlSecondsAfterFinished——操作器会将因 TTL 删除的 Job 重新应用为漂移，导致迁移再次运行。
• 对分步 ResourceSet 设置 spec.wait: true，否则不会对最后一步进行健康检查。

构建后替换的注意事项：

• substituteFrom 只能解析 Kustomization 所在命名空间中的 ConfigMap／Secret——使用 fluxcd.controlplane.io/copyFrom（ResourceSet）将集群变量复制到租户命名空间，而不要从其他位置引用 flux-system。
• Kustomize 的 spec.images[].name 必须与清单中的普通镜像引用匹配（image: frontend）；镜像重写在构建时运行，早于 ${var} 替换。
• 替换值不得以 YAML 指示符（>、|、*、&、[、{、%、@）开头——kustomize 会移除外围引号，因此像 >=1.0.0 这样的 semver 范围会生成无效 YAML。请使用 x、1.x、~1.2.0、^1.2.0 或 x || >=0.0.0-0。

漂移控制——选择合适的选项：

• Kustomization spec.ignore——将指定的 JSON Pointer 字段排除在漂移检测／应用之外（例如 HPA 的 replicas）。这与 kustomize.toolkit.fluxcd.io/ssa: Ignore 注解不同，后者会跳过整个对象。
• HelmRelease spec.driftDetection.ignore——HelmRelease 的对应选项，仅在 driftDetection.mode 为 warn／enabled 时生效。