FluxCD Official Documentation: The Complete Guide to GitOps on Kubernetes
Add to your library first to use in Claude Code
About
A comprehensive reference for FluxCD, the CNCF Graduated project for GitOps-based continuous delivery on Kubernetes.
Preview
FluxCD Official Documentation: The Complete Guide to GitOps on Kubernetes
About This Book
This book is a comprehensive reference for FluxCD, the CNCF Graduated project for GitOps-based continuous delivery on Kubernetes. It covers everything from core concepts and installation to advanced topics like OCI artifacts, secrets management, multi-tenancy security, monitoring, cloud integrations, and operational best practices. Based on the official FluxCD documentation (https://github.com/fluxcd/website).
Part I: Foundations
Chapter 1: Introduction to Flux
Flux is a tool for keeping Kubernetes clusters in sync with sources of configuration (like Git repositories), and automating updates to configuration when there is new code to deploy.
Flux is built from the ground up to use Kubernetes' API extension system, and to integrate with Prometheus and other core components of the Kubernetes ecosystem. Flux supports multi-tenancy and syncing an arbitrary number of Git repositories.
Who is Flux For?
Flux helps:
- Cluster operators who automate provision and configuration of clusters
- Platform engineers who build continuous delivery for developer teams
- App developers who rely on continuous delivery to get their code live
Key Features
- Source configuration from Git and Helm repositories, and S3-compatible buckets
- Kustomize and Helm support
- Event-triggered and periodic reconciliation
- Integration with Kubernetes RBAC
- Health assessment (clusters and workloads)
- Dependency management (infrastructure and workloads)
- Alerting to external systems (webhook senders)
- External events handling (webhook receivers)
- Automated container image updates to Git (image scanning and patching)
- Policy-driven validation (OPA, Kyverno, admission controllers)
- Seamless integration with Git providers (GitHub, GitLab, Bitbucket)
- Interoperability with workflow providers (GitHub Actions, Tekton, Argo)
- Interoperability with Cluster API (CAPI) providers
Flux in Short
| Feature | Description |
|---|---|
| GitOps for apps and infrastructure | Flux and Flagger deploy apps with canaries, feature flags, and A/B rollouts. Flux can also manage any Kubernetes resource. |
| Just push to Git | Flux enables application deployment (CD) and progressive delivery (PD) through automatic reconciliation. |
| Works with existing tools | Flux works with GitHub, GitLab, Bitbucket, S3-compatible buckets, all major container registries, and fully integrates with OCI. |
| Security by design | Pull vs. Push, least amount of privileges, adherence to Kubernetes security policies. |
| Works with any Kubernetes | Kustomize, Helm, RBAC, and policy-driven validation (OPA, Kyverno, admission controllers). |
| Multi-Tenancy | Flux uses true Kubernetes RBAC via impersonation and supports multiple Git repositories. |
| Alerts and notifications | Flux provides health assessments, alerting to external systems, and external events handling. |
| CNCF Graduated | Flux is a CNCF Graduated project, categorised as "Adopt" on the CNCF CI/CD Tech Radar. |
Chapter 2: Core Concepts
GitOps
GitOps is a way of managing your infrastructure and applications so that the whole system is described declaratively and version controlled (most likely in a Git repository), and having an automated process that ensures that the deployed environment matches the state specified in a repository.
Key GitOps Principles (from OpenGitOps):
- Declarative: The desired state of the system is expressed declaratively
- Versioned and Immutable: The desired state is stored in a way that enforces immutability and versioning
- Pulled Automatically: Software agents automatically pull the desired state declarations
- Continuously Reconciled: Software agents continuously observe actual system state and attempt to apply the desired state
Gitless GitOps
Gitless GitOps was pioneered by the Flux team back in 2022 with the introduction of the OCIRepository source type and Flux OCI Artifact media type.
In the Gitless GitOps model, the Flux controllers are fully decoupled from Git, relying solely on container registries as the source of truth for the desired state of Kubernetes clusters. From a user perspective, Git remains the primary interface for managing the desired state, but the underlying implementation leverages OCI-compliant registries to store and distribute the configuration artifacts.
This approach allows for greater flexibility and scalability — the Git server is no longer a production dependency, while the OCI registry becomes the unified source of truth for all configuration artifacts, SBOMs, cryptographic signatures, and app images.
Sources
A Source defines the origin of a repository containing the desired state of the system and the requirements to obtain it (e.g. credentials, version selectors).
Sources produce an artifact that is consumed by other Flux components to perform actions. A source may be shared by multiple consumers to deduplicate configuration and/or storage. The origin is checked for changes on a defined interval.
All sources are specified as Custom Resources: GitRepository, OCIRepository, HelmRepository and Bucket.
Reconciliation
Reconciliation refers to ensuring that a given state matches a desired state declaratively defined somewhere.
Examples:
- OCIRepository: downloads and stores OCI Artifact contents on interval
- HelmRelease: ensures Helm release state matches the resource definition
- Kustomization: ensures deployed application state matches resources in Git/OCI/S3
Kustomization
The Kustomization custom resource represents a local set of Kubernetes resources that Flux reconciles in the cluster. Default reconciliation interval is 5 minutes. Changes made via kubectl edit/patch/delete are promptly reverted.
Bootstrap
The process of installing Flux components in a GitOps manner. Manifests are applied to the cluster, a GitRepository and Kustomization are created, then manifests are pushed to a Git repository. Flux can manage itself.
Continuous Delivery vs. Continuous Deployment
- Continuous Delivery: delivering software updates frequently and reliably
- Continuous Deployment: automatically deploying code changes to production after automated testing
Progressive Delivery
Progressive Delivery gradually rolls out new features using techniques like feature flags, canary releases, and A/B testing. The Flux project offers Flagger for this purpose.
Chapter 3: GitOps Toolkit Components
Flux is constructed with the GitOps Toolkit — specialized tools, composable APIs, and reusable Go packages under the fluxcd GitHub organisation.
Source Controllers
Manages the lifecycle of Flux sources. Fetches artifacts from external sources and makes them available to other controllers.
Custom Resources:
- GitRepository — tracks a Git repository
- OCIRepository — tracks an OCI artifact in a container registry
- HelmRepository — tracks a Helm chart repository index
- HelmChart — tracks a Helm chart
- Bucket — tracks an S3-compatible bucket
- ExternalArtifact — references external artifacts
- ArtifactGenerator — generates artifacts programmatically
Key Options:
--concurrent(default 2) — number of concurrent reconciliations--artifact-retention-records(default 2) — number of artifact revisions retained--helm-chart-max-size(default 10MB) — max Helm chart size--helm-index-max-size(default 50MB) — max Helm repo index size--interval-jitter-percentage(default 5) — jitter for reconciliation interval- Feature gates:
CacheSecretsAndConfigMaps,ObjectLevelWorkloadIdentity,OptimizedGitClones
Kustomize Controller
Applies Kubernetes manifests from sources. Supports Kustomize overlays, in-line patches, variable substitution, and SOPS-based secret decryption.
Custom Resources:
- Kustomization — defines resources to reconcile
Key Options:
--concurrent(default 4),--concurrent-ssa(default 4)--no-remote-bases— disable external kustomize bases--sops-age-secret— secret name for age decryption- Feature gates:
StrictPostBuildSubstitutions,GroupChangeLog
Helm Controller
Manages Helm chart releases declaratively.
Custom Resources:
- HelmRelease — defines a Helm chart release
Key Options:
--concurrent(default 4)--graceful-shutdown-timeout(default 600s)- Feature gates:
AllowDNSLookups(disabled by default for security),OOMWatch,AdoptLegacyReleases,CancelHealthCheckOnNewRevision
Notification Controller
Handles events and alerts. Sends notifications and receives webhooks.
Custom Resources:
- Provider — notification targets (Slack, Teams, Discord, PagerDuty, GitHub, GitLab, etc.)
- Alert — event forwarding rules
- Receiver — webhook endpoints (port 9292)
Key Options:
--rate-limit-interval(default 5m)--receiverAddr(default :9292)
Image Automation Controllers
Enable automated container image updates to Git.
Custom Resources:
- ImageRepository — scans container registries for new image tags
- ImagePolicy — defines policies for selecting latest image (semver, alphabetical, numerical)
- ImageUpdateAutomation — updates YAML manifests in Git
Part II: Installation and Bootstrap
Chapter 4: Installation
Prerequisites
Cluster admin rights required. Supported Kubernetes versions:
| Kubernetes version | Minimum required |
|---|---|
v1.33 | >= 1.33.0 |
v1.34 | >= 1.34.1 |
v1.35 and later | >= 1.35.0 |
Install the Flux CLI
Homebrew: brew install fluxcd/tap/flux
Bash script: curl -s https://fluxcd.io/install.sh | sudo bash
Arch Linux: yay -S flux-bin
NixOS: nix-env -i fluxcd
Windows: choco install flux
Shell completions: . <(flux completion bash)
Container images: docker.io/fluxcd/flux-cli:<version> and ghcr.io/fluxcd/flux-cli:<version>
Bootstrap Overview
The flux bootstrap command deploys the Flux controllers and configures them to sync cluster state from a Git repository. It pushes Flux manifests to the Git repository and configures Flux to update itself from Git. Bootstrap is idempotent.
After bootstrap, all operations (including Flux upgrades) can be done via Git push.
Dev Install (Testing Only)
flux install