This guide installs the Flux CLI, bootstraps Flux into a cluster, and shows what it committed to your Git repository. You need kubectl configured for a cluster you can freely experiment on. A local kind or minikube cluster is ideal, and a GitHub account to hold the repository.

Create a cluster and install the CLI

For a disposable local cluster:

kind create cluster --name flux-demo
kubectl get nodes

Install the Flux CLI with Homebrew, or with the install script on Linux:

brew install fluxcd/tap/flux
# or
curl -s https://fluxcd.io/install.sh | sudo bash

Check it works:

flux --version

You can also download a binary from the releases page. Flux supports the latest three Kubernetes minor versions, so use a reasonably recent cluster.

Run the pre-flight checks

With kubectl pointing at your cluster, ask Flux whether the cluster is compatible:

flux check --pre

You should see the Kubernetes version and a final line saying the prerequisites are satisfied.

Create a personal access token

Bootstrap needs a token so it can create the repository, push commits, and register a deploy key. In GitHub, create a classic personal access token with the repo scope, or a fine-grained token with read and write access to Contents and Administration on the target repository. Export it for the current shell:

export GITHUB_TOKEN=<your-token>

The token is only used by the CLI during bootstrap. By default Flux creates an SSH deploy key for its long-term access, and the token isn’t stored in the cluster, so a short expiry (days, not months) is fine.

Bootstrap Flux

Run bootstrap against a personal account. The repository is created if it doesn’t exist:

flux bootstrap github \
  --owner=<your-github-user> \
  --repository=fleet-infra \
  --branch=main \
  --path=clusters/dev \
  --personal

For an organization, omit --personal. The flags that matter:

• --repository is where Flux stores its own manifests and, later, your application configuration.
• --path is the folder inside the repository that this cluster syncs from. Use one path per cluster, such as clusters/dev and clusters/production, so one repository can serve many clusters.
• --branch is the branch Flux commits to and tracks.

The command connects to GitHub, clones the repository, generates the Flux manifests, commits and pushes them, installs Flux into the cluster, and waits for the controllers to become ready. Two variants you’ll meet later:

• --token-auth uses the personal access token itself over HTTPS instead of generating an SSH deploy key.
• --read-write-key gives the deploy key write access. You need this when Flux itself pushes commits, as it does for image automation.

Bootstrap is safe to run again. Running it with a newer CLI upgrades the controllers, and it will pick up any extra options you pass.

Verify the installation

flux check
kubectl get pods -n flux-system

flux check reports each controller as healthy. You should see the source, kustomize, helm, and notification controllers running. Then see what Flux committed:

git clone https://github.com/<your-github-user>/fleet-infra.git
cd fleet-infra
tree clusters

clusters/
└── dev/
    └── flux-system/
        ├── gotk-components.yaml   # the Flux controllers and CRDs
        ├── gotk-sync.yaml         # a GitRepository and Kustomization pointing back at this repo
        └── kustomization.yaml

gotk stands for GitOps Toolkit. The two objects in gotk-sync.yaml are the heart of the setup:

flux get sources git
flux get kustomizations

The flux-system GitRepository tells source-controller where your repository is and which branch to follow. The flux-system Kustomization tells kustomize-controller to apply everything under ./clusters/dev from that repository. Anything you add under that path is picked up automatically, which is how the next guide deploys an application.

Clean up

To remove Flux from the cluster:

flux uninstall

This removes the controllers and CRDs and the resources Flux manages in the cluster. It does not delete your Git repository. For a local experiment, kind delete cluster --name flux-demo removes everything.