fluxcd

Configure Flux CD GitRepository, Kustomization, and HelmRelease resources; troubleshoot reconciliation and image-update automation.

SKILL.md

GitHub

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

Object Not Ready clue Action
GitRepository auth / clone fail Fix secret, URL, ref
Kustomization build/apply error flux logs; fix YAML
HelmRelease values/schema helm template locally; pin chart
ImagePolicy no tag match Fix semver policy filter

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