adding katacoda tutorials (knative#3142)

* adding katacoda scenarios

katacoda scenarios let people try out Knative without installing
anything on their local machines. The goal is add a number of basic as
well as advanced scenarios that would serve as a guided tutorial for
knative. We start off by adding a serving-intro tutorial

* move up the scenario

* fixing the repo structure to enable multiple scenarios

* upgrading to knative 0.19.0

* adding yaml getting started tutorial

* don't install kn cli for yaml tutorial

* fix revision name

* fix curl command for yaml demo

* check status of the service

* update the title

* adding eventing intro scenario

* fix indent for katacoda markdown

* fix more markdown

* polish

* fix api version

* fix typos

* add a step for sequence

* add broker tutorial

* polish

* adding pathway file

* add order to tutorials

* incorporate feedback

* more feedback

* Apply suggestions from code review

Co-authored-by: Mike Petersen <[email protected]>

* remove hardcoded version

* adding missing newlines

* fixing trailing whitespace

* more trailing whitespace

* Apply suggestions from code review

Co-authored-by: Mike Petersen <[email protected]>

* reformat sentence

* review feedback

Co-authored-by: Carlos Santana <[email protected]>

* review feedback

dark revision, full migration to green

* quote around T2 does not work

* update apiversion

* cosmetic fixes

* bump timeout to 90 seconds

* blue to green for yaml

Co-authored-by: Mike Petersen <[email protected]>
Co-authored-by: Carlos Santana <[email protected]>

katacoda.yaml

@@ -0,0 +1 @@
+scenario_root : tutorials/katacoda

tutorials/katacoda/1-serving-intro/index.json

@@ -0,0 +1,35 @@
+{
+  "title": "Getting Started with Knative Serving (kn cli)",
+  "description": "Introduction to Knative by installing knative serving and deploying an application (If you want to script your workflow, or really don't like yaml)",
+  "difficulty": "Beginner",
+  "time": "20",
+  "details": {
+    "steps": [
+      {
+        "title": "Step 1",
+        "text": "step1.md"
+      },
+      {
+        "title": "Step 2",
+        "text": "step2.md"
+      },
+      {
+        "title": "Step 3",
+        "text": "step3.md"
+      }
+    ],
+    "intro": {
+      "code": "scripts/install-dependencies.sh",
+      "text": "intro.md"
+    },
+    "finish": {
+      "text": "finish.md"
+    }
+  },
+  "environment": {
+    "uilayout": "terminal"
+  },
+  "backend": {
+    "imageid": "minikube-running"
+  }
+}

tutorials/katacoda/1-serving-intro/intro.md

@@ -0,0 +1,7 @@
+## What is Knative?
+Knative brings the "serverless" experience to kubernetes. It also tries to codify common patterns and best practices for running applications while hiding the complexity of doing so on kubernetes. It does so by providing two components:
+- Eventing - Management and delivery of events
+- Serving - Request-driven compute that can scale to zero
+
+## What will we learn in this tutorial?
+This tutorial will serve as an introduction to Knative. Here we will install Knative (Serving only), deploy an application, watch Knative's "scale down to zero" feature then deploy a second version of the application and watch traffic split between the two versions.

tutorials/katacoda/1-serving-intro/scripts/install-dependencies.sh

@@ -0,0 +1,12 @@
+echo "Installing kn cli..."
+wget https://storage.googleapis.com/knative-nightly/client/latest/kn-linux-amd64 -O kn
+chmod +x kn
+mv kn /usr/local/bin/
+echo "Done"
+
+echo "Waiting for Kubernetes to start. This may take a few moments, please wait..."
+while [ `minikube status &>/dev/null; echo $?` -ne 0 ]; do sleep 1; done
+echo "Kubernetes Started"
+
+export latest_version=$(curl -H "Accept: application/vnd.github.v3+json" https://api.github.com/repos/knative/serving/tags?per_page=1 | jq -r .[0].name)
+echo "Latest knative version is: ${latest_version}"

tutorials/katacoda/1-serving-intro/step1.md

@@ -0,0 +1,20 @@
+## Installation
+> The startup script running on the right will install the `kn` cli and wait for kubernetes to start. Once you see a prompt, you can click on the commands below at your own pace, and they will be copied and run for you in the terminal on the right.
+
+1. Install Knative Serving's core components
+    ```
+    kubectl apply --filename https://github.com/knative/serving/releases/download/${latest_version}/serving-crds.yaml
+    kubectl apply --filename https://github.com/knative/serving/releases/download/${latest_version}/serving-core.yaml
+    ```{{execute}}
+1. Install contour as the networking layer. (Knative also supports Courier, Gloo, Istio and Kourier as options)
+    ```
+    kubectl apply --filename https://github.com/knative/net-contour/releases/download/${latest_version}/contour.yaml
+    kubectl apply --filename https://github.com/knative/net-contour/releases/download/${latest_version}/net-contour.yaml
+    ```{{execute}}
+1. Configure Knative Serving to use Contour by default
+    ```
+    kubectl patch configmap/config-network \
+      --namespace knative-serving \
+      --type merge \
+      --patch '{"data":{"ingress.class":"contour.ingress.networking.knative.dev"}}'
+    ```{{execute}}

tutorials/katacoda/1-serving-intro/step2.md

@@ -0,0 +1,26 @@
+## Deploy and autoscale application
+
+We are going to deploy the [Hello world sample web application](https://knative.dev/docs/serving/samples/hello-world/helloworld-go/). This basic web application reads in an env variable TARGET and prints `Hello ${TARGET}!`. If TARGET is not specified, it will use `World` as the TARGET.
+
+We will now deploy the application by specifying the image location and the `TARGET` env variable set to `blue`.
+
+Knative defines a `service.serving.knative.dev` CRD to control the lifecycle of the application (not to be confused with kubernetes service). We will use the `kn` cli to create the Knative service: (This may take up to a minute)
+
+```
+kn service create demo --image gcr.io/knative-samples/helloworld-go --env TARGET=blue --autoscale-window 15s
+```{{execute}}
+
+We can now invoke the application using `curl`. We first need to figure out the IP address of minikube and the ingress port.
+```
+MINIKUBE_IP=$(minikube ip)
+INGRESS_PORT=$(kubectl get svc envoy --namespace contour-external --output 'jsonpath={.spec.ports[?(@.port==80)].nodePort}')
+```{{execute}}
+Then invoke the application using curl:
+```
+curl http://$MINIKUBE_IP:$INGRESS_PORT/ -H 'Host: demo.default.example.com'
+```{{execute T1}}
+
+### Scale down to zero
+You can run `watch kubectl get pods`{{execute T2}} (may need two clicks) in a new Terminal tab to see a pod created to serve the requests. Knative will scale this pod down to zero if there are no incoming requests, we have configured this window to be 15 seconds above.
+
+You can wait for the pods to scale down to zero and then issue the above `curl` again to see the pod spin up and serve the request.

tutorials/katacoda/1-serving-intro/step3.md

@@ -0,0 +1,47 @@
+## Blue/Green deploy
+The Knative `service` resource creates additional resources "route, configuration and revision" to manage the lifecycle of the application.
+- revision: just like a git revision, any change to the Service's `spec.template` results in a new revision
+- route: control traffic to several revisions
+
+You can list those resources by running `kubectl get ksvc,configuration,route,revision` or by using the `kn` cli
+
+We will now update the service to change the `TARGET` env variable to `green`.
+
+But, before we do that, let us update the revision name to "hello-v1", so that we can direct traffic to it.
+```
+kn service update demo --revision-name="demo-v1"```{{execute T1}}
+
+Now, let's update the env variable to `green`, but let's do it as a dark launch i.e. zero traffic will go to this new revision:
+```
+kn service update demo --env TARGET=green --revision-name="demo-v2" --traffic demo-v1=100,demo-v2=0
+```{{execute T1}}
+
+This will result in a new `revision` being created. Verify this by running `kn revision list`{{execute T1}}.
+
+All these revisions are capable of serving requests. Let's tag the `green` revision, so as to get a custom hostname to be able to access the revision.
+```
+kn service update demo --tag demo-v2=v2
+```{{execute T1}}
+
+You can now test the `green` revision like so: (This hostname can  be listed with `kn route describe demo` command).
+```
+curl http://$MINIKUBE_IP:$INGRESS_PORT/ -H 'Host: v2-demo.default.example.com'
+```{{execute T1}}
+
+We now need to split our traffic between the two revisions.
+```
+kn service update demo --traffic demo-v1=50,@latest=50
+```{{execute T1}}
+Then proceed by issuing the curl command multiple times to see that the traffic is split between the two revisions.
+```
+curl http://$MINIKUBE_IP:$INGRESS_PORT/ -H 'Host: demo.default.example.com'
+```{{execute T1}}
+
+We can now make all traffic go to the `green` revision:
+```
+kn service update demo --traffic @latest=100
+```{{execute T1}}
+Then proceed by issuing the curl command multiple times to see that all traffic is routed to `green` revision.
+```
+curl http://$MINIKUBE_IP:$INGRESS_PORT/ -H 'Host: demo.default.example.com'
+```{{execute T1}}

tutorials/katacoda/2-serving-intro-yaml/index.json

@@ -0,0 +1,35 @@
+{
+  "title": "Getting Started with Knative Serving (yaml)",
+  "description": "Introduction to Knative by installing knative serving and deploy an application",
+  "difficulty": "Beginner",
+  "time": "20",
+  "details": {
+    "steps": [
+      {
+        "title": "Step 1",
+        "text": "step1.md"
+      },
+      {
+        "title": "Step 2",
+        "text": "step2.md"
+      },
+      {
+        "title": "Step 3",
+        "text": "step3.md"
+      }
+    ],
+    "intro": {
+      "code": "scripts/install-dependencies.sh",
+      "text": "intro.md"
+    },
+    "finish": {
+      "text": "finish.md"
+    }
+  },
+  "environment": {
+    "uilayout": "terminal"
+  },
+  "backend": {
+    "imageid": "minikube-running"
+  }
+}

tutorials/katacoda/2-serving-intro-yaml/intro.md

@@ -0,0 +1,7 @@
+## What is Knative?
+Knative brings the "serverless" experience to kubernetes. It also tries to codify common patterns and best practices for running applications while hiding the complexity of doing so on kubernetes. It does so by providing two components:
+- Eventing - Management and delivery of events
+- Serving - Request-driven compute that can scale to zero
+
+## What will we learn in this tutorial?
+This tutorial will serve as an introduction to Knative. Here we will install Knative (Serving only), deploy an application, watch Knative's "scale down to zero" feature then deploy a second version of the application and watch traffic split between the two versions.

tutorials/katacoda/2-serving-intro-yaml/scripts/install-dependencies.sh

@@ -0,0 +1,6 @@
+echo "Waiting for Kubernetes to start. This may take a few moments, please wait..."
+while [ `minikube status &>/dev/null; echo $?` -ne 0 ]; do sleep 1; done
+echo "Kubernetes Started"
+
+export latest_version=$(curl -H "Accept: application/vnd.github.v3+json" https://api.github.com/repos/knative/serving/tags?per_page=1 | jq -r .[0].name)
+echo "Latest knative version is: ${latest_version}"

tutorials/katacoda/2-serving-intro-yaml/step1.md

@@ -0,0 +1,20 @@
+## Installation
+> The startup script running on the right will wait for kubernetes to start. Once you see a prompt, you can click on the commands below at your own pace, and they will be copied and run for you in the terminal on the right.
+
+1. Install Knative Serving's core components
+    ```
+    kubectl apply --filename https://github.com/knative/serving/releases/download/${latest_version}/serving-crds.yaml
+    kubectl apply --filename https://github.com/knative/serving/releases/download/${latest_version}/serving-core.yaml
+    ```{{execute}}
+1. Install contour as the networking layer. (Knative also supports Courier, Gloo, Istio and Kourier as options)
+    ```
+    kubectl apply --filename https://github.com/knative/net-contour/releases/download/${latest_version}/contour.yaml
+    kubectl apply --filename https://github.com/knative/net-contour/releases/download/${latest_version}/net-contour.yaml
+    ```{{execute}}
+1. Configure Knative Serving to use Contour by default
+    ```
+    kubectl patch configmap/config-network \
+      --namespace knative-serving \
+      --type merge \
+      --patch '{"data":{"ingress.class":"contour.ingress.networking.knative.dev"}}'
+    ```{{execute}}

tutorials/katacoda/2-serving-intro-yaml/step2.md

@@ -0,0 +1,43 @@
+## Deploy and autoscale application
+
+We are going to deploy the [Hello world sample application](https://knative.dev/docs/serving/samples/hello-world/helloworld-go/). This application reads in an env variable TARGET and prints `Hello ${TARGET}!`. If TARGET is not specified, it will use `World` as the TARGET.
+
+We will now deploy the application by specifying the image location and the `TARGET` env variable.
+
+Knative defines a `service.serving.knative.dev` CRD to control the lifecycle of the application (not to be confused with kubernetes service). We will create the Knative service using the yaml below:
+
+```
+cat <<EOF | kubectl apply -f -
+apiVersion: serving.knative.dev/v1
+kind: Service
+metadata:
+  name: helloworld-go
+spec:
+  template:
+    metadata:
+      name: helloworld-go-blue
+    spec:
+      containers:
+      - env:
+        - name: TARGET
+          value: blue
+        image: gcr.io/knative-samples/helloworld-go
+
+EOF
+```{{execute}}
+Check the status of the service by running `watch kubectl get ksvc`{{execute T2}}. When `READY` becomes `True` the service is ready to serve traffic.
+
+We can now invoke the application using `curl`. We first need to figure out the IP address of minikube and ingress port.
+```
+MINIKUBE_IP=$(minikube ip)
+INGRESS_PORT=$(kubectl get svc envoy --namespace contour-external --output 'jsonpath={.spec.ports[?(@.port==80)].nodePort}')
+```{{execute}}
+Then invoke the application using curl:
+```
+curl http://$MINIKUBE_IP:$INGRESS_PORT/ -H 'Host: helloworld-go.default.example.com'
+```{{execute T1}}
+
+### Scale down to zero
+You can run `watch kubectl get pods`{{execute T2}} in a new Terminal tab to see a pod created to serve the requests. Knative will scale this pod down to zero if there are no incoming requests for 60 seconds by default.
+
+You can wait for the pods to scale down to zero and then issue the above `curl` again to see the pod spin up and serve the request.

tutorials/katacoda/2-serving-intro-yaml/step3.md

@@ -0,0 +1,98 @@
+## Blue/Green deploy
+The Knative `service` resource creates additional resources "route, configuration and revision" to manage the lifecycle of the application.
+- revision: just like a git revision, any change to the Service's `spec.template` results in a new revision
+- route: control traffic to several revisions
+
+You can list those resources by running ```kubectl get ksvc,configuration,route,revision```{{execute T1}} or by using the `kn` cli
+
+We will now update the service to change the `TARGET` env variable to `green`. Note that the name of the service is the same, we have updated the value of the environment
+variable and `.spec.template.metadata.name`
+
+```
+cat <<EOF | kubectl apply -f -
+apiVersion: serving.knative.dev/v1
+kind: Service
+metadata:
+  name: helloworld-go
+spec:
+  template:
+    metadata:
+      name: helloworld-go-green
+    spec:
+      containers:
+      - env:
+        - name: TARGET
+          value: green
+        image: gcr.io/knative-samples/helloworld-go
+
+EOF
+```{{execute T1}}
+
+This will result in a new `revision` being created. Verify this by running `kubectl get revisions`{{execute T1}}.
+Both these revisions are capable of serving requests. By default all traffic will be routed to the latest revision. You can test that by running the `curl` command again.
+We will now split our traffic between the two revisions by using the `traffic` block in the Service definition.
+```
+cat <<EOF | kubectl apply -f -
+apiVersion: serving.knative.dev/v1
+kind: Service
+metadata:
+  name: helloworld-go
+spec:
+  template:
+    metadata:
+      name: helloworld-go-green
+    spec:
+      containers:
+      - env:
+        - name: TARGET
+          value: green
+        image: gcr.io/knative-samples/helloworld-go
+  traffic:
+  - tag: current
+    revisionName: helloworld-go-green
+    percent: 50
+  - tag: candidate
+    revisionName: helloworld-go-blue
+    percent: 50
+  - tag: latest
+    latestRevision: true
+    percent: 0
+
+EOF
+
+```{{execute T1}}
+Then proceed by issuing the curl command multiple times to see that the traffic is split between the two revisions:
+```
+curl http://$MINIKUBE_IP:$INGRESS_PORT/ -H 'Host: helloworld-go.default.example.com'
+```{{execute T1}}
+
+
+Once you are satisfied with the new revision, all the traffic can be moved to the new `green` revision
+```
+cat <<EOF | kubectl apply -f -
+apiVersion: serving.knative.dev/v1
+kind: Service
+metadata:
+  name: helloworld-go
+spec:
+  template:
+    metadata:
+      name: helloworld-go-green
+    spec:
+      containers:
+      - env:
+        - name: TARGET
+          value: green
+        image: gcr.io/knative-samples/helloworld-go
+  traffic:
+  - tag: latest
+    latestRevision: true
+    percent: 100
+
+EOF
+```{{execute T1}}
+
+Then proceed by issuing the curl command multiple times to see that the traffic is goes to the new revision:
+```
+curl http://$MINIKUBE_IP:$INGRESS_PORT/ -H 'Host: helloworld-go.default.example.com'
+```{{execute T1}}