fluxcd

Flux CD GitOps AI Skill Guide

Overview

Flux reconciles Kubernetes clusters from Git using composable controllers: source-controller (GitRepository, OCIRepository, HelmRepository), kustomize-controller, helm-controller, and optional image-automation. Unlike a single Application CR, Flux models sources and apply pipelines as separate objects. Agents should debug by reading Ready conditions on each object in the dependency chain.

GitRepository / OCIRepository
        |
        v
Kustomization / HelmRelease  -->  cluster apply
        ^
ImageRepository + ImagePolicy + ImageUpdateAutomation (optional)

When to use

• Bootstrapping Flux on a cluster (flux bootstrap)
• Authoring GitRepository + Kustomization or HelmRelease pipelines
• Debugging stalled reconciliations and chart render errors
• Image tag automation updating Git automatically

Operational directives

1. Trace Ready conditions from source -> Kustomization/HelmRelease -> workload health.
2. Prefer immutable digests in production overlays; use image automation deliberately.
3. Keep bootstrap and tenant paths separated; restrict Impersonation / SA privileges.
4. Use flux reconcile after Git pushes when waiting on long intervals is costly.
5. Do not manually patch Flux-managed resources without suspending first.

Concrete examples

Bootstrap (GitHub)

flux bootstrap github \
  --owner=example \
  --repository=fleet-gitops \
  --branch=main \
  --path=clusters/prod \
  --personal

GitRepository + Kustomization

apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
  name: platform
  namespace: flux-system
spec:
  interval: 1m
  url: https://github.com/example/fleet-gitops
  ref: { branch: main }
---
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: api
  namespace: flux-system
spec:
  interval: 5m
  path: ./apps/api/prod
  prune: true
  sourceRef:
    kind: GitRepository
    name: platform
  targetNamespace: api