Elevating IaC Workflows with Spacelift Stacks and Dependencies 🛠️

Register for the July 23 demo →


What Is Flux CD & How Does It Work? [Tutorial]

What is Flux CD & How Does It Work?

Flux CD implements continuous delivery to Kubernetes clusters using a GitOps process. It provides a set of Kubernetes controllers that synchronize your cluster’s state to match the configuration defined in your Git repositories and other sources.

In this article, we’ll explore Flux CD’s key features and explain how they work. We’ll also provide a simple tutorial that guides you through deploying your first app — let’s get started!

What we will cover:

  1. What is FluxCD? What is FluxCD used for?
  2. Flux CD features and benefits
  3. How does Flux CD work?
  4. Flux CD vs Argo CD
  5. How to use FluxCD?
  6. IaC management for Kubernetes

What is Flux CD?

Flux CD is a continuous delivery (CD) tool that automates GitOps-powered app deployments to Kubernetes clusters. It allows you to automate Kubernetes app deployments each time you change your code.

Flux CD runs controllers in your Kubernetes cluster that periodically check for updates to the repository sources you’ve connected. When changes are committed, Flux CD adds, replaces, and removes Kubernetes objects to update the deployment in your cluster. This ensures apps deploy continually with minimal risk.

GitOps refers to the use of Git repositories as the single source of truth for your operations. You define your infrastructure configuration as declarative files in your repositories. Those files are then consumed by tools like Flux CD that automatically apply the required changes to make your infrastructure’s state match the config you’ve declared.

What is Flux CD used for?

Flux CD is used to automate the deployment and lifecycle management of applications and infrastructure on Kubernetes clusters. It got popular because it makes it easier to deploy complex apps without having to manually configure each new release. You can simply commit your changes and then wait for Flux CD to sync them into your Kubernetes clusters. This lets you stay focused on building new features and enables more consistency for your deployment process.

FluxCD integrates easily with:

  • Kubernetes
  • Helm
  • Grafana
  • Istio
  • Prometheus
  • Linkerd
  • Kyverno
  • SOPS

Flux CD features and benefits

Although Flux CD is easy to get started with, it also offers numerous advanced features to support powerful deployment workflows:

  • Kubernetes RBAC support lets you configure robust access controls for your apps.
  • Integrations with policy-driven validation systems such as OPA and admission controllers help ensure your apps stay compliant.
  • You can optionally automate image patches and updates based on scans of your deployed containers, with pushes back to your Git repository.
  • A multi-tenant enabled architecture makes Flux CD suitable for clusters that serve multiple teams and apps.
  • Compatibility with the Kubernetes Cluster API permits management of other clusters and provisioning operations.
  • Can be used to implement canary, blue/green, and A/B deployments when combined with the optional Flagger component.
  • A rich ecosystem of extensions, interfaces, and compatible development platforms lets you customize your Flux CD experience to match the way you work.

Overall, Flux CD allows you to achieve robust automated app deployments in Kubernetes. It ensures consistent configuration, security, and resilience by removing the need to manually initiate deployments or train developers on how to use Kubernetes directly.

How does FluxCD work?

At a high level, Flux CD monitors your repositories for changes and reconciles them against the current state of your Kubernetes cluster. This produces a continuous delivery workflow, where changes are automatically deployed to users after they’re applied to your repos.

Flux CD refers to repositories as Sources. Sources are often Git repos, but you can also sync content directly from Helm repositories, OCI image registries, and Amazon S3 buckets.

Once a Source has been connected, Flux CD synchronizes its contents using a Reconciliation process. Reconciliation ensures that the resources in your Kubernetes cluster accurately reflect the current configuration defined by the Source. The operations involved in Reconciliation depend on the type of Source being used—for a Git repository, Flux CD will apply the Kubernetes manifests within the repository, for example, whereas a Helm repository will create a new Helm release.

In addition to your app’s resources, Flux CD creates Custom Resources in your cluster that describe the Flux configuration being used. For example, a GitRepository object will be created for apps that are being deployed from Git. You can save the manifests for these objects and commit them to another repository to programmatically manage Flux itself using an IaC solution like Terraform.

Flux CD also uses Kustomize to let you deploy multiple instances of your apps with different overrides, such as for staging and production environments. Kustomizations are created as YAML files within your repositories and are managed by Flux’s Kustomize controller. This lets you customize each deployment individually without having to touch the source files.

The GitOps Toolkit Flux components

All these Flux components work together to form Flux’s core GitOps Toolkit. The toolkit comprises the APIs, controllers, and tools you need to successfully implement a GitOps-powered continuous delivery workflow for your Kubernetes clusters. 

Below, you can find the architectural diagram of the GitOps Toolkit components:

fluxcd components

Image source

The Flux Toolkit consists of five main components:

  • Source Controller — This Flux component is responsible for monitoring your Sources for changes, such as commits to a Git repository or an updated Helm chart.
  • Kustomize Controller — Manages the manifest overrides that let you customize apps before you deploy without modifying the source files. This controller then reconciles your cluster’s state against your configured sources.
  • Helm Controller — This specialized controller enables declarative management of Helm chart releases via the HelmRelease CRD.
  • Notification Controller — The notification controller mediates between Flux and external systems. It emits events for new Flux activity and handles any incoming events, such as a Slack request to reconcile a repository’s changes.
  • Image Automation Controllers — These advanced controllers allow you to automatically update your Git repositories based on the results of image scans; you can also automate Kubernetes resource updates after an image tag is changed.

The controllers are configured using the Flux CLI and CRDs in your cluster. Together, these allow you to register new GitOps CI pipelines, run reconciliation, and declaratively enable alerts and automated image updates.

Flux CD vs Argo CD

Argo CD is another popular Kubernetes continuous delivery tool with similar features to Flux CD. Although both Flux CD and Argo CD enable GitOps deployments to your clusters, they offer slightly different experiences that are suited to individual use cases.

Argo CD has a broader scope; as a result, it can be easier to get started with. It includes a versatile web interface that lets you visualize your app components, whereas no UI is bundled with Flux CD. Conversely, Flux CD’s toolkit ethos can be the better choice for more advanced use or where you need easy integrations with other tools. Unlike Argo, it uses the Kubernetes API directly, which helps facilitate connections with ecosystem components—for example, GitLab is working to natively support FluxCD deployment within its DevOps platform.

Tutorial: How to use Flux CD

We’ll walk through a simple demo of how to set up a Flux CD pipeline for a Git repository. Flux is installed in your cluster by bootstrapping it using a separate Git repository that allows you to manage your Flux configuration as code. You can then register your app’s repository as a Flux reconciliation source.

In a real scenario, you would also need to build a container image and push it to your image registry, ready for Flux to pull into your cluster. We’re skipping this step and using a prebuilt public image instead, so this tutorial is easy to follow.

You should have Kubectl, Helm, a GitHub account, and a Kubernetes cluster ready before you continue.

1. Install the Flux CLI

Before we install Flux CD, first, run the following command to add the flux CLI to your system:

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

This command works on Linux and macOS. You can find instructions for other supported installation methods in the Flux documentation.

Check the Fluxc CLI is working by running the flux --version command:

$ flux --version
flux version 2.2.3

2. Check if your Kubernetes cluster is ready to use Flux

Before going any further, you should check that your cluster meets all the required prerequisites to use Flux. The flux check --pre command runs a pre-installation check that lets you confirm compatibility without adding anything to your cluster:

$ flux check --pre
► checking prerequisites
✔ Kubernetes 1.28.3 >=1.26.0-0
✔ prerequisites checks passed

You’ll need to fix any warnings that display before you can use Flex. However, most Kubernetes clusters should immediately satisfy the requirements, as long as your Kubernetes version is updated.

3. Create your app’s Git repository

Next, create your app’s Git repository. Clone the repository to your machine, then copy the following Kubernetes manifests, save them to your repo, and commit and push them:


apiVersion: apps/v1
kind: Deployment
  name: demo-app
  replicas: 3
      app: demo-app
        app: demo-app
        - name: nginx
          image: nginx:latest
            - containerPort: 80


apiVersion: v1
kind: Service
  name: demo-app
    app: demo-app
    - name: nginx
      port: 80

Commit and Push

$ git add .
$ git commit -m "Added initial Kubernetes manifests"
$ git push

4. Prepare your GitHub credentials

Flux needs authenticated access to your GitHub account to create the new repository that will store your Flux GitOps Toolkit manifests. Setting the GITHUB_USER and GITHUB_TOKEN environment variables in your shell is the easiest way to provide credentials for this tutorial.

$ export GITHUB_USER=<username>
$ export GITHUB_TOKEN=<token>

You can generate a token in your GitHub account settings. Assign the token the API and repository read/write scopes.

5. Install and bootstrap Flux CD

Now. you can install and bootstrap Flux CD in your Kubernetes cluster. 

The following bootstrap command will install Flux and commit its manifests to a new GitHub project called flux-cd:

$ flux bootstrap github \
  --personal \
  --owner=$GITHUB_USER \

The bootstrap process could take a few moments to complete. Wait until you see the all components are healthy message appear:

► connecting to github.com
✔ repository "https://github.com/ilmiont/flux-cd" created
► cloning branch "main" from Git repository "https://github.com/ilmiont/flux-cd.git"
✔ cloned repository
► generating component manifests
✔ generated component manifests
✔ committed component manifests to "main" ("b5e6afe53fdeffd80a9086ef82d15a3a3c73c2ec")
► pushing component manifests to "https://github.com/ilmiont/flux-cd.git"
► installing components in "flux-system" namespace
✔ installed components
✔ reconciled components
► determining if source secret "flux-system/flux-system" exists
► generating source secret
✔ public key: ecdsa-sha2-nistp384 AAAAE2VjZHNhLXNoYTItbmlzdHAzODQAAAAIbmlzdHAzODQAAABhBJExUXKGqaRpQsPUeiIYOeN7UFWBV83VTZ0mhgIpxl33q0yd+Qj5aat6V8Vjjy3Pf7Mpb0qtdTWF9ICedCGFghr6lClUjbntkJxepitiaaKc4eJzCJw5lVKOexJYTzC/Dg==
✔ configured deploy key "flux-system-main-flux-system" for "https://github.com/ilmiont/flux-cd"
► applying source secret "flux-system/flux-system"
✔ reconciled source secret
► generating sync manifests
✔ generated sync manifests
✔ committed sync manifests to "main" ("0ece87bab80b0b1919d4886afb3ee12bf6272eef")
► pushing sync manifests to "https://github.com/ilmiont/flux-cd.git"
► applying sync manifests
✔ reconciled sync configuration
◎ waiting for GitRepository "flux-system/flux-system" to be reconciled
✔ GitRepository reconciled successfully
◎ waiting for Kustomization "flux-system/flux-system" to be reconciled
✔ Kustomization reconciled successfully
► confirming components are healthy
✔ helm-controller: deployment ready
✔ kustomize-controller: deployment ready
✔ notification-controller: deployment ready
✔ source-controller: deployment ready
✔ all components are healthy

The bootstrap command above creates a new Git repository on your GitHub account and adds Flux component manifests to that repository.

If you now inspect your GitHub account, you’ll see a new flux-cd repository has been created. Within the repository, Flux CD has committed Kubernetes manifests that allow you to reproduce your current configuration in the future:

fluxcd github

Flux CD is now installed in your cluster, ready to begin deploying your apps.

6. Register your app repository as a Flux source

Use the flux create source command to register a new Git source with your Flux installation. This will instruct Flux CD to start monitoring your app’s Git repository.

$ flux create source git demo-app \
  --url=https://github.com/$GITHUB_USER/<repo>.git \
  --branch=master \
✚ generating GitRepository source
► applying GitRepository source
✔ GitRepository source created
◎ waiting for GitRepository source reconciliation
✔ GitRepository source reconciliation completed
✔ fetched revision: master@sha1:3659ff528093f383ecfe625d24382dfdc7afecf1

You can see that Flux reconciles the content of your repository and retrieves the latest commit. The --interval=1m flag means Flux will check for new repository changes every minute.

7. Deploy your application

Although your repository is now connected to Flux, it hasn’t yet been deployed. To do this, you must create a Kustomization object that lets you configure the deployment. Here’s a simple example:

$ flux create kustomization demo-app \
  --target-namespace=default \
  --source=demo-app \
  --prune=true \
  --wait=true \

This Kustomization specifies that the demo-app source created above should be deployed to the default namespace.

The --prune flag means that redundant cluster resources will be automatically removed when they’re no longer defined in the repository, while --wait instructs the command to block your terminal until it’s completed.

The --interval option is used to set up automatic drift resolution: every five minutes, Flux will check whether the deployed resources have drifted from the correct state and revert any unwanted changes.

When you run the command, you should see that Flux successfully deploys the current revision of your app, based on your latest Git commit:

✚ generating Kustomization
► applying Kustomization
✔ Kustomization created
◎ waiting for Kustomization reconciliation
✔ Kustomization demo-app is ready
✔ applied revision master@sha1:3659ff528093f383ecfe625d24382dfdc7afecf1

If you list the Deployments in your cluster’s default namespace, your demo-app Deployment should now show up:

$ kubectl get deployments
demo-app   3/3     3            3           57s

It’s running the three replicas configured in your manifests/deployment.yml file.

8. Update your application

Next, let’s see what happens when you update your application. Modify your manifests/deployment.yml file by changing the spec.replicas field to 5 instead of 3:

  replicas: 5

Commit and push your changes:

$ git add .
$ git commit -m "Change replica count to 5"
$ git push

Next, wait a minute—this is the reconciliation interval configured above, when you registered your repository as a Flux source. Once the delay has elapsed, repeat the kubectl get deployments command—you should see five replicas are now running:

$ kubectl get deployments
demo-app   5/5     5            5           3m32s

You’ve successfully used Flux CD to automate continuous delivery to your Kubernetes cluster! Flux has automatically adjusted your Deployment’s replica count to match the state defined by your repository, without requiring any manual interaction with Kubernetes resources or Kubectl.

IaC management for Kubernetes

Flux CD is a great option for teams looking to automate the deployment of their Kubernetes workloads. It’s not the only option, though: Argo CD is a popular FluxCD alternative that can be simpler to get started with, while IaC management tools like Spacelift make it easier to automate changes to your cluster environments and cloud resources. 

Spacelift simplifies IaC management for Kubernetes and helps you stay on top of your infrastructure. This gives you the most powerful Kubernetes experience when operating your clusters at scale.

Spacelift brings with it a GitOps flow, so your Kubernetes Deployments are synced with your Kubernetes Stacks, and pull requests show you a preview of what they’re planning to change. It also has an extensive selection of policies, which lets you automate compliance checks and build complex multi-stack workflows.

Other than Kubernetes, Spacelift also supports Terraform, OpenTofu, Terragrunt, Pulumi, AWS CloudFormation, Ansible, and more, and enables users to create stacks based on them. Leveraging Spacelift, you can build CI/CD pipelines to combine them and get the best of each tool.

fluxcd tutorial

If you want to learn more about Spacelift, create a free account today or book a demo with one of our engineers.

Key points

We’ve seen that FluxCD, the Cloud Native Computing Foundation Graduated project, is a leading Kubernetes continuous delivery solution. It keeps your Kubernetes clusters in sync with your Git repositories, facilitating automatic deployments each time you push new commits. Compared with manually executing release pipelines, this workflow is simpler, safer, and more maintainable at scale.

Manage Kubernetes Faster and More Easily

Spacelift allows you to automate, audit, secure, and continuously deliver your infrastructure. It helps overcome common state management issues and adds several must-have features for infrastructure management.

Start free trial

The Practitioner’s Guide to Scaling Infrastructure as Code

Transform your IaC management to scale

securely, efficiently, and productively

into the future.

ebook global banner
Share your data and download the guide