Add workflow overview to get started guide

docs/get-started/index.md

@@ -2,11 +2,7 @@
 
 ## Prerequisites
 
-* Kubernetes >= 1.14
+You will need a Kubernetes cluster version 1.14 or newer and kubectl version 1.18.
-* 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.
 
@@ -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 
+Run the bootstrap command:
-
-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.
 
 ```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.
+!!! hint
-If the toolkit components are present on the cluster,
+    It is safe to run the bootstrap command as many times as you want.
-the bootstrap command will perform an upgrade if needed.
+    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
 ```
-