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.ioor check specific types - Describe a resource:
kubectl describe <resource-type> <name> -n <namespace> - View status conditions: Look at
.status.conditionsarray - 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 templateto 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