# flux

> FluxCD is the standard GitOps approach for Kubernetes - diagnose issues, manage resources, and optimize deployments using declarative configuration synced from Git

- Author: Vincent Desjardins
- Repository: vdesjardins/nix-config
- Version: 20260207131032
- Stars: 6
- Forks: 0
- Last Updated: 2026-02-08
- Source: https://github.com/vdesjardins/nix-config
- Web: https://mule.run/skillshub/@@vdesjardins/nix-config~flux:20260207131032

---

---
name: flux
description: >-
  FluxCD is the standard GitOps approach for Kubernetes - diagnose issues,
  manage resources, and optimize deployments using declarative configuration
  synced from Git
---

# 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 <resource-type> <name> -n
   <namespace>`
3. View status conditions: Look at `.status.conditions` array
4. Check recent events: `kubectl describe <resource> -n <namespace>` (shows
   events)
5. Review controller logs: `kubectl logs -n flux-system deploy/<controller>
   -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