# Vdesjardins Nix Config Skill Flux > FluxCD Skill - Skill: `tomevault-io/vdesjardins-nix-config-skill-flux` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/vdesjardins-nix-config-skill-flux` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/vdesjardins-nix-config-skill-flux/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/vdesjardins-nix-config-skill-flux --- # 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 1. **Identify the resource type**: Determine which Flux resource is failing (GitRepository, HelmRelease, Kustomization, etc.) 2. **Get resource status**: Check the custom resource's status conditions and lastObservedGeneration 3. **Review logs**: Examine controller logs for reconciliation errors or warnings 4. **Check dependencies**: Verify source resources (GitRepository, HelmRepository) are ready before sync resources 5. **Analyze events**: Look at Kubernetes events for more context on failures 6. **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: 1. List all Flux resources: `kubectl get fluxcd.io` or check specific types 2. Describe a resource: `kubectl describe -n ` 3. View status conditions: Look at `.status.conditions` array 4. Check recent events: `kubectl describe -n ` (shows events) 5. Review controller logs: `kubectl logs -n flux-system deploy/ -f` 6. Validate Git sync: Check the commit hash in status matches Git 7. 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 --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/vdesjardins) — claim your Tome and manage your conversions.