Flux bootstrap for Git servers

How to bootstrap Flux with a generic Git server

The flux bootstrap git command deploys the Flux controllers on a Kubernetes cluster and configures the controllers to sync the cluster state from a Git repository. Besides installing the controllers, the bootstrap command pushes the Flux manifests to the Git repository and configures Flux to update itself from Git.

After running the bootstrap command, any operation on the cluster (including Flux upgrades) can be done via Git push, without the need to connect to the Kubernetes cluster.

SSH Private Key

Run bootstrap for an exiting Git repository and authenticate with a SSH key which has pull and push access:

flux bootstrap git \
  --url=ssh://git@<host>/<org>/<repository> \
  --branch=main \
  --private-key-file=<path/to/private.key> \
  --password=<key-passphrase> \

The private key is stored in the cluster as a Kubernetes secret named flux-system inside the flux-system namespace.

SSH Agent

Run bootstrap for an exiting Git repository and authenticate with your SSH agent:

flux bootstrap git \
  --url=ssh://git@<host>/<org>/<repository> \
  --branch=main \

When using the SSH Agent, the bootstrap command will generate a new SSH private key for the cluster, and it will prompt you to add the SSH public key as a deploy key to your repository.

The generated SSH key defaults to ECDSA P-384, to change the format use --ssh-key-algorithm and --ssh-ecdsa-curve.

HTTPS basic auth

If your Git server has basic auth enabled, you can bootstrap Flux over HTTPS with:

flux bootstrap git \
  --url=https://<host>/<org>/<repository> \
  --username=<my-username> \
  --password=<my-password> \
  --token-auth=true \

You can also supply the password or Git token using a pipe e.g. echo "<my-pass>" | flux bootstrap git.

If your Git server uses a self-signed TLS certificate, you can specify the CA file with --ca-file=<path/to/ca.crt>.

Boostrap multiple clusters

With --path you can configure the directory which will be used to reconcile the target cluster. To control multiple clusters from the same Git repository, you have to set a unique path per cluster e.g. clusters/staging and clusters/production:

├── staging # <- path=clusters/staging
│   └── flux-system # <- namespace dir generated by bootstrap
│       ├── gotk-components.yaml
│       ├── gotk-sync.yaml
│       └── kustomization.yaml
└── production # <- path=clusters/production
    └── flux-system
Last modified 2023-08-17: Add bootstrap guides (f81dc81)