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

HelmRelease sketch

apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
  name: redis
  namespace: data
spec:
  interval: 10m
  chart:
    spec:
      chart: redis
      version: "19.x"
      sourceRef:
        kind: HelmRepository
        name: bitnami
        namespace: flux-system
  values:
    auth:
      enabled: true

CLI debug chain

flux get sources git
flux get kustomizations
flux get helmreleases -A
flux logs --kind=Kustomization --name=api
flux reconcile source git platform
flux reconcile kustomization api --with-source
flux suspend kustomization api
flux resume kustomization api

Condition cheat sheet

Best practices

1. Directory-per-cluster under clusters/ with clear promotion paths.
2. Enable prune carefully; review inventory before first automated prune.
3. Use OCI artifacts for air-gapped or signed delivery when required.
4. Document suspend/resume runbook for incident freezes.

Limitations

• Flux does not replace CI builds; it consumes artifacts and manifests.
• Multi-tenancy needs careful RBAC and namespace isolation.
• HelmRelease debugging can be opaque without local helm rendering.

Related skills

• argocd - alternative GitOps UX and Application model
• kubernetes - workload-level failure diagnosis
• trivy - scan images before automation bumps tags
• makefile-automation - local render/validate targets for GitOps repos