Add workflow overview to get started guide

5 years ago · 041b475f49
parent c0a8604f90
commit 041b475f49
1 changed files with 57 additions and 35 deletions
--- 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
 ```
-