Flux CD Knowledge Base

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.
• When a question requires detail beyond this file, load the relevant reference file from

  references/

  .
• Prefer Flux Operator (FluxInstance) for cluster setup. Do not reference

  flux bootstrap

  or legacy

  gotk-*

  files.

What is 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

flux

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.

Controllers and CRDs

How Flux Works

Reconciliation Loop

Flux controllers run a continuous reconciliation loop:

1. Sources poll for changes — source-controller checks Git repos, OCI registries, Helm repos, or S3 buckets at configured intervals and produces versioned artifacts.
2. 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.
3. 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).
4. Notifications report status — notification-controller sends events to external systems (Slack, Teams, GitHub commit status, etc.) based on Alert rules.

Dependency Ordering

Use

dependsOn

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

ResourceSets support richer dependencies with

readyExpr

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:

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

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)

Kustomization vs HelmRelease?

• Plain YAML or Kustomize overlays →

  Kustomization

• Helm chart →

  HelmRelease

• Both can deploy to remote clusters via

  kubeConfig

  and support

  dependsOn

  .

ResourceSet vs 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.

How to Set Up GitOps from Scratch

1. Install Flux Operator (Helm chart or Terraform)
2. Create a

   FluxInstance

   named

   flux

   in the

   flux-system

   namespace
3. Configure

   .spec.sync

   to point to your Git repo or OCI registry
4. Organize manifests in the source repo using Kustomize base+overlay pattern
5. Create

   Kustomization

   resources to apply manifests from the source
6. Add

   Provider

   +

   Alert

   for notifications

Canonical YAML Patterns

1. GitOps Pipeline (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. Helm from HTTPS Repository

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)

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

4. FluxInstance with OCI Sync (Gitless 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"

5. ResourceSet for Multi-Component Orchestration

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

Flux supports two delivery models for updating container images and Helm chart versions. Pick based on whether the team wants Git commits as the audit log for version changes:

• Git-based —

  ImageRepository

  +

  ImagePolicy

  +

  ImageUpdateAutomation

  scan the registry and commit tag bumps back to Git via

  $imagepolicy

  YAML markers. Requires

  image-reflector-controller

  and

  image-automation-controller

  on the cluster. Load

  references/image-automation.md

  .
• Gitless —

  ResourceSet

  +

  ResourceSetInputProvider

  (

  type: OCIArtifactTag

  ) scans the registry and re-renders the

  ResourceSet

  directly, upgrading the downstream

  HelmRelease

  or

  Kustomization

  without touching Git. No bot credentials, no Git poll lag, no extra controllers. Recommended default for Flux Operator deployments. Load

  references/gitless-image-automation.md

  .

Gitless is the better fit when the tag lives in Helm values, when tags should differ per cluster in a fleet, or when the team doesn't want a bot writing to the repo. Git-based is the better fit when PR-based approval of version bumps is required or when Git must remain the canonical record of every deployed version.

7. Notifications (Slack, GitHub, Webhooks)

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

v1beta3

v1

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

references/notifications.md

Common Mistakes

Wrong template delimiters:

• ResourceSet uses

  << inputs.field >>

  — NOT

  {{ .inputs.field }}

  or

  {{ 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

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

  or

  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:

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

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.

references/flux-operator.md

assets/schemas/fluxinstance-fluxcd-v1.json

references/flux-operator.md

assets/schemas/fluxreport-fluxcd-v1.json

references/resourcesets.md

assets/schemas/resourceset-fluxcd-v1.json

references/resourcesets.md

assets/schemas/resourcesetinputprovider-fluxcd-v1.json

references/sources.md

assets/schemas/gitrepository-source-v1.json

references/sources.md

assets/schemas/ocirepository-source-v1.json

references/sources.md

assets/schemas/helmrepository-source-v1.json

references/sources.md

assets/schemas/helmchart-source-v1.json

references/sources.md

assets/schemas/bucket-source-v1.json

references/sources.md

assets/schemas/externalartifact-source-v1.json

references/sources.md

assets/schemas/artifactgenerator-source-v1beta1.json

references/kustomization.md

assets/schemas/kustomization-kustomize-v1.json

references/helmrelease.md

assets/schemas/helmrelease-helm-v2.json

references/notifications.md

assets/schemas/provider-notification-v1beta3.json

references/notifications.md

assets/schemas/alert-notification-v1beta3.json

references/notifications.md

assets/schemas/receiver-notification-v1.json

references/image-automation.md

assets/schemas/imagerepository-image-v1.json

references/image-automation.md

assets/schemas/imagepolicy-image-v1.json

references/image-automation.md

assets/schemas/imageupdateautomation-image-v1.json

references/repo-patterns.md

references/best-practices.md

references/web-ui.md

references/mcp-server.md

references/terraform-bootstrap.md

references/gitless-image-automation.md