From c0a8604f901bcb34884f526b27e0eb46cefe60ed Mon Sep 17 00:00:00 2001 From: stefanprodan Date: Fri, 19 Jun 2020 20:15:00 +0300 Subject: [PATCH 1/3] Add production workflow to docs --- docs/get-started/index.md | 114 +++++++++++++++++++++++++++++++++++++- 1 file changed, 113 insertions(+), 1 deletion(-) diff --git a/docs/get-started/index.md b/docs/get-started/index.md index cc2dd461..8704f043 100644 --- a/docs/get-started/index.md +++ b/docs/get-started/index.md @@ -186,7 +186,7 @@ tk create kustomization webapp-frontend \ Push changes to origin: ```sh -git add -A && git commit -m "add webapp" && git push +git add -A && git commit -m "add dev webapp" && git push ``` In about 30s the synchronization should start: @@ -214,3 +214,115 @@ service/backend ClusterIP 10.52.10.22 9898/TCP,9999/TCP 4 service/frontend ClusterIP 10.52.9.85 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: + +```sh +tk bootstrap github \ + --owner=$GITHUB_USER \ + --repository=fleet-infra \ + --path=prod-cluster \ + --personal +``` + +Pull the changes locally: + +```sh +git pull +``` + +Create a git source using a semver range to target stable releases: + +```sh +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: + +```sh +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: + +```sh +git add -A && git commit -m "add prod webapp" && git push +``` + +List git sources: + +```text +$ 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: + +```text +$ 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: + +```sh +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: + +```text +$ 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: + +```text +$ watch tk get kustomizations + +✔ gitops-system last applied revision master/d751ea264d48bf0db8b588d1d08184834ac8fec9 +✔ webapp last applied revision 4.0.5/f43f9b2eb6766e07f318d266a99d2ec7c940b0cf +``` + From 041b475f49b57e58abe3c6421303193db087aebf Mon Sep 17 00:00:00 2001 From: stefanprodan Date: Mon, 22 Jun 2020 10:02:17 +0300 Subject: [PATCH 2/3] Add workflow overview to get started guide --- docs/get-started/index.md | 92 ++++++++++++++++++++++++--------------- 1 file changed, 57 insertions(+), 35 deletions(-) diff --git a/docs/get-started/index.md b/docs/get-started/index.md index 8704f043..60fec415 100644 --- a/docs/get-started/index.md +++ b/docs/get-started/index.md @@ -2,11 +2,7 @@ ## Prerequisites -* Kubernetes >= 1.14 -* kubectl >= 1.18 -* git - -You will need to have Kubernetes set up. +You will need a Kubernetes cluster version 1.14 or newer and kubectl version 1.18. For a quick local test, you can use `minikube`, `kubeadm` or `kind`. Any other Kubernetes setup will work as well though. @@ -14,6 +10,13 @@ In order to follow the guide you'll need a GitHub account and a [personal access token](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line) that can create repositories. +Export your GitHub personal access token and username: + +```sh +export GITHUB_TOKEN= +export GITHUB_USER= +``` + ## Install the toolkit CLI To install the latest `tk` release run: @@ -33,7 +36,20 @@ To configure your shell to load tk completions add to your bash profile: . <(tk completion) ``` -Verify that your cluster satisfies the prerequisites with: +## GitOps workflow + +You'll be using a dedicated Git repository e.g. `fleet-infra` to manage one or more Kubernetes clusters. +This guide assumes that you have two clusters, one for staging and one for production. + +Using the toolkit CLI you'll do the following: + +- configure each cluster to synchronise with a directory inside the fleet repository +- register app sources (git repositories) that contain plain Kubernetes manifests or Kustomize overlays +- configure app deployments on both clusters (pre-releases on staging, semver releases on production) + +## Staging bootstrap + +Verify that your staging cluster satisfies the prerequisites with: ```text $ tk check --pre @@ -44,29 +60,20 @@ $ tk check --pre ✔ 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: - -```sh -export GITHUB_TOKEN= -export GITHUB_USER= -``` - -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. +Run the bootstrap command: ```sh tk bootstrap github \ --owner=$GITHUB_USER \ --repository=fleet-infra \ - --path=dev-cluster \ + --path=staging-cluster \ --personal ``` +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. + If you wish to create the repository under a GitHub organization: ```sh @@ -75,13 +82,13 @@ tk bootstrap github \ --repository= \ --team= \ --team= \ - --path=dev-cluster + --path=staging-cluster ``` Example output: ```text -$ tk bootstrap github --owner=gitopsrun --repository=fleet-infra --path=dev-cluster --team=devs +$ tk bootstrap github --owner=gitopsrun --repository=fleet-infra --path=staging-cluster --team=devs ► connecting to github.com ✔ repository created @@ -118,11 +125,12 @@ deployment "kustomize-controller" successfully rolled out If you prefer GitLab, export `GITLAB_TOKEN` env var and use the command [tk bootstrap gitlab](../cmd/tk_bootstrap_gitlab.md). -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. +!!! hint + 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 +## Staging workflow Clone the repository with: @@ -131,14 +139,14 @@ git clone https://github.com/$GITHUB_USER/fleet-infra cd fleet-infra ``` -Create a git source pointing to a public repository: +Create a git source pointing to a public repository master branch: ```sh tk create source git webapp \ --url=https://github.com/stefanprodan/podinfo \ --branch=master \ --interval=30s \ - --export > ./dev-cluster/webapp-source.yaml + --export > ./staging-cluster/webapp-source.yaml ``` Create a kustomization for synchronizing the common manifests on the cluster: @@ -150,7 +158,7 @@ tk create kustomization webapp-common \ --prune=true \ --validate=client \ --interval=1h \ - --export > ./dev-cluster/webapp-common.yaml + --export > ./staging-cluster/webapp-common.yaml ``` Create a kustomization for the backend service that depends on common: @@ -165,7 +173,7 @@ tk create kustomization webapp-backend \ --interval=10m \ --health-check="Deployment/backend.webapp" \ --health-check-timeout=2m \ - --export > ./dev-cluster/webapp-backend.yaml + --export > ./staging-cluster/webapp-backend.yaml ``` Create a kustomization for the frontend service that depends on backend: @@ -180,13 +188,13 @@ tk create kustomization webapp-frontend \ --interval=10m \ --health-check="Deployment/frontend.webapp" \ --health-check-timeout=2m \ - --export > ./dev-cluster/webapp-frontend.yaml + --export > ./staging-cluster/webapp-frontend.yaml ``` Push changes to origin: ```sh -git add -A && git commit -m "add dev webapp" && git push +git add -A && git commit -m "add staging webapp" && git push ``` In about 30s the synchronization should start: @@ -214,7 +222,20 @@ service/backend ClusterIP 10.52.10.22 9898/TCP,9999/TCP 4 service/frontend ClusterIP 10.52.9.85 80/TCP 3m31s ``` -## Production workflow +!!! note + From this moment forward, any changes made to the webapp + master branch will be synchronised with the cluster. + +If a Kubernetes manifest is removed from source, the reconclier will remove it from your cluster. If you +delete a kustomization from the fleet infra repo, the reconciler will remove all Kubernetes objects that +were previously applied from that kustomization. + +If you alter the webapp deployment using `kubectl edit`, the changes will be reverted to match +the state described in git. When dealing with an incident, you can pause the recitation of a +kustomization with `tk suspend kustomization `. Once the debugging session +is over, you can re-enable the reconciliation with `tk resume kustomization `. + +## Production bootstrap 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. @@ -235,6 +256,8 @@ Pull the changes locally: git pull ``` +## Production workflow + Create a git source using a semver range to target stable releases: ```sh @@ -325,4 +348,3 @@ $ watch tk get kustomizations ✔ gitops-system last applied revision master/d751ea264d48bf0db8b588d1d08184834ac8fec9 ✔ webapp last applied revision 4.0.5/f43f9b2eb6766e07f318d266a99d2ec7c940b0cf ``` - From da95b7559d1b0d47ef9c24c0f9f44bff845ed7be Mon Sep 17 00:00:00 2001 From: stefanprodan Date: Mon, 22 Jun 2020 13:13:30 +0300 Subject: [PATCH 3/3] Add cluster creation commands to docs --- docs/get-started/index.md | 36 ++++++++++++++++++++++++++---------- 1 file changed, 26 insertions(+), 10 deletions(-) diff --git a/docs/get-started/index.md b/docs/get-started/index.md index 60fec415..57692d69 100644 --- a/docs/get-started/index.md +++ b/docs/get-started/index.md @@ -2,13 +2,13 @@ ## Prerequisites -You will need a Kubernetes cluster version 1.14 or newer and kubectl version 1.18. -For a quick local test, you can use `minikube`, `kubeadm` or `kind`. +You will need two Kubernetes clusters version 1.14 or newer and kubectl version 1.18. +For a quick local test, you can use [Kubernetes kind](https://kind.sigs.k8s.io/docs/user/quick-start/). 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](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line) -that can create repositories. +that can create repositories (check all permissions under `repo`). Export your GitHub personal access token and username: @@ -49,6 +49,13 @@ Using the toolkit CLI you'll do the following: ## Staging bootstrap +Create the staging cluster using Kubernetes kind or set the kubectl context to an existing cluster: + +```sh +kind create cluster --name staging +kubectl cluster-info --context kind-staging +``` + Verify that your staging cluster satisfies the prerequisites with: ```text @@ -56,7 +63,7 @@ $ tk check --pre ► checking prerequisites ✔ kubectl 1.18.3 >=1.18.0 -✔ kubernetes 1.16.8-eks-e16311 >=1.14.0 +✔ kubernetes 1.18.2 >=1.14.0 ✔ prerequisites checks passed ``` @@ -125,10 +132,12 @@ deployment "kustomize-controller" successfully rolled out If you prefer GitLab, export `GITLAB_TOKEN` env var and use the command [tk bootstrap gitlab](../cmd/tk_bootstrap_gitlab.md). -!!! hint +!!! hint "Idempotency" 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. + You can target a specific toolkit [version](https://github.com/fluxcd/toolkit/releases) + with `tk bootstrap --version=`. ## Staging workflow @@ -222,12 +231,12 @@ service/backend ClusterIP 10.52.10.22 9898/TCP,9999/TCP 4 service/frontend ClusterIP 10.52.9.85 80/TCP 3m31s ``` -!!! note +!!! tip From this moment forward, any changes made to the webapp - master branch will be synchronised with the cluster. + Kubernetes manifests in the master branch will be synchronised with the staging cluster. -If a Kubernetes manifest is removed from source, the reconclier will remove it from your cluster. If you -delete a kustomization from the fleet infra repo, the reconciler will remove all Kubernetes objects that +If a Kubernetes manifest is removed from the webapp repository, the reconciler will remove it from your cluster. +If you delete a kustomization from the `fleet-infra` repo, the reconciler will remove all Kubernetes objects that were previously applied from that kustomization. If you alter the webapp deployment using `kubectl edit`, the changes will be reverted to match @@ -240,7 +249,14 @@ is over, you can re-enable the reconciliation with `tk resume kustomization