9.3 KiB
Get started with GitOps Toolkit
Prerequisites
- Kubernetes >= 1.14
- kubectl >= 1.18
- git
You will need to have Kubernetes set up.
For a quick local test, you can use minikube
, kubeadm
or kind
.
Any other Kubernetes setup will work as well though.
In order to follow the guide you'll need a GitHub account and a personal access token that can create repositories.
Install the toolkit CLI
To install the latest tk
release run:
curl -s https://toolkit.fluxcd.io/install.sh | sudo bash
The install script downloads the tk binary to /usr/local/bin
.
Binaries for macOS and Linux AMD64 are available for download on the
release page.
To configure your shell to load tk completions add to your bash profile:
# ~/.bashrc or ~/.bash_profile
. <(tk completion)
Verify that your cluster satisfies the prerequisites with:
$ tk check --pre
► checking prerequisites
✔ kubectl 1.18.3 >=1.18.0
✔ kubernetes 1.16.8-eks-e16311 >=1.14.0
✔ prerequisites checks passed
Bootstrap
You'll be using a dedicated Git repository e.g. fleet-infra
to manage one or more Kubernetes clusters.
First export your GitHub personal access token and GitHub username:
export GITHUB_TOKEN=<your-token>
export GITHUB_USER=<your-username>
The bootstrap command creates a repository if one doesn't exist and commits the toolkit components manifests to the master branch at the specified path. Then it configures the target cluster to synchronize with the specified path inside the repository.
tk bootstrap github \
--owner=$GITHUB_USER \
--repository=fleet-infra \
--path=dev-cluster \
--personal
If you wish to create the repository under a GitHub organization:
tk bootstrap github \
--owner=<organization> \
--repository=<repo-name> \
--team=<team1-slug> \
--team=<team2-slug> \
--path=dev-cluster
Example output:
$ tk bootstrap github --owner=gitopsrun --repository=fleet-infra --path=dev-cluster --team=devs
► connecting to github.com
✔ repository created
✔ devs team access granted
✔ repository cloned
✚ generating manifests
✔ components manifests pushed
► installing components in gitops-system namespace
namespace/gitops-system created
customresourcedefinition.apiextensions.k8s.io/gitrepositories.source.fluxcd.io created
customresourcedefinition.apiextensions.k8s.io/helmcharts.source.fluxcd.io created
customresourcedefinition.apiextensions.k8s.io/helmrepositories.source.fluxcd.io created
customresourcedefinition.apiextensions.k8s.io/kustomizations.kustomize.fluxcd.io created
customresourcedefinition.apiextensions.k8s.io/profiles.kustomize.fluxcd.io created
role.rbac.authorization.k8s.io/crd-controller-gitops-system created
rolebinding.rbac.authorization.k8s.io/crd-controller-gitops-system created
clusterrolebinding.rbac.authorization.k8s.io/cluster-reconciler-gitops-system created
service/source-controller created
deployment.apps/kustomize-controller created
deployment.apps/source-controller created
networkpolicy.networking.k8s.io/deny-ingress created
Waiting for deployment "source-controller" rollout to finish: 0 of 1 updated replicas are available...
deployment "source-controller" successfully rolled out
deployment "kustomize-controller" successfully rolled out
✔ install completed
► configuring deploy key
✔ deploy key configured
► generating sync manifests
✔ sync manifests pushed
► applying sync manifests
◎ waiting for cluster sync
✔ bootstrap finished
If you prefer GitLab, export GITLAB_TOKEN
env var and use the command tk bootstrap gitlab.
It is safe to run the bootstrap command as many times as you want. If the toolkit components are present on the cluster, the bootstrap command will perform an upgrade if needed.
Create a GitOps workflow
Clone the repository with:
git clone https://github.com/$GITHUB_USER/fleet-infra
cd fleet-infra
Create a git source pointing to a public repository:
tk create source git webapp \
--url=https://github.com/stefanprodan/podinfo \
--branch=master \
--interval=30s \
--export > ./dev-cluster/webapp-source.yaml
Create a kustomization for synchronizing the common manifests on the cluster:
tk create kustomization webapp-common \
--source=webapp \
--path="./deploy/webapp/common" \
--prune=true \
--validate=client \
--interval=1h \
--export > ./dev-cluster/webapp-common.yaml
Create a kustomization for the backend service that depends on common:
tk create kustomization webapp-backend \
--depends-on=webapp-common \
--source=webapp \
--path="./deploy/webapp/backend" \
--prune=true \
--validate=client \
--interval=10m \
--health-check="Deployment/backend.webapp" \
--health-check-timeout=2m \
--export > ./dev-cluster/webapp-backend.yaml
Create a kustomization for the frontend service that depends on backend:
tk create kustomization webapp-frontend \
--depends-on=webapp-backend \
--source=webapp \
--path="./deploy/webapp/frontend" \
--prune=true \
--validate=client \
--interval=10m \
--health-check="Deployment/frontend.webapp" \
--health-check-timeout=2m \
--export > ./dev-cluster/webapp-frontend.yaml
Push changes to origin:
git add -A && git commit -m "add dev webapp" && git push
In about 30s the synchronization should start:
$ watch tk get kustomizations
✔ gitops-system last applied revision master/35d5765a1acb9e9ce66cad7274c6fe03eee1e8eb
✔ webapp-backend reconciling
✔ webapp-common last applied revision master/f43f9b2eb6766e07f318d266a99d2ec7c940b0cf
✗ webapp-frontend dependency 'gitops-system/webapp-backend' is not ready
When the synchronization finishes you can check that the webapp services are running:
$ kubectl -n webapp get deployments,services
NAME READY UP-TO-DATE AVAILABLE AGE
deployment.apps/backend 1/1 1 1 4m1s
deployment.apps/frontend 1/1 1 1 3m31s
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
service/backend ClusterIP 10.52.10.22 <none> 9898/TCP,9999/TCP 4m1s
service/frontend ClusterIP 10.52.9.85 <none> 80/TCP 3m31s
Production workflow
On production clusters, you may wish to deploy stable releases of an application. When creating a git source instead of a branch, you can specify a git tag or a semver expression.
Change your kubectl context to a different cluster and run the bootstrap for the production environment:
tk bootstrap github \
--owner=$GITHUB_USER \
--repository=fleet-infra \
--path=prod-cluster \
--personal
Pull the changes locally:
git pull
Create a git source using a semver range to target stable releases:
tk create source git webapp \
--url=https://github.com/stefanprodan/podinfo \
--tag-semver=">=4.0.0 <4.0.2" \
--interval=30s \
--export > ./prod-cluster/webapp-source.yaml
Create a kustomization for webapp pointing to the production overlay:
tk create kustomization webapp \
--source=webapp \
--path="./deploy/overlays/production" \
--prune=true \
--validate=client \
--interval=10m \
--health-check="Deployment/frontend.production" \
--health-check="Deployment/backend.production" \
--health-check-timeout=2m \
--export > ./prod-cluster/webapp-production.yaml
Push changes to origin:
git add -A && git commit -m "add prod webapp" && git push
List git sources:
$ tk get sources git
✔ gitops-system last fetched revision master/99072ee132abdead8b7799d7891eae2f524eb73d
✔ webapp last fetched revision 4.0.1/113360052b3153e439a0cf8de76b8e3d2a7bdf27
The kubectl equivalent is kubectl -n gitops-system get gitrepositories
.
List kustomization:
$ tk get kustomizations
✔ gitops-system last applied revision master/99072ee132abdead8b7799d7891eae2f524eb73d
✔ webapp last applied revision 4.0.1/113360052b3153e439a0cf8de76b8e3d2a7bdf27
The kubectl equivalent is kubectl -n gitops-system get kustomizations
.
If you want to upgrade to the latest 4.x version, you can change the semver expression to:
tk create source git webapp \
--url=https://github.com/stefanprodan/podinfo \
--tag-semver=">=4.0.0 <5.0.0" \
--interval=30s \
--export > ./prod-cluster/webapp-source.yaml
git add -A && git commit -m "update prod webapp" && git push
Trigger a git sync:
$ tk sync ks gitops-system --with-source
► annotating source gitops-system
✔ source annotated
◎ waiting for git sync
✔ git sync completed
✔ fetched revision master/d751ea264d48bf0db8b588d1d08184834ac8fec9
◎ waiting for kustomization sync
✔ kustomization sync completed
✔ applied revision master/d751ea264d48bf0db8b588d1d08184834ac8fec9
The kubectl equivalent is kubectl -n gitops-system annotate gitrepository/gitops-system source.fluxcd.io/syncAt="$(date +%s)"
.
Wait for the webapp to be upgraded:
$ watch tk get kustomizations
✔ gitops-system last applied revision master/d751ea264d48bf0db8b588d1d08184834ac8fec9
✔ webapp last applied revision 4.0.5/f43f9b2eb6766e07f318d266a99d2ec7c940b0cf