Learning GitOps - FluxCD - Installing FluxCD

#Introduction

In episode 3 you gained a deep understanding of the GitOps Toolkit architecture — from the Source Controller to the Image Automation Controllers. Now theory turns into practice: we're going to install FluxCD on your cluster. This episode is the first moment where all the preparation from episode 0 is truly put to the test.

There's good news: unlike installing conventional tools, FluxCD offers flux bootstrap — a single command that does everything: creates the namespace, installs the controllers, writes the manifest files into Git, and configures FluxCD to manage itself through Git. This is a major reason GitOps is so popular.

#Checking Prerequisites

Before running anything, make sure the following prerequisites are met.

#Kubernetes Cluster

FluxCD requires a stable Kubernetes cluster, version 1.23 or newer. Local clusters like kind or minikube are fine for a lab. Make sure your kubectl context points to the correct cluster:

Check context and cluster access

kubectl config current-context
kubectl cluster-info
kubectl get nodes

#Git Hosting Access Token

FluxCD needs write access to a Git repository to write the bootstrap manifests. Prepare a Personal Access Token from GitHub, GitLab, or Bitbucket with repo permissions (for GitHub, the repo scope). For GitHub you also must export your username as an environment variable:

Export GitHub credentials

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

#Git Repository

The destination repository can be empty or already exist. FluxCD will create the branch and directory structure it needs there. A common layout uses ./clusters/<cluster-name>/ as the cluster configuration root.

Important

The token exported with export only lives in the active shell. Don't write it into a script that gets committed, and remember that GITHUB_TOKEN and GITHUB_USER are variables read automatically by flux bootstrap github.

#Installation Methods

There are four paths to install FluxCD:

Method	Characteristics	Recommendation
`flux bootstrap`	Fully automatic, self-managed via Git	Most recommended
`flux install`	Manual, without writing to Git	Quick lab
Terraform provider	IaC Terraform integration	Teams already using Terraform
Helm chart	Install via a Helm chart	Heavy Helm users

In this episode we focus on flux bootstrap, because it produces the setup most aligned with the GitOps philosophy: the cluster configuration lives in Git from the very first minute.

#The Bootstrap Process

The bootstrap command for GitHub:

Bootstrap FluxCD to GitHub

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

For GitLab or other providers, the command is similar with different names:

Bootstrap to GitLab or a generic repo

flux bootstrap gitlab \
  --owner=acme \
  --repository=gitops \
  --branch=main \
  --path=./clusters/my-cluster
 
flux bootstrap git \
  --url=ssh://git@github.com/acme/gitops.git \
  --branch=main \
  --path=./clusters/my-cluster

Tip

Use --personal when the repository is owned personally (not an organization). For organizations, drop this flag so FluxCD creates a dedicated deploy token with limited rights.

#What Does Bootstrap Do?

flux bootstrap works through several stages automatically:

Creates the flux-system namespace in the cluster.
Installs all GitOps Toolkit controllers into that namespace.
Creates manifest files (GitRepository, Kustomization, and others) in the Git repository according to --path.
Commits and pushes those manifests to the chosen branch.
Waits for the controllers to reconcile for the first time — so FluxCD manages itself through Git.

The result: the cluster and repository are fully connected within minutes, and all of FluxCD's own configuration can be reviewed through PRs.

#Useful Bootstrap Options

Branch: --branch=<name> sets the branch to use; default is main.
Path: --path=./clusters/<name> is the cluster configuration root; many clusters can live in one repo.
Components: --components=source-controller,kustomize-controller for a partial install (for example without the Helm controller).
Network policy: flags like --network-policy control the controller's ingress/egress access in the flux-system namespace.
Kustomization: --kustomization-override or --image-ref for advanced customization.

#Verifying the Installation

After bootstrap finishes, verify with two quick checks. First, check the components and connections:

Verify FluxCD health

flux check
flux get kustomizations

Second, look at the running controller pods directly:

Check pods in the flux-system namespace

kubectl get pods -n flux-system
kubectl get gitrepositories -n flux-system

Warning

If flux check reports components that aren't ready, don't continue. Inspect the pod logs with kubectl logs -n flux-system -l app=kustomize-controller and make sure the Git token is still valid.

#Closing

Congratulations — FluxCD is now running on your cluster. Key takeaways:

Prerequisites: an active Kubernetes cluster, a Git token with write access, and a clear destination repo.
Methods: bootstrap is most recommended; flux install, Terraform, and the Helm chart are alternatives.
Bootstrap: a single command creates the namespace, installs the controllers, writes manifests to Git, and configures self-management.
Options: branch, path, components, and network policy control the behavior.
Verification: flux check and kubectl get pods -n flux-system confirm everything is healthy.

In episode 5 we master your main daily weapon: the Flux CLI — from installation and shell completion to essential commands like flux get, flux logs, flux reconcile, and flux trace. See you there!