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:

• A Kubernetes cluster. We recommend Kubernetes kind for trying Flux out in a local development environment.
• A GitHub personal access token with repo permissions. See the GitHub documentation on creating a personal access token.

Note that for production use, it is recommended to have a dedicated GitHub account for Flux and use fine-grained access tokens with the minimum required permissions.

Objectives

• 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 \
  --personal

The output is similar to:

► connecting to github.com
✔ 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 https://github.com/$GITHUB_USER/fleet-infra
cd fleet-infra

Add podinfo repository to Flux

This example uses a public repository github.com/stefanprodan/podinfo, 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=https://github.com/stefanprodan/podinfo \
     --branch=master \
     --interval=1m \
     --export > ./clusters/my-cluster/podinfo-source.yaml
   

   The output is similar to:

   apiVersion: source.toolkit.fluxcd.io/v1
   kind: GitRepository
   metadata:
     name: podinfo
     namespace: flux-system
   spec:
     interval: 1m
     ref:
       branch: master
     url: https://github.com/stefanprodan/podinfo
   

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:

   apiVersion: kustomize.toolkit.fluxcd.io/v1
   kind: Kustomization
   metadata:
     name: podinfo
     namespace: flux-system
   spec:
     interval: 30m0s
     path: ./kustomize
     prune: true
     retryInterval: 2m0s
     sourceRef:
       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:

   fleet-infra
   └── 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:

   NAME          REVISION             SUSPENDED  READY   MESSAGE
   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   10.100.149.126   <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:

     patches:
       - patch: |-
           apiVersion: autoscaling/v2
           kind: HorizontalPodAutoscaler
           metadata:
             name: podinfo
           spec:
             minReplicas: 3             
         target:
           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.

1. https://github.com/fluxcd/flux2-kustomize-helm-example
2. https://github.com/fluxcd/flux2-multi-tenancy