Flux bootstrap for Git servers

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 existing 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> \
  --path=clusters/my-cluster

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

flux create secret git flux-system \
  --url=ssh://git@<host>/<org>/<repository> \
  --private-key-file=<path/to/private.key> \
  --password=<key-passphrase>

SSH Agent

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

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

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.

flux create secret git flux-system \
  --url=ssh://git@<host>/<org>/<repository> \
  --ssh-key-algorithm=ecdsa \
  --ssh-ecdsa-curve=p384

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 \
  --path=clusters/my-cluster

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>.

HTTPS authorization header

To access Git repositories that require a bearer token in the HTTP headers as an Authorization header such as Oracle VBS Git Repositories:

flux bootstrap git \
  --url=https://<host>/<org>/<repository> \
  --password=<Access Token> \
  --with-bearer-token \
  --path=clusters/my-cluster

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

Bootstrap 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:

./clusters/
├── 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