Skip to main content
This guide shows how to install the Flux v2 CLI, deploy Flux controllers into a Kubernetes cluster, and bootstrap Flux to manage itself from a GitHub repository. Steps were performed using Visual Studio Code on Ubuntu 18.04 under Windows Subsystem for Linux (WSL) with Docker Desktop as the Kubernetes provider (single-node cluster). The instructions below are applicable to most Linux/macOS development environments and can be adapted for other editors or terminals. Environment summary Docker Desktop must have Kubernetes enabled. The Docker Desktop settings (Kubernetes enabled) are shown here:
A screenshot of Docker Desktop's Settings on the Kubernetes tab, showing options like "Enable Kubernetes" and a highlighted "Reset Kubernetes Cluster" button. The left sidebar lists other settings such as General, Resources, Docker Engine, and Extensions.
Verify the cluster and node
Installing the Flux CLI
  1. Confirm the flux CLI is not installed:
  1. Install the Flux CLI using the official install script and enable Bash completion:
  1. Verify the installed CLI version:
Note: At this point the CLI is installed, but Flux controllers are not yet deployed into your cluster. Running flux version without cluster components will report:
Bootstrapping Flux to GitHub (GitOps) Flux provides a bootstrap command that installs the Flux controllers into your cluster and configures them to sync with a Git repository. The GitHub bootstrap requires a GitHub Personal Access Token (PAT) with the appropriate scopes (typically repo for repository creation/management and deploy key configuration). Quick example of the bootstrap command (placeholders shown in backticks):
Important flags Create a GitHub Personal Access Token Create a PAT with the minimum scopes required for bootstrap (commonly repo). On GitHub: Settings → Developer settings → Personal access tokens → Generate new token (classic). Copy and store the token securely — GitHub will not show it again after you leave the page.
A screenshot of GitHub’s "New Personal Access Token" page in dark mode, showing the Expiration set to "No expiration" and a highlighted recommendation to set an expiry. The OAuth scopes list is visible with "repo" and several repo-related permissions checked.
For security, grant tokens the minimum scopes required and set an expiry. The bootstrap process typically requires the repo scope to create a repository and add deploy keys; consider using a short-lived token if possible.
Run the bootstrap command Replace the placeholders below with your own values (owner, repository, path, and token):
What happens during bootstrap
  1. Flux connects to GitHub and creates (or uses) the specified repository.
  2. Flux generates component manifests (namespace, CRDs, controllers).
  3. Flux installs controllers into the flux-system namespace.
  4. Flux generates a deploy key pair: the public key is added to the GitHub repo; the private key is stored in a Kubernetes Secret in flux-system.
  5. Flux commits generated manifests into the repository and pushes them to the main branch.
  6. Flux reconciles the Kustomization to apply manifests and validates component health.
Sample trimmed bootstrap output (annotated)
After bootstrap completes, Flux controllers are running in the cluster and the generated manifests have been pushed into the Git repo. Inspect the created repository Clone the repository created by bootstrap:
Example clone output:
Repository layout (typical)
  • flux-clusters/dev-cluster/flux-system/ — contains generated manifests such as:
    • gotk-components.yaml
    • gotk-sync.yaml
    • Kustomization YAML files
Example excerpt from gotk-components.yaml (auto-generated by Flux):
Verify Flux components in the cluster
  1. Confirm the flux-system namespace exists:
  1. Inspect resources in flux-system:
You should see Deployments, ReplicaSets, and Pods for:
  • source-controller
  • kustomize-controller
  • helm-controller
  • notification-controller
Also observe a Secret (for example flux-system) that holds the private deploy key. The public key is configured as a deploy key in the GitHub repository.
  1. List Flux-related CRDs:
  1. Check CLI and controller versions:
Summary
  • You installed the flux CLI and bootstrapped Flux to your Kubernetes cluster using flux bootstrap github.
  • Bootstrap created (or used) a GitHub repository, generated and committed Flux manifests, installed Flux controllers into the flux-system namespace, created CRDs, and configured a deploy key so Flux can sync with the repository.
  • The repository contains Flux-generated manifests (e.g., gotk-components.yaml, gotk-sync.yaml, and Kustomizations). You can now edit the repo to add your cluster manifests and let Flux reconcile and apply changes automatically (GitOps).
Links and references

Watch Video

Practice Lab