# 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 in your project root:

## 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 |

## 常见问题

**Q: Flux 和 Argo CD 怎么选？**
A: Flux 更纯粹的 GitOps（所有变更通过 Git），Argo CD 提供漂亮的 Web UI 可以做手动操作。Flux 更适合追求 GitOps 纪律的团队，Argo CD 更适合需要可视化的团队。两者都是 CNCF 毕业项目。

**Q: 需要 Web UI 怎么办？**
A: Flux 本身没有 UI，但可以搭配 Weave GitOps（免费）或 VMware Tanzu Mission Control（商业）。也有社区工具如 Capacitor 提供 Flux 可视化。

**Q: 迁移成本高吗？**
A: Flux 与标准 Kubernetes 资源完全兼容（Kustomize、Helm）。迁移主要是将现有 CI/CD 流水线改为提交 Git + Flux 自动同步。通常 1-2 周可以完成迁移。

## 来源与致谢

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

---
Source: https://tokrepo.com/en/workflows/ca59b463-353d-11f1-9bc6-00163e2b0d79
Author: AI Open Source