10 KiB
Installation
This guide walks you through setting up Flux v2 (hereafter: "Flux") to manage one or more Kubernetes clusters.
Prerequisites
You will need a Kubernetes cluster version 1.16 or newer and kubectl version 1.18 or newer.
Install the Flux CLI
With Homebrew:
brew install fluxcd/tap/flux
With Bash:
curl -s https://toolkit.fluxcd.io/install.sh | sudo bash
# enable completions in ~/.bash_profile
. <(flux completion bash)
Command-line completion for zsh
, fish
, and powershell
are also supported with their own sub-commands.
Binaries for macOS, Windows and Linux AMD64/ARM are available for download on the release page.
Verify that your cluster satisfies the prerequisites with:
flux check --pre
Bootstrap
Using the flux bootstrap
command you can install Flux on a
Kubernetes cluster and configure it to manage itself from a Git
repository.
The bootstrap creates a Git repository if one doesn't exist and commits the Flux components manifests to the main branch. Then it configures the target cluster to synchronize with that repository by setting up SSH deploy keys.
If the Flux components are present on the cluster, the bootstrap command will perform an upgrade if needed. The bootstrap is idempotent, it's safe to run the command as many times as you want.
You can choose what components to install and for which cluster with:
flux bootstrap <GIT-PROVIDER> \
--components=source-controller,kustomize-controller,helm-controller,notification-controller \
--path=my-cluster \
--version=latest
!!! hint "ARM"
When deploying to a Kubernetes cluster with ARM architecture,
you can use --arch=arm
for ARMv7 32-bit container images
and --arch=arm64
for ARMv8 64-bit container images.
If you wish to install a specific version, use the Flux
release tag e.g. --version=v0.2.0
.
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. staging-cluster
and production-cluster
:
├── staging-cluster # <- path=staging-cluster
│ └── flux-system # <- namespace dir generated by bootstrap
│ ├── gotk-components.yaml
│ ├── gotk-sync.yaml
│ └── kustomization.yaml
└── production-cluster # <- path=production-cluster
└── flux-system
!!! hint "Change the default branch"
If you wish to change the branch to something else than main, create the repository manually,
push a branch to origin and then use flux bootstrap <GIT-PROVIDER> --branch=your-branch
.
GitHub and GitHub Enterprise
Generate a personal access token
that can create repositories by checking all permissions under repo
.
Export your GitHub personal access token as an environment variable:
export GITHUB_TOKEN=<your-token>
Run the bootstrap for a repository on your personal GitHub account:
flux bootstrap github \
--owner=my-github-username \
--repository=my-repository \
--path=my-cluster \
--personal
Run the bootstrap for a repository owned by a GitHub organization:
flux bootstrap github \
--owner=my-github-organization \
--repository=my-repository \
--team=team1-slug \
--team=team2-slug \
--path=my-cluster
When you specify a list of teams, those teams will be granted maintainer access to the repository.
To run the bootstrap for a repository hosted on GitHub Enterprise, you have to specify your GitHub hostname:
flux bootstrap github \
--hostname=my-github-enterprise.com \
--owner=my-github-organization \
--repository=my-repository \
--branch=main \
--path=my-cluster
GitLab and GitLab Enterprise
Generate a personal access token that grants complete read/write access to the GitLab API.
Export your GitLab personal access token as an environment variable:
export GITLAB_TOKEN=<your-token>
Run the bootstrap for a repository on your personal GitLab account:
flux bootstrap gitlab \
--owner=my-gitlab-username \
--repository=my-repository \
--branch=master \
--path=my-cluster \
--personal
To run the bootstrap for a repository using deploy keys for authentication, you have to specify the SSH hostname:
flux bootstrap gitlab \
--ssh-hostname=gitlab.com \
--owner=my-gitlab-username \
--repository=my-repository \
--branch=master \
--path=my-cluster
!!! hint "Authentication"
When providing the --ssh-hostname
, a read-only (SSH) deploy key will be added
to your repository, otherwise your GitLab personal token will be used to
authenticate against the HTTPS endpoint instead.
Run the bootstrap for a repository owned by a GitLab group:
flux bootstrap gitlab \
--owner=my-gitlab-group \
--repository=my-repository \
--branch=master \
--path=my-cluster
To run the bootstrap for a repository hosted on GitLab on-prem or enterprise, you have to specify your GitLab hostname:
flux bootstrap gitlab \
--hostname=my-gitlab.com \
--owner=my-gitlab-group \
--repository=my-repository \
--branch=master \
--path=my-cluster
Generic Git Server
For other Git providers such as Bitbucket, Gogs, Gitea, etc you can manually setup the repository and the deploy key.
Create a Git repository and clone it locally:
git clone ssh://<host>/<org>/my-repository
cd my-repository
Create a directory inside the repository:
mkdir -p ./my-cluster/flux-system
Generate the Flux manifests with:
flux install --version=latest \
--arch=amd64 \ # on ARM64/AARCH64 clusters use --arch=arm64
--export > ./my-cluster/flux-system/gotk-components.yaml
If your cluster must pull images from a private container registry, first you should pull the toolkit images from GitHub Container Registry and push them to your registry, for example:
docker pull ghcr.io/fluxcd/source-controller:v0.2.0
docker tag ghcr.io/fluxcd/source-controller:v0.2.0 registry.internal/fluxcd/source-controller:v0.2.0
docker push registry.internal/fluxcd/source-controller:v0.2.0
Create the pull secret in the flux-system
namespace:
kubectl create ns flux-system
kubectl -n flux-system create secret generic regcred \
--from-file=.dockerconfigjson=/.docker/config.json \
--type=kubernetes.io/dockerconfigjson
Set your registry domain, and the pull secret when generating the manifests:
flux install --version=latest \
--registry=registry.internal/fluxcd \
--image-pull-secret=regcred \
--export > ./my-cluster/flux-system/gotk-components.yaml
Commit and push the manifest to the master branch:
git add -A && git commit -m "add components" && git push
Apply the manifests on your cluster:
kubectl apply -f ./my-cluster/flux-system/gotk-components.yaml
Verify that the controllers have started:
flux check
Create a GitRepository
object on your cluster by specifying the SSH address of your repo:
flux create source git flux-system \
--url= ssh://<host>/<org>/my-repository \
--ssh-key-algorithm=ecdsa \
--ssh-ecdsa-curve=p521 \
--branch=master \
--interval=1m
You will be prompted to add a deploy key to your repository.
If you don't specify the SSH algorithm, then flux
will generate an RSA 2048 bits key.
If your Git server supports basic auth, you can set the URL to HTTPS and specify the credentials with:
flux create source git flux-system \
--url=https://<host>/<org>/my-repository \
--username=my-username \
--password=my-password \
--branch=master \
--interval=1m
Create a Kustomization
object on your cluster:
flux create kustomization flux-system \
--source=flux-system \
--path="./my-cluster" \
--prune=true \
--interval=10m
Export both objects, generate a kustomization.yaml
, commit and push the manifests to Git:
flux export source git flux-system \
> ./my-cluster/flux-system/gotk-sync.yaml
flux export kustomization flux-system \
>> ./my-cluster/flux-system/gotk-sync.yaml
cd ./my-cluster/flux-system && kustomize create --autodetect
git add -A && git commit -m "add sync manifests" && git push
To upgrade the Flux components to a newer version, run the install command and commit the changes:
flux install --version=latest \
--export > ./my-cluster/flux-system/gotk-components.yaml
git add -A && git commit -m "update flux" && git push
The source-controller will pull the changes on the cluster, then the kustomize-controller will perform a rolling update of all Flux components including itself.
Dev install
For testing purposes you can install Flux without storing its manifests in a Git repository.
Here is the equivalent to fluxctl install
:
flux install \
--components=source-controller,kustomize-controller
Then you can register Git repositories and reconcile them on your cluster:
flux create source git podinfo \
--url=https://github.com/stefanprodan/podinfo \
--tag-semver=">=4.0.0" \
--interval=1m
flux create kustomization podinfo-default \
--source=podinfo \
--path="./kustomize" \
--prune=true \
--validation=client \
--interval=10m \
--health-check="Deployment/podinfo.default" \
--health-check-timeout=2m
Here is the equivalent to helm install helm-operator
:
flux install \
--components=source-controller,kustomize-controller,helm-controller
Then you can register Helm repositories and create Helm releases:
flux create source helm stable \
--interval=1h \
--url=https://charts.helm.sh/stable
flux create helmrelease sealed-secrets \
--interval=1h \
--release-name=sealed-secrets \
--target-namespace=flux-system \
--source=HelmRepository/stable \
--chart=sealed-secrets \
--chart-version="1.10.x"
Monitoring with Prometheus and Grafana
Flux comes with a monitoring stack composed of Prometheus and Grafana. The controllers expose metrics that can be used to track the readiness of the cluster reconciliation process.
To install the monitoring stack please follow this guide.
Uninstall
You can uninstall the Flux components with:
flux uninstall --crds
The above command will delete the custom resources definitions, the controllers, and the namespace where they were installed.