update install instructions (#118)

* update install instructions

Signed-off-by: Michael Kalantar <[email protected]>

* update wordlist

Signed-off-by: Michael Kalantar <[email protected]>

* clarify differences in candidate

Signed-off-by: Michael Kalantar <[email protected]>

* routemap for abn

Signed-off-by: Michael Kalantar <[email protected]>

* update wordlist

Signed-off-by: Michael Kalantar <[email protected]>

* fix spelling

Signed-off-by: Michael Kalantar <[email protected]>

* update for null strategy

Signed-off-by: Michael Kalantar <[email protected]>

* routemap topic

Signed-off-by: Michael Kalantar <[email protected]>

* spelling

Signed-off-by: Michael Kalantar <[email protected]>

* update roadmap

Signed-off-by: Michael Kalantar <[email protected]>

* roadmap

Signed-off-by: Michael Kalantar <[email protected]>

* refine based on feedback

Signed-off-by: Michael Kalantar <[email protected]>

---------

Signed-off-by: Michael Kalantar <[email protected]>

Author: kalantar

.github/wordlist.txt

@@ -10,6 +10,7 @@ Cha
 chaosengine
 CLI
 CLIs
+CRD
 cronjob
 crontab
 ConfigMap
@@ -67,6 +68,8 @@ protobuf
 protoc
 quickstart
 roadmap
+routemap
+Routemaps
 scikit
 SDK
 sed
@@ -80,6 +83,7 @@ SRE
 Srinivasan
 subdirectory
 Sysdig
+stringified
 tada
 Tekton
 toc
@@ -184,3 +188,6 @@ Autoscaling
 composable
 Hyperparameter
 LLM
+odh
+contrib
+opendatahub

CONTRIBUTING.md

@@ -118,8 +118,7 @@ IMG=[Docker image name]
 Build and push Iter8 image to Docker
 
 ```shell
-make build
-docker build -f docker/Dockerfile -t $IMG bin 
+docker build -f docker/Dockerfile -t $IMG . 
 docker push $IMG
 ```
 

docs/getting-started/concepts.md

@@ -56,7 +56,7 @@ Iter8 provides three inter-related components to support the above use-cases.
 ## Advantages
 Iter8 has several advantages compared to other tooling in this space. 
 
-First, Iter8 has no restrictions on the types of resources that make up a version of an application. The definition of a version is declarative. While there is a default set of resource types that can be referenced, it is easy to [declaratively extend](../user-guide/topics/extensions.md) this set. Furthermore, this same extension mechanism allows Iter8 to be used with any service mesh.
+First, Iter8 has no restrictions on the types of resources that make up a version of an application. This includes custom resources; that is, those defined by a custom resource definition (CRD). Because the set of resources that comprise a version is declarative, it is easy to [extend](../user-guide/topics/extensions.md). Note that this same extension mechanism also allows Iter8 to be used with any service mesh.
 
 Second, the Iter8 client SDK addresses a key challenge to [A/B/n testing](../user-guide/topics/ab_testing.md): the decoupling of the front-end release process from that of the back-end. It allows the front-end to reliably associate business metrics with the contributing version of the back-end.
 

docs/getting-started/first-abn.md

@@ -20,7 +20,7 @@ This tutorial describes how to do A/B testing of a backend component using the [
 
 ## Install the Iter8 controller
 
---8<-- "docs/tutorials/installiter8controller.md"
+--8<-- "docs/getting-started/install.md"
 
 ## Deploy the sample application
 
@@ -55,47 +55,28 @@ A sample application using the Iter8 SDK is provided. Deploy both the frontend a
 
 ## Describe the application
 
-In order to support `Lookup()`, Iter8 needs to know what the application component versions look like. A `ConfigMap` is used to describe the make up of possible versions:
+In order to support `Lookup()`, Iter8 needs to know what the application component versions look like. A _routemap_ is created to do this. A routemap contains a description of each version of an application and may contain [routing templates](../user-guide/topics/routemap.md). To create the routemap:
 
 ```shell
-cat <<EOF | kubectl apply -f -
-apiVersion: v1
-kind: ConfigMap
-metadata:
-  name: backend
-  labels:
-    app.kubernetes.io/managed-by: iter8
-    iter8.tools/kind: routemap
-    iter8.tools/version: "v0.18"
-immutable: true
-data:
-  strSpec: |
-    versions:
-    - resources:
-      - gvrShort: svc
-        name: backend
-        namespace: default
-      - gvrShort: deploy
-        name: backend
-        namespace: default
-    - resources:
-      - gvrShort: svc
-        name: backend-candidate-1
-        namespace: default
-      - gvrShort: deploy
-        name: backend-candidate-1
-        namespace: default
+cat <<EOF | helm template routing --repo https://iter8-tools.github.io/iter8 routing-actions --version 0.18 -f - | kubectl apply -f -
+appType: deployment
+appName: backend
+action: initialize
+appVersions:
+- name: backend
+- name: backend-candidate-1
 EOF
 ```
 
-In this definition, each version of the application is composed of a `Service` and a `Deployment`. In the primary version, both are named `backend`. In any candidate version they are named `backend-candidate-1`. Iter8 uses this definition to identify when any of the versions of the application are available. It can then respond appropriately to `Lookup()` requests. 
+The `initialize` action (with strategy `none`) creates a routemap that only defines the resources that make up each version of the application. In this case, two versions: `backend` and `backend-candidate-1`. Each version is comprised of a `Service` and a `Deployment`. Iter8 uses this information to identify when any of the versions of the application are available. It can then respond appropriately to `Lookup()` requests. 
 
 ## Generate load
 
-In separate shells, port-forward requests to the frontend component and generate load for multiple users. A [script](https://raw.githubusercontent.com/iter8-tools/docs/main/samples/abn-sample/generate_load.sh) is provided to do this. To use it:
+In one shell, port-forward requests to the frontend component:
     ```shell
     kubectl port-forward service/frontend 8090:8090
     ```
+In another shell, run a script to generate load from multiple users:
     ```shell
     curl -s https://raw.githubusercontent.com/iter8-tools/docs/v0.17.3/samples/abn-sample/generate_load.sh | sh -s --
     ```
@@ -164,12 +145,20 @@ svc/backend deploy/backend \
 svc/backend-candidate-1 deploy/backend-candidate-1
 ```
 
-Delete the application description:
+Delete the application routemap:
 
 ```shell
-kubectl delete cm/backend
+cat <<EOF | helm template routing --repo https://iter8-tools.github.io/iter8 routing-actions --version 0.18 -f - | kubectl delete -f -
+appType: deployment
+appName: backend
+action: initialize
+appVersions:
+- name: backend
+- name: backend-candidate-1
+EOF
+
 ```
 
 Uninstall the Iter8 controller:
 
---8<-- "docs/tutorials/deleteiter8controller.md"
+--8<-- "docs/getting-started/uninstall.md"

docs/getting-started/first-performance.md

@@ -25,7 +25,7 @@ Run your first performance test by load testing a Kubernetes HTTP service and vi
 
 ## Install the Iter8 controller
 
---8<-- "docs/tutorials/installiter8controller.md"
+--8<-- "docs/getting-started/install.md"
 
 ## Launch performance test
 
@@ -100,7 +100,7 @@ kubectl delete deploy/httpbin
 
 ### Uninstall the Iter8 controller
 
---8<-- "docs/tutorials/deleteiter8controller.md"
+--8<-- "docs/getting-started/uninstall.md"
 
 ***
 

docs/getting-started/first-routing.md

@@ -16,7 +16,7 @@ After a one-time initialization step, the end user merely deploys candidate vers
 
 ## Install the Iter8 controller
 
---8<-- "docs/tutorials/installiter8controller.md"
+--8<-- "docs/getting-started/install.md"
 
 ## Initialize primary
 
@@ -83,7 +83,7 @@ To send inference requests to the model:
     3. Send requests:
     ```shell
     curl httpbin.default -s -D - \
-    | grep -e HTTP -e app-version
+    | grep -e '^HTTP' -e app-version
     ```
 
 === "From outside the cluster"
@@ -95,7 +95,7 @@ To send inference requests to the model:
     2. Send requests:
     ```shell
     curl -H 'Host: httpbin.default' localhost:8080 -s -D - \
-    | grep -e HTTP -e app-version
+    | grep -e '^HTTP' -e app-version
     ```
 
 ??? note "Sample output"
@@ -104,7 +104,6 @@ To send inference requests to the model:
     ```
     HTTP/1.1 200 OK
     app-version: httpbin-0
-                                        <p>A simple HTTP Request &amp; Response Service.
     ```
 
 Note that the model version responding to each inference request is noted in the response header `app-version`. In the requests above, we display only the response code and this header.
@@ -121,7 +120,7 @@ kubectl expose deployment httpbin-1 --port=80
 ```
 
 ??? note "About the candidate"
-    In this tutorial, the image is the same as for the primary version. In a real world example, it would be different.
+    In this tutorial, the candidate image is the same as the one for the primary version. In a real world example, it would be different. The version label (`app.kubernetes.io/version`) can be used to distinguish between versions.
 
 ### Verify routing changes
 
@@ -141,14 +140,12 @@ You can send additional inference requests as described above. They will be hand
     ```
     HTTP/1.1 200 OK
     app-version: httpbin-0
-                                        <p>A simple HTTP Request &amp; Response Service.
     ```
 
     `httpbin-1` output:
     ```
     HTTP/1.1 200 OK
     app-version: httpbin-1
-                                        <p>A simple HTTP Request &amp; Response Service.
     ```
 
 ## Modify weights (optional)
@@ -183,7 +180,7 @@ kubectl label deployment httpbin-0 app.kubernetes.io/version=v1 --overwrite
 ```
 
 ??? note "What is different?"
-    The version label (`app.kubernets.io/version`) was updated. In a real world example, the image would also have been updated.
+    The version label (`app.kubernetes.io/version`) was updated. In a real world example, the image would also have been updated.
 
 ### Delete candidate
 
@@ -224,4 +221,4 @@ kubectl delete deployment/httpbin-0 service/httpbin-0
 
 Uninstall Iter8 controller:
 
---8<-- "docs/tutorials/deleteiter8controller.md"
+--8<-- "docs/getting-started/uninstall.md"

docs/getting-started/install.md

@@ -0,0 +1,6 @@
+```shell
+helm install --repo https://iter8-tools.github.io/iter8 --version 0.18 iter8 controller \
+--set clusterScoped=true
+```
+
+For additional install options, see [Iter8 Installation](https://iter8.tools/0.18/user-guide/topics/install/).

docs/getting-started/uninstall.md

@@ -0,0 +1,5 @@
+```shell
+helm delete iter8
+```
+
+For additional uninstall options, see [Iter8 Uninstall](https://iter8.tools/0.18/user-guide/topics/uninstall/).

docs/roadmap.md

@@ -7,10 +7,13 @@ hide:
 
 # Roadmap
 
-1. Open Data Hub tier 1 project
-2. Diverse examples of `autoroute` with CRDs (such as Knative and KServe) and other types of k8s resources (like statefulsets)
-3. Stabilizing Iter8 APIs for CNCF sandboxing
-4. Autoscaling the metrics service
-5. Metrics & evaluation for foundation model/LLM-based apps
-6. Hyperparameter tuning for foundation model/LLM-based inference pipelines
-7. Data/concept drift detection for ML models
+1. Stabilizing Iter8 APIs for CNCF sandboxing
+2. Autoscaling the metrics service
+3. Install infrastructure components such as Istio
+4. Install ML components such as KServe and KServe ModelMesh
+5. Extend routing templates to include application management
+6. Support multi-cluster installs
+7. Open Data Hub tier 1 project
+8. Metrics & evaluation for foundation model/LLM-based apps
+9. Hyperparameter tuning for foundation model/LLM-based inference pipelines
+10. Data/concept drift detection for ML models