gitops-knowledge

--- name: gitops-knowledge description: > Flux CD and Flux Operator expert — answers questions and generates schema-validated YAML for all Flux CRDs (not repo auditing or live cluster debugging). Use when users ask about Flux concepts, want manifests for HelmRelease, Kustomization, GitRepository, OCIRepository, ResourceSet, FluxInstance, or any Flux resource. When user needs guidance on GitOps repository structure, bootstrap Flux with Terraform, multi-tenancy, OCI-based delivery, image tag automation, drift detection, preview environments, monorepo app delivery, running migration Jobs before or after a deployment, notifications, or the Flux Web UI and MCP Server. license: Apache-2.0 ---

# 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, verify field names, types, enums and required fields against its field index in `assets/schemas/`. Each line is `<dotted.path> <type> [(required)] [enum=a|b] [default=x] [pattern="..."] [min=N max=N] # description` (arrays as `path[]`, maps as `<map[string]T>`). Grep a path prefix to list a subtree (`grep '^spec\.chart\.' assets/schemas/helmrelease-helm-v2.fields.txt`) or a field name to find where it lives. Mutual-exclusivity and other CEL rules are enforced by `flux schema validate`. - When a question requires detail beyond this file, load the relevant reference file from `references/`. - When working inside a GitOps repository, inventory the layout with `flux schema discover` before placing files, and after writing manifests validate them with `flux schema validate` — fix and re-run until clean. Load `references/flux-cli.md` for the full CLI workflow, local rendering, and overlay debugging. If the tools aren't installed, skip validation and say so. - 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: Git or OCI registries are the source of truth, and Flux continuously reconciles that desired state with the cluster. Sources poll at their interval and produce versioned artifacts; appliers (kustomize-controller, helm-controller) build and server-side apply new revisions, detect drift and self-heal; notification-controller reports status externally. **Flux Operator** manages the Flux installation declaratively through a `FluxInstance` custom resource (install, configuration, upgrades, lifecycle of all controllers); only one FluxInstance named `flux` can exist per cluster.

``` 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, ... ```

**Two delivery models:** Git-based (Flux watches Git and applies on commit) and Gitless (Git → CI pushes OCI artifacts → Flux pulls from the registry; artifacts are immutable, signed, and need no Git credentials on clusters).

## Controllers, CRDs and References

The field index for each CRD is `assets/schemas/<kind>-<group>-<version>.fields.txt` in lowercase (e.g. `helmrelease-helm-v2.fields.txt`, `fluxinstance-fluxcd-v1.fields.txt`).

| Kind | apiVersion | Controller | Reference | |------|-----------|------------|-----------| | 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 | (3rd-party controllers) | `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/v1beta3 | 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` |

| Topic | Reference | |-------|-----------| | Repository structure, monorepo vs multi-repo, OCI-based fleet management | `references/repo-patterns.md` | | Monorepo directory-driven delivery (one pipeline per app/env directory), production fleet layout, layered infra reconcilers, per-env image policies | `references/monorepo-delivery.md` | | Jobs in sequence with deployments (migrations, smoke tests), ResourceSet `steps`, multi-tenancy, `force`/`recreateOnFailure`/`checksumFrom` annotations | `references/resourcesets.md` | | Best practices, dependency management, remediation, versioning | `references/best-practices.md` | | Gitless GitOps, Flux OCI artifacts, `flux push artifact`, registry-based delivery | `references/gitless-gitops.md` | | Gitless image automation (ResourceSet + OCIArtifactTag) | `references/gitless-image-automation.md` | | Flux CLI and plugins: `flux schema` discover/validate/extract, local rendering with `flux build` and `flux operator build`, overlay debugging | `references/flux-cli.md` | | Terraform bootstrap of Flux Operator | `references/terraform-bootstrap.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` |

## Ordering and Reactivity

Use `dependsOn` to control reconciliation order (CRDs before CRs, infrastructure before apps):

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

ResourceSet `dependsOn` entries take `apiVersion`/`kind`/`name`/`namespace` of any resource, plus `ready: true` or a `readyExpr` CEL expression for custom readiness. For ordering *within* a single ResourceSet, use `spec.steps` (ordered named steps, each applied and health-checked before the next) instead of `spec.resources` — see `references/resourcesets.md`.

Controllers poll sources at their interval. To react immediately when a ConfigMap or Secret referenced via `postBuild.substituteFrom` or `valuesFrom` changes, label it `reconcile.fluxcd.io/watch: Enabled`.

## 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) - **Monorepo where every `apps/<app>/envs/<env>` directory gets its own pipeline automatically** → `ArtifactGenerator` `pathPattern` + `ResourceSetInputProvider` (`type: ExternalArtifact`) + `ResourceSet` templating a `Kustomization` per artifact — load `references/monorepo-delivery.md` - **Helm chart + env-specific values from Git** → `ArtifactGenerator` (composes chart with values overlay)

### Kustomization vs HelmRelease vs ResourceSet?

- **Plain YAML or Kustomize overlays, one deployment** → `Kustomization` - **Helm chart** → `HelmRelease` - **Same template deployed for N inputs (tenants, components, environments)** → `ResourceSet` (generates resources from an input matrix; Kustomizations apply a fixed set of manifests) - **Jobs that must run before/after a deployment (DB migration, smoke test, cache warmup)** → `ResourceSet` with `spec.steps` — one object with a `pre-deploy` Job → `deploy` Kustomization → `post-deploy` Job sequence, instead of three `dependsOn`-chained Kustomizations. See `references/resourcesets.md` (Step-Based Reconciliation). - Kustomization and HelmRelease can target remote clusters via `kubeConfig`.

### How to Set Up GitOps from Scratch

Install Flux Operator (Helm chart or Terraform) → create a `FluxInstance` named `flux` in `flux-system` with `.spec.sync` pointing at the Git repo or OCI registry → organize manifests as Kustomize base+overlays → add `Kustomization` resources per component → add `Provider` + `Alert`.

## Canonical YAML Patterns

### 1. GitOps Pipeline (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 ```

### 2. Helm from OCI Registry (Recommended)

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

For HTTPS Helm repositories use `HelmRepository` + `HelmRelease` with `spec.chart.spec` (`chart`, `version: "3.x"`, `sourceRef`) instead of `chartRef` — see `references/helmrelease.md`.

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

### 4. ResourceSet for Multi-Component Orchestration

A `ResourceSet` lists `spec.inputs` (e.g. `tenant`/`environment` pairs) and `spec.resources` templates that reference them with `<< inputs.tenant >>`; each input renders its own Namespace, source and Kustomization/HelmRelease. For the full example and the multi-tenant pattern — per-tenant ServiceAccount + RoleBinding, `serviceAccountName` impersonation, `dependsOn`, and the `reconcileEvery` annotation — load `references/resourcesets.md`.

### 5. Image Automation

- **Git-based** — `ImageRepository` + `ImagePolicy` + `ImageUpdateAutomation` commit tag bumps to Git via `$imagepolicy` YAML mark