Installation and Bootstrap

How flux bootstrap differs from flux install, why committing Flux own manifests to Git makes it self-managing, and the operational lifecycle: auth choices, cluster path layout, upgrades, air-gapped installs, and uninstall.

Overview

Install versus bootstrap

There are two ways to get Flux onto a cluster, and the difference is the difference between a demo and a production installation. flux install applies the GitOps Toolkit controllers and stops. flux bootstrap does that, then commits the same manifests into Git and configures Flux to reconcile the directory it just wrote.

After bootstrap, Flux is managing Flux.

Installs controllers, CRDs, RBAC — Yes — Yes
Writes to Git — No — Yes
Flux managed by Flux — No — Yes
Production answer — No — Yes

The three files bootstrap writes

The gotk prefix is GitOps Toolkit.

gotk-components.yaml — The rendered controller installation, including CRDs and RBAC
gotk-sync.yaml — The GitRepository and Kustomization that point back at this same directory
kustomization.yaml — A Kustomize overlay listing both; your customizations go here

Because Flux reconciles that path like any other Kustomization, three operations become Git operations.

Upgrading Flux — A commit
Customizing controller flags — A patch
Rebuilding a destroyed cluster — Re-running the same bootstrap command against the same path

> [!IMPORTANT] Bootstrap is idempotent by design. Re-running it is not a recovery action; it is the normal way to change the Flux version, add components or rotate credentials. The docs call it declarative-first and disaster-resilient for this reason.

Provider subcommands

Subcommands exist for github, gitlab, bitbucket-server, gitea, azure devops, aws codecommit, google cloud source repositories and oracle VBS, plus a generic git for anything reachable over SSH or HTTPS.

> [!NOTE] Provider variants want a token with administration permission even when the resulting sync credential is a read-only deploy key, because they do that extra API work.

The authentication decision

This is the choice with lasting consequences.

--token-auth (default) — The provider token, as Secret flux-system in namespace flux-system — Whatever the token grants
--token-auth=false — A generated SSH private key; the public half is a repository deploy key — One repository, read-only unless --read-write-key
flux create secret githubapp — GitHub App credentials that yield short-lived installation tokens — Per App installation; command still marked in preview

> [!TIP] The deploy key is the narrower credential and the better default. Read-write is needed only when image automation must push commits back.

The rest of the lifecycle

> [!WARNING] Engineers routinely assume uninstalling Flux tears down their applications. It does not: every workload Flux was reconciling stays running. Interviewers probe this detail.

Key concepts

flux install: Deploys the controllers into a namespace and performs an in-place upgrade if a previous version is present. Writes nothing to Git and creates no GitRepository or Kustomization, so Flux does not manage itself. Its most useful production role is flux install --export, which prints the manifests to stdout for committing or for use with kubectl apply --dry-run.
flux bootstrap: Installs the controllers, commits the same manifests to Git under --path, creates the GitRepository and Kustomization that point back at that path, and configures repository authentication. Idempotent, so re-running it is the supported way to change version, components, or credentials.
Self-management: The property that Flux reconciles a path whose contents define Flux itself. Upgrades become commits, controller customizations become Kustomize patches that survive reconciliation, and rebuilding a lost cluster becomes re-running the same bootstrap command.
The gotk files: gotk-components.yaml is the rendered controller install (CRDs, Deployments, RBAC). gotk-sync.yaml holds the self-referential GitRepository and Kustomization. kustomization.yaml lists both and carries your patches. GOTK is GitOps Toolkit.
--path: The repository-relative directory that scopes one cluster, conventionally clusters/. Flux reconciles only what is under it, which is how a single repository serves many clusters without a change to one reaching another.
--token-auth versus deploy key: With --token-auth (the default) the provider token is stored as a Secret named flux-system in the flux-system namespace. With --token-auth=false Flux generates an SSH key, keeps the private key in that Secret, and registers the public key as a repository deploy key, read-only unless --read-write-key is passed. The deploy key is scoped to one repository and is the tighter credential.
--components and --components-extra: Default components are source-controller, kustomize-controller, helm-controller, notification-controller. --components-extra adds opt-in controllers, in practice image-reflector-controller and image-automation-controller. Adding them later means re-running bootstrap or regenerating gotk-components.yaml with the extra flag.
flux check: Two modes. flux check --pre runs before installation and validates the Kubernetes version against Flux prerequisites. flux check runs after and reports controller versions, readiness, and CRD status. It is the verification step after every upgrade and the first diagnostic when reconciliation stalls.

When to use it

Any cluster you intend to keep — bootstrap rather than flux install, so Flux manages its own upgrades and survives cluster rebuilds
Fleet management from one repository, with each cluster scoped by its own --path such as clusters/prod-eu and clusters/prod-us
Disaster recovery drills — provision an empty cluster, re-run the original bootstrap command against the same path, and let Flux rebuild the workloads from Git
Air-gapped or regulated environments — mirror controller images with crane and bootstrap with --registry, --registry-creds, and --image-pull-secret against an internal Git server
Fleet-wide version pinning from CI or Terraform, using the fluxcd/flux provider flux_bootstrap_git resource, which is safe to re-apply because bootstrap is idempotent

Interview questions

What is the difference between flux install and flux bootstrap, and why does self-management matter?
Walk through the repository layout bootstrap generates and how you would customize the controllers.
Compare the authentication options for bootstrap: PAT, deploy key, and GitHub App.
How do you upgrade Flux, and how do you install it in an air-gapped environment?
How do you uninstall Flux, and what happens to the applications it was managing?