# Flux — GitOps Toolkit for Kubernetes Continuous Delivery

> Flux is a CNCF-graduated GitOps toolkit for Kubernetes. Keep clusters in sync with Git repositories automatically. Composable controllers, Helm/Kustomize support, and image automation.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

## Quick Use

```bash
# Install Flux CLI
brew install fluxcd/tap/flux

# Bootstrap Flux on your cluster with GitHub
export GITHUB_TOKEN=your-pat
flux bootstrap github 
  --owner=your-username 
  --repository=flux-repo 
  --branch=main 
  --path=./clusters/production 
  --personal
```

## Intro

**Flux** is a set of continuous and progressive delivery solutions for Kubernetes that are open and extensible. Originally created by Weaveworks, Flux v2 is a CNCF-graduated project built on a set of composable Kubernetes controllers — the GitOps Toolkit — that you can mix and match to build your ideal GitOps workflow.

With 8K+ GitHub stars and Apache-2.0 license, Flux is the original GitOps tool and remains the purest implementation of GitOps principles — all operations happen through Git, with no UI-based actions.

## What Flux Does

- **GitOps**: Git as the single source of truth for cluster state
- **Auto-Sync**: Continuously reconcile cluster with Git
- **Multi-Source**: Git repositories, Helm repositories, OCI registries, S3 buckets
- **Helm Releases**: Declaratively manage Helm chart deployments
- **Kustomize**: Native Kustomize support
- **Image Automation**: Auto-update image tags in Git when new images are pushed
- **Notifications**: Slack, Discord, MS Teams, webhook alerts
- **Multi-Tenancy**: Isolated GitOps workflows for different teams
- **Cluster Federation**: Manage multiple clusters from a central repository
- **Progressive Delivery**: Canary deployments via Flagger integration

## Architecture

```
┌──────────────┐     ┌──────────────────────────────┐
│  Git Repo    │────▶│  Flux Controllers            │
│  (Source of  │     │  ┌──────────┐  ┌──────────┐  │
│   Truth)     │     │  │ Source   │  │Kustomize │  │
└──────────────┘     │  │Controller│  │Controller│  │
                     │  └──────────┘  └──────────┘  │
                     │  ┌──────────┐  ┌──────────┐  │
                     │  │  Helm    │  │Image Auto│  │
                     │  │Controller│  │Controller│  │
                     │  └──────────┘  └──────────┘  │
                     │  ┌─────────────────────────┐  │
                     │  │   Notification          │  │
                     │  │   Controller            │  │
                     │  └─────────────────────────┘  │
                     └──────────────┬───────────────┘
                                    │
                             ┌──────┴───────┐
                             │  Kubernetes  │
                             │  Cluster     │
                             └──────────────┘
```

## Getting Started

### 1. Install Flux CLI

```bash
# macOS
brew install fluxcd/tap/flux

# Linux
curl -s https://fluxcd.io/install.sh | sudo bash

# Verify
flux --version
```

### 2. Check Prerequisites

```bash
flux check --pre
```

### 3. Bootstrap with GitHub

```bash
export GITHUB_TOKEN=ghp_xxx
export GITHUB_USER=your-username

flux bootstrap github 
  --owner=$GITHUB_USER 
  --repository=fleet-infra 
  --branch=main 
  --path=./clusters/my-cluster 
  --personal
```

This creates a GitHub repo, adds Flux manifests, and installs Flux in your cluster.

### 4. Add Your First Application

```bash
# Create a Git source
flux create source git podinfo 
  --url=https://github.com/stefanprodan/podinfo 
  --branch=master 
  --interval=1m 
  --export > ./clusters/my-cluster/podinfo-source.yaml

# Create a Kustomization
flux create kustomization podinfo 
  --target-namespace=default 
  --source=podinfo 
  --path="./kustomize" 
  --prune=true 
  --interval=10m 
  --export > ./clusters/my-cluster/podinfo-kustomization.yaml

# Commit and push
git add -A && git commit -m "Add podinfo" && git push
```

Flux will automatically detect the new files and deploy podinfo to your cluster.

## Key Concepts

### GitRepository (Source)

```yaml
apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
  name: my-app
  namespace: flux-system
spec:
  interval: 1m
  ref:
    branch: main
  url: https://github.com/org/my-app
  secretRef:
    name: git-credentials
```

### Kustomization

```yaml
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: my-app
  namespace: flux-system
spec:
  interval: 10m
  path: "./kustomize/overlays/production"
  prune: true
  sourceRef:
    kind: GitRepository
    name: my-app
  validation: client
  healthChecks:
    - apiVersion: apps/v1
      kind: Deployment
      name: my-app
      namespace: production
```

### HelmRelease

```yaml
apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
  name: podinfo
  namespace: production
spec:
  interval: 5m
  chart:
    spec:
      chart: podinfo
      version: "6.x"
      sourceRef:
        kind: HelmRepository
        name: podinfo
        namespace: flux-system
  values:
    replicaCount: 3
    resources:
      requests:
        cpu: 100m
        memory: 128Mi
  install:
    remediation:
      retries: 3
  upgrade:
    remediation:
      remediateLastFailure: true
```

### Image Automation

Automatically update image tags when new versions are pushed:

```yaml
# Watch for new image tags
apiVersion: image.toolkit.fluxcd.io/v1beta2
kind: ImageRepository
metadata:
  name: podinfo
spec:
  image: ghcr.io/stefanprodan/podinfo
  interval: 1m

---
# Policy for which tags to use
apiVersion: image.toolkit.fluxcd.io/v1beta2
kind: ImagePolicy
metadata:
  name: podinfo
spec:
  imageRepositoryRef:
    name: podinfo
  policy:
    semver:
      range: ">=6.0.0 <7.0.0"

---
# Update Git automatically
apiVersion: image.toolkit.fluxcd.io/v1beta1
kind: ImageUpdateAutomation
metadata:
  name: podinfo
spec:
  interval: 1m
  sourceRef:
    kind: GitRepository
    name: fleet-infra
  git:
    checkout:
      ref:
        branch: main
    commit:
      author:
        email: fluxbot@users.noreply.github.com
        name: fluxbot
      messageTemplate: '{{range .Updated.Images}}{{println .}}{{end}}'
    push:
      branch: main
  update:
    path: ./clusters/my-cluster
    strategy: Setters
```

### Notifications

```yaml
apiVersion: notification.toolkit.fluxcd.io/v1beta2
kind: Provider
metadata:
  name: slack
spec:
  type: slack
  channel: alerts
  secretRef:
    name: slack-webhook

---
apiVersion: notification.toolkit.fluxcd.io/v1beta2
kind: Alert
metadata:
  name: all-events
spec:
  providerRef:
    name: slack
  eventSeverity: info
  eventSources:
    - kind: GitRepository
      name: '*'
    - kind: Kustomization
      name: '*'
    - kind: HelmRelease
      name: '*'
```

## Flux vs Argo CD

| Feature | Flux | Argo CD |
|---------|------|---------|
| Architecture | Multiple controllers (GitOps Toolkit) | Monolithic |
| UI | Terraform/Weave GitOps (separate) | Built-in beautiful UI |
| Image automation | Built-in | Image Updater (separate) |
| GitOps purity | Strict (no manual sync) | Allows manual sync |
| Multi-tenancy | Native (Flux v2) | Projects |
| Helm support | Full | Full |
| Kustomize | Native | Native |
| Progressive delivery | Via Flagger | Via Argo Rollouts |
| Community | Strong | Very large |

## FAQ

**Q: Flux or Argo CD — which should I choose?**
A: Flux is more purely GitOps (all changes go through Git); Argo CD offers a polished Web UI that supports manual operations. Flux suits teams that want strict GitOps discipline; Argo CD suits teams that need visualization. Both are CNCF graduated projects.

**Q: What if I need a Web UI?**
A: Flux itself has no UI, but you can pair it with Weave GitOps (free) or VMware Tanzu Mission Control (commercial). There are also community tools like Capacitor that provide Flux visualization.

**Q: Is migration costly?**
A: Flux is fully compatible with standard Kubernetes resources (Kustomize, Helm). Migration mainly involves switching existing CI/CD pipelines to a commit-to-Git + Flux auto-sync model. It typically takes 1-2 weeks.

## Sources & Credits

- GitHub: [fluxcd/flux2](https://github.com/fluxcd/flux2) — 8K+ ⭐ | Apache-2.0
- Official site: [fluxcd.io](https://fluxcd.io)

---
Source: https://tokrepo.com/en/workflows/flux-gitops-toolkit-kubernetes-continuous-delivery-ca59b463
Author: AI Open Source