gitops-knowledge

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Flux CD Knowledge Base

Flux CD 知识库

You are an expert on Flux CD, the GitOps toolkit for Kubernetes. Use this knowledge base to answer questions accurately, generate correct YAML manifests, and explain Flux concepts.

Rules:

Always use the exact apiVersion/kind combinations from the CRD table below. Never invent API versions.
Before generating YAML for any CRD, read its OpenAPI schema from
```
assets/schemas/
```
to verify field names, types, and enum values.
ResourceSet templates use
```
<< >>
```
delimiters, NEVER
```
{{ }}
```
(Go templates are only used inside ImageUpdateAutomation commit messages).
When a question requires detail beyond this file, load the relevant reference file from
```
references/
```
. Load at most 1-2 reference files per question.
Prefer Flux Operator (FluxInstance) for cluster setup. Do not reference
```
flux bootstrap
```
or legacy
```
gotk-*
```
files.

你是Flux CD（Kubernetes的GitOps工具集）领域专家，请基于本知识库准确解答问题、生成正确的YAML清单、讲解Flux相关概念。

规则：

始终使用下方CRD表格中给出的准确apiVersion/kind组合，禁止编造API版本。
为任意CRD生成YAML前，请先从
```
assets/schemas/
```
目录读取对应的OpenAPI schema，校验字段名、字段类型和枚举值正确性。
ResourceSet模板使用
```
<< >>
```
作为分隔符，绝对不能用
```
{{ }}
```
（Go模板仅允许在ImageUpdateAutomation的提交消息中使用）。
如果问题所需信息超出本文档范围，请从
```
references/
```
目录加载相关参考文件，每个问题最多加载1-2个参考文件。
集群部署优先推荐使用Flux Operator（FluxInstance）实现，不要提及
```
flux bootstrap
```
或旧版
```
gotk-*
```
文件。

What is Flux

什么是Flux

Flux is a set of Kubernetes controllers that implement GitOps — the practice of using Git (or OCI registries) as the source of truth for declarative infrastructure and applications. Flux continuously reconciles the desired state stored in sources with the actual state of the cluster.

Flux Operator manages the Flux installation declaratively through a

FluxInstance

custom resource. It handles installation, configuration, upgrades, and lifecycle of all Flux controllers. Only one FluxInstance named

flux

can exist per cluster.

How resources relate:

Sources (Git, OCI, Helm, Bucket)
  │
  ▼ produce artifacts
Artifacts (tarballs, Helm charts, OCI layers)
  │
  ▼ consumed by
Appliers (Kustomization, HelmRelease)
  │
  ▼ create/update
Managed Resources (Deployments, Services, ConfigMaps, ...)
  │
  ▼ status reported to
Notifications (Provider + Alert → Slack, Teams, GitHub, ...)

ResourceSet orchestration flow:

ResourceSetInputProvider (GitHub PRs, OCI tags, ...)
  │
  ▼ exports inputs
ResourceSet (template + input matrix)
  │
  ▼ generates per-input
Namespaces, Sources, Kustomizations, HelmReleases, RBAC, ...

Two delivery models:

Git-based: Flux watches Git repositories and applies changes on commit.
Gitless (OCI-based): Git → CI pushes OCI artifacts → Flux pulls from registry. OCI artifacts are immutable, signed, and don't require Git credentials on clusters.

Flux是一组实现GitOps理念的Kubernetes控制器，GitOps是指将Git（或OCI镜像仓库）作为声明式基础设施和应用的唯一可信源的实践。Flux会持续将源中存储的期望状态与集群实际运行状态进行调和。

Flux Operator通过

FluxInstance

自定义资源以声明式方式管理Flux的安装，负责所有Flux控制器的安装、配置、升级和全生命周期管理。每个集群中仅允许存在一个名为

flux

的FluxInstance资源。

资源关联关系：

Sources (Git, OCI, Helm, Bucket)
  │
  ▼ produce artifacts
Artifacts (tarballs, Helm charts, OCI layers)
  │
  ▼ consumed by
Appliers (Kustomization, HelmRelease)
  │
  ▼ create/update
Managed Resources (Deployments, Services, ConfigMaps, ...)
  │
  ▼ status reported to
Notifications (Provider + Alert → Slack, Teams, GitHub, ...)

ResourceSet编排流程：

ResourceSetInputProvider (GitHub PRs, OCI tags, ...)
  │
  ▼ exports inputs
ResourceSet (template + input matrix)
  │
  ▼ generates per-input
Namespaces, Sources, Kustomizations, HelmReleases, RBAC, ...

两种交付模式：

基于Git： Flux监听Git仓库变动，代码提交后自动应用变更。
无Git（基于OCI）： Git → CI推送OCI制品 → Flux从镜像仓库拉取制品。OCI制品不可变、可签名，且集群无需配置Git凭证。

Controllers and CRDs

控制器与CRD

Kind	apiVersion	Controller	Purpose
FluxInstance	fluxcd.controlplane.io/v1	flux-operator	Manages Flux installation lifecycle
FluxReport	fluxcd.controlplane.io/v1	flux-operator	Read-only observed state of Flux
ResourceSet	fluxcd.controlplane.io/v1	flux-operator	Template resources from input matrix
ResourceSetInputProvider	fluxcd.controlplane.io/v1	flux-operator	Fetch inputs from external services
GitRepository	source.toolkit.fluxcd.io/v1	source-controller	Fetch from Git repositories
OCIRepository	source.toolkit.fluxcd.io/v1	source-controller	Fetch OCI artifacts from registries
HelmRepository	source.toolkit.fluxcd.io/v1	source-controller	Index Helm chart repositories
HelmChart	source.toolkit.fluxcd.io/v1	source-controller	Fetch and package Helm charts
Bucket	source.toolkit.fluxcd.io/v1	source-controller	Fetch from S3-compatible storage
ExternalArtifact	source.toolkit.fluxcd.io/v1	(external)	Generic artifact storage for 3rd-party controllers
ArtifactGenerator	source.extensions.fluxcd.io/v1beta1	source-controller	Compose/decompose artifacts from multiple sources
Kustomization	kustomize.toolkit.fluxcd.io/v1	kustomize-controller	Build and apply Kustomize overlays or plain YAML
HelmRelease	helm.toolkit.fluxcd.io/v2	helm-controller	Install and manage Helm releases
Provider	notification.toolkit.fluxcd.io/v1beta3	notification-controller	External notification provider config
Alert	notification.toolkit.fluxcd.io/v1beta3	notification-controller	Route events to notification providers
Receiver	notification.toolkit.fluxcd.io/v1	notification-controller	Webhook receiver for incoming events
ImageRepository	image.toolkit.fluxcd.io/v1	image-reflector-controller	Scan container image registries
ImagePolicy	image.toolkit.fluxcd.io/v1	image-reflector-controller	Select image by version policy
ImageUpdateAutomation	image.toolkit.fluxcd.io/v1	image-automation-controller	Update YAML in Git with new image tags

Kind	apiVersion	Controller	用途
FluxInstance	fluxcd.controlplane.io/v1	flux-operator	管理Flux安装全生命周期
FluxReport	fluxcd.controlplane.io/v1	flux-operator	Flux运行状态的只读观测结果
ResourceSet	fluxcd.controlplane.io/v1	flux-operator	基于输入矩阵生成模板化资源
ResourceSetInputProvider	fluxcd.controlplane.io/v1	flux-operator	从外部服务拉取输入参数
GitRepository	source.toolkit.fluxcd.io/v1	source-controller	从Git仓库拉取资源
OCIRepository	source.toolkit.fluxcd.io/v1	source-controller	从镜像仓库拉取OCI制品
HelmRepository	source.toolkit.fluxcd.io/v1	source-controller	索引Helm Chart仓库
HelmChart	source.toolkit.fluxcd.io/v1	source-controller	拉取并打包Helm Chart
Bucket	source.toolkit.fluxcd.io/v1	source-controller	从S3兼容存储拉取资源
ExternalArtifact	source.toolkit.fluxcd.io/v1	(external)	供第三方控制器使用的通用制品存储
ArtifactGenerator	source.extensions.fluxcd.io/v1beta1	source-controller	从多个源组合/拆分制品
Kustomization	kustomize.toolkit.fluxcd.io/v1	kustomize-controller	构建并应用Kustomize覆盖层或纯YAML
HelmRelease	helm.toolkit.fluxcd.io/v2	helm-controller	安装并管理Helm发布
Provider	notification.toolkit.fluxcd.io/v1beta3	notification-controller	外部通知提供方配置
Alert	notification.toolkit.fluxcd.io/v1beta3	notification-controller	将事件路由到通知提供方
Receiver	notification.toolkit.fluxcd.io/v1	notification-controller	接收外部事件的Webhook
ImageRepository	image.toolkit.fluxcd.io/v1	image-reflector-controller	扫描容器镜像仓库
ImagePolicy	image.toolkit.fluxcd.io/v1	image-reflector-controller	基于版本策略选择镜像
ImageUpdateAutomation	image.toolkit.fluxcd.io/v1	image-automation-controller	用新镜像标签更新Git中的YAML

How Flux Works

Flux工作原理

Reconciliation Loop

调和循环

Flux controllers run a continuous reconciliation loop:

Sources poll for changes — source-controller checks Git repos, OCI registries, Helm repos, or S3 buckets at configured intervals and produces versioned artifacts.
Appliers consume artifacts — kustomize-controller and helm-controller detect new artifact revisions, build manifests (Kustomize overlays or Helm templates), and apply them to the cluster using server-side apply.
Drift detection and self-healing — Flux compares the desired state from the source with the live state in the cluster. When drift is detected, Flux corrects it automatically (if enabled).
Notifications report status — notification-controller sends events to external systems (Slack, Teams, GitHub commit status, etc.) based on Alert rules.

Flux控制器会持续运行调和循环：

源轮询变更 — source-controller按照配置的间隔检查Git仓库、OCI仓库、Helm仓库或S3存储桶，生成带版本的制品。
应用器消费制品 — kustomize-controller和helm-controller检测到新的制品版本后，构建清单（Kustomize覆盖层或Helm模板），并通过服务端应用的方式部署到集群。
漂移检测与自愈 — Flux将源中定义的期望状态与集群实际运行状态对比，检测到漂移后会自动修正（如果开启了该功能）。
状态通知上报 — notification-controller根据Alert规则将事件发送到外部系统（Slack、Teams、GitHub提交状态等）。

Dependency Ordering

依赖顺序控制

Use

dependsOn

to control reconciliation order. For example, install CRDs before CRs, or infrastructure before applications:

yaml

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

ResourceSets support richer dependencies with

readyExpr

(CEL expressions):

yaml

spec:
  dependsOn:
    - apiVersion: fluxcd.controlplane.io/v1
      kind: ResourceSet
      name: policies
      ready: true
      readyExpr: "status.conditions.filter(e, e.type == 'Ready').all(e, e.status == 'True')"

使用

dependsOn

控制调和顺序，例如先安装CRD再安装CR，或是先部署基础设施再部署应用：

yaml

spec:
  dependsOn:
    - name: infra-controllers  # 等待该Kustomization状态变为Ready

ResourceSet支持通过

readyExpr

（CEL表达式）实现更灵活的依赖配置：

yaml

spec:
  dependsOn:
    - apiVersion: fluxcd.controlplane.io/v1
      kind: ResourceSet
      name: policies
      ready: true
      readyExpr: "status.conditions.filter(e, e.type == 'Ready').all(e, e.status == 'True')"

Reactivity with Watch Labels

监听标签实现即时响应

By default, Flux controllers poll sources at the configured interval. To react immediately when a dependency changes, add the watch label to the upstream resource:

yaml

metadata:
  labels:
    reconcile.fluxcd.io/watch: Enabled

When a ConfigMap or Secret with this label changes, any Kustomization or HelmRelease that references it via

postBuild.substituteFrom

valuesFrom

will reconcile immediately.

默认情况下Flux控制器按照配置的间隔轮询源，若要在依赖变更时立即触发调和，请给上游资源添加监听标签：

yaml

metadata:
  labels:
    reconcile.fluxcd.io/watch: Enabled

当带有该标签的ConfigMap或Secret发生变更时，所有通过

postBuild.substituteFrom

或

valuesFrom

引用它的Kustomization或HelmRelease都会立即触发调和。

Decision Trees

决策树

Which Source Type?

选择哪种源类型？

Git repo with Kustomize overlays or plain YAML →
```
GitRepository
```
OCI artifact (container image with manifests) →
```
OCIRepository
```
Helm chart from OCI registry →
```
OCIRepository
```
with
```
layerSelector
```
for Helm media type
Helm chart from HTTPS Helm repo →
```
HelmRepository
```
(default type)
S3/GCS/MinIO bucket →
```
Bucket
```
Monorepo that needs splitting →
```
ArtifactGenerator
```
(creates
```
ExternalArtifact
```
per path)
Helm chart + env-specific values from Git →
```
ArtifactGenerator
```
(composes chart with values overlay)

包含Kustomize覆盖层或纯YAML的Git仓库 →
```
GitRepository
```
OCI制品（包含清单的容器镜像） →
```
OCIRepository
```
来自OCI仓库的Helm Chart → 配置了Helm媒体类型
```
layerSelector
```
的
```
OCIRepository
```
来自HTTPS Helm仓库的Helm Chart →
```
HelmRepository
```
（默认类型）
S3/GCS/MinIO存储桶 →
```
Bucket
```
需要拆分的单体仓库 →
```
ArtifactGenerator
```
（为每个路径生成
```
ExternalArtifact
```
）
Helm Chart + 存储在Git中的环境专属值 →
```
ArtifactGenerator
```
（将Chart与值覆盖层组合）

Kustomization vs HelmRelease?

Kustomization还是HelmRelease？

Plain YAML or Kustomize overlays →
```
Kustomization
```
Helm chart →
```
HelmRelease
```
Both can deploy to remote clusters via
```
kubeConfig
```
and support
```
dependsOn
```
.

纯YAML或Kustomize覆盖层 →
```
Kustomization
```
Helm Chart →
```
HelmRelease
```
两者都支持通过
```
kubeConfig
```
部署到远程集群，也都支持
```
dependsOn
```
依赖配置。

How to Reference Helm Charts (3 Patterns)

引用Helm Chart的3种模式

Pattern 1 — HTTPS Helm repository:

yaml

undefined

模式1 — HTTPS Helm仓库：

yaml

undefined

HelmRelease creates a HelmChart automatically

HelmRelease会自动创建HelmChart资源

spec: chart: spec: chart: metrics-server version: "3.x" sourceRef: kind: HelmRepository name: metrics-server


**Pattern 2 — OCI registry with chartRef (recommended):**
```yaml

spec: chart: spec: chart: metrics-server version: "3.x" sourceRef: kind: HelmRepository name: metrics-server


**模式2 — 基于OCI仓库的chartRef（推荐）：**
```yaml

Separate OCIRepository + HelmRelease with chartRef

独立的OCIRepository + 配置chartRef的HelmRelease

spec: chartRef: kind: OCIRepository name: nginx-chart


**Pattern 3 — HelmChart from Git/Bucket source:**
```yaml

spec: chartRef: kind: OCIRepository name: nginx-chart


**模式3 — 来自Git/Bucket源的HelmChart：**
```yaml

Chart stored in Git, HelmRelease references HelmChart

Chart存储在Git中，HelmRelease引用HelmChart资源

spec: chart: spec: chart: ./charts/my-app sourceRef: kind: GitRepository name: my-repo


`chart.spec` and `chartRef` are **mutually exclusive** — use one or the other.

spec: chart: spec: chart: ./charts/my-app sourceRef: kind: GitRepository name: my-repo


`chart.spec`和`chartRef`**互斥**，只能使用其中一种。

ResourceSet vs Kustomization?

ResourceSet还是Kustomization？

One set of manifests, one deployment →
```
Kustomization
```
Same template deployed for N inputs (tenants, components, environments) →
```
ResourceSet
```
ResourceSets generate resources from an input matrix; Kustomizations apply a fixed set of manifests.

一套清单对应一个部署 →
```
Kustomization
```
同一份模板需要基于N个输入部署（租户、组件、环境） →
```
ResourceSet
```
ResourceSet基于输入矩阵生成资源，Kustomization应用固定的清单集合。

How to Set Up GitOps from Scratch

从零搭建GitOps流程

Install Flux Operator (Helm chart or Terraform)
Create a
```
FluxInstance
```
named
```
flux
```
in the
```
flux-system
```
namespace
Configure
```
.spec.sync
```
to point to your Git repo or OCI registry
Organize manifests in the source repo using Kustomize base+overlay pattern
Create
```
Kustomization
```
resources to apply manifests from the source
Add
```
Provider
```
+
```
Alert
```
for notifications

安装Flux Operator（通过Helm Chart或Terraform）
在
```
flux-system
```
命名空间下创建名为
```
flux
```
的
```
FluxInstance
```
资源
配置
```
.spec.sync
```
指向你的Git仓库或OCI镜像仓库
使用Kustomize base+overlay模式在源仓库中组织清单
创建
```
Kustomization
```
资源应用源仓库中的清单
添加
```
Provider
```
+
```
Alert
```
实现通知能力

Canonical YAML Patterns

标准YAML模式

1. GitOps Pipeline (GitRepository + Kustomization)

1. GitOps流水线（GitRepository + Kustomization）

yaml

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

yaml

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  # 私有仓库可选配置
---
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. Helm from HTTPS Repository

2. 基于HTTPS仓库的Helm部署

yaml

apiVersion: source.toolkit.fluxcd.io/v1
kind: HelmRepository
metadata:
  name: metrics-server
  namespace: kube-system
spec:
  interval: 1h
  url: https://kubernetes-sigs.github.io/metrics-server/
---
apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
  name: metrics-server
  namespace: kube-system
spec:
  interval: 30m
  chart:
    spec:
      chart: metrics-server
      version: "3.x"
      sourceRef:
        kind: HelmRepository
        name: metrics-server
  values:
    args:
      - --kubelet-insecure-tls

yaml

apiVersion: source.toolkit.fluxcd.io/v1
kind: HelmRepository
metadata:
  name: metrics-server
  namespace: kube-system
spec:
  interval: 1h
  url: https://kubernetes-sigs.github.io/metrics-server/
---
apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
  name: metrics-server
  namespace: kube-system
spec:
  interval: 30m
  chart:
    spec:
      chart: metrics-server
      version: "3.x"
      sourceRef:
        kind: HelmRepository
        name: metrics-server
  values:
    args:
      - --kubelet-insecure-tls

3. Helm from OCI Registry (Recommended)

3. 基于OCI仓库的Helm部署（推荐）

yaml

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
      keep: false

yaml

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
      keep: false

4. FluxInstance with OCI Sync (Gitless GitOps)

4. 配置OCI同步的FluxInstance（无Git的GitOps）

yaml

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"

yaml

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"

5. ResourceSet for Multi-Component Orchestration

5. 用于多组件编排的ResourceSet

yaml

apiVersion: fluxcd.controlplane.io/v1
kind: ResourceSet
metadata:
  name: apps
  namespace: flux-system
  annotations:
    fluxcd.controlplane.io/reconcileEvery: "5m"
spec:
  dependsOn:
    - apiVersion: fluxcd.controlplane.io/v1
      kind: ResourceSet
      name: infra
      ready: true
  inputs:
    - tenant: "frontend"
      tag: "latest"
      environment: "production"
    - tenant: "backend"
      tag: "latest"
      environment: "production"
  resources:
    - apiVersion: v1
      kind: Namespace
      metadata:
        name: << inputs.tenant >>
        labels:
          toolkit.fluxcd.io/role: "tenant"
    - apiVersion: v1
      kind: ServiceAccount
      metadata:
        name: flux
        namespace: << inputs.tenant >>
    - apiVersion: rbac.authorization.k8s.io/v1
      kind: RoleBinding
      metadata:
        name: flux
        namespace: << inputs.tenant >>
      roleRef:
        apiGroup: rbac.authorization.k8s.io
        kind: ClusterRole
        name: admin
      subjects:
        - kind: ServiceAccount
          name: flux
          namespace: << inputs.tenant >>
    - apiVersion: source.toolkit.fluxcd.io/v1
      kind: OCIRepository
      metadata:
        name: apps
        namespace: << inputs.tenant >>
      spec:
        interval: 5m
        url: "oci://ghcr.io/my-org/apps/<< inputs.tenant >>"
        ref:
          tag: << inputs.tag >>
    - apiVersion: kustomize.toolkit.fluxcd.io/v1
      kind: Kustomization
      metadata:
        name: apps
        namespace: << inputs.tenant >>
      spec:
        targetNamespace: << inputs.tenant >>
        serviceAccountName: flux
        interval: 30m
        retryInterval: 5m
        wait: true
        timeout: 5m
        sourceRef:
          kind: OCIRepository
          name: apps
        path: "./<< inputs.environment >>"
        prune: true

yaml

apiVersion: fluxcd.controlplane.io/v1
kind: ResourceSet
metadata:
  name: apps
  namespace: flux-system
  annotations:
    fluxcd.controlplane.io/reconcileEvery: "5m"
spec:
  dependsOn:
    - apiVersion: fluxcd.controlplane.io/v1
      kind: ResourceSet
      name: infra
      ready: true
  inputs:
    - tenant: "frontend"
      tag: "latest"
      environment: "production"
    - tenant: "backend"
      tag: "latest"
      environment: "production"
  resources:
    - apiVersion: v1
      kind: Namespace
      metadata:
        name: << inputs.tenant >>
        labels:
          toolkit.fluxcd.io/role: "tenant"
    - apiVersion: v1
      kind: ServiceAccount
      metadata:
        name: flux
        namespace: << inputs.tenant >>
    - apiVersion: rbac.authorization.k8s.io/v1
      kind: RoleBinding
      metadata:
        name: flux
        namespace: << inputs.tenant >>
      roleRef:
        apiGroup: rbac.authorization.k8s.io
        kind: ClusterRole
        name: admin
      subjects:
        - kind: ServiceAccount
          name: flux
          namespace: << inputs.tenant >>
    - apiVersion: source.toolkit.fluxcd.io/v1
      kind: OCIRepository
      metadata:
        name: apps
        namespace: << inputs.tenant >>
      spec:
        interval: 5m
        url: "oci://ghcr.io/my-org/apps/<< inputs.tenant >>"
        ref:
          tag: << inputs.tag >>
    - apiVersion: kustomize.toolkit.fluxcd.io/v1
      kind: Kustomization
      metadata:
        name: apps
        namespace: << inputs.tenant >>
      spec:
        targetNamespace: << inputs.tenant >>
        serviceAccountName: flux
        interval: 30m
        retryInterval: 5m
        wait: true
        timeout: 5m
        sourceRef:
          kind: OCIRepository
          name: apps
        path: "./<< inputs.environment >>"
        prune: true

6. Image Automation Pipeline

6. 镜像自动化流水线

Pipeline: ImageRepository → ImagePolicy → ImageUpdateAutomation. Mark images in YAML with

# {"$imagepolicy": "namespace:policy-name"}

comment markers for automatic tag updates.

For complete YAML examples, tag filtering, commit message templates, and marker formats, load

references/image-automation.md

流水线流程：ImageRepository → ImagePolicy → ImageUpdateAutomation。在YAML中为镜像添加

# {"$imagepolicy": "namespace:policy-name"}

注释标记即可实现标签自动更新。

完整的YAML示例、标签过滤、提交消息模板、标记格式请加载

references/image-automation.md

查看。

7. Notifications (Slack, GitHub, Webhooks)

7. 通知能力（Slack、GitHub、Webhooks）

Provider + Alert for outgoing notifications, Receiver for incoming webhooks. Alert and Provider use

v1beta3

, Receiver uses

v1

For Slack, GitHub commit status, webhook receivers, and all provider types, load

references/notifications.md

Provider + Alert用于对外发送通知，Receiver用于接收外部Webhook事件。Alert和Provider使用

v1beta3

版本，Receiver使用

v1

版本。

Slack通知、GitHub提交状态、Webhook Receiver、所有支持的提供方类型请加载

references/notifications.md

查看。

Common Mistakes

常见错误

Wrong template delimiters:

ResourceSet uses

<< inputs.field >>

— NOT

{{ .inputs.field }}

{{ inputs.field }}

Go templates
```
{{ }}
```
are only used in ImageUpdateAutomation
```
.spec.git.commit.messageTemplate
```

Mutual exclusivity:

HelmRelease:
```
spec.chart.spec
```
and
```
spec.chartRef
```
are mutually exclusive
FluxInstance: only one per cluster, must be named
```
flux
```

Required fields often forgotten:

```
Kustomization.spec.prune
```
— must be set (true or false), controls garbage collection
```
Kustomization.spec.sourceRef
```
— must specify kind and name
```
HelmRelease.spec.interval
```
— required for reconciliation
```
Alert.spec.eventSources
```
— at least one source required

Wrong API versions:

Alert and Provider use

v1beta3

, not

v1

—

notification.toolkit.fluxcd.io/v1beta3

Receiver uses
```
v1
```
—
```
notification.toolkit.fluxcd.io/v1
```
HelmRelease uses
```
v2
```
, not
```
v1
```
or
```
v2beta1
```
—
```
helm.toolkit.fluxcd.io/v2
```
ImageRepository and ImagePolicy use
```
v1
```
—
```
image.toolkit.fluxcd.io/v1
```

HelmRelease strategy fields:

Install/upgrade strategy is at

spec.install.strategy.name

and

spec.upgrade.strategy.name

Always use
```
RetryOnFailure
```
— it retries without rollback or uninstall, avoiding downtime

Do not use

RemediateOnFailure

spec.install.remediation

spec.upgrade.remediation

OCIRepository for Helm charts:

When using OCIRepository to fetch Helm charts from OCI registries, set

layerSelector

to extract the chart:

yaml

layerSelector:
  mediaType: "application/vnd.cncf.helm.chart.content.v1.tar+gzip"
  operation: copy

Without
```
layerSelector
```
, the OCIRepository fetches the full OCI artifact, not the extracted chart.

模板分隔符错误：

ResourceSet使用

<< inputs.field >>

— 不能用

{{ .inputs.field }}

或

{{ inputs.field }}

Go模板
```
{{ }}
```
仅允许在ImageUpdateAutomation的
```
.spec.git.commit.messageTemplate
```
中使用

互斥配置错误：

HelmRelease的
```
spec.chart.spec
```
和
```
spec.chartRef
```
互斥
每个集群仅允许一个FluxInstance，且必须命名为
```
flux
```

遗漏必填字段：

```
Kustomization.spec.prune
```
— 必须设置为true或false，用于控制垃圾回收
```
Kustomization.spec.sourceRef
```
— 必须指定kind和name
```
HelmRelease.spec.interval
```
— 调和必须配置该字段
```
Alert.spec.eventSources
```
— 至少配置一个事件源

API版本错误：

Alert和Provider使用

v1beta3

而非

v1

—

notification.toolkit.fluxcd.io/v1beta3

Receiver使用
```
v1
```
—
```
notification.toolkit.fluxcd.io/v1
```
HelmRelease使用
```
v2
```
而非
```
v1
```
或
```
v2beta1
```
—
```
helm.toolkit.fluxcd.io/v2
```
ImageRepository和ImagePolicy使用
```
v1
```
—
```
image.toolkit.fluxcd.io/v1
```

HelmRelease策略字段错误：

安装/升级策略配置在

spec.install.strategy.name

和

spec.upgrade.strategy.name

路径下

始终使用
```
RetryOnFailure
```
— 它会重试部署但不会回滚或卸载，避免服务 downtime

不要使用

RemediateOnFailure

或

spec.install.remediation

spec.upgrade.remediation

OCIRepository拉取Helm Chart配置错误：

使用OCIRepository从OCI仓库拉取Helm Chart时，必须配置

layerSelector

提取Chart：

yaml

layerSelector:
  mediaType: "application/vnd.cncf.helm.chart.content.v1.tar+gzip"
  operation: copy

没有
```
layerSelector
```
的话，OCIRepository会拉取完整的OCI制品，而不是提取后的Chart。

Reference Index

参考索引

Load reference files and OpenAPI schemas based on the question topic. Load at most 1-2 reference files per question. Read schemas for field-level validation when generating YAML.

CRD	Reference	Schema
FluxInstance	`references/flux-operator.md`	`assets/schemas/fluxinstance-fluxcd-v1.json`
FluxReport	`references/flux-operator.md`	`assets/schemas/fluxreport-fluxcd-v1.json`
ResourceSet	`references/resourcesets.md`	`assets/schemas/resourceset-fluxcd-v1.json`
ResourceSetInputProvider	`references/resourcesets.md`	`assets/schemas/resourcesetinputprovider-fluxcd-v1.json`
GitRepository	`references/sources.md`	`assets/schemas/gitrepository-source-v1.json`
OCIRepository	`references/sources.md`	`assets/schemas/ocirepository-source-v1.json`
HelmRepository	`references/sources.md`	`assets/schemas/helmrepository-source-v1.json`
HelmChart	`references/sources.md`	`assets/schemas/helmchart-source-v1.json`
Bucket	`references/sources.md`	`assets/schemas/bucket-source-v1.json`
ExternalArtifact	`references/sources.md`	`assets/schemas/externalartifact-source-v1.json`
ArtifactGenerator	`references/sources.md`	`assets/schemas/artifactgenerator-source-v1beta1.json`
Kustomization	`references/kustomization.md`	`assets/schemas/kustomization-kustomize-v1.json`
HelmRelease	`references/helmrelease.md`	`assets/schemas/helmrelease-helm-v2.json`
Provider	`references/notifications.md`	`assets/schemas/provider-notification-v1beta3.json`
Alert	`references/notifications.md`	`assets/schemas/alert-notification-v1beta3.json`
Receiver	`references/notifications.md`	`assets/schemas/receiver-notification-v1.json`
ImageRepository	`references/image-automation.md`	`assets/schemas/imagerepository-image-v1.json`
ImagePolicy	`references/image-automation.md`	`assets/schemas/imagepolicy-image-v1.json`
ImageUpdateAutomation	`references/image-automation.md`	`assets/schemas/imageupdateautomation-image-v1.json`

Topic	Reference
Repository structure, monorepo vs multi-repo, OCI-based fleet management	`references/repo-patterns.md`
Best practices, dependency management, remediation, versioning	`references/best-practices.md`
Web UI, dashboard, SSO, OIDC, Dex, Keycloak, Entra ID, RBAC	`references/web-ui.md`
MCP Server, AI assistant integration, in-cluster deployment	`references/mcp-server.md`

请根据问题主题加载参考文件和OpenAPI schema，每个问题最多加载1-2个参考文件。生成YAML时请读取schema做字段级别校验。

CRD	参考文件	Schema路径
FluxInstance	`references/flux-operator.md`	`assets/schemas/fluxinstance-fluxcd-v1.json`
FluxReport	`references/flux-operator.md`	`assets/schemas/fluxreport-fluxcd-v1.json`
ResourceSet	`references/resourcesets.md`	`assets/schemas/resourceset-fluxcd-v1.json`
ResourceSetInputProvider	`references/resourcesets.md`	`assets/schemas/resourcesetinputprovider-fluxcd-v1.json`
GitRepository	`references/sources.md`	`assets/schemas/gitrepository-source-v1.json`
OCIRepository	`references/sources.md`	`assets/schemas/ocirepository-source-v1.json`
HelmRepository	`references/sources.md`	`assets/schemas/helmrepository-source-v1.json`
HelmChart	`references/sources.md`	`assets/schemas/helmchart-source-v1.json`
Bucket	`references/sources.md`	`assets/schemas/bucket-source-v1.json`
ExternalArtifact	`references/sources.md`	`assets/schemas/externalartifact-source-v1.json`
ArtifactGenerator	`references/sources.md`	`assets/schemas/artifactgenerator-source-v1beta1.json`
Kustomization	`references/kustomization.md`	`assets/schemas/kustomization-kustomize-v1.json`
HelmRelease	`references/helmrelease.md`	`assets/schemas/helmrelease-helm-v2.json`
Provider	`references/notifications.md`	`assets/schemas/provider-notification-v1beta3.json`
Alert	`references/notifications.md`	`assets/schemas/alert-notification-v1beta3.json`
Receiver	`references/notifications.md`	`assets/schemas/receiver-notification-v1.json`
ImageRepository	`references/image-automation.md`	`assets/schemas/imagerepository-image-v1.json`
ImagePolicy	`references/image-automation.md`	`assets/schemas/imagepolicy-image-v1.json`
ImageUpdateAutomation	`references/image-automation.md`	`assets/schemas/imageupdateautomation-image-v1.json`

主题	参考文件
仓库结构、单体仓库vs多仓库、基于OCI的集群 fleet 管理	`references/repo-patterns.md`
最佳实践、依赖管理、修复策略、版本管理	`references/best-practices.md`
Web UI、控制面板、SSO、OIDC、Dex、Keycloak、Entra ID、RBAC	`references/web-ui.md`
MCP Server、AI助手集成、集群内部署	`references/mcp-server.md`

FluxInstance Enums

FluxInstance 枚举值

Cluster types:

kubernetes

openshift

aws

azure

gcp

Cluster sizes:

small

(5 concurrency, 512Mi),

medium

(10, 1Gi),

large

(20, 3Gi)

Components:

source-controller

kustomize-controller

helm-controller

notification-controller

image-reflector-controller

image-automation-controller

source-watcher

Sync kinds:

GitRepository

OCIRepository

Bucket

Distribution variants:

upstream-alpine

enterprise-alpine

enterprise-distroless

enterprise-distroless-fips

For enums of other CRDs (HelmRelease strategies, Provider types, ImagePolicy types, ResourceSetInputProvider types, etc.), check the relevant reference file or OpenAPI schema.

集群类型：

kubernetes

openshift

aws

azure

gcp

集群规模：

small

（5并发、512Mi内存）,

medium

（10并发、1Gi内存）,

large

（20并发、3Gi内存）

组件：

source-controller

kustomize-controller

helm-controller

notification-controller

image-reflector-controller

image-automation-controller

source-watcher

同步源类型：

GitRepository

OCIRepository

Bucket

发行版变体：

upstream-alpine

enterprise-alpine

enterprise-distroless

enterprise-distroless-fips

其他CRD的枚举值（HelmRelease策略、Provider类型、ImagePolicy类型、ResourceSetInputProvider类型等）请查看对应参考文件或OpenAPI schema。