You are viewing documentation for Flux version: 2.1

Version 2.1 of the documentation is no longer actively maintained. The site that you are currently viewing is an archived snapshot. For up-to-date documentation, see the latest version.

Get Started with Flux

Get Started with Flux.

This tutorial shows you how to bootstrap Flux to a Kubernetes cluster and deploy a sample application in a GitOps manner.

Before you begin

To follow the guide, you need the following:


  • Bootstrap Flux on a Kubernetes Cluster.
  • Deploy a sample application using Flux.
  • Customize application configuration through Kustomize patches.

Install the Flux CLI

The flux command-line interface (CLI) is used to bootstrap and interact with Flux.

To install the CLI with Homebrew run:

brew install fluxcd/tap/flux

For other installation methods, see the CLI install documentation.

Export your credentials

Export your GitHub personal access token and username:

export GITHUB_TOKEN=<your-token>
export GITHUB_USER=<your-username>

Check your Kubernetes cluster

Check you have everything needed to run Flux by running the following command:

flux check --pre

The output is similar to:

► checking prerequisites
✔ kubernetes 1.28.0 >=1.25.0
✔ prerequisites checks passed

Install Flux onto your cluster

For information on how to bootstrap using a GitHub org, Gitlab and other git providers, see Bootstrapping.

Run the bootstrap command:

flux bootstrap github \
  --owner=$GITHUB_USER \
  --repository=fleet-infra \
  --branch=main \
  --path=./clusters/my-cluster \

The output is similar to:

► connecting to
✔ repository created
✔ repository cloned
✚ generating manifests
✔ components manifests pushed
► installing components in flux-system namespace
deployment "source-controller" successfully rolled out
deployment "kustomize-controller" successfully rolled out
deployment "helm-controller" successfully rolled out
deployment "notification-controller" successfully rolled out
✔ install completed
► configuring deploy key
✔ deploy key configured
► generating sync manifests
✔ sync manifests pushed
► applying sync manifests
◎ waiting for cluster sync
✔ bootstrap finished

The bootstrap command above does the following:

  • Creates a git repository fleet-infra on your GitHub account.
  • Adds Flux component manifests to the repository.
  • Deploys Flux Components to your Kubernetes Cluster.
  • Configures Flux components to track the path /clusters/my-cluster/ in the repository.

Clone the git repository

Clone the fleet-infra repository to your local machine:

git clone$GITHUB_USER/fleet-infra
cd fleet-infra

Add podinfo repository to Flux

This example uses a public repository, podinfo is a tiny web application made with Go.

  1. Create a GitRepository manifest pointing to podinfo repository’s master branch:

    flux create source git podinfo \
      --url= \
      --branch=master \
      --interval=1m \
      --export > ./clusters/my-cluster/podinfo-source.yaml

    The output is similar to:

    kind: GitRepository
      name: podinfo
      namespace: flux-system
      interval: 1m
        branch: master
  2. Commit and push the podinfo-source.yaml file to the fleet-infra repository:

    git add -A && git commit -m "Add podinfo GitRepository"
    git push

Deploy podinfo application

Configure Flux to build and apply the kustomize directory located in the podinfo repository.

  1. Use the flux create command to create a Kustomization that applies the podinfo deployment.

    flux create kustomization podinfo \
      --target-namespace=default \
      --source=podinfo \
      --path="./kustomize" \
      --prune=true \
      --wait=true \
      --interval=30m \
      --retry-interval=2m \
      --health-check-timeout=3m \
      --export > ./clusters/my-cluster/podinfo-kustomization.yaml

    The output is similar to:

    kind: Kustomization
      name: podinfo
      namespace: flux-system
      interval: 30m0s
      path: ./kustomize
      prune: true
      retryInterval: 2m0s
        kind: GitRepository
        name: podinfo
      targetNamespace: default
      timeout: 3m0s
      wait: true
  2. Commit and push the Kustomization manifest to the repository:

    git add -A && git commit -m "Add podinfo Kustomization"
    git push

    The structure of the fleet-infra repo should be similar to:

    └── clusters/
        └── my-cluster/
            ├── flux-system/                        
            │   ├── gotk-components.yaml
            │   ├── gotk-sync.yaml
            │   └── kustomization.yaml
            ├── podinfo-kustomization.yaml
            └── podinfo-source.yaml

Watch Flux sync the application

  1. Use the flux get command to watch the podinfo app.

    flux get kustomizations --watch

    The output is similar to:

    flux-system   main@sha1:4e9c917f   False      True    Applied revision: main@sha1:4e9c917f
    podinfo       master@sha1:44157ecd False      True    Applied revision: master@sha1:44157ecd
  2. Check podinfo has been deployed on your cluster:

    kubectl -n default get deployments,services

    The output is similar to:

    NAME                      READY   UP-TO-DATE   AVAILABLE   AGE
    deployment.apps/podinfo   2/2     2            2           108s
    NAME                 TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)             AGE
    service/podinfo      ClusterIP   <none>        9898/TCP,9999/TCP   108s

Changes made to the podinfo Kubernetes manifests in the master branch are reflected in your cluster.

When a Kubernetes manifest is removed from the podinfo repository, Flux removes it from your cluster. When you delete a Kustomization from the fleet-infra repository, Flux removes all Kubernetes objects previously applied from that Kustomization.

When you alter the podinfo deployment using kubectl edit, the changes are reverted to match the state described in Git.

Suspend updates

Suspending updates to a kustomization allows you to directly edit objects applied from a kustomization, without your changes being reverted by the state in Git.

To suspend updates for a kustomization, run the command flux suspend kustomization <name>.

To resume updates run the command flux resume kustomization <name>.

Customize podinfo deployment

To customize a deployment from a repository you don’t control, you can use Flux in-line patches. The following example shows how to use in-line patches to change the podinfo deployment.

  1. Add the following to the field spec of your podinfo-kustomization.yaml file:

        - patch: |-
            apiVersion: autoscaling/v2
            kind: HorizontalPodAutoscaler
              name: podinfo
              minReplicas: 3             
            name: podinfo
            kind: HorizontalPodAutoscaler
  2. Commit and push the podinfo-kustomization.yaml changes:

    git add -A && git commit -m "Increase podinfo minimum replicas"
    git push

After the synchronization finishes, running kubectl get pods should display 3 pods.

Multi-cluster Setup

To use Flux to manage more than one cluster or promote deployments from staging to production, take a look at the two approaches in the repositories listed below.