Flux CD Expert

This skill covers Flux CD v2. Flux is a set of continuous delivery controllers for Kubernetes that reconcile the cluster state against desired state stored in Git repositories, Helm charts, OCI artifacts, and S3-compatible buckets.

How to Approach Tasks

Classify the request:
- Troubleshooting -- Load references/diagnostics.md for reconciliation failures, source errors, and connectivity issues
- Architecture -- Load references/architecture.md for controller design, reconciliation loop, source types, and multi-tenancy model
- Best practices -- Load references/best-practices.md for repository structure, Helm/Kustomize patterns, security, and scaling
Load context -- Read the relevant reference file.
Analyze -- Apply Flux-specific reasoning. Consider source type, reconciliation interval, dependency ordering, and namespace scoping.
Recommend -- Provide Flux CRD YAML examples and flux CLI commands.
Verify -- Suggest validation (flux get all, flux reconcile, flux logs).

Core Concepts

Flux Components

Controller	CRDs	Purpose
Source Controller	GitRepository, HelmRepository, OCIRepository, Bucket	Fetch artifacts from external sources
Kustomize Controller	Kustomization	Apply Kustomize overlays and plain YAML
Helm Controller	HelmRelease	Manage Helm chart releases
Notification Controller	Provider, Alert, Receiver	Send/receive notifications and webhooks
Image Reflector	ImageRepository, ImagePolicy	Scan container registries for new tags
Image Automation	ImageUpdateAutomation	Automatically update image tags in Git

Bootstrap

# Bootstrap Flux with GitHub
flux bootstrap github \
  --owner=my-org \
  --repository=fleet-config \
  --branch=main \
  --path=clusters/production \
  --personal

# Bootstrap with GitLab
flux bootstrap gitlab \
  --owner=my-group \
  --repository=fleet-config \
  --branch=main \
  --path=clusters/production

Bootstrap:

Creates the Git repository (if it doesn't exist)
Installs Flux controllers in the cluster
Configures Flux to manage itself from the repository
Creates the initial Kustomization pointing to --path

Source: GitRepository

apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
spec:
  interval: 5m
  url: https://github.com/org/config-repo.git
  ref:
    branch: main
  secretRef:
    name: git-credentials    # SSH key or token
  ignore: |
    # Ignore files not relevant to deployment
    /*.md
    /docs/

Kustomization (Flux CRD)

apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
spec:
  interval: 10m
  targetNamespace: myapp
  sourceRef:
    kind: GitRepository
    name: app-config
  path: ./overlays/production
  prune: true                    # Delete resources removed from Git
  timeout: 5m
  retryInterval: 2m
  wait: true                     # Wait for resources to be ready
  force: false                   # Don't force apply (avoids conflicts)
  healthChecks:
    - apiVersion: apps/v1
      kind: Deployment
      name: myapp
      namespace: myapp
  dependsOn:
    - name: cert-manager         # Wait for cert-manager to be ready
    - name: database             # Wait for database to be ready
  postBuild:
    substitute:
      ENVIRONMENT: production
    substituteFrom:
      - kind: ConfigMap
        name: cluster-config

Important: Flux's Kustomization CRD is different from Kubernetes' Kustomization (kustomize.config.k8s.io/v1beta1). Flux's version wraps Kustomize and adds reconciliation, health checks, and dependency management.

HelmRelease

apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
spec:
  interval: 30m
  chart:
    spec:
      chart: ingress-nginx
      version: '4.x'              # Semver range
      sourceRef:
        kind: HelmRepository
        name: ingress-nginx
      interval: 12h               # How often to check for new chart versions
  values:
    controller:
      replicaCount: 3
      resources:
        requests:
          cpu: 200m
          memory: 256Mi
  valuesFrom:
    - kind: ConfigMap
      name: ingress-values
      valuesKey: overrides.yaml
  upgrade:
    remediation:
      retries: 3
      remediateLastFailure: true
  rollback:
    cleanupOnFail: true
  test:
    enable: true                  # Run Helm tests after install/upgrade
  install:
    createNamespace: true
  uninstall:
    keepHistory: false

HelmRepository

apiVersion: source.toolkit.fluxcd.io/v1
kind: HelmRepository
spec:
  interval: 24h
  url: https://kubernetes.github.io/ingress-nginx
  type: default    # or 'oci' for OCI registries

Image Automation

Automatically update container image tags in Git when new images are pushed:

# 1. Scan registry for tags
apiVersion: image.toolkit.fluxcd.io/v1beta2
kind: ImageRepository
spec:
  image: ghcr.io/org/myapp
  interval: 5m

# 2. Define policy for selecting tags
apiVersion: image.toolkit.fluxcd.io/v1beta2
kind: ImagePolicy
spec:
  imageRepositoryRef:
    name: myapp
  policy:
    semver:
      range: '>=1.0.0'

# 3. Automate Git updates
apiVersion: image.toolkit.fluxcd.io/v1beta2
kind: ImageUpdateAutomation
spec:
  interval: 30m
  sourceRef:
    kind: GitRepository
    name: app-config
  git:
    checkout:
      ref:
        branch: main
    commit:
      author:
        name: fluxcdbot
        email: flux@example.com
      messageTemplate: 'Update image {{ range .Changed.Changes }}{{ .OldValue }} -> {{ .NewValue }}{{ end }}'
    push:
      branch: main
  update:
    path: ./overlays/production
    strategy: Setters

Mark fields in YAML for auto-update:

spec:
  containers:
    - name: myapp
      image: ghcr.io/org/myapp:1.2.3  # {"$imagepolicy": "flux-system:myapp"}

Dependency Ordering

# cert-manager must be ready before apps
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
  dependsOn:
    - name: cert-manager
    - name: database
  # myapp won't reconcile until cert-manager and database are Ready

Notifications

# Provider: where to send notifications
apiVersion: notification.toolkit.fluxcd.io/v1beta3
kind: Provider
spec:
  type: slack
  channel: deployments
  secretRef:
    name: slack-webhook-url

# Alert: what events to notify about
apiVersion: notification.toolkit.fluxcd.io/v1beta3
kind: Alert
spec:
  providerRef:
    name: slack
  eventSeverity: info
  eventSources:
    - kind: Kustomization
      name: '*'
    - kind: HelmRelease
      name: '*'

CLI Reference

# Status
flux get all                          # All resources
flux get kustomizations               # Kustomizations
flux get helmreleases                 # HelmReleases
flux get sources git                  # Git sources

# Reconciliation
flux reconcile source git app-config  # Force Git pull
flux reconcile kustomization myapp    # Force Kustomize apply
flux reconcile helmrelease nginx      # Force Helm upgrade

# Debugging
flux logs                             # All controller logs
flux logs --kind=Kustomization        # Filtered by kind
flux events                           # Recent events

# Suspend/Resume
flux suspend kustomization myapp      # Pause reconciliation
flux resume kustomization myapp       # Resume

# Export (backup)
flux export source git --all > sources.yaml
flux export kustomization --all > kustomizations.yaml

# Health check
flux check                            # Verify Flux installation
flux check --pre                      # Pre-flight checks

Reference Files

references/architecture.md — Controller design, reconciliation loop, source types, artifact storage, multi-tenancy model
references/best-practices.md — Repository structure, Kustomize/Helm patterns, multi-cluster, security, dependency management
references/diagnostics.md — Reconciliation failures, source errors, Helm release issues, image automation problems

flux

SKILL.mdplugins/devops/skills/flux/SKILL.md