flux
Table of Content
flux¶
[[flux]]
To get started, you need followings.
- Kubernetes cluster
- git server
- a node that has access to the control plane of the cluster
Here are the brief steps:
- install flux cli
- create a git repository used for gitops
- create an access token (short-lived, but a separate deploy token will be created by flux during bootstrap)
- use the token to run flux command to bootstrap the repository and cluster
installation¶
Install flux cli on a node that has access to the control plane.
curl -s https://fluxcd.io/install.sh | sudo bash
flux version --client
# or, use brew on mac
brew install fluxcd/tap/flux
# optionally, pin flux to control version changes
# brew pin flux
# brew list --pinned
# brew unpin flux
# brew upgrade flux
bootstrap¶
Now run a bootstrap command to install flux to the cluster.
As a sidenote, the GitLab access token expiration has become very short since the recent update (in 2023), and the flux boot strap command now should be --deploy-token-auth instead of --token-auth so that a new deploy token gets created by flux on GitLab as part of the bootstrap process.
export GITLAB_TOKEN={token_string_here}
export GITLAB_SERVER={gitlab_server}
flux bootstrap gitlab \
--deploy-token-auth \
--hostname="$GITLAB_SERVER" \
--owner=gitops \
--repository=flux \
--path=./clusters/my-cluster \
--branch=main
By running this bootstrap command, flux will:
- access the git source and clone the repository
- generate the manifests for flux components to install to the cluster and push to the repository
- install the flux components to the cluster
- create a deploy token and store it as a secret in the cluster
- confirm all the installed flux components are working fine
how to use flux¶
Simply put, whatever kubernetes manifest you'd kubectl apply can be placed at or called from ./clusters/my-cluster/ directory. However, you should follow this guide available on the official site and decide.
https://fluxcd.io/flux/guides/repository-structure/
https://github.com/fluxcd/flux2-kustomize-helm-example
You can setup a repository to manage multiple kubernetes clusters, and the directory structure from the second link has the example of how it should look like.
It all starts from ./clusters/production or ./clusters/staging, and each folder is going to be bootstrapped with separate clusters.
.
|-apps
| |-staging
| | |-kustomization.yaml
| | |-podinfo-values.yaml
| |-base
| | |-podinfo
| | | |-namespace.yaml
| | | |-kustomization.yaml
| | | |-repository.yaml
| | | |-release.yaml
| |-production
| | |-kustomization.yaml
| | |-podinfo-values.yaml
|-clusters
| |-staging
| | |-infrastructure.yaml
| | |-apps.yaml
| | |-flux-system
| | | |-kustomization.yaml
| | | |-gotk-sync.yaml
| | | |-gotk-components.yaml
| |-production
| | |-infrastructure.yaml
| | |-apps.yaml
| | |-flux-system
| | | |-kustomization.yaml
| | | |-gotk-sync.yaml
| | | |-gotk-components.yaml
|-infrastructure
| |-configs
| | |-kustomization.yaml
| | |-cluster-issuers.yaml
| | |-network-policies.yaml
| |-controllers
| | |-kustomization.yaml
| | |-cert-manager.yaml
| | |-weave-gitops.yaml
| | |-ingress-nginx.yaml
|-.sourceignore
Let's just focus on the staging cluster. The --path value when bootstrapping should be ./clusters/staging, and the flux will install its components to the cluster and create ./clusters/staging/flux-system/ and manifest files inside it.
gotk-components.yaml has all the components, and gotk-sync.yaml contains gitrepo manifest that points flux to watch this repository bootstrapped, and kustomizations manifest to have flux periodically run kustomize resources available at --path.
The flux kustomizations will pick up two manifest files in this case, infrastructure.yaml and apps.yaml.
The infrastructure.yaml contains two kustomizations watching ./infrastructure/controllers/ and ./infrastructure/configs/, and apps.yaml contains one kustomization watching ./apps/staging/.
%%{init: { 'theme': 'forest', "curve": "linear"} }%%
graph LR
infra([Infrastructure kustomizations<br/>./clusters/staging/infrastructure.yaml])
controllers([Controllers<br/>./infrastructure/controllers/])
configs([Configs<br/>./infrastructure/configs/])
apps([Apps kustomizations<br/>./clusters/staging/apps.yaml])
staging_apps([Apps<br/>./apps/staging/])
infra --> |ks|controllers
infra --> |ks|configs
apps --> |ks|staging_appsinfrastructure/controllers/ dir contains namespaces and Helm release definitions for Kubernetes Controllers
In case of this example, cert-manager, weave-gitops, and ingress-nginx are prepared.
infrastructure/configs/ dir contains Kubernetes custom resources such as cert issuers and networks policies
In case of this example, issuer config and network policy config are prepared.
As for apps, the kustomizations from ./clusters/staging/apps.yaml points to ./apps/staging/ and picks up kustomizations there, and it then points to another kustomization in ./app/base/{applications, in this case podinfo only}/ which contains the basic setup configuration, and the "staging" environment specific configurations will be applied by the another file ./apps/staging/{applications, in this case podinfo only}-values.yaml.
There are dependencies set in the manifests in a way that the flux system handles the controllers first, then the configs, and then the apps.
%%{init: { 'theme': 'forest', "curve": "linear"} }%%
graph LR
controllers([kustomizations and manifests<br/>under Controllers])
configs([kustomizations and manifests<br/>under Configs])
apps([Apps kustomizations])
apps --> |dependsOn|configs
configs --> |dependsOn|controllers