diff --git a/docs/get-started/index.md b/docs/get-started/index.md index 8704f0436a95c7aa457d18679ca1a5d9942781b7..60fec4154cddd4b6276e7cd408c9c410b3242b88 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=<your-token> +export GITHUB_USER=<your-username> +``` + ## 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=<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. +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=<repo-name> \ --team=<team1-slug> \ --team=<team2-slug> \ - --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 <none> 9898/TCP,9999/TCP 4 service/frontend ClusterIP 10.52.9.85 <none> 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 <name>`. Once the debugging session +is over, you can re-enable the reconciliation with `tk resume kustomization <name>`. + +## 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 ``` -