FluxCD Skill

FluxCD is the standard GitOps tool for Kubernetes. It continuously reconciles desired state from Git repositories with actual cluster state. Use this skill when:

• Troubleshooting Flux reconciliation failures or synchronization issues

• Managing Flux custom resources (GitRepository, HelmRepository, Kustomization, HelmRelease)

• Analyzing and fixing pod/deployment issues in Flux-managed clusters

• Debugging webhook receivers and automation flows

• Optimizing image automation and deployment strategies

• Understanding cluster state and reconciliation status

Core Concepts

Flux Architecture: FluxCD operates as controllers within Kubernetes that reconcile desired state (from Git) with actual cluster state. The primary components are:

Source Controllers: Pull configuration and charts from Git/OCI registries

• GitRepository: Watch and fetch from Git repositories

• OCIRepository: Fetch from OCI registries

• HelmRepository: Index Helm charts from repositories

Sync Controllers: Apply configuration to the cluster

• Kustomization: Apply Kustomize overlays declaratively

• HelmRelease: Deploy and manage Helm charts with templating

Notification & Webhooks:

• Receiver: Webhook endpoint for Git push notifications

• Provider: Configure notification destinations

• Alert: Monitor resource status changes

Image Automation:

• ImageRepository: Poll container registries

• ImagePolicy: Define versioning policies (semver, alphabetical, etc.)

• ImageUpdateAutomation: Automatically commit image updates to Git

Troubleshooting Workflow

Identify the resource type: Determine which Flux resource is failing (GitRepository, HelmRelease, Kustomization, etc.)

Get resource status: Check the custom resource's status conditions and lastObservedGeneration

Review logs: Examine controller logs for reconciliation errors or warnings

Check dependencies: Verify source resources (GitRepository, HelmRepository) are ready before sync resources

Analyze events: Look at Kubernetes events for more context on failures

Check Git/Registry: Validate that referenced Git branches, OCI registries, or Helm repos are accessible

Common Issues and Patterns

GitRepository Failures

• Authentication: SSH keys or credentials misconfigured

• Branch/ref: Target branch doesn't exist or is wrong

• Network: Repository unreachable or firewall blocked

• Secrets: GitRepository can't find SSH keys or HTTP auth secrets

HelmRelease Failures

• Chart not found: HelmRepository not ready or chart doesn't exist

• Values: Chart values invalid or incompatible with installed version

• Dependencies: Chart dependencies not available

• Secrets: Release references secret that doesn't exist

Kustomization Failures

• Source not ready: Referenced GitRepository hasn't synced yet

• Validation: Kustomize validation errors in the overlay

• RBAC: Controller doesn't have permissions to apply resources

• Reconciliation: Resource conflicts or immutable field changes

Image Automation

• Scan failures: ImageRepository can't access registry

• Policy matching: No tags match the version policy

• Git operations: Can't push image update commits to repository

• Permission: Missing write access to Git repo for automation commits

Key Commands for Analysis

When analyzing a Flux-managed cluster:

• List all Flux resources: kubectl get fluxcd.io or check specific types

• Describe a resource: kubectl describe <resource-type> <name> -n <namespace>

• View status conditions: Look at .status.conditions array

• Check recent events: kubectl describe <resource> -n <namespace> (shows events)

• Review controller logs: kubectl logs -n flux-system deploy/<controller> -f

• Validate Git sync: Check the commit hash in status matches Git

• Test Helm chart: Use helm template to validate rendering

Integration Points

• Git repositories: Source of truth for all configuration

• Container registries: Image sources for workloads

• Helm repositories: Chart repositories for package management

• Kubernetes API: All resources apply via standard kubectl

• Webhooks: Git platforms trigger Flux reconciliation via receivers

References

See the references/ directory for detailed documentation:

• FLUX-API-REFERENCE.md: Complete API reference for all FluxCD custom resources (GitRepository, HelmRelease, Kustomization, ImagePolicy, etc.) with field descriptions, examples, and status conditions

• BEST-PRACTICES.md: Production deployment patterns and optimization strategies

• TROUBLESHOOTING-WORKFLOWS.md: Step-by-step diagnostic procedures for common failure scenarios

• COMMON-COMMANDS.md: kubectl and flux CLI command reference