Skip to content
FluxCD Official Documentation
On Trove · from yotam fromm

FluxCD Official Documentation

The Complete Guide to GitOps on Kubernetes

A comprehensive reference for FluxCD, the CNCF Graduated project for GitOps-based continuous delivery on Kubernetes.

Read a preview

You can read the contents and the first 2,000 characters.
Free accounts get the whole book.

  • By yotam fromm
  • 120 chapters
  • Updated Nov 8, 2026
  • 27 readers

What’s inside

  • FluxCD Documentation
  • Flux Documentation
  • Core Concepts
  • Get Started with Flux
  • Installation > Flux installation
  • Installation > Bootstrap > Flux bootstrap for Git servers

What is FluxCD Official Documentation?

A comprehensive reference for FluxCD, the CNCF Graduated project for GitOps-based continuous delivery on Kubernetes.

markdown · Listed Mar 16, 2026

  • devops
  • ci/cd
  • kubernetes

From the first page

Source: https://github.com/fluxcd/website/tree/main/content/en/flux (English docs, commit 186a68ff; rebuilt 2026-11-08)

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 support for syncing an arbitrary number of Git repositories.

If you want to find out more about Flux UIs, check out our dedicated section.

Preview · 2,000 of 936,555 characters

Envoy Proxy Documentation
Kubernetes: Official Documentation
Dynamic Workflows in Claude Code: A Complete Guide to Multi-Agent Harnesses
SEO for AI Agents

Contents

  1. 01FluxCD Documentationp.1
  2. 02Flux Documentationp.2
    1. Flux UIsp.2
    2. Flux in Shortp.2
    3. Who is Flux for?p.2
    4. What can I do with Flux?p.2
    5. Where do I start?p.2
    6. More detail on what's in Fluxp.2
    7. What is the GitOps Toolkit?p.2
    8. Communityp.2
  3. 03Core Conceptsp.3
    1. GitOpsp.3
    2. Gitless GitOpsp.3
    3. GitOps Toolkit (gotk)p.3
    4. Sourcesp.3
    5. Reconciliationp.3
    6. Kustomizationp.3
    7. Bootstrapp.3
    8. Continuous Deliveryp.3
    9. +2 more sections
  4. 04Get Started with Fluxp.4
    1. Before you beginp.4
    2. Objectivesp.4
    3. Install the Flux CLIp.4
    4. Export your credentialsp.4
    5. Check your Kubernetes clusterp.4
    6. Install Flux onto your clusterp.4
    7. Clone the git repositoryp.4
    8. Add podinfo repository to Fluxp.4
    9. +5 more sections
  5. 05Installation > Flux installationp.5
    1. Prerequisitesp.5
    2. Install the Flux CLIp.5
    3. Install the Flux controllersp.5
  6. 06Installation > Bootstrap > Flux bootstrap for Git serversp.6
    1. SSH Private Keyp.6
    2. SSH Agentp.6
    3. HTTPS basic authp.6
    4. HTTPS authorization headerp.6
    5. Bootstrap multiple clustersp.6
  7. 07Installation > Bootstrap > Flux bootstrap for Giteap.7
    1. Gitea PATp.7
    2. Gitea Personal Accountp.7
    3. Gitea Organizationp.7
    4. Gitea Deploy Keysp.7
    5. Bootstrap without a Gitea PATp.7
  8. 08Installation > Bootstrap > Flux bootstrap for GitHubp.8
    1. GitHub PATp.8
    2. GitHub Personal Accountp.8
    3. GitHub Organizationp.8
    4. GitHub Enterprisep.8
    5. GitHub Deploy Keysp.8
    6. GitHub Appp.8
    7. Bootstrap without a GitHub PATp.8
See all 120 parts
  1. 09Installation > Bootstrap > Flux bootstrap for GitLabp.9
    1. GitLab PATp.9
    2. GitLab Personal Accountp.9
    3. GitLab Groupsp.9
    4. GitLab Enterprisep.9
    5. GitLab Deploy Keysp.9
    6. Bootstrap without a GitLab PATp.9
  2. 10Installation > Bootstrap > Flux bootstrap for Bitbucketp.10
    1. Bitbucket HTTP Access Tokenp.10
    2. Bitbucket Personal Accountp.10
    3. Bitbucket Personal Projectp.10
    4. Bitbucket SSH Access Keysp.10
    5. Bootstrap without a Bitbucket tokenp.10
  3. 11Installation > Bootstrap > Flux bootstrap for AWS CodeCommitp.11
    1. Bootstrap over HTTPS with IAM rolep.11
    2. Bootstrap over SSHp.11
  4. 12Installation > Bootstrap > Flux bootstrap for Azure DevOpsp.12
    1. Azure DevOps PATp.12
    2. Bootstrap using a DevOps PATp.12
    3. Bootstrap using SSH keysp.12
  5. 13Installation > Bootstrap > Flux bootstrap for Google Cloud Sourcep.13
    1. Bootstrap over SSHp.13
  6. 14Installation > Bootstrap > Flux bootstrap for Oracle VBS Git Repositoriesp.14
    1. Oracle VBS PATp.14
    2. Bootstrap using an Oracle VBS PATp.14
  7. 15Installation > Configuration > Flux optional componentsp.15
    1. Default componentsp.15
    2. Extra componentsp.15
    3. Network policiesp.15
    4. Cluster domainp.15
  8. 16Installation > Configuration > Flux bootstrap customizationp.16
  9. 17Installation > Configuration > Flux vertical scalingp.17
    1. Increase the number of workers and limitsp.17
    2. Enable in-memory kustomize buildsp.17
    3. Enable Helm repositories cachingp.17
    4. Persistent storage for Flux internal artifactsp.17
    5. Node affinity and tolerationsp.17
  10. 18Installation > Configuration > Flux sharding and horizontal scalingp.18
    1. Bootstrap with shardingp.18
    2. Assign resources to shardsp.18
  11. 19Installation > Configuration > Flux multi-tenancyp.19
    1. Flux authorization modelp.19
    2. Flux user rolesp.19
    3. How to configure Flux multi-tenancyp.19
  12. 20Installation > Configuration > Flux Workload Identityp.20
    1. Configuring Flux resourcesp.20
    2. EKS IAM Roles for Service Accountsp.20
    3. AKS Workload Identityp.20
    4. GKE Workload Identityp.20
  13. 21Installation > Configuration > Flux Object Identity Installationp.21
    1. Kubernetes credential providerp.21
    2. SPIFFE credential providerp.21
    3. Multi-tenancy lockdownp.21
  14. 22Installation > Configuration > Flux Inter-controller mTLSp.22
    1. Prerequisitesp.22
    2. Traffic types and flagsp.22
    3. Example configurationp.22
    4. Verifyingp.22
  15. 23Installation > Configuration > SPIFFE Workload APIp.23
    1. Prerequisitesp.23
    2. Configurationp.23
  16. 24Installation > Configuration > Flux air-gapped installationp.24
    1. Copy the container imagesp.24
    2. Bootstrap Fluxp.24
    3. Bootstrap Flux and authenticate to a private container registryp.24
  17. 25Installation > Configuration > Flux OpenShift installationp.25
    1. OperatorHubp.25
  18. 26Installation > Configuration > Flux proxy settingsp.26
    1. Using HTTP/S proxy for egress trafficp.26
    2. Git repository access via SOCKS5 SSH proxyp.26
  19. 27Installation > Configuration > Flux deploy key rotationp.27
  20. 28Installation > Configuration > Flux drift detection for Helm Releasesp.28
  21. 29Installation > Configuration > Flux near OOM detection for Helmp.29
  22. 30Installation > Configuration > Flux DNS lookups for Helm Releasesp.30
  23. 31Installation > Flux upgradep.31
    1. Flux CLI upgradep.31
    2. Flux controllers upgradep.31
  24. 32Installation > Flux uninstallp.32
    1. Uninstall with Flux CLIp.32
  25. 33Guides > Ways of structuring your repositoriesp.33
    1. Monorepop.33
    2. Repo per environmentp.33
    3. Repo per teamp.33
    4. Repo per appp.33
  26. 34Guides > Manage Helm Releasesp.34
    1. Prerequisitesp.34
    2. Define a chart sourcep.34
    3. Define a Helm releasep.34
    4. Reacting immediately to changes in referenced Secrets and ConfigMapsp.34
    5. Refer to values in Secret generated with Kustomize and SOPSp.34
    6. Refer to values inside the chartp.34
    7. Configure notificationsp.34
    8. Configure webhook receiversp.34
  27. 35Guides > Manage Helm Releases (part 2)p.35
    1. Release when a source revision changes for Git and Cloud Storagep.35
  28. 36Guides > Setup Webhook Receiversp.36
    1. Prerequisitesp.36
    2. Expose the webhook receiverp.36
    3. Using a LoadBalancerp.36
    4. Using an Ingressp.36
    5. Using a HTTPRoute (Gateway API)p.36
    6. Define a Git repositoryp.36
    7. Define a Git repository receiverp.36
  29. 37Guides > Manage Kubernetes secrets with SOPSp.37
    1. Prerequisitesp.37
    2. Generate a GPG keyp.37
    3. Configure in-cluster secrets decryptionp.37
    4. Optional: Export the public key into the Git directoryp.37
    5. Configure the Git directory for encryptionp.37
    6. Encrypting secrets using OpenPGPp.37
    7. Encrypting secrets using agep.37
    8. Encrypting secrets using HashiCorp Vaultp.37
    9. +3 more sections
  30. 38Guides > Sealed Secretsp.38
    1. Prerequisitesp.38
    2. Deploy sealed-secrets with a HelmReleasep.38
    3. Encrypt secretsp.38
    4. GitOps workflowp.38
  31. 39Guides > Automate image updates to Gitp.39
    1. Prerequisitesp.39
    2. Install Fluxp.39
    3. Deploy a demo appp.39
    4. Configure image scanningp.39
    5. Configure image updatesp.39
    6. Configure image update for custom resourcesp.39
    7. Push updates to a different branchp.39
    8. Configure the commit messagep.39
    9. +2 more sections
  32. 40Guides > Automate image updates to Git (part 2)p.40
    1. ImageRepository cloud providers authenticationp.40
    2. ImagePolicy Examplesp.40
    3. Digest pinningp.40
  33. 41Guides > How to make sortable image tags to use with automationp.41
    1. Formats and alternativesp.41
    2. Example of a build process with timestamp taggingp.41
    3. Using in an `ImagePolicy` objectp.41
  34. 42Integrations > Integrationsp.42
  35. 43Integrations > Flux Object Identity APIp.43
    1. Prerequisitesp.43
    2. Configuring Flux resourcesp.43
    3. Authentication annotationsp.43
    4. Mutual TLS annotationsp.43
    5. Migration notesp.43
    6. Examplesp.43
  36. 44Integrations > Flux and Amazon Web Servicesp.44
    1. Identityp.44
    2. Access Managementp.44
    3. Authorizationp.44
  37. 45Integrations > Flux and Amazon Web Services (part 2)p.45
    1. Authenticationp.45
  38. 46Integrations > Flux and Amazon Web Services (part 3)p.46
    1. At the node levelp.46
  39. 47Integrations > Flux and Microsoft Azurep.47
    1. Identityp.47
    2. Access Managementp.47
    3. Authorizationp.47
  40. 48Integrations > Flux and Microsoft Azure (part 2)p.48
    1. Authenticationp.48
  41. 49Integrations > Flux and Microsoft Azure (part 3)p.49
    1. Supported Azure Cloudsp.49
  42. 50Integrations > Flux and Google Cloud Platformp.50
    1. Identityp.50
    2. Access Managementp.50
    3. Authorizationp.50
  43. 51Integrations > Flux and Google Cloud Platform (part 2)p.51
    1. Authenticationp.51
  44. 52Integrations > Flux and Google Cloud Platform (part 3)p.52
    1. At the node levelp.52
  45. 53Integrations > Flux Cross-cloud Supportp.53
    1. Source cluster setupp.53
  46. 54Integrations > Flux SPIFFE mTLSp.54
  47. 55Monitoring > Flux alertsp.55
    1. Prerequisitesp.55
    2. Define a providerp.55
    3. Define an alertp.55
    4. Git commit statusp.55
    5. Grafana annotationsp.55
  48. 56Monitoring > Flux Prometheus metricsp.56
    1. Controller metricsp.56
    2. Resource metricsp.56
    3. Monitoring setupp.56
  49. 57Monitoring > Flux custom Prometheus metricsp.57
    1. Set up kube-state-metricsp.57
    2. Adding custom metricsp.57
    3. Adding custom metric labelsp.57
  50. 58Monitoring > Flux logsp.58
    1. Controller logsp.58
    2. Querying logs associated with resourcesp.58
    3. Log aggregation with Grafana Lokip.58
  51. 59Monitoring > Flux eventsp.59
    1. Kubernetes eventsp.59
    2. Events inspection with kubectlp.59
    3. Events inspection with flux CLIp.59
  52. 60Use Cases > Running pre and post-deployment jobs with Fluxp.60
    1. Repository structurep.60
    2. Configure the deployment pipelinep.60
  53. 61Use Cases > Karmada + Fluxp.61
    1. Backgroundp.61
    2. Karmada Setupp.61
    3. Helm release propagationp.61
    4. Customize the Helm release for specific clustersp.61
  54. 62Use Cases > Flux for Helm Usersp.62
    1. What Does Flux add to Helm?p.62
    2. Getting Startedp.62
    3. Customizing Your Releasep.62
    4. Managing Secrets and ConfigMapsp.62
    5. Automatic Release Upgradesp.62
    6. Automatic Uninstalls and Rollbackp.62
    7. Helm Chart Composition from Multiple Sourcesp.62
    8. Next Stepsp.62
  55. 63Use Cases > Promote Flux Helm Releases with GitHub Actionsp.63
    1. Prerequisitesp.63
    2. Define staging and production releasesp.63
    3. Define the promotion GitHub workflowp.63
    4. Configure Flux for repository dispatchingp.63
    5. Relevant documentationp.63
  56. 64Use Cases > GitHub Actions Basic App Builderp.64
    1. Example GitHub Actions Workflowp.64
  57. 65Use Cases > GitHub Actions Manifest Generationp.65
    1. Use Manifest Generationp.65
    2. Manifest Generation Examplesp.65
  58. 66Use Cases > GitHub Actions Manifest Generation (part 2)p.66
    1. Jsonnet Render Actionp.66
  59. 67Use Cases > GitHub Actions Manifest Generation (part 3)p.67
    1. Breaking It Downp.67
    2. Handling `Secret`sp.67
  60. 68Use Cases > GitHub Actions Manifest Generation (part 4)p.68
    1. Commit Across Repositories Workflowp.68
    2. Adapting for Flux v2p.68
  61. 69Use Cases > GitHub Actions Auto Pull Requestp.69
  62. 70Use Cases > Jenkins + Fluxp.70
    1. Declarative Artifactsp.70
    2. Example Jenkinsfilep.70
  63. 71Use Cases > Jenkins + Flux (part 2)p.71
    1. Wrap Upp.71
  64. 72Components > GitOps Toolkit componentsp.72
  65. 73Components > Source > Source Controllersp.73
    1. Source controllerp.73
    2. Source watcherp.73
  66. 74Components > Source > Controller Optionsp.74
  67. 75Components > Kustomize > Kustomize Controllerp.75
  68. 76Components > Kustomize > Controller Optionsp.76
  69. 77Components > Helm > Helm Controllerp.77
  70. 78Components > Helm > Controller Optionsp.78
  71. 79Components > Notification > Notification Controllerp.79
  72. 80Components > Notification > Controller Optionsp.80
  73. 81Components > Image > Image reflector and automation controllersp.81
  74. 82Components > Image > Controller Optionsp.82
  75. 83Gitops Toolkit > Using the GitOps Toolkit APIs with Gop.83
    1. Go Packagesp.83
    2. CRUD Examplep.83
    3. Artifact SDKp.83
  76. 84Gitops Toolkit > Watching for source changesp.84
    1. Prerequisitesp.84
    2. Install Fluxp.84
    3. Clone the sample controllerp.84
    4. Run the controllerp.84
    5. How it worksp.84
  77. 85Gitops Toolkit > Building ExternalArtifact Controllersp.85
    1. Overviewp.85
    2. Prerequisitesp.85
    3. Install Fluxp.85
    4. Reference implementationp.85
    5. SDK Quick Startp.85
    6. Consuming ExternalArtifactsp.85
    7. Storage API Referencep.85
    8. Security Best Practicesp.85
    9. +2 more sections
  78. 86Gitops Toolkit > Advanced debuggingp.86
    1. Pprofp.86
    2. Resource usagep.86
  79. 87Cmd > Flux CLIp.87
    1. Install using package managementp.87
    2. Install using Bashp.87
    3. Install using Dockerp.87
    4. Enable shell autocompletionp.87
    5. Install using GitHub Actionsp.87
  80. 88Cheatsheets > CEL cheatsheetp.88
    1. Aboutp.88
    2. Contributingp.88
    3. FAQp.88
    4. Libraryp.88
  81. 89Cheatsheets > OCI cheatsheetp.89
    1. How does Flux OCI work?p.89
    2. Workflow examplesp.89
    3. Authenticationp.89
    4. Signing and verificationp.89
    5. Monitoringp.89
  82. 90Cheatsheets > OCI cheatsheet (part 2)p.90
    1. Tracingp.90
    2. Git commit status updatesp.90
    3. Automated updates to Gitp.90
  83. 91Cheatsheets > CRD resource categoriesp.91
    1. Categoriesp.91
    2. Flux CLI Comparisonp.91
  84. 92Cheatsheets > Troubleshooting cheatsheetp.92
    1. Getting basic informationp.92
    2. Kustomize-related issuesp.92
    3. Helm-related issuesp.92
    4. Raspberry Pi related issuesp.92
  85. 93Security > Security Documentationp.93
    1. Introductionp.93
    2. Signed container imagesp.93
    3. Software Bill of Materialsp.93
    4. SLSA Provenancep.93
    5. Scanning for CVEsp.93
    6. Pod security standardp.93
    7. Controller permissionsp.93
    8. Cross-Namespace reference policyp.93
    9. +1 more section
  86. 94Security > Security Best Practicesp.94
    1. Introductionp.94
    2. Security Best Practicesp.94
    3. Additional Best Practices for Shared Cluster Multi-tenancyp.94
    4. Additional Best Practices for Tenant Dedicated Cluster Multi-tenancyp.94
  87. 95Security > Contextual Authorizationp.95
    1. Introductionp.95
    2. Current Supportp.95
  88. 96Security > Secrets Managementp.96
    1. Introductionp.96
  89. 97Security > SLSA Assessmentp.97
    1. Introductionp.97
    2. SLSA Requirements and Flux Compliance Statep.97
    3. Provenance verificationp.97
  90. 98Releases > Flux releasesp.98
    1. Release versioningp.98
    2. Release cadencep.98
    3. Supported releasesp.98
    4. Supported upgradesp.98
    5. Kubernetes supported versionsp.98
    6. Release artifactsp.98
    7. Release changelogp.98
  91. 99Releases > Flux controller releasesp.99
    1. API versioningp.99
    2. Controller versioningp.99
    3. Release cadencep.99
    4. Supported releasesp.99
    5. Release artifactsp.99
  92. 100Releases > Flux plugin releasesp.100
  93. 101Releases > Flux shared packages releasesp.101
    1. Release versioningp.101
    2. Supported releasesp.101
    3. Deprecation policyp.101
  94. 102Releases > Flux release proceduresp.102
    1. Table of contentsp.102
    2. General rulesp.102
    3. Component typesp.102
  95. 103Releases > Flux release procedures (part 2)p.103
    1. Backport changes for patch releasesp.103
  96. 104Frequently asked questionsp.104
    1. General questionsp.104
    2. Kustomize questionsp.104
    3. Helm questionsp.104
    4. Flux v1 vs v2 questionsp.104
  97. 105Flux AI Agent Skillsp.105
    1. gitops-knowledgep.105
    2. gitops-repo-auditp.105
    3. gitops-cluster-debugp.105
    4. Getting Startedp.105
  98. 106Flux GitHub Actionp.106
    1. Usagep.106
    2. Compatibilityp.106
    3. Examplesp.106
  99. 107Flux from End-to-Endp.107
    1. Terminologyp.107
    2. Microservice architecturep.107
    3. Commit flowp.107
  100. 108Flux from End-to-End (part 2)p.108
    1. Git as a Single Source of Truthp.108
    2. Flux's default configuration for `NetworkPolicy`p.108
    3. Trigger Reconciling on Git push with Webhook Receiversp.108
    4. Sources - (Artifacts and Revisions)p.108
    5. Secret Decryption via SOPSp.108
    6. Kustomize Controller builds and validates resourcesp.108
    7. Kustomize Controller applies changes with Server-Side Applyp.108
    8. Helm Controller reconciles HelmRelease resourcesp.108
    9. +2 more sections
  101. 109Flux from End-to-End (part 3)p.109
    1. Channel-based Providers for Notificationsp.109
    2. Git Commit Status Provider Notificationsp.109
    3. Waiting and Health Checking for Flux Kustomizationp.109
    4. OCIRepository as a Sourcep.109
    5. ArtifactGenerator for Monorepo Decompositionp.109
    6. ArtifactGenerator for Helm Chart Compositionp.109
  102. 110Flux from End-to-End (part 4)p.110
    1. Diagram: Helm chart composition with ArtifactGeneratorp.110
  103. 111Migration > Migrate from Flux v1p.111
    1. Resourcesp.111
  104. 112Migration > Migrate from Flux v1 to v2p.112
    1. Prerequisitesp.112
    2. GitOps migrationp.112
    3. In-place migrationp.112
  105. 113Migration > Migrating image update automation to Flux v2p.113
    1. Overview of changes between v1 and v2p.113
    2. Preparing for migrationp.113
    3. Running the automation controllersp.113
    4. Controlling automation with an `ImageUpdateAutomation` objectp.113
    5. Migrating each manifest to Flux v2p.113
  106. 114Migration > Migrating image update automation to Flux v2 (part 2)p.114
    1. Troubleshootingp.114
  107. 115Migration > Migrate to the Helm Controllerp.115
    1. Overview of changesp.115
    2. API spec changesp.115
  108. 116Migration > Migrate to the Helm Controller (part 2)p.116
    1. Migration strategyp.116
    2. Frequently Asked Questionsp.116
  109. 117Migration > Migrate to the Helm Controller (part 3)p.117
    1. I have another questionp.117
  110. 118Migration > FAQp.118
    1. Flux v1 vs v2 questionsp.118
  111. 119Migration > Timetablep.119
  112. 120Appendix · Reader gapsp.120
    1. Self-update bootstrap recoveryp.120