Update docs after last workshop

itdesign · May 12, 2019 · bf417cf · bf417cf
1 parent ce0413b
commit bf417cf
Show file tree

Hide file tree

Showing 17 changed files with 180 additions and 98 deletions.
diff --git a/Makefile b/Makefile
@@ -1,5 +1,5 @@
 
-build-and-push: backend frontend-v1 frontend-v2
+build-and-push: backend frontend-v1 frontend-v2 frontend-v3
 
 backend:
 	cd services/calculator-backend && \
@@ -16,5 +16,10 @@ frontend-v2:
 	docker build -t quay.io/kubernetes-workshop/calculator-frontend:v2 --build-arg appVersion=2 .
 	docker push quay.io/kubernetes-workshop/calculator-frontend:v2
 
+frontend-v3:
+	cd services/calculator-frontend && \
+	docker build -t quay.io/kubernetes-workshop/calculator-frontend:v3 --build-arg appVersion=3 .
+	docker push quay.io/kubernetes-workshop/calculator-frontend:v3
+
 serve-docs:
 	cd docs && docker run --rm -it --name github-pages -u `id -u`:`id -g` -v `pwd`:/usr/src/app -p 4000:4000 starefossen/github-pages jekyll serve --watch --force_polling -H 0.0.0.0 -P 4000
diff --git a/docs/_config.yml b/docs/_config.yml
@@ -4,8 +4,9 @@ description: Start with us your first kubernetes workloads!
 
 remote_theme: pmarsceill/[email protected]
 aux_links:
-    "GitHub": "https://github.com/itdesign/kubernetes-workshop"
-    "itdesign GmbH": "https://itdesign.de"
+    "Slides": "https://bit.ly/itd-k8s-slides"
+    "Source on GitHub": "https://github.com/itdesign/kubernetes-workshop"
+    "Jobs at itdesign GmbH": "https://itdesign.de/jobs"
 
 plugins:
   - jekyll-redirect-from
diff --git a/docs/_sass/custom/custom.scss b/docs/_sass/custom/custom.scss
@@ -5,18 +5,27 @@ $link-color: #a71417;
     margin: 5px;
     box-shadow: 0 1px 3px rgba(0, 0, 0, 0.07), 0 4px 14px rgba(0, 0, 0, 0.05);
   }
-  input,
-  button {
-    padding: 5px;
-    border-radius: 5px;
-    border: 1px solid #ccc;
-  }
-  button {
-    background-color: #555;
-    font-size: 0.9em;
-    color: #fff;
-  }
+
   ::placeholder {
     color: #ccc;
   }
+  .customization {
+    padding: 10px;
+    background-color: rgba(167, 20, 23, 0.5);
+    color: #fff;
+    input {
+      color: #000;
+    }
+    input,
+    button {
+      padding: 5px;
+      border-radius: 5px;
+      border: 0;
+    }
+    button {
+      background-color: #555;
+      font-size: 0.9em;
+      color: #fff;
+    }
+  }
 }
diff --git a/docs/tutorial/00-get-started/01-setup-account.md b/docs/tutorial/00-get-started/01-setup-account.md
@@ -14,8 +14,10 @@ The project in Google Cloud contains all the resources you will create during th
 1. Open the [Cloud Console](https://console.cloud.google.com)
 2. Login with your Google account used for registration
 3. Find your personal project for the workshop (`k8sworkshop-stuttgart2019-[0-9]+`)
-4. Enter your project id below, this will customize the tutorial<br>
+4. <div class="customization">
+   Enter your project id below, this will customize the tutorial:<br>
    <input id="gcloud-project-id" placeholder="k8sworkshop-stuttgart2019-22" style="width:300px"> <button id="gcloud-project-id-apply">Apply</button>
+   </div>
 
 ## Start Cloud Shell
 
@@ -35,4 +37,4 @@ We have a repository that contains examples and solutions that will help to solv
    ```
 2. You should see the repository with its directories in the upper screen:
    ![Screenshot of workspace files in cloud shell](01-workspace-files.png)
-3. The directory `kubernetes-workshop/k8s-files` contains everything we need for the workshop.
+3. The directory `kubernetes-workshop/k8s-examples` contains everything we need for the workshop.
diff --git a/docs/tutorial/00-get-started/03-access-cluster.md b/docs/tutorial/00-get-started/03-access-cluster.md
@@ -15,10 +15,13 @@ The Cloud Shell provides a proxy that allows us access to the resources in your
    ```
 2. Access your cluster using the preview functionality of Cloud Shell:
    ![Screenshot of Cloud Shell preview](03-cloud-shell-preview.png)
-3. This will open a new tab with an URL like `https://8080-dot-7136354-dot-devshell.appspot.com/path`.
-   Paste the URL **without** the path into the following field, it will customize the tutorial:<br>
-   <input id="gcloud-shell-url" placeholder="https://8080-dot-7136354-dot-devshell.appspot.com" style="width:400px"> <button id="gcloud-shell-url-apply">Apply</button><br>
-4. Test [this link]($GCLOUD_SHELL_URL/version) to verify the proxy is set up correctly. You should see a JSON response:
+3. This will open a new tab with an URL.
+4. <div class="customization">
+   Paste the URL <b>without</b> the path into the following field, it will customize the tutorial:<br>
+   Example: https://8080-dot-7136354-dot-devshell.appspot.com<br>
+   <input id="gcloud-shell-url" placeholder="https://8080-dot-7136354-dot-devshell.appspot.com" style="width:400px"> <button id="gcloud-shell-url-apply">Apply</button>
+   </div>
+5. Test [this link]($GCLOUD_SHELL_URL/version) to verify the proxy is set up correctly. You should see a JSON response:
    ```json
    {
      "major": "1",

diff --git a/docs/tutorial/01-run-the-backend/01-first-pod.md b/docs/tutorial/01-run-the-backend/01-first-pod.md
@@ -52,19 +52,20 @@ pod "calculator-backend" created
 
 ## Monitor the startup
 
-You can now monitor the startup of the pod with `kubectl get pods -w`. The flag `-w` enables the
-watch mode on every update the console is updated with the new pod state.
+You can now monitor the startup of the pod with `kubectl get pods`.
 
-You can exit the watch mode with `ctrl-c`.
+After a successful startup the output should look like this:
 
-The output can be seen as follows:
+```
+NAME                 READY     STATUS              RESTARTS  AGE
+calculator-backend   1/1       Running             0         3s
+```
+
+During the startup the console would look like this:
 
 ```
 NAME                 READY     STATUS              RESTARTS  AGE
 calculator-backend   0/1       Pending             0         0s
-calculator-backend   0/1       Pending             0         0s
-calculator-backend   0/1       ContainerCreating   0         0s
-calculator-backend   1/1       Running             0         3s
 ```
 
 ## Access the pod
@@ -85,7 +86,7 @@ To run your calculation against the API you can use the Swagger UI.
 
 1. Click on `GET /calculate`
 2. Click on `Try it out` on the right side
-3. Enter a expression into the field, e.g. `100 * sqrt(3)`
+3. Enter a valid expression into the field, e.g. `100 * sqrt(3)`
 4. Click on `Execute`
 5. The UI displays the response below:
    ![Screenshot of the response](01-api-response-success.png)
@@ -103,4 +104,4 @@ The service does not handle invalid expressions well. It crashes when an invalid
 3. Execute an invalid expression, e.g. `sqrt(Hello World)`
 4. The UI displays the error:
    ![Screenshot of the response](01-api-response-error.png)
-5. Try a valid expression, there will still be an error.
+5. Now try a valid expression, there will still be an error.
diff --git a/docs/tutorial/01-run-the-backend/03-deployment.md b/docs/tutorial/01-run-the-backend/03-deployment.md
@@ -19,12 +19,13 @@ We will change the configuration to use a deployment instead of a manually creat
 
 ## Write the deployment definition
 
-To get started copy the contents of `kubernetes-workshop/k8s-examples/deployment.yml` into your `backend.yml`.
-
-1. Under `.spec.template.spec` you'll find the similar fields like in the pod configuration, make the same changes as previously.
-2. The two new configuration items `livenessProbe` and `readinessProbe` need to configured with the correct port of your service, otherwise the health checks will fail.
-3. Ensure that the deployment has the name `calculator-backend`.
-4. Also ensure that `.template.metadata.labels.'app.kubernetes.io/name'` is set to the same value, we will need this later.
+1. Delete all contents of your `backend.yml`.
+2. Copy the contents from `kubernetes-workshop/k8s-examples/deployment.yml`.
+3. Under `.spec.template.spec` you'll find the similar fields like in the pod configuration, make the same changes as previously.
+4. The two new configuration items `livenessProbe` and `readinessProbe` need to configured with the correct port of your service, otherwise the health checks will fail.
+5. Ensure that the deployment has the name `calculator-backend`.
+6. Also ensure that `.template.metadata.labels.'app.kubernetes.io/name'` is set to the same value, we will need this later.
+7. The last required change is to set `.spec.selector.matchLabels` to the same content as the labels.
 
 ## Apply the pod definition
 

diff --git a/docs/tutorial/01-run-the-backend/04-fault-tolerance.md b/docs/tutorial/01-run-the-backend/04-fault-tolerance.md
@@ -73,10 +73,11 @@ service does only provide access to the pods that are up and running. Crashed po
    ```
 3. Use the correct selector at `.spec.selectors.'app.kubernetes.io/name'` to find the pods of your `calculator-backend`. The selector
    is used to identify the pods which should be load balanced by the service.
-4. Use the right `targetPort` so that the service can find our backend (look at `.spec.containers[].ports`).
+4. Set `.metadata.name` to `calculator-backend`.
+5. Use the right `targetPort` so that the service can find our backend (look at `.spec.containers[].ports`).
    ![Diagram of port definitions between services](04-service-ports.svg)
-5. Use `kubectl apply -f k8s-files/` to apply the changes.
-6. `kubectl get services -o wide` should now show the service:
+6. Use `kubectl apply -f k8s-files/` to apply the changes.
+7. `kubectl get services -o wide` should now show the service:
    ```
    NAME                 TYPE        CLUSTER-IP     EXTERNAL-IP   PORT(S)   AGE       SELECTOR
    calculator-backend   ClusterIP   10.110.74.55   <none>        80/TCP    11m       app=calculator-backend

diff --git a/docs/tutorial/02-add-the-frontend/02-public-access.md b/docs/tutorial/02-add-the-frontend/02-public-access.md
@@ -12,7 +12,7 @@ We will now expose the frontend to the public internet.
 
 ## Change the configuration
 
-1. Edit the `frontend.yml` and change the type from `ClusterIP` to `LoadBalancer`.
+1. Edit the `frontend.yml` and set the service to `LoadBalancer`. You need to have a look into the [API documentation](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.11/#servicespec-v1-core) of Kubernetes.
 2. Apply the configuration: `kubectl apply -f k8s-files/`.
 3. Watch for the service to update: `kubectl get svc -w`
 4. The service changed the type to `LoadBalancer` and external-ip changed into the state `<pending>`, we will now wait until an IP is assigned.
@@ -23,8 +23,10 @@ We will now expose the frontend to the public internet.
    calculator-frontend   LoadBalancer   10.3.248.49    <pending>       80:31311/TCP   3s
    calculator-frontend   LoadBalancer   10.3.248.49    35.246.160.32   80:31311/TCP   1m
    ```
+   <div class="customization">
    Enter the external IP of your service, this will customize the tutorial:<br>
    <input id="gcloud-public-ip" placeholder="35.246.160.32" style="width:400px"> <button id="gcloud-public-ip-apply">Apply</button>
+   </div>
 6. You can now access your frontend using [`http://$GCLOUD_PUBLIC_IP/`](http://$GCLOUD_PUBLIC_IP/).
 
 The following chapter will give you more details about the network architecture in the background.
diff --git a/docs/tutorial/02-add-the-frontend/04-rolling-update.md b/docs/tutorial/02-add-the-frontend/04-rolling-update.md
@@ -21,40 +21,7 @@ It provides some new features we will look into later.
 
 1. Change the docker image tag in your `frontend.yml` from `v1` to `v2`.
 2. Apply the changes `kubectl apply -f k8s-files/`
-3. Watch for the rolling update: `kubectl get pods -w`
-   ```
-   NAME                                   READY     STATUS              AGE
-   calculator-frontend-6b5d85558c-4mh2s   1/1       Running             1h
-   calculator-frontend-6b5d85558c-9nzh2   1/1       Running             1h
-   calculator-frontend-6b5d85558c-msppb   1/1       Running             1h
-   calculator-frontend-d69f59b46-fvp54    0/1       Pending             0s
-   calculator-frontend-d69f59b46-fvp54    0/1       Pending             1s
-   calculator-frontend-d69f59b46-fvp54    0/1       ContainerCreating   1s
-   calculator-frontend-d69f59b46-fvp54    0/1       Running             5s
-   calculator-frontend-d69f59b46-fvp54    1/1       Running             8s
-   calculator-frontend-6b5d85558c-msppb   1/1       Terminating         1h
-   calculator-frontend-d69f59b46-mfmpm    0/1       Pending             0s
-   calculator-frontend-d69f59b46-mfmpm    0/1       Pending             0s
-   calculator-frontend-d69f59b46-mfmpm    0/1       ContainerCreating   0s
-   calculator-frontend-6b5d85558c-msppb   0/1       Terminating         1h
-   calculator-frontend-d69f59b46-mfmpm    0/1       Running             4s
-   calculator-frontend-6b5d85558c-msppb   0/1       Terminating         1h
-   calculator-frontend-6b5d85558c-msppb   0/1       Terminating         1h
-   calculator-frontend-d69f59b46-mfmpm    1/1       Running             8s
-   calculator-frontend-6b5d85558c-9nzh2   1/1       Terminating         1h
-   calculator-frontend-d69f59b46-v2vgv    0/1       Pending             0s
-   calculator-frontend-d69f59b46-v2vgv    0/1       Pending             0s
-   calculator-frontend-d69f59b46-v2vgv    0/1       ContainerCreating   0s
-   calculator-frontend-6b5d85558c-9nzh2   0/1       Terminating         1h
-   calculator-frontend-d69f59b46-v2vgv    0/1       Running             3s
-   calculator-frontend-6b5d85558c-9nzh2   0/1       Terminating         1h
-   calculator-frontend-6b5d85558c-9nzh2   0/1       Terminating         1h
-   calculator-frontend-d69f59b46-v2vgv    1/1       Running             11s
-   calculator-frontend-6b5d85558c-4mh2s   1/1       Terminating         1h
-   ```
-4. The old configuration is `-6b5d85558c-`. Each pod of the old configuration is terminated after a pod of the new configuration `-d69f59b46-` is running and ready `1/1`.
-5. You can change the configuration back to `v1` and apply the changes.
-6. With `kubectl rollout status deployment calculator-frontend` will see this output:
+3. With `kubectl rollout status deployment calculator-frontend` will see this output:
    ```
    Waiting for deployment "calculator-frontend" rollout to finish: 1 out of 3 new replicas have been updated...
    Waiting for deployment "calculator-frontend" rollout to finish: 1 out of 3 new replicas have been updated...
@@ -66,25 +33,4 @@ It provides some new features we will look into later.
    Waiting for deployment "calculator-frontend" rollout to finish: 1 old replicas are pending termination...
    deployment "calculator-frontend" successfully rolled out
    ```
-7. Now, one last rolling update. Change the frontend deployment again to `v2` and apply the changes.
-8. Continuously refresh the page after applying the changes.
-9. The page will be served with different layouts, this is because sometimes a pod of the old configuration
-   and sometimes a pod of the new configuration answers your request.
-10. After some time only the new layout should be returned.
-
-## We did it! 🎉
-
-You are now able to do the following things using Kubernetes:
-
-- Deploy an application
-- Inspect your application when something goes wrong
-- Configure multiple replicas for fault tolerance
-- Create a service for load balancing
-- Expose an application to the public internet
-- Update applications without any downtime
-
-### Want to learn more?
-
-Have a look at the new version of the frontend. It looks like history does not work correctly. 😉
-
-We need to fix this! Try the [bonus chapters](../03-bonus.md).
+4. When the command is completed you should now [see the updated version](http://$GCLOUD_PUBLIC_IP) of the calculator.
diff --git a/docs/tutorial/02-add-the-frontend/05-rollback.md b/docs/tutorial/02-add-the-frontend/05-rollback.md
@@ -0,0 +1,19 @@
+---
+title: Rollback Changes
+parent: Add the Frontend
+---
+
+# Rollback Changes
+
+Sometimes a deploy has unexpected results. In this case we deployed a developer preview.
+This is not what we want in production. So lets rollback our changes.
+
+1. Run `kubectl rollout undo deployment calculator-frontend` to revert the latest changes.
+2. Continuously refresh the page after applying the changes.
+3. The page will be served with different layouts. This is because sometimes a pod with
+   `v3` and sometimes a pod with `v1` answers your request.
+4. After some time only `v1` of the calculator frontend should be visible.
+5. You can verify this by running `kubectl rollout status deployment calculator-frontend`:
+   ```
+   deployment "calculator-frontend" successfully rolled out
+   ```
diff --git a/docs/tutorial/02-add-the-frontend/06-end.md b/docs/tutorial/02-add-the-frontend/06-end.md
@@ -0,0 +1,66 @@
+---
+title: Last Steps
+parent: Add the Frontend
+---
+
+# Last Steps
+
+We are nearing the end, but lets deploy a version that is ready to be served in our cluster. `v2` this should be safe to deploy.
+
+## Deploy a stable version
+
+1. Change the image in the `fronted.yml` to `v2`.
+2. Apply the changes and watch for pod changes:
+   ```
+   kubectl apply -f k8s-files/ && kubectl get pods -w
+   ```
+3. You should now see the new pods starting and the old pods shuting down:
+   ```
+   NAME                                   READY     STATUS              RESTARTS   AGE
+   calculator-frontend-58968fd9b8-22np7   0/1       ContainerCreating   0          1s
+   calculator-frontend-65876567ff-68p8s   1/1       Running             0          2m
+   calculator-frontend-65876567ff-rvpvb   1/1       Running             0          34s
+   calculator-frontend-65876567ff-wj62x   1/1       Running             0          46s
+   calculator-frontend-58968fd9b8-22np7   0/1       Running             0          4s
+   calculator-frontend-58968fd9b8-22np7   1/1       Running             0          6s
+   calculator-frontend-65876567ff-rvpvb   1/1       Terminating         0          39s
+   calculator-frontend-58968fd9b8-sfmhv   0/1       Pending             0          0s
+   calculator-frontend-58968fd9b8-sfmhv   0/1       Pending             0          0s
+   calculator-frontend-58968fd9b8-sfmhv   0/1       ContainerCreating   0          0s
+   calculator-frontend-65876567ff-rvpvb   0/1       Terminating         0          40s
+   calculator-frontend-58968fd9b8-sfmhv   0/1       Running             0          5s
+   calculator-frontend-65876567ff-rvpvb   0/1       Terminating         0          44s
+   calculator-frontend-65876567ff-rvpvb   0/1       Terminating         0          44s
+   calculator-frontend-58968fd9b8-sfmhv   1/1       Running             0          9s
+   calculator-frontend-65876567ff-wj62x   1/1       Terminating         0          1m
+   calculator-frontend-58968fd9b8-w48gr   0/1       Pending             0          0s
+   calculator-frontend-58968fd9b8-w48gr   0/1       Pending             0          0s
+   calculator-frontend-58968fd9b8-w48gr   0/1       ContainerCreating   0          0s
+   calculator-frontend-65876567ff-wj62x   0/1       Terminating         0          1m
+   calculator-frontend-58968fd9b8-w48gr   0/1       Running             0          5s
+   calculator-frontend-65876567ff-wj62x   0/1       Terminating         0          1m
+   calculator-frontend-65876567ff-wj62x   0/1       Terminating         0          1m
+   calculator-frontend-58968fd9b8-w48gr   1/1       Running             0          8s
+   calculator-frontend-65876567ff-68p8s   1/1       Terminating         0          2m
+   calculator-frontend-65876567ff-68p8s   0/1       Terminating         0          2m
+   calculator-frontend-65876567ff-68p8s   0/1       Terminating         0          3m
+   calculator-frontend-65876567ff-68p8s   0/1       Terminating         0          3m
+   ```
+4. The app should now be served in `v2`.
+
+## We did it! 🎉
+
+You are now able to do the following things using Kubernetes:
+
+- Deploy an application
+- Inspect your application when something goes wrong
+- Configure multiple replicas for fault tolerance
+- Create a service for load balancing
+- Expose an application to the public internet
+- Update applications without any downtime
+
+### Want to learn more?
+
+Have a look at the new version of the frontend. It looks like history does not work correctly. 😉
+
+We need to fix this! Try the [bonus chapters](../03-bonus.md).
diff --git a/k8s-examples/service.yml b/k8s-examples/service.yml
@@ -3,7 +3,6 @@ apiVersion: v1
 metadata:
   name: nginx-proxy
 spec:
-  type: ClusterIP
   ports:
   - port: 80
     targetPort: 80

diff --git a/services/calculator-frontend/src/react/components/BetaOverlay.tsx b/services/calculator-frontend/src/react/components/BetaOverlay.tsx
@@ -0,0 +1,20 @@
+import React from 'react';
+
+export const BetaOverlay: React.FunctionComponent<{}> = () => (
+  <div
+    style={{
+      position: 'absolute',
+      left: '50%',
+      top: '85px',
+      marginLeft: '50px',
+      transform: 'rotate(40deg)',
+      backgroundColor: '#fff',
+      fontSize: '40px',
+      fontWeight: 'bold',
+      color: '#f00',
+      zIndex: 100
+    }}
+  >
+    developer preview
+  </div>
+);