Install

mkdocs/docs/concepts/buildingblocks.md

@@ -67,7 +67,7 @@ Metric backends like Prometheus, New Relic, Sysdig and Elastic collect metrics f
     ![Conformance](/assets/images/conformance.png)
 
     !!! tip ""
-        Try a [conformance experiment](/code-samples/knative/conformance/).
+        Try a [conformance experiment](/tutorials/knative/conformance/).
 
 ## Deployment pattern
 
@@ -79,15 +79,15 @@ Metric backends like Prometheus, New Relic, Sysdig and Elastic collect metrics f
     ![Canary](/assets/images/canary-progressive-helm.png)
 
     !!! tip ""
-        Try a [progressive deployment experiment](/code-samples/knative/canary-progressive/).
+        Try a [progressive deployment experiment](/tutorials/knative/canary-progressive/).
 
 === "Fixed-split"
     Fixed-split deployment does not shift traffic between versions.
 
     ![Canary](/assets/images/canary-fixedsplit-kustomize.png)
 
     !!! tip ""
-        Try a [fixed-split deployment experiment](/code-samples/knative/canary-fixedsplit/).
+        Try a [fixed-split deployment experiment](/tutorials/knative/canary-fixedsplit/).
 
 ## Traffic shaping
 
@@ -101,15 +101,15 @@ Iter8 enables you to take total advantage of all the traffic shaping features av
     ![Canary](/assets/images/mirroring.png)
 
     !!! tip ""
-        Try an experiment with [traffic mirroring/shadowing](/code-samples/knative/mirroring/).
+        Try an experiment with [traffic mirroring/shadowing](/tutorials/knative/mirroring/).
 
 === "Traffic segmentation"
     **Traffic segmentation** is the ability to carve out a specific segment of the traffic to be used in an experiment, leaving the rest of the traffic unaffected by the experiment. Service meshes and ingress controllers often provide the ability to route requests dynamically to different versions based on request attributes such as user identity, URI, IP address prefixes, or origin. Iter8 can leverage this functionality in experiments to control the segment of the traffic that will participate in the experiment. For example, in the canary experiment depicted below, requests from the country `Wakanda` may be routed to baseline or candidate; requests that are not from `Wakanda` will not participate in the experiment and are routed only to the baseline.
 
     ![Canary](/assets/images/request-routing.png)
 
     !!! tip ""
-        Try an experiment with [traffic segmentation](/code-samples/knative/traffic-segmentation/).
+        Try an experiment with [traffic segmentation](/tutorials/knative/traffic-segmentation/).
 
 
 ## Version promotion
@@ -122,15 +122,15 @@ Iter8 can optionally **promote a version** at the end of an experiment, based on
     ![Canary](/assets/images/canary-progressive-helm.png)
 
     !!! tip ""
-        Try an [experiment that uses Helm charts](/code-samples/knative/canary-progressive/).
+        Try an [experiment that uses Helm charts](/tutorials/knative/canary-progressive/).
 
 === "Kustomize resources"
     An experiment that uses `kustomize` for version promotion is illustrated below.
 
     ![Canary](/assets/images/canary-fixedsplit-kustomize.png)
 
     !!! tip ""
-        Try an [experiment that uses Kustomize resources](/code-samples/knative/canary-fixedsplit/).
+        Try an [experiment that uses Kustomize resources](/tutorials/knative/canary-fixedsplit/).
 
 === "Plain YAML/JSON manifests"
     An experiment that uses plain YAML/JSON manifests and the `kubectl` CLI for version promotion is illustrated below.

mkdocs/docs/contributing.md

@@ -35,14 +35,14 @@ mkdocs serve -s
 Browse [http://localhost:8000](http://localhost:8000) to view your local Iter8 docs.
 
 ## Locally viewing live changes to Iter8 docs
-1. The overall structure of the documentation, as reflected in the nav tabs of https://iter8.tools, is located in the `iter8/mkdocs/mkdocs.yml` file.
+1. The overall structure of the documentation, as reflected in the nav tabs of [https://iter8.tools](https://iter8.tools), is located in the `iter8/mkdocs/mkdocs.yml` file.
 
 2. The markdown files for Iter8 docs are located under the `iter8/mkdocs/docs` folder.
 
 You will see live updates to [http://localhost:8000](http://localhost:8000) as you update markdown files in the `iter8/mkdocs` folder.
 
 ## Contributing an Iter8 tutorial
-All iter8 tutorials include e2e tests, either as [part of GitHub Actions workflows](https://github.com/iter8-tools/iter8/blob/master/.github/workflows/knative-e2e-tests.yaml) or as a [standalone test script](https://github.com/iter8-tools/iter8/blob/master/samples/knative/mirroring/manuale2etest.sh) if they require more resources than what is available in GitHub Actions workflows. When contributing a tutorial, please include relevant e2e tests.
+All iter8 tutorials include e2e tests, either as [part of GitHub Actions workflows](https://github.com/iter8-tools/iter8/blob/master/.github/workflows/knative-e2e-tests.yaml) or as a standalone test script [like this one](https://github.com/iter8-tools/iter8/blob/master/samples/knative/mirroring/e2etest.sh) if they require more resources than what is available in GitHub Actions workflows. When contributing a tutorial, please include relevant e2e tests.
 
 ## Extending Iter8 in other ways
 Documentation for contributing other Iter8 extensions such as new handler tasks, analytics capabilities, and observability features is coming soon.

mkdocs/docs/reference/apispec.md

@@ -7,7 +7,7 @@ template: overrides/main.html
 !!! abstract "Abstract"
     The Iter8 API provides two [Kubernetes custom resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) to automate metrics and AI-driven experiments, progressive delivery, and rollout of Kubernetes and OpenShift apps.
 
-    1. The **Experiment** resource provides expressive controls required by application developers and service operators who wish to automate new releases of their apps in a robust, principled and metrics-driven manner. These controls encompass [testing, deployment, traffic shaping, and version promotion functions](/concepts/buildingblocks/) and can be flexibly composed to automate [diverse use-cases](/code-samples/knative/canary-progressive/).
+    1. The **Experiment** resource provides expressive controls required by application developers and service operators who wish to automate new releases of their apps in a robust, principled and metrics-driven manner. These controls encompass [testing, deployment, traffic shaping, and version promotion functions](/concepts/buildingblocks/) and can be flexibly composed to automate [diverse use-cases](/tutorials/knative/canary-progressive/).
     2. The **Metric** resource encapsulates the REST query that is used by Iter8 for retrieving a metric value from the metrics backend. Metrics are referenced in experiments.
 
 

mkdocs/docs/code-samples/knative/annotations.md → mkdocs/docs/tutorials/knative/annotations.md

@@ -33,7 +33,7 @@ spec:
 ```
 
 ## Pod retention period
-The `scale-to-zero-pod-retention-period` annotation can be used to specify the minimum amount of time that the last pod will remain active after the Knative Autoscaler decides to scale pods to zero. Like the `minScale` annotation, this annotation is also useful for avoiding cold start issues during an experiment. For more information, see the [Knative documentation on configuring scale to zero](https://knative.dev/docs/serving/autoscaling/scale-to-zero/). The following example from the [Iter8 request routing tutorial](/code-samples/knative/requestrouting/) shows how you can use this annotation in a service.
+The `scale-to-zero-pod-retention-period` annotation can be used to specify the minimum amount of time that the last pod will remain active after the Knative Autoscaler decides to scale pods to zero. Like the `minScale` annotation, this annotation is also useful for avoiding cold start issues during an experiment. For more information, see the [Knative documentation on configuring scale to zero](https://knative.dev/docs/serving/autoscaling/scale-to-zero/). The following example from the [Iter8 request routing tutorial](/tutorials/knative/traffic-segmentation/) shows how you can use this annotation in a service.
 
 ``` yaml linenums="1" hl_lines="11"
 apiVersion: serving.knative.dev/v1

mkdocs/docs/code-samples/knative/canary-fixedsplit.md → mkdocs/docs/tutorials/knative/canary-fixedsplit.md

@@ -23,9 +23,9 @@ You will create the following resources in this tutorial.
 
     **Cleanup:** If you ran an Iter8 tutorial earlier, run the associated cleanup step.
 
-    **ITER8:** Ensure that `ITER8` environment variable is set to the root directory of your cloned Iter8 repo. See [Step 2 of the quick start tutorial for Knative](/getting-started/quick-start/with-knative/#2-clone-repo) for example.
+    **ITER8:** Ensure that `ITER8` environment variable is set to the root directory of your cloned Iter8 repo. See [Step 2 of the quick start tutorial for Knative](/getting-started/quick-start/with-knative/#2-clone-iter8-repo) for example.
 
-    **[Kustomize v3+](https://kustomize.io/) and [`iter8ctl`](/getting-started/install/#step-4-install-iter8ctl):** This tutorial uses Kustomize v3+ and `iter8ctl`.
+    **[Kustomize v3+](https://kustomize.io/) and [`iter8ctl`](/getting-started/install/#optional-step-3-iter8ctl):** This tutorial uses Kustomize v3+ and `iter8ctl`.
 
 ## 1. Create app versions
 

mkdocs/docs/code-samples/knative/canary-progressive.md → mkdocs/docs/tutorials/knative/canary-progressive.md

@@ -23,9 +23,9 @@ You will create the following resources in this tutorial.
 
     **Cleanup:** If you ran an Iter8 tutorial earlier, run the associated cleanup step.
 
-    **ITER8:** Ensure that `ITER8` environment variable is set to the root directory of your cloned Iter8 repo. See [Step 2 of the quick start tutorial for Knative](/getting-started/quick-start/with-knative/#2-clone-repo) for example.
+    **ITER8:** Ensure that `ITER8` environment variable is set to the root directory of your cloned Iter8 repo. See [Step 2 of the quick start tutorial for Knative](/getting-started/quick-start/with-knative/#2-clone-iter8-repo) for example.
 
-    **[Helm v3](https://helm.sh/) and [`iter8ctl`](/getting-started/install/#step-4-install-iter8ctl):** This tutorial uses Helm v3 and `iter8ctl`.
+    **[Helm v3](https://helm.sh/) and [`iter8ctl`](/getting-started/install/#optional-step-3-iter8ctl):** This tutorial uses Helm v3 and `iter8ctl`.
 
 ## 1. Create versions
 ```shell

mkdocs/docs/code-samples/knative/conformance.md → mkdocs/docs/tutorials/knative/conformance.md

@@ -20,9 +20,9 @@ You will create the following resources in this tutorial.
 
     **Cleanup:** If you ran an Iter8 tutorial earlier, run the associated cleanup step.
 
-    **ITER8:** Ensure that `ITER8` environment variable is set to the root directory of your cloned Iter8 repo. See [Step 2 of the quick start tutorial for Knative](/getting-started/quick-start/with-knative/#2-clone-repo) for example.
+    **ITER8:** Ensure that `ITER8` environment variable is set to the root directory of your cloned Iter8 repo. See [Step 2 of the quick start tutorial for Knative](/getting-started/quick-start/with-knative/#2-clone-iter8-repo) for example.
 
-    **[`iter8ctl`](/getting-started/install/#step-4-install-iter8ctl):** This tutorial uses `iter8ctl`.
+    **[`iter8ctl`](/getting-started/install/#optional-step-3-iter8ctl):** This tutorial uses `iter8ctl`.
 
 ## 1. Create app
 ```shell

mkdocs/docs/code-samples/knative/mirroring.md → mkdocs/docs/tutorials/knative/mirroring.md

@@ -21,7 +21,7 @@ You will create the following resources in this tutorial.
 
     **Cleanup:** If you ran an Iter8 tutorial earlier, run the associated cleanup step.
 
-    **ITER8:** Ensure that `ITER8` environment variable is set to the root directory of your cloned Iter8 repo. See [Step 2 of the quick start tutorial for Knative](/getting-started/quick-start/with-knative/#2-clone-repo) for example.
+    **ITER8:** Ensure that `ITER8` environment variable is set to the root directory of your cloned Iter8 repo. See [Step 2 of the quick start tutorial for Knative](/getting-started/quick-start/with-knative/#2-clone-iter8-repo) for example.
 
 ## 1. Create app with live and dark versions
 ```shell

mkdocs/docs/code-samples/knative/traffic-segmentation.md → mkdocs/docs/tutorials/knative/traffic-segmentation.md

@@ -21,12 +21,12 @@ You will create the following resources in this tutorial.
 
     **Cleanup:** If you ran an Iter8 tutorial earlier, run the associated cleanup step.
 
-    **ITER8:** Ensure that `ITER8` environment variable is set to the root directory of your cloned Iter8 repo. See [Step 2 of the quick start tutorial for Knative](/getting-started/quick-start/with-knative/#2-clone-repo) for example.
+    **ITER8:** Ensure that `ITER8` environment variable is set to the root directory of your cloned Iter8 repo. See [Step 2 of the quick start tutorial for Knative](/getting-started/quick-start/with-knative/#2-clone-iter8-repo) for example.
 
 
 ## 1. Create versions
 ```shell
-kubectl apply -f $ITER8/samples/knative/requestrouting/services.yaml
+kubectl apply -f $ITER8/samples/knative/traffic-segmentation/services.yaml
 ```
 
 ??? info "Look inside services.yaml"
@@ -71,7 +71,7 @@ kubectl apply -f $ITER8/samples/knative/requestrouting/services.yaml
 
 ## 2. Create Istio virtual service
 ```shell
-kubectl apply -f $ITER8/samples/knative/requestrouting/routing-rule.yaml
+kubectl apply -f $ITER8/samples/knative/traffic-segmentation/routing-rule.yaml
 ```
 
 ??? info "Look inside routing-rule.yaml"
@@ -127,7 +127,7 @@ kubectl apply -f $ITER8/samples/knative/requestrouting/routing-rule.yaml
 TEMP_DIR=$(mktemp -d)
 cd $TEMP_DIR
 curl -L https://istio.io/downloadIstio | ISTIO_VERSION=1.8.2 sh -
-istio-1.8.2/bin/istioctl kube-inject -f $ITER8/samples/knative/requestrouting/curl.yaml | kubectl create -f -
+istio-1.8.2/bin/istioctl kube-inject -f $ITER8/samples/knative/traffic-segmentation/curl.yaml | kubectl create -f -
 cd $ITER8
 ```
 
@@ -169,7 +169,7 @@ cd $ITER8
 ```shell
 kubectl wait --for=condition=Ready ksvc/sample-app-v1
 kubectl wait --for=condition=Ready ksvc/sample-app-v2
-kubectl apply -f $ITER8/samples/knative/requestrouting/experiment.yaml
+kubectl apply -f $ITER8/samples/knative/traffic-segmentation/experiment.yaml
 ```
 
 ??? info "Look inside experiment.yaml"
@@ -260,10 +260,10 @@ Observe the experiment in realtime. Paste commands from the tabs below in separa
 
 ## 6. Cleanup
 ```shell
-kubectl delete -f $ITER8/samples/knative/requestrouting/experiment.yaml
-kubectl delete -f $ITER8/samples/knative/requestrouting/curl.yaml
-kubectl delete -f $ITER8/samples/knative/requestrouting/routing-rule.yaml
-kubectl delete -f $ITER8/samples/knative/requestrouting/services.yaml
+kubectl delete -f $ITER8/samples/knative/traffic-segmentation/experiment.yaml
+kubectl delete -f $ITER8/samples/knative/traffic-segmentation/curl.yaml
+kubectl delete -f $ITER8/samples/knative/traffic-segmentation/routing-rule.yaml
+kubectl delete -f $ITER8/samples/knative/traffic-segmentation/services.yaml
 ```
 
 ???+ info "Understanding what happened"

mkdocs/docs/code-samples/traffic.md → mkdocs/docs/tutorials/traffic.md

@@ -8,9 +8,9 @@ hide:
 
 All Iter8 tutorials use [`Fortio`](https://github.com/fortio/fortio) or `curl`-based Kubernetes jobs that run inside the cluster to simulate user requests during experiments. You can try other variations of these tutorials where requests are generated outside the cluster.
 
-- The Knative service setup of [quick start](/getting-started/quick-start/with-knative/), [Canary + Progressive + Helm](/code-samples/knative/canary-progressive/), [Canary + FixedSplit + Kustomize](/code-samples/knative/canary-fixedsplit/), and [Conformance](/code-samples/knative/conformance/) tutorials is similar to that of this [Knative tutorial](https://knative.dev/docs/serving/samples/traffic-splitting/index.html#traffic-splitting).
+- The Knative service setup of [quick start](/getting-started/quick-start/with-knative/), [Canary + Progressive + Helm](/tutorials/knative/canary-progressive/), [Canary + FixedSplit + Kustomize](/tutorials/knative/canary-fixedsplit/), and [Conformance](/tutorials/knative/conformance/) tutorials is similar to that of this [Knative tutorial](https://knative.dev/docs/serving/samples/traffic-splitting/index.html#traffic-splitting).
 
-- The Istio virtual service setup of [Conformance + Mirroring](/code-samples/knative/mirroring/) and [Canary + Request routing](/code-samples/knative/requestrouting/) tutorials is similar to that of this [Knative tutorial](https://knative.dev/docs/serving/samples/knative-routing-go/index.html#access-the-services).
+- The Istio virtual service setup of [Conformance + Mirroring](/tutorials/knative/mirroring/) and [Canary + Request routing](/tutorials/knative/traffic-segmentation/) tutorials is similar to that of this [Knative tutorial](https://knative.dev/docs/serving/samples/knative-routing-go/index.html#access-the-services).
 
 Refer to the above mentioned Knative tutorials for generating requests for your applications from outside the cluster.
 

mkdocs/mkdocs.yml

@@ -106,13 +106,13 @@ nav:
     - Getting help: getting-started/help.md
   - Tutorials:
     - Knative:
-      - Progressive canary release: code-samples/knative/canary-progressive.md
-      - Fixed split canary release: code-samples/knative/canary-fixedsplit.md
-      - Conformance testing: code-samples/knative/conformance.md
-      - Conformance testing with traffic mirroring: code-samples/knative/mirroring.md
-      - Progressive canary release with traffic segmentation: code-samples/knative/traffic-segmentation.md
-      - Useful Knative annotations: code-samples/knative/annotations.md
-    - Generating requests externally: code-samples/traffic.md
+      - Progressive canary release: tutorials/knative/canary-progressive.md
+      - Fixed split canary release: tutorials/knative/canary-fixedsplit.md
+      - Conformance testing: tutorials/knative/conformance.md
+      - Conformance testing with traffic mirroring: tutorials/knative/mirroring.md
+      - Progressive canary release with traffic segmentation: tutorials/knative/traffic-segmentation.md
+      - Useful Knative annotations: tutorials/knative/annotations.md
+    - Generating requests externally: tutorials/traffic.md
   - Metrics:
     - Using metrics in experiments: metrics/using-metrics.md
   - Reference:

samples/knative/requestrouting/e2etest.sh → samples/knative/traffic-segmentation/e2etest.sh

@@ -12,38 +12,38 @@ $ITER8/samples/knative/quickstart/platformsetup.sh istio
 
 # create app with live and dark versions
 echo "Creating live and dark versions"
-kubectl apply -f $ITER8/samples/knative/requestrouting/services.yaml
+kubectl apply -f $ITER8/samples/knative/traffic-segmentation/services.yaml
 
 # create Istio virtual services
 echo "Creating Istio virtual services"
-kubectl apply -f $ITER8/samples/knative/requestrouting/routing-rule.yaml 
+kubectl apply -f $ITER8/samples/knative/traffic-segmentation/routing-rule.yaml 
 
 # Generate requests
 echo "Generating requests"
 TEMP_DIR=$(mktemp -d)
 cd $TEMP_DIR
 curl -L https://istio.io/downloadIstio | ISTIO_VERSION=1.8.2 sh -
-istio-1.8.2/bin/istioctl kube-inject -f $ITER8/samples/knative/requestrouting/curl.yaml | kubectl create -f -
+istio-1.8.2/bin/istioctl kube-inject -f $ITER8/samples/knative/traffic-segmentation/curl.yaml | kubectl create -f -
 cd $ITER8
 
 # Create Iter8 experiment
 echo "Creating an Iter8 experiment"
 kubectl wait --for=condition=Ready ksvc/sample-app-v1
 kubectl wait --for=condition=Ready ksvc/sample-app-v2
-kubectl apply -f $ITER8/samples/knative/requestrouting/experiment.yaml        
+kubectl apply -f $ITER8/samples/knative/traffic-segmentation/experiment.yaml        
 
 # Sleep
 echo "Sleep for 150s"
 sleep 150.0
 
 # Check
-source  $ITER8/samples/knative/requestrouting/check.sh
+source  $ITER8/samples/knative/traffic-segmentation/check.sh
 
 # Cleanup .. not needed since cluster is getting deleted; just forming a good habit!
-kubectl delete -f $ITER8/samples/knative/requestrouting/experiment.yaml
-kubectl delete -f $ITER8/samples/knative/requestrouting/curl.yaml
-kubectl delete -f $ITER8/samples/knative/requestrouting/routing-rule.yaml
-kubectl delete -f $ITER8/samples/knative/requestrouting/services.yaml
+kubectl delete -f $ITER8/samples/knative/traffic-segmentation/experiment.yaml
+kubectl delete -f $ITER8/samples/knative/traffic-segmentation/curl.yaml
+kubectl delete -f $ITER8/samples/knative/traffic-segmentation/routing-rule.yaml
+kubectl delete -f $ITER8/samples/knative/traffic-segmentation/services.yaml
 
 # delete kind cluster
 kind delete cluster