# fluxcd/flux2 architecture

> Architecture diagram of the GitHub repository fluxcd/flux2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fluxcd/flux2
- Repository: https://github.com/fluxcd/flux2

## Overview

Flux v2’s repository here is the `flux` command-line client, not the GitOps Toolkit controllers themselves. A user invokes commands to bootstrap or manage a cluster: the CLI supports source and workload operations, reconciliation and status inspection, image automation, notifications, Helm releases, and plugin management. Bootstrap has plain-Git and provider-backed implementations; supporting packages generate manifests and apply them to Kubernetes. The README documents broader toolkit capabilities, but their controllers are outside this tree. Several command families are unsampled, so their internal call links are omitted.

Main entry points: [`pkg/bootstrap/bootstrap.go`](https://github.com/fluxcd/flux2/blob/main/pkg/bootstrap/bootstrap.go) (Bootstrap orchestration), [`pkg/bootstrap/bootstrap_plain_git.go`](https://github.com/fluxcd/flux2/blob/main/pkg/bootstrap/bootstrap_plain_git.go) (Plain Git bootstrap), [`internal/utils/apply.go`](https://github.com/fluxcd/flux2/blob/main/internal/utils/apply.go) (Cluster apply), [`cmd/flux/main.go`](https://github.com/fluxcd/flux2/blob/main/cmd/flux/main.go) (Flux command)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI commands"]
  node_fluxcli["Flux command<br/>[main.go]"]
  node_sources["Sources<br/>[source.go]"]
  node_kustomize["Kustomizations<br/>[kustomization.go]"]
  node_helm["Helm releases<br/>[helmrelease.go]"]
  node_images["Image automation<br/>[image.go]"]
  node_notifications["Notifications<br/>[alert.go]"]
  node_uninstall["Flux uninstall<br/>[uninstall.go]"]
end

subgraph group_bootstrap["Bootstrap"]
  node_bootstrap_cmd["Bootstrap command<br/>[bootstrap.go]"]
  node_bootstrap_api["Bootstrap orchestration<br/>[bootstrap.go]"]
  node_plain_git["Plain Git bootstrap"]
  node_provider_bootstrap["Provider bootstrap"]
  node_provider_factory["Provider factory<br/>[factory.go]"]
end

subgraph group_manifest["Manifest operations"]
  node_install_manifests["Install manifests<br/>[manifests.go]"]
  node_sync_manifests["Sync manifests<br/>[sync.go]"]
  node_kustomize_gen["Kustomize generation<br/>[kustomization.go]"]
  node_apply["Cluster apply<br/>[apply.go]"]
end

subgraph group_extensions["Extensions"]
  node_plugins["Plugin catalog<br/>[catalog.go]"]
  node_plugin_install["Plugin installation<br/>[install.go]"]
end

node_user(("Cluster operator"))
node_cluster[("Kubernetes API")]

node_user -->|"runs commands"| node_fluxcli
node_fluxcli -.->|"bootstraps"| node_bootstrap_cmd
node_bootstrap_cmd -.->|"invokes"| node_bootstrap_api
node_bootstrap_api -.->|"uses Git mode"| node_plain_git
node_bootstrap_api -.->|"uses provider mode"| node_provider_bootstrap
node_provider_bootstrap -->|"creates provider"| node_provider_factory
node_bootstrap_api -->|"generates components"| node_install_manifests
node_plain_git -->|"generates components"| node_install_manifests
node_plain_git -->|"generates sync"| node_sync_manifests
node_plain_git -->|"applies sync"| node_apply
node_apply -->|"builds Kustomize"| node_kustomize_gen
node_apply -.->|"applies resources"| node_cluster
node_user -->|"manages sources"| node_sources
node_user -->|"manages deployments"| node_kustomize
node_user -->|"manages releases"| node_helm
node_user -->|"automates image updates"| node_images
node_user -->|"configures alerts"| node_notifications
node_user -->|"uninstalls Flux"| node_uninstall
node_user -.->|"searches plugins"| node_plugins
node_plugins -.->|"installs selected plugin"| node_plugin_install

click node_fluxcli "https://github.com/fluxcd/flux2/blob/main/cmd/flux/main.go"
click node_sources "https://github.com/fluxcd/flux2/blob/main/cmd/flux/source.go"
click node_kustomize "https://github.com/fluxcd/flux2/blob/main/cmd/flux/kustomization.go"
click node_helm "https://github.com/fluxcd/flux2/blob/main/cmd/flux/helmrelease.go"
click node_images "https://github.com/fluxcd/flux2/blob/main/cmd/flux/image.go"
click node_notifications "https://github.com/fluxcd/flux2/blob/main/cmd/flux/alert.go"
click node_bootstrap_cmd "https://github.com/fluxcd/flux2/blob/main/cmd/flux/bootstrap.go"
click node_bootstrap_api "https://github.com/fluxcd/flux2/blob/main/pkg/bootstrap/bootstrap.go"
click node_plain_git "https://github.com/fluxcd/flux2/blob/main/pkg/bootstrap/bootstrap_plain_git.go"
click node_provider_bootstrap "https://github.com/fluxcd/flux2/blob/main/pkg/bootstrap/bootstrap_provider.go"
click node_provider_factory "https://github.com/fluxcd/flux2/blob/main/pkg/bootstrap/provider/factory.go"
click node_install_manifests "https://github.com/fluxcd/flux2/blob/main/pkg/manifestgen/install/manifests.go"
click node_sync_manifests "https://github.com/fluxcd/flux2/blob/main/pkg/manifestgen/sync/sync.go"
click node_kustomize_gen "https://github.com/fluxcd/flux2/blob/main/pkg/manifestgen/kustomization/kustomization.go"
click node_apply "https://github.com/fluxcd/flux2/blob/main/internal/utils/apply.go"
click node_plugins "https://github.com/fluxcd/flux2/blob/main/internal/plugin/catalog.go"
click node_plugin_install "https://github.com/fluxcd/flux2/blob/main/internal/plugin/install.go"
click node_uninstall "https://github.com/fluxcd/flux2/blob/main/pkg/uninstall/uninstall.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_fluxcli,node_sources,node_kustomize,node_helm,node_images,node_notifications,node_uninstall toneBlue
class node_bootstrap_cmd,node_bootstrap_api,node_plain_git,node_provider_bootstrap,node_provider_factory,node_cluster toneAmber
class node_install_manifests,node_sync_manifests,node_kustomize_gen,node_apply toneMint
class node_plugins,node_plugin_install toneRose
class node_user toneIndigo
```

## Components

### CLI commands

- [Flux command](https://github.com/fluxcd/flux2/blob/main/cmd/flux/main.go): `cmd/flux/main.go`
- [Sources](https://github.com/fluxcd/flux2/blob/main/cmd/flux/source.go): `cmd/flux/source.go`
- [Kustomizations](https://github.com/fluxcd/flux2/blob/main/cmd/flux/kustomization.go): `cmd/flux/kustomization.go`
- [Helm releases](https://github.com/fluxcd/flux2/blob/main/cmd/flux/helmrelease.go): `cmd/flux/helmrelease.go`
- [Image automation](https://github.com/fluxcd/flux2/blob/main/cmd/flux/image.go): `cmd/flux/image.go`
- [Notifications](https://github.com/fluxcd/flux2/blob/main/cmd/flux/alert.go): `cmd/flux/alert.go`
- [Flux uninstall](https://github.com/fluxcd/flux2/blob/main/pkg/uninstall/uninstall.go): `pkg/uninstall/uninstall.go`

### Bootstrap

- [Bootstrap command](https://github.com/fluxcd/flux2/blob/main/cmd/flux/bootstrap.go): `cmd/flux/bootstrap.go`
- [Bootstrap orchestration](https://github.com/fluxcd/flux2/blob/main/pkg/bootstrap/bootstrap.go): `pkg/bootstrap/bootstrap.go`
- [Plain Git bootstrap](https://github.com/fluxcd/flux2/blob/main/pkg/bootstrap/bootstrap_plain_git.go): `pkg/bootstrap/bootstrap_plain_git.go`
- [Provider bootstrap](https://github.com/fluxcd/flux2/blob/main/pkg/bootstrap/bootstrap_provider.go): `pkg/bootstrap/bootstrap_provider.go`
- [Provider factory](https://github.com/fluxcd/flux2/blob/main/pkg/bootstrap/provider/factory.go): `pkg/bootstrap/provider/factory.go`

### Manifest operations

- [Install manifests](https://github.com/fluxcd/flux2/blob/main/pkg/manifestgen/install/manifests.go): `pkg/manifestgen/install/manifests.go`
- [Sync manifests](https://github.com/fluxcd/flux2/blob/main/pkg/manifestgen/sync/sync.go): `pkg/manifestgen/sync/sync.go`
- [Kustomize generation](https://github.com/fluxcd/flux2/blob/main/pkg/manifestgen/kustomization/kustomization.go): `pkg/manifestgen/kustomization/kustomization.go`
- [Cluster apply](https://github.com/fluxcd/flux2/blob/main/internal/utils/apply.go): `internal/utils/apply.go`

### Extensions

- [Plugin catalog](https://github.com/fluxcd/flux2/blob/main/internal/plugin/catalog.go): `internal/plugin/catalog.go`
- [Plugin installation](https://github.com/fluxcd/flux2/blob/main/internal/plugin/install.go): `internal/plugin/install.go`

### Other components

- **Cluster operator**
- **Kubernetes API**

## Connections

- Cluster operator → Flux command: runs commands (evidence: `cmd/flux/main.go`)
- Flux command → Bootstrap command: bootstraps
- Bootstrap command → Bootstrap orchestration: invokes
- Bootstrap orchestration → Plain Git bootstrap: uses Git mode
- Bootstrap orchestration → Provider bootstrap: uses provider mode
- Provider bootstrap → Provider factory: creates provider (evidence: `pkg/bootstrap/bootstrap_provider.go`)
- Bootstrap orchestration → Install manifests: generates components (evidence: `pkg/bootstrap/bootstrap.go`)
- Plain Git bootstrap → Install manifests: generates components (evidence: `pkg/bootstrap/bootstrap_plain_git.go`)
- Plain Git bootstrap → Sync manifests: generates sync (evidence: `pkg/bootstrap/bootstrap_plain_git.go`)
- Plain Git bootstrap → Cluster apply: applies sync (evidence: `pkg/bootstrap/bootstrap_plain_git.go`)
- Cluster apply → Kustomize generation: builds Kustomize (evidence: `internal/utils/apply.go`)
- Cluster apply → Kubernetes API: applies resources
- Cluster operator → Sources: manages sources (evidence: `README.md`)
- Cluster operator → Kustomizations: manages deployments (evidence: `README.md`)
- Cluster operator → Helm releases: manages releases (evidence: `README.md`)
- Cluster operator → Image automation: automates image updates (evidence: `README.md`)
- Cluster operator → Notifications: configures alerts (evidence: `README.md`)
- Cluster operator → Flux uninstall: uninstalls Flux
- Cluster operator → Plugin catalog: searches plugins
- Plugin catalog → Plugin installation: installs selected plugin
