From 704cecbb96f8fa49839c6ca1d60bae242b50f407 Mon Sep 17 00:00:00 2001 From: Michael Kalantar Date: Fri, 22 Sep 2023 16:26:10 -0400 Subject: [PATCH 01/12] update install instructions Signed-off-by: Michael Kalantar --- docs/getting-started/first-abn.md | 4 +-- docs/getting-started/first-performance.md | 4 +-- docs/getting-started/first-routing.md | 4 +-- docs/getting-started/install.md | 6 ++++ docs/getting-started/uninstall.md | 5 +++ docs/roadmap.md | 13 ++++--- docs/tutorials/deleteiter8controller.md | 15 -------- docs/tutorials/installiter8controller.md | 22 ------------ docs/tutorials/integrations/ghactions.md | 2 +- docs/tutorials/integrations/kserve-mm/abn.md | 4 +-- .../integrations/kserve-mm/blue-green.md | 4 +-- .../integrations/kserve-mm/canary.md | 4 +-- .../tutorials/integrations/kserve/abn-grpc.md | 4 +-- .../tutorials/integrations/kserve/abn-http.md | 4 +-- .../integrations/kserve/blue-green.md | 4 +-- docs/tutorials/integrations/kserve/canary.md | 4 +-- docs/tutorials/integrations/kserve/grpc.md | 4 +-- docs/tutorials/integrations/kserve/http.md | 4 +-- docs/tutorials/integrations/slack.md | 2 +- docs/tutorials/load-test-grpc-multiple.md | 4 +-- docs/tutorials/load-test-grpc.md | 4 +-- docs/tutorials/load-test-http-multiple.md | 4 +-- docs/user-guide/topics/install.md | 34 +++++++++++++++++++ docs/user-guide/topics/uninstall.md | 25 ++++++++++++++ mkdocs.yml | 7 ++-- 25 files changed, 112 insertions(+), 79 deletions(-) create mode 100644 docs/getting-started/install.md create mode 100644 docs/getting-started/uninstall.md delete mode 100644 docs/tutorials/deleteiter8controller.md delete mode 100644 docs/tutorials/installiter8controller.md create mode 100644 docs/user-guide/topics/install.md create mode 100644 docs/user-guide/topics/uninstall.md diff --git a/docs/getting-started/first-abn.md b/docs/getting-started/first-abn.md index 9742a43c..a0c79792 100644 --- a/docs/getting-started/first-abn.md +++ b/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 @@ -172,4 +172,4 @@ kubectl delete cm/backend Uninstall the Iter8 controller: ---8<-- "docs/tutorials/deleteiter8controller.md" +--8<-- "docs/getting-started/uninstall.md" diff --git a/docs/getting-started/first-performance.md b/docs/getting-started/first-performance.md index e694bb80..2484fba6 100644 --- a/docs/getting-started/first-performance.md +++ b/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" *** diff --git a/docs/getting-started/first-routing.md b/docs/getting-started/first-routing.md index 849e2678..f53c99c7 100644 --- a/docs/getting-started/first-routing.md +++ b/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 @@ -224,4 +224,4 @@ kubectl delete deployment/httpbin-0 service/httpbin-0 Uninstall Iter8 controller: ---8<-- "docs/tutorials/deleteiter8controller.md" +--8<-- "docs/getting-started/uninstall.md" diff --git a/docs/getting-started/install.md b/docs/getting-started/install.md new file mode 100644 index 00000000..3597d8a9 --- /dev/null +++ b/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/). \ No newline at end of file diff --git a/docs/getting-started/uninstall.md b/docs/getting-started/uninstall.md new file mode 100644 index 00000000..db64f47a --- /dev/null +++ b/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/). \ No newline at end of file diff --git a/docs/roadmap.md b/docs/roadmap.md index c1192509..bb90495d 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -7,10 +7,9 @@ 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 \ No newline at end of file +1. Stabilizing Iter8 APIs for CNCF sandboxing +2. Autoscaling the metrics service +3. Open Data Hub tier 1 project +4. Metrics & evaluation for foundation model/LLM-based apps +5. Hyperparameter tuning for foundation model/LLM-based inference pipelines +6. Data/concept drift detection for ML models \ No newline at end of file diff --git a/docs/tutorials/deleteiter8controller.md b/docs/tutorials/deleteiter8controller.md deleted file mode 100644 index c803fb95..00000000 --- a/docs/tutorials/deleteiter8controller.md +++ /dev/null @@ -1,15 +0,0 @@ -=== "Helm" - ```shell - helm delete iter8 - ``` - -=== "Kustomize" - === "Namespace scoped" - ```shell - kubectl delete -k 'https://github.com/iter8-tools/iter8.git/kustomize/controller/namespaceScoped?ref=v0.18.3' - ``` - - === "Cluster scoped" - ```shell - kubectl delete -k 'https://github.com/iter8-tools/iter8.git/kustomize/controller/clusterScoped?ref=v0.18.3' - ``` diff --git a/docs/tutorials/installiter8controller.md b/docs/tutorials/installiter8controller.md deleted file mode 100644 index a7510f26..00000000 --- a/docs/tutorials/installiter8controller.md +++ /dev/null @@ -1,22 +0,0 @@ -=== "Helm" - === "Namespace scoped" - ```shell - helm install --repo https://iter8-tools.github.io/iter8 --version 0.18 iter8 controller - ``` - - === "Cluster scoped" - ```shell - helm install --repo https://iter8-tools.github.io/iter8 --version 0.18 iter8 controller \ - --set clusterScoped=true - ``` - -=== "Kustomize" - === "Namespace scoped" - ```shell - kubectl apply -k 'https://github.com/iter8-tools/iter8.git/kustomize/controller/namespaceScoped?ref=v0.18.3' - ``` - - === "Cluster scoped" - ```shell - kubectl apply -k 'https://github.com/iter8-tools/iter8.git/kustomize/controller/clusterScoped?ref=v0.18.3' - ``` diff --git a/docs/tutorials/integrations/ghactions.md b/docs/tutorials/integrations/ghactions.md index 123ced03..8ed59e48 100644 --- a/docs/tutorials/integrations/ghactions.md +++ b/docs/tutorials/integrations/ghactions.md @@ -39,7 +39,7 @@ Also note that the `on.repository_dispatch.types` is set to `iter8`. The default 4. Ensure that you have a Kubernetes cluster and the [`kubectl` CLI](https://kubernetes.io/docs/reference/kubectl/). You can create a local Kubernetes cluster using tools like [Kind](https://kind.sigs.k8s.io/) or [Minikube](https://minikube.sigs.k8s.io/docs/). 5. Install the Iter8 controller - --8<-- "docs/tutorials/installiter8controller.md" + --8<-- "docs/getting-started/install.md" 6. Deploy the sample HTTP service in the Kubernetes cluster. ```shell diff --git a/docs/tutorials/integrations/kserve-mm/abn.md b/docs/tutorials/integrations/kserve-mm/abn.md index 7afdb90a..e4d7d5e1 100644 --- a/docs/tutorials/integrations/kserve-mm/abn.md +++ b/docs/tutorials/integrations/kserve-mm/abn.md @@ -24,7 +24,7 @@ This tutorial describes how to do A/B testing of a backend ML model hosted on [K ## Install the Iter8 controller ---8<-- "docs/tutorials/installiter8controller.md" +--8<-- "docs/getting-started/install.md" ## Deploy the sample application @@ -236,4 +236,4 @@ kubectl delete deploy/frontend svc/frontend Uninstall Iter8 controller: ---8<-- "docs/tutorials/deleteiter8controller.md" +--8<-- "docs/getting-started/uninstall.md" diff --git a/docs/tutorials/integrations/kserve-mm/blue-green.md b/docs/tutorials/integrations/kserve-mm/blue-green.md index 58249766..8cd696b0 100644 --- a/docs/tutorials/integrations/kserve-mm/blue-green.md +++ b/docs/tutorials/integrations/kserve-mm/blue-green.md @@ -22,7 +22,7 @@ In this tutorial, we use the Istio service mesh to distribute inference requests ## Install the Iter8 controller ---8<-- "docs/tutorials/installiter8controller.md" +--8<-- "docs/getting-started/install.md" ## Initialize primary @@ -279,4 +279,4 @@ kubectl delete isvc/wisdom-0 Uninstall Iter8 controller: ---8<-- "docs/tutorials/deleteiter8controller.md" +--8<-- "docs/getting-started/uninstall.md" diff --git a/docs/tutorials/integrations/kserve-mm/canary.md b/docs/tutorials/integrations/kserve-mm/canary.md index 6983dcb3..2d3bf029 100644 --- a/docs/tutorials/integrations/kserve-mm/canary.md +++ b/docs/tutorials/integrations/kserve-mm/canary.md @@ -22,7 +22,7 @@ In this tutorial, we use the Istio service mesh to distribute inference requests ## Install the Iter8 controller ---8<-- "docs/tutorials/installiter8controller.md" +--8<-- "docs/getting-started/install.md" ## Initialize primary @@ -253,4 +253,4 @@ kubectl delete isvc/wisdom-0 Uninstall Iter8 controller: ---8<-- "docs/tutorials/deleteiter8controller.md" +--8<-- "docs/getting-started/uninstall.md" diff --git a/docs/tutorials/integrations/kserve/abn-grpc.md b/docs/tutorials/integrations/kserve/abn-grpc.md index 1930b099..c552baa4 100644 --- a/docs/tutorials/integrations/kserve/abn-grpc.md +++ b/docs/tutorials/integrations/kserve/abn-grpc.md @@ -24,7 +24,7 @@ This tutorial describes how to do A/B testing of a backend ML model hosted on [K ## Install the Iter8 controller ---8<-- "docs/tutorials/installiter8controller.md" +--8<-- "docs/getting-started/install.md" ## Deploy the sample application @@ -245,4 +245,4 @@ kubectl delete deploy/frontend svc/frontend Uninstall Iter8 controller: ---8<-- "docs/tutorials/deleteiter8controller.md" +--8<-- "docs/getting-started/uninstall.md" diff --git a/docs/tutorials/integrations/kserve/abn-http.md b/docs/tutorials/integrations/kserve/abn-http.md index 3710d772..03ccb039 100644 --- a/docs/tutorials/integrations/kserve/abn-http.md +++ b/docs/tutorials/integrations/kserve/abn-http.md @@ -24,7 +24,7 @@ This tutorial describes how to do A/B testing of a backend ML model hosted on [K ## Install the Iter8 controller ---8<-- "docs/tutorials/installiter8controller.md" +--8<-- "docs/getting-started/install.md" ## Deploy the sample application @@ -230,4 +230,4 @@ kubectl delete deploy/frontend svc/frontend Uninstall Iter8 controller: ---8<-- "docs/tutorials/deleteiter8controller.md" +--8<-- "docs/getting-started/uninstall.md" diff --git a/docs/tutorials/integrations/kserve/blue-green.md b/docs/tutorials/integrations/kserve/blue-green.md index 0db0968c..125e0128 100644 --- a/docs/tutorials/integrations/kserve/blue-green.md +++ b/docs/tutorials/integrations/kserve/blue-green.md @@ -20,7 +20,7 @@ After a one-time initialization step, the end user merely deploys candidate mode ## Install the Iter8 controller ---8<-- "docs/tutorials/installiter8controller.md" +--8<-- "docs/getting-started/install.md" ## Initialize primary @@ -275,4 +275,4 @@ kubectl delete isvc/wisdom-0 Uninstall Iter8 controller: ---8<-- "docs/tutorials/deleteiter8controller.md" +--8<-- "docs/getting-started/uninstall.md" diff --git a/docs/tutorials/integrations/kserve/canary.md b/docs/tutorials/integrations/kserve/canary.md index a241f721..0f47c903 100644 --- a/docs/tutorials/integrations/kserve/canary.md +++ b/docs/tutorials/integrations/kserve/canary.md @@ -20,7 +20,7 @@ After a one-time initialization step, the end user merely deploys candidate mode ## Install the Iter8 controller ---8<-- "docs/tutorials/installiter8controller.md" +--8<-- "docs/getting-started/install.md" ## Initialize primary @@ -241,4 +241,4 @@ kubectl delete isvc/wisdom-0 Uninstall Iter8 controller: ---8<-- "docs/tutorials/deleteiter8controller.md" +--8<-- "docs/getting-started/uninstall.md" diff --git a/docs/tutorials/integrations/kserve/grpc.md b/docs/tutorials/integrations/kserve/grpc.md index 49d2d5e0..505181c6 100644 --- a/docs/tutorials/integrations/kserve/grpc.md +++ b/docs/tutorials/integrations/kserve/grpc.md @@ -21,7 +21,7 @@ This tutorial shows how easy it is to run a load test for KServe when using gRPC ## Install the Iter8 controller ---8<-- "docs/tutorials/installiter8controller.md" +--8<-- "docs/getting-started/install.md" ## Deploy an InferenceService @@ -103,7 +103,7 @@ kubectl delete inferenceservice sklearn-irisv2 ### Uninstall the Iter8 controller ---8<-- "docs/tutorials/deleteiter8controller.md" +--8<-- "docs/getting-started/uninstall.md" ??? note "Some variations and extensions of this performance test" 1. The [grpc task](../../../user-guide/tasks/grpc.md) can be configured with load related parameters such as the number of requests, requests per second, or number of concurrent connections. \ No newline at end of file diff --git a/docs/tutorials/integrations/kserve/http.md b/docs/tutorials/integrations/kserve/http.md index bf9e398c..65c88a4f 100644 --- a/docs/tutorials/integrations/kserve/http.md +++ b/docs/tutorials/integrations/kserve/http.md @@ -21,7 +21,7 @@ This tutorial shows how easy it is to run a load test for KServe when using HTTP ## Install the Iter8 controller ---8<-- "docs/tutorials/installiter8controller.md" +--8<-- "docs/getting-started/install.md" ## Deploy an InferenceService @@ -92,7 +92,7 @@ kubectl delete inferenceservice sklearn-irisv2 ### Uninstall the Iter8 controller ---8<-- "docs/tutorials/deleteiter8controller.md" +--8<-- "docs/getting-started/uninstall.md" ??? note "Some variations and extensions of this performance test" 1. The [http task](../../../user-guide/tasks/http.md) can be configured with load related parameters such as the number of requests, queries per second, or number of parallel connections. diff --git a/docs/tutorials/integrations/slack.md b/docs/tutorials/integrations/slack.md index e03bd926..12a6014a 100644 --- a/docs/tutorials/integrations/slack.md +++ b/docs/tutorials/integrations/slack.md @@ -23,7 +23,7 @@ The `slack` task requires the URL of the Slack webhook. To see a full list of th 3. Ensure that you have a Kubernetes cluster and the [`kubectl` CLI](https://kubernetes.io/docs/reference/kubectl/). You can create a local Kubernetes cluster using tools like [Kind](https://kind.sigs.k8s.io/) or [Minikube](https://minikube.sigs.k8s.io/docs/). 4. Install the Iter8 controller - --8<-- "docs/tutorials/installiter8controller.md" + --8<-- "docs/getting-started/install.md" 5. Deploy the sample HTTP service in the Kubernetes cluster. ```shell diff --git a/docs/tutorials/load-test-grpc-multiple.md b/docs/tutorials/load-test-grpc-multiple.md index ce43953d..d8cf0692 100644 --- a/docs/tutorials/load-test-grpc-multiple.md +++ b/docs/tutorials/load-test-grpc-multiple.md @@ -26,7 +26,7 @@ template: main.html ## Install the Iter8 controller ---8<-- "docs/tutorials/installiter8controller.md" +--8<-- "docs/getting-started/install.md" ## Launch performance test @@ -90,7 +90,7 @@ kubectl delete deploy/routeguide ### Uninstall the Iter8 controller ---8<-- "docs/tutorials/deleteiter8controller.md" +--8<-- "docs/getting-started/uninstall.md" ??? note "Some variations and extensions of this performance test" 1. The [grpc task](../user-guide/tasks/grpc.md) can be configured with load related parameters such as the total number of requests, requests per second, or number of concurrent connections. \ No newline at end of file diff --git a/docs/tutorials/load-test-grpc.md b/docs/tutorials/load-test-grpc.md index 9898c96c..b646c429 100644 --- a/docs/tutorials/load-test-grpc.md +++ b/docs/tutorials/load-test-grpc.md @@ -27,7 +27,7 @@ See [Load Test multiple gRPC methods](./load-test-http-multiple.md) to see a tut ## Install the Iter8 controller ---8<-- "docs/tutorials/installiter8controller.md" +--8<-- "docs/getting-started/install.md" ## Launch performance test @@ -132,7 +132,7 @@ kubectl delete deploy/routeguide ### Uninstall the Iter8 controller ---8<-- "docs/tutorials/deleteiter8controller.md" +--8<-- "docs/getting-started/uninstall.md" ??? note "Some variations and extensions of this performance test" 1. The [grpc task](../user-guide/tasks/grpc.md) can be configured with load related parameters such as the total number of requests, requests per second, or number of concurrent connections. \ No newline at end of file diff --git a/docs/tutorials/load-test-http-multiple.md b/docs/tutorials/load-test-http-multiple.md index c1cdbf2d..9a6bc941 100644 --- a/docs/tutorials/load-test-http-multiple.md +++ b/docs/tutorials/load-test-http-multiple.md @@ -26,7 +26,7 @@ template: main.html ## Install the Iter8 controller ---8<-- "docs/tutorials/installiter8controller.md" +--8<-- "docs/getting-started/install.md" ## Launch performance test @@ -88,7 +88,7 @@ kubectl delete deploy/httpbin ### Uninstall the Iter8 controller ---8<-- "docs/tutorials/deleteiter8controller.md" +--8<-- "docs/getting-started/uninstall.md" ??? note "Some variations and extensions of this performance test" 1. The [http task](../user-guide/tasks/http.md) can be configured with load related parameters such as the number of requests, queries per second, or number of parallel connections. diff --git a/docs/user-guide/topics/install.md b/docs/user-guide/topics/install.md new file mode 100644 index 00000000..dc376282 --- /dev/null +++ b/docs/user-guide/topics/install.md @@ -0,0 +1,34 @@ +Iter8 can be installed and configured to watch resources either in a single namespace (namespace scoped) or in the whole cluster (cluster scoped). + +## Install with `helm` + +=== "Namespace scoped" + ```shell + helm install --repo https://iter8-tools.github.io/iter8 --version 0.18 iter8 controller + ``` + +=== "Cluster scoped" + ```shell + helm install --repo https://iter8-tools.github.io/iter8 --version 0.18 iter8 controller \ + --set clusterScoped=true + ``` + +To install Iter8 in a non-default namespace, use the `-n` option. + +## Install with `kustomize` + +=== "Namespace scoped" + ```shell + kubectl apply -k 'https://github.com/iter8-tools/iter8.git/kustomize/controller/namespaceScoped?ref=v0.18.3' + ``` + +=== "Cluster scoped" + ```shell + kubectl apply -k 'https://github.com/iter8-tools/iter8.git/kustomize/controller/clusterScoped?ref=v0.18.3' + ``` + +To install Iter8 in a non-default namespace, download the kustomize folder and modify the `namespace` field in the `kustomization.yaml` file. + +## Install on OpenDataHub + +See [https://github.com/opendatahub-io-contrib/odh-contrib-manifests/tree/main/iter8](https://github.com/opendatahub-io-contrib/odh-contrib-manifests/tree/main/iter8) \ No newline at end of file diff --git a/docs/user-guide/topics/uninstall.md b/docs/user-guide/topics/uninstall.md new file mode 100644 index 00000000..5c2ffc25 --- /dev/null +++ b/docs/user-guide/topics/uninstall.md @@ -0,0 +1,25 @@ +--- +template: main.html +--- + +## Uninstall with `helm` + +If installed with `helm`, uninstall with: + +```shell +helm delete iter8 +``` + +## Uninstall with `kustomize` + +If installed with `kustomize` uninstall with one of the following: + +=== "Namespace scoped" + ```shell + kubectl delete -k 'https://github.com/iter8-tools/iter8.git/kustomize/controller/namespaceScoped?ref=v0.18.3' + ``` + +=== "Cluster scoped" + ```shell + kubectl delete -k 'https://github.com/iter8-tools/iter8.git/kustomize/controller/clusterScoped?ref=v0.18.3' + ``` diff --git a/mkdocs.yml b/mkdocs.yml index 53e2cf22..535633bf 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -117,7 +117,6 @@ nav: - Your first A/B test: getting-started/first-abn.md - Your first performance test: getting-started/first-performance.md - Concepts: getting-started/concepts.md - - Install the Iter8 controller: tutorials/installiter8controller.md - Get help: getting-started/help.md - Tutorials: - Automated routing: tutorials/automated-routing.md @@ -146,15 +145,17 @@ nav: - Slack: tutorials/integrations/slack.md - User guide: - Tasks: - - grpc: user-guide/tasks/grpc.md - http: user-guide/tasks/http.md + - grpc: user-guide/tasks/grpc.md + - ready: user-guide/tasks/ready.md - github: user-guide/tasks/github.md - slack: user-guide/tasks/slack.md - - ready: user-guide/tasks/ready.md - Topics: - Test parameters: user-guide/topics/parameters.md - A/B/n testing: user-guide/topics/ab_testing.md - Controller extensions: user-guide/topics/extensions.md + - Install options: user-guide/topics/install.md + - Uninstall options: user-guide/topics/uninstall.md - Contributing: contributing.md - Roadmap: roadmap.md - Community: From c9a225df12398998c393419f61e0c21afb14aaad Mon Sep 17 00:00:00 2001 From: Michael Kalantar Date: Fri, 22 Sep 2023 16:29:59 -0400 Subject: [PATCH 02/12] update wordlist Signed-off-by: Michael Kalantar --- .github/wordlist.txt | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.github/wordlist.txt b/.github/wordlist.txt index ecd1a4cd..a3a72ac9 100644 --- a/.github/wordlist.txt +++ b/.github/wordlist.txt @@ -184,3 +184,6 @@ Autoscaling composable Hyperparameter LLM +odh +contrib +opendatahub \ No newline at end of file From b1eda4999697275b4b53091ac954b453c58d0e20 Mon Sep 17 00:00:00 2001 From: Michael Kalantar Date: Fri, 22 Sep 2023 17:01:19 -0400 Subject: [PATCH 03/12] clarify differences in candidate Signed-off-by: Michael Kalantar --- docs/getting-started/first-routing.md | 4 ++-- docs/tutorials/integrations/kserve-mm/abn.md | 8 ++++---- docs/tutorials/integrations/kserve-mm/blue-green.md | 8 ++++---- docs/tutorials/integrations/kserve-mm/canary.md | 8 ++++---- docs/tutorials/integrations/kserve/abn-grpc.md | 8 ++++---- docs/tutorials/integrations/kserve/abn-http.md | 8 ++++---- docs/tutorials/integrations/kserve/blue-green.md | 6 +++--- docs/tutorials/integrations/kserve/canary.md | 8 ++++---- 8 files changed, 29 insertions(+), 29 deletions(-) diff --git a/docs/getting-started/first-routing.md b/docs/getting-started/first-routing.md index f53c99c7..cb865e7d 100644 --- a/docs/getting-started/first-routing.md +++ b/docs/getting-started/first-routing.md @@ -121,7 +121,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, image is the same as 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 @@ -183,7 +183,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 diff --git a/docs/tutorials/integrations/kserve-mm/abn.md b/docs/tutorials/integrations/kserve-mm/abn.md index e4d7d5e1..0b4b8f6d 100644 --- a/docs/tutorials/integrations/kserve-mm/abn.md +++ b/docs/tutorials/integrations/kserve-mm/abn.md @@ -64,7 +64,7 @@ A sample application using the Iter8 SDK is provided. Deploy both the frontend a ``` ??? note "About the primary `InferenceService`" - The base name (`backend`) and version (`v0`) are identified using the labels `app.kubernets.io/name` and `app.kubernets.io/version`, respectively. These labels are not required. + The base name (`backend`) and version (`v0`) are identified using the labels `app.kubernetes.io/name` and `app.kubernetes.io/version`, respectively. These labels are not required. Naming the instance with the suffix `-0` (and the candidate with the suffix `-1`) simplifies describing the application (see below). However, any name can be specified. @@ -138,8 +138,8 @@ spec: EOF ``` -??? note "About the candidate `InferenceService`" - In this tutorial, the model source (field `spec.predictor.model.storageUri`) is the same as for the primary version of the model. In a real example, this would be different. +??? note "About the candidate" + In this tutorial, the model source (field `spec.predictor.model.storageUri`) is the same as for the primary version of the model. In a real example, this would be different. The version label (`app.kubernetes.io/version`) can be used to distinguish between versions. Until the candidate version is ready, calls to `Lookup()` will return only the version number `0`; the primary version of the model. Once the candidate version is ready, `Lookup()` will return both version numbers (`0` and `1`) so that requests can be distributed across versions. @@ -196,7 +196,7 @@ EOF ``` ??? note "What is different?" - The version label (`app.kubernets.io/version`) was updated. In a real world example, `spec.predictor.model.storageUri` would also be updated. + The version label (`app.kubernetes.io/version`) was updated. In a real world example, `spec.predictor.model.storageUri` would also be updated. ### Delete candidate diff --git a/docs/tutorials/integrations/kserve-mm/blue-green.md b/docs/tutorials/integrations/kserve-mm/blue-green.md index 8cd696b0..981c2ce3 100644 --- a/docs/tutorials/integrations/kserve-mm/blue-green.md +++ b/docs/tutorials/integrations/kserve-mm/blue-green.md @@ -53,7 +53,7 @@ EOF ``` ??? note "About the primary `InferenceService`" - The base name (`wisdom`) and version (`v0`) are identified using the labels `app.kubernets.io/name` and `app.kubernets.io/version`, respectively. These labels are not required. + The base name (`wisdom`) and version (`v0`) are identified using the labels `app.kubernetes.io/name` and `app.kubernetes.io/version`, respectively. These labels are not required. Naming the instance with the suffix `-0` (and the candidate with the suffix `-1`) simplifies the routing initialization (see below). However, any name can be specified. @@ -163,8 +163,8 @@ spec: EOF ``` -??? note "About the candidate `InferenceService`" - In this tutorial, the model source (field `spec.predictor.model.storageUri`) is the same as for the primary version of the model. In a real world example, this would be different. +??? note "About the candidate" + In this tutorial, the model source (field `spec.predictor.model.storageUri`) is the same as for the primary version of the model. In a real world example, this would be different. The version label (`app.kubernetes.io/version`) can be used to distinguish between versions. ## Verify routing changes @@ -238,7 +238,7 @@ EOF ``` ??? note "What is different?" - The version label (`app.kubernets.io/version`) was updated. In a real world example, `spec.predictor.model.storageUri` would also be updated. + The version label (`app.kubernetes.io/version`) was updated. In a real world example, `spec.predictor.model.storageUri` would also be updated. ### Delete candidate diff --git a/docs/tutorials/integrations/kserve-mm/canary.md b/docs/tutorials/integrations/kserve-mm/canary.md index 2d3bf029..79ef8cc8 100644 --- a/docs/tutorials/integrations/kserve-mm/canary.md +++ b/docs/tutorials/integrations/kserve-mm/canary.md @@ -53,7 +53,7 @@ EOF ``` ??? note "About the primary `InferenceService`" - The base name (`wisdom`) and version (`v0`) are identified using the labels `app.kubernets.io/name` and `app.kubernets.io/version`, respectively. These labels are not required. + The base name (`wisdom`) and version (`v0`) are identified using the labels `app.kubernetes.io/name` and `app.kubernetes.io/version`, respectively. These labels are not required. Naming the instance with the suffix `-0` (and the candidate with the suffix `-1`) simplifies the routing initialization (see below). However, any name can be specified. @@ -170,8 +170,8 @@ spec: EOF ``` -??? note "About the candidate `InferenceService`" - In this tutorial, the model source (field `spec.predictor.model.storageUri`) is the same as for the primary version of the model. In a real example, this would be different. +??? note "About the candidate" + In this tutorial, the model source (field `spec.predictor.model.storageUri`) is the same as for the primary version of the model. In a real example, this would be different. The version label (`app.kubernetes.io/version`) can be used to distinguish between versions. ## Verify routing changes @@ -212,7 +212,7 @@ EOF ``` ??? note "What is different?" - The version label (`app.kubernets.io/version`) was updated. In a real world example, `spec.predictor.model.storageUri` would also be updated. + The version label (`app.kubernetes.io/version`) was updated. In a real world example, `spec.predictor.model.storageUri` would also be updated. ### Delete candidate diff --git a/docs/tutorials/integrations/kserve/abn-grpc.md b/docs/tutorials/integrations/kserve/abn-grpc.md index c552baa4..c5c9d415 100644 --- a/docs/tutorials/integrations/kserve/abn-grpc.md +++ b/docs/tutorials/integrations/kserve/abn-grpc.md @@ -67,7 +67,7 @@ A sample application using the Iter8 SDK is provided. Deploy both the frontend a ``` ??? note "About the primary `InferenceService`" - The base name (`backend`) and version (`v0`) are identified using the labels `app.kubernets.io/name` and `app.kubernets.io/version`, respectively. These labels are not required. + The base name (`backend`) and version (`v0`) are identified using the labels `app.kubernetes.io/name` and `app.kubernetes.io/version`, respectively. These labels are not required. Naming the instance with the suffix `-0` (and the candidate with the suffix `-1`) simplifies describing the application (see below). However, any name can be specified. @@ -144,8 +144,8 @@ spec: EOF ``` -??? note "About the candidate `InferenceService`" - In this tutorial, the model source (field `spec.predictor.model.storageUri`) is the same as for the primary version of the model. In a real example, this would be different. +??? note "About the candidate" + In this tutorial, the model source (field `spec.predictor.model.storageUri`) is the same as for the primary version of the model. In a real example, this would be different. The version label (`app.kubernetes.io/version`) can be used to distinguish between versions. Until the candidate version is ready, calls to `Lookup()` will return only the version number `0`; the primary version of the model. Once the candidate version is ready, `Lookup()` will return both version numbers (`0` and `1`) so that requests can be distributed across versions. @@ -205,7 +205,7 @@ EOF ``` ??? note "What is different?" - The version label (`app.kubernets.io/version`) was updated. In a real world example, `spec.predictor.model.storageUri` would also be updated. + The version label (`app.kubernetes.io/version`) was updated. In a real world example, `spec.predictor.model.storageUri` would also be updated. ### Delete candidate diff --git a/docs/tutorials/integrations/kserve/abn-http.md b/docs/tutorials/integrations/kserve/abn-http.md index 03ccb039..88308a75 100644 --- a/docs/tutorials/integrations/kserve/abn-http.md +++ b/docs/tutorials/integrations/kserve/abn-http.md @@ -62,7 +62,7 @@ A sample application using the Iter8 SDK is provided. Deploy both the frontend a ``` ??? note "About the primary `InferenceService`" - The base name (`backend`) and version (`v0`) are identified using the labels `app.kubernets.io/name` and `app.kubernets.io/version`, respectively. These labels are not required. + The base name (`backend`) and version (`v0`) are identified using the labels `app.kubernetes.io/name` and `app.kubernetes.io/version`, respectively. These labels are not required. Naming the instance with the suffix `-0` (and the candidate with the suffix `-1`) simplifies describing the application (see below). However, any name can be specified. @@ -134,8 +134,8 @@ spec: EOF ``` -??? note "About the candidate `InferenceService`" - In this tutorial, the model source (field `spec.predictor.model.storageUri`) is the same as for the primary version of the model. In a real example, this would be different. +??? note "About the candidate" + In this tutorial, the model source (field `spec.predictor.model.storageUri`) is the same as for the primary version of the model. In a real example, this would be different. The version label (`app.kubernetes.io/version`) can be used to distinguish between versions. Until the candidate version is ready, calls to `Lookup()` will return only the version number `0`; the primary version of the model. Once the candidate version is ready, `Lookup()` will return both version numbers (`0` and `1`) so that requests can be distributed across versions. @@ -190,7 +190,7 @@ EOF ``` ??? note "What is different?" - The version label (`app.kubernets.io/version`) was updated. In a real world example, `spec.predictor.model.storageUri` would also be updated. + The version label (`app.kubernetes.io/version`) was updated. In a real world example, `spec.predictor.model.storageUri` would also be updated. ### Delete candidate diff --git a/docs/tutorials/integrations/kserve/blue-green.md b/docs/tutorials/integrations/kserve/blue-green.md index 125e0128..689624ee 100644 --- a/docs/tutorials/integrations/kserve/blue-green.md +++ b/docs/tutorials/integrations/kserve/blue-green.md @@ -50,7 +50,7 @@ EOF ``` ??? note "About the primary" - The base name (`wisdom`) and version (`v0`) are identified using the labels `app.kubernets.io/name` and `app.kubernets.io/version`, respectively. These labels are not required. + The base name (`wisdom`) and version (`v0`) are identified using the labels `app.kubernetes.io/name` and `app.kubernetes.io/version`, respectively. These labels are not required. Naming the instance with the suffix `-0` (and the candidate with the suffix `-1`) simplifies the routing initialization (see below). However, any name can be specified. @@ -157,7 +157,7 @@ EOF ``` ??? note "About the candidate" - In this tutorial, the model source (field `spec.predictor.model.storageUri`) is the same as for the primary version of the model. In a real world example, this would be different. + In this tutorial, the model source (field `spec.predictor.model.storageUri`) is the same as for the primary version of the model. In a real world example, this would be different. The version label (`app.kubernetes.io/version`) can be used to distinguish between versions. ## Verify routing changes @@ -234,7 +234,7 @@ EOF ``` ??? note "What is different?" - The version label (`app.kubernets.io/version`) was updated. In a real world example, `spec.predictor.model.storageUri` would also be updated. + The version label (`app.kubernetes.io/version`) was updated. In a real world example, `spec.predictor.model.storageUri` would also be updated. ### Delete candidate diff --git a/docs/tutorials/integrations/kserve/canary.md b/docs/tutorials/integrations/kserve/canary.md index 0f47c903..7a687daf 100644 --- a/docs/tutorials/integrations/kserve/canary.md +++ b/docs/tutorials/integrations/kserve/canary.md @@ -50,7 +50,7 @@ EOF ``` ??? note "About the primary `InferenceService`" - The base name (`wisdom`) and version (`v0`) are identified using the labels `app.kubernets.io/name` and `app.kubernets.io/version`, respectively. These labels are not required. + The base name (`wisdom`) and version (`v0`) are identified using the labels `app.kubernetes.io/name` and `app.kubernetes.io/version`, respectively. These labels are not required. Naming the instance with the suffix `-0` (and the candidate with the suffix `-1`) simplifies the routing initialization (see below). However, any name can be specified. @@ -159,8 +159,8 @@ spec: EOF ``` -??? note "About the candidate `InferenceService`" - In this tutorial, the model source (field `spec.predictor.model.storageUri`) is the same as for the primary version of the model. In a real world example, this would be different. +??? note "About the candidate" + In this tutorial, the model source (field `spec.predictor.model.storageUri`) is the same as for the primary version of the model. In a real world example, this would be different. The version label (`app.kubernetes.io/version`) can be used to distinguish between versions. ## Verify routing changes @@ -200,7 +200,7 @@ EOF ``` ??? note "What is different?" - The version label (`app.kubernets.io/version`) was updated. In a real world example, `spec.predictor.model.storageUri` would also be updated. + The version label (`app.kubernetes.io/version`) was updated. In a real world example, `spec.predictor.model.storageUri` would also be updated. ### Delete candidate From 2956ec4cd29039c1ec4c43c9b98ab1d5d4cc8e0b Mon Sep 17 00:00:00 2001 From: Michael Kalantar Date: Tue, 26 Sep 2023 09:05:30 -0400 Subject: [PATCH 04/12] routemap for abn Signed-off-by: Michael Kalantar --- CONTRIBUTING.md | 3 +- docs/getting-started/concepts.md | 2 +- docs/getting-started/first-abn.md | 54 ++++++++----------- docs/getting-started/first-routing.md | 5 +- docs/tutorials/integrations/kserve-mm/abn.md | 43 ++++++--------- .../tutorials/integrations/kserve/abn-grpc.md | 45 ++++++---------- .../tutorials/integrations/kserve/abn-http.md | 47 +++++++--------- .../integrations/kserve/blue-green.md | 4 +- docs/tutorials/integrations/kserve/canary.md | 6 +-- docs/tutorials/integrations/kserve/grpc.md | 2 +- docs/tutorials/integrations/kserve/http.md | 2 +- docs/user-guide/topics/extensions.md | 2 +- 12 files changed, 85 insertions(+), 130 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6a21d585..e7158f88 100644 --- a/CONTRIBUTING.md +++ b/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 ``` diff --git a/docs/getting-started/concepts.md b/docs/getting-started/concepts.md index 04a97295..c3ddbbd3 100644 --- a/docs/getting-started/concepts.md +++ b/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). The identification of the resources that make up a version is declarative. The set of resource types that can be referenced, is easy to [declaratively extend](../user-guide/topics/extensions.md). Note that this same extension mechanism 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. diff --git a/docs/getting-started/first-abn.md b/docs/getting-started/first-abn.md index a0c79792..918d5c71 100644 --- a/docs/getting-started/first-abn.md +++ b/docs/getting-started/first-abn.md @@ -55,44 +55,25 @@ 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 a routing template. To create the routemap: ```shell -cat <A simple HTTP Request & 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. diff --git a/docs/tutorials/integrations/kserve-mm/abn.md b/docs/tutorials/integrations/kserve-mm/abn.md index 0b4b8f6d..95ca8773 100644 --- a/docs/tutorials/integrations/kserve-mm/abn.md +++ b/docs/tutorials/integrations/kserve-mm/abn.md @@ -72,42 +72,26 @@ 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 backend 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 a routing template. To create the routemap: ```shell -cat < Date: Tue, 26 Sep 2023 09:17:19 -0400 Subject: [PATCH 05/12] update wordlist Signed-off-by: Michael Kalantar --- .github/wordlist.txt | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/wordlist.txt b/.github/wordlist.txt index a3a72ac9..31c1fd0c 100644 --- a/.github/wordlist.txt +++ b/.github/wordlist.txt @@ -10,6 +10,7 @@ Cha chaosengine CLI CLIs +CRD cronjob crontab ConfigMap @@ -67,6 +68,7 @@ protobuf protoc quickstart roadmap +routemap scikit SDK sed From bd1955103562cb12519d24f7ca8bbdd722781452 Mon Sep 17 00:00:00 2001 From: Michael Kalantar Date: Tue, 26 Sep 2023 09:19:37 -0400 Subject: [PATCH 06/12] fix spelling Signed-off-by: Michael Kalantar --- docs/tutorials/integrations/kserve-mm/abn.md | 2 +- docs/tutorials/integrations/kserve/abn-grpc.md | 2 +- docs/tutorials/integrations/kserve/abn-http.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/tutorials/integrations/kserve-mm/abn.md b/docs/tutorials/integrations/kserve-mm/abn.md index 95ca8773..be9c861c 100644 --- a/docs/tutorials/integrations/kserve-mm/abn.md +++ b/docs/tutorials/integrations/kserve-mm/abn.md @@ -83,7 +83,7 @@ strategy: none EOF ``` -The `initialize` action (with strategy `none`) configures a routemap without a routing template. That is, it only defines the reosurces that make up each version of the application. In this case, a single `InferenceService`. +The `initialize` action (with strategy `none`) configures a routemap without a routing template. That is, it only defines the resources that make up each version of the application. In this case, a single `InferenceService`. Since no version specific naming is provided, the primary version is expected to be named `backend-0` and any candidate version `backend-1`. 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 diff --git a/docs/tutorials/integrations/kserve/abn-grpc.md b/docs/tutorials/integrations/kserve/abn-grpc.md index bf896fb4..9f12af09 100644 --- a/docs/tutorials/integrations/kserve/abn-grpc.md +++ b/docs/tutorials/integrations/kserve/abn-grpc.md @@ -86,7 +86,7 @@ strategy: none EOF ``` -The `initialize` action (with strategy `none`) configures a routemap without a routing template. That is, it only defines the reosurces that make up each version of the application. In this case, a single `InferenceService`. +The `initialize` action (with strategy `none`) configures a routemap without a routing template. That is, it only defines the resources that make up each version of the application. In this case, a single `InferenceService`. Since no version specific naming is provided, the primary version is expected to be named `backend-0` and any candidate version `backend-1`. 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 diff --git a/docs/tutorials/integrations/kserve/abn-http.md b/docs/tutorials/integrations/kserve/abn-http.md index c1a8b8c7..d1bc6a1a 100644 --- a/docs/tutorials/integrations/kserve/abn-http.md +++ b/docs/tutorials/integrations/kserve/abn-http.md @@ -81,7 +81,7 @@ strategy: none EOF ``` -The `initialize` action (with strategy `none`) configures a routemap without a routing template. That is, it only defines the reosurces that make up each version of the application. In this case, a single `InferenceService`. +The `initialize` action (with strategy `none`) configures a routemap without a routing template. That is, it only defines the resources that make up each version of the application. In this case, a single `InferenceService`. Since no version specific naming is provided, the primary version is expected to be named `backend-0` and any candidate version `backend-1`. 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 From b3f77eb522f2f0134153a24c425dd32607894f09 Mon Sep 17 00:00:00 2001 From: Michael Kalantar Date: Tue, 26 Sep 2023 14:04:43 -0400 Subject: [PATCH 07/12] update for null strategy Signed-off-by: Michael Kalantar --- docs/getting-started/first-abn.md | 2 -- docs/getting-started/first-routing.md | 2 -- docs/tutorials/integrations/kserve-mm/abn.md | 2 -- docs/tutorials/integrations/kserve/abn-grpc.md | 2 -- docs/tutorials/integrations/kserve/abn-http.md | 2 -- docs/tutorials/integrations/kserve/blue-green.md | 2 -- 6 files changed, 12 deletions(-) diff --git a/docs/getting-started/first-abn.md b/docs/getting-started/first-abn.md index 918d5c71..17ac9b7e 100644 --- a/docs/getting-started/first-abn.md +++ b/docs/getting-started/first-abn.md @@ -62,7 +62,6 @@ cat <A simple HTTP Request & Response Service. ``` `httpbin-1` output: ``` HTTP/1.1 200 OK app-version: httpbin-1 -

A simple HTTP Request & Response Service. ``` ## Modify weights (optional) diff --git a/docs/tutorials/integrations/kserve-mm/abn.md b/docs/tutorials/integrations/kserve-mm/abn.md index be9c861c..535b1437 100644 --- a/docs/tutorials/integrations/kserve-mm/abn.md +++ b/docs/tutorials/integrations/kserve-mm/abn.md @@ -79,7 +79,6 @@ cat <A simple HTTP Request & Response Service. ``` `wisdom-1` output: ``` HTTP/1.1 200 OK app-version: wisdom-1 -

A simple HTTP Request & Response Service. ``` ## Modify weights (optional) From 8c0d18c67d4ba47f18dc158b89fdb7074756d535 Mon Sep 17 00:00:00 2001 From: Michael Kalantar Date: Tue, 26 Sep 2023 14:50:24 -0400 Subject: [PATCH 08/12] routemap topic Signed-off-by: Michael Kalantar --- docs/user-guide/topics/routemap.md | 87 ++++++++++++++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 88 insertions(+) create mode 100644 docs/user-guide/topics/routemap.md diff --git a/docs/user-guide/topics/routemap.md b/docs/user-guide/topics/routemap.md new file mode 100644 index 00000000..cf27919b --- /dev/null +++ b/docs/user-guide/topics/routemap.md @@ -0,0 +1,87 @@ +--- +template: main.html +--- + +# Routemaps + +A _routemap_ contains a description of each version of an application and may contain one or more routing templates. The description of versions is used by Iter8 to identify which versions of the application are available at any moment. Whenever versions become avaiable or disappear, any routing templates are applied allowing the routing to be automatically reconfigured. + +## Version list + +A version is a list of resources that, when available and ready, indicate that the version is available. For example, the following describes a application with 2 versions. In this case, each version has a `Service` and a `Deployment` object. In one version, each has the name `httpbin-0`; in the other, `httpbin-1`: + +```yaml +versions: +- resources: + - gvrShort: svc + name: httpbin-0 + namespace: default + - gvrShort: deploy + name: httpbin-0 + namespace: default +- resources: + - gvrShort: svc + name: httpbin-1 + namespace: default + - gvrShort: deploy + name: httpbin-1 + namespace: default +``` + +Note that the resources types are specified using a short name. In this example, `svc` and `deploy`. A short name is used to simplify the specification of the resources in a version. A mapping of short name to Kubernetes Group, Version, Resource is captured in the configuration of the Iter8 controller. This set can be [extended](extensions.md) to include any types including custom resources; that is, those defined by a CRD. + +A version may optionally specify an integer `weight` indicating the propotion of traffic that should be sent to this version relative to other versions. + +## Routing templates + +A routing template is a go template that is applied each time a version becomes available goes away. Multiple templates can be defined/applied. + +THe application of the templates allows Iter8 to automatically reconfigure the routing when versions come and go. For example, the template created by the `initialize` action in the [automated blue-green rollout tutorial](../../getting-started/first-routing.md#routing) is for an Istio `VirtualService`. Applying the template to the available versions yields the necessesary `VirtualSerivce` definition. The template definition is as follows: + +```yaml +blue-green: + gvrShort: vs + template: | + apiVersion: networking.istio.io/v1beta1 + kind: VirtualService + metadata: + name: httpbin + spec: + gateways: + - mm-gateway + - mesh + hosts: + - httpbin.default + - httpbin.default.svc + - httpbin.default.svc.cluster.local + http: + - route: + # primary version + - destination: + host: httpbin-0.default.svc.cluster.local + {{- if gt (index .Weights 1) 0 }} + weight: {{ index .Weights 0 }} + {{- end }} + headers: + response: + add: + app-version: httpbin-0 + # other versions + {{- if gt (index .Weights 1) 0 }} + - destination: + host: httpbin-1.default.svc.cluster.local + weight: {{ index .Weights 1 }} + headers: + response: + add: + app-version: httpbin-1 + {{- end }} +``` + +## Implementation + +A routemap is implemented as an immutable `ConfigMap` with the following labels: +- `iter8.tools/kind` with value `routemap` +- `iter8.tools/version` with value corresponding the version of the controller being used + +The list of versions and routing templates are stored as stringified yaml. \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 535633bf..3cc95387 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -154,6 +154,7 @@ nav: - Test parameters: user-guide/topics/parameters.md - A/B/n testing: user-guide/topics/ab_testing.md - Controller extensions: user-guide/topics/extensions.md + - Routemaps: user-guide/topics/routemap.md - Install options: user-guide/topics/install.md - Uninstall options: user-guide/topics/uninstall.md - Contributing: contributing.md From 6b43cc83d509a90ac267ba32c8ef795e5744d62e Mon Sep 17 00:00:00 2001 From: Michael Kalantar Date: Tue, 26 Sep 2023 15:11:36 -0400 Subject: [PATCH 09/12] spelling Signed-off-by: Michael Kalantar --- .github/wordlist.txt | 2 ++ docs/user-guide/topics/routemap.md | 6 +++--- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/.github/wordlist.txt b/.github/wordlist.txt index 31c1fd0c..fa7a87bd 100644 --- a/.github/wordlist.txt +++ b/.github/wordlist.txt @@ -69,6 +69,7 @@ protoc quickstart roadmap routemap +Routemaps scikit SDK sed @@ -82,6 +83,7 @@ SRE Srinivasan subdirectory Sysdig +stringified tada Tekton toc diff --git a/docs/user-guide/topics/routemap.md b/docs/user-guide/topics/routemap.md index cf27919b..d1e57876 100644 --- a/docs/user-guide/topics/routemap.md +++ b/docs/user-guide/topics/routemap.md @@ -4,7 +4,7 @@ template: main.html # Routemaps -A _routemap_ contains a description of each version of an application and may contain one or more routing templates. The description of versions is used by Iter8 to identify which versions of the application are available at any moment. Whenever versions become avaiable or disappear, any routing templates are applied allowing the routing to be automatically reconfigured. +A _routemap_ contains a description of each version of an application and may contain one or more routing templates. The description of versions is used by Iter8 to identify which versions of the application are available at any moment. Whenever versions become available or disappear, any routing templates are applied allowing the routing to be automatically reconfigured. ## Version list @@ -30,13 +30,13 @@ versions: Note that the resources types are specified using a short name. In this example, `svc` and `deploy`. A short name is used to simplify the specification of the resources in a version. A mapping of short name to Kubernetes Group, Version, Resource is captured in the configuration of the Iter8 controller. This set can be [extended](extensions.md) to include any types including custom resources; that is, those defined by a CRD. -A version may optionally specify an integer `weight` indicating the propotion of traffic that should be sent to this version relative to other versions. +A version may optionally specify an integer `weight` indicating the proportion of traffic that should be sent to this version relative to other versions. ## Routing templates A routing template is a go template that is applied each time a version becomes available goes away. Multiple templates can be defined/applied. -THe application of the templates allows Iter8 to automatically reconfigure the routing when versions come and go. For example, the template created by the `initialize` action in the [automated blue-green rollout tutorial](../../getting-started/first-routing.md#routing) is for an Istio `VirtualService`. Applying the template to the available versions yields the necessesary `VirtualSerivce` definition. The template definition is as follows: +THe application of the templates allows Iter8 to automatically reconfigure the routing when versions come and go. For example, the template created by the `initialize` action in the [automated blue-green rollout tutorial](../../getting-started/first-routing.md#routing) is for an Istio `VirtualService`. Applying the template to the available versions yields the necessary `VirtualSerivce` definition. The template definition is as follows: ```yaml blue-green: From af576ae080dee86e9f1312e257e03ad616743704 Mon Sep 17 00:00:00 2001 From: Michael Kalantar Date: Tue, 26 Sep 2023 15:31:59 -0400 Subject: [PATCH 10/12] update roadmap Signed-off-by: Michael Kalantar --- docs/roadmap.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/roadmap.md b/docs/roadmap.md index bb90495d..188904ba 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -9,7 +9,8 @@ hide: 1. Stabilizing Iter8 APIs for CNCF sandboxing 2. Autoscaling the metrics service -3. Open Data Hub tier 1 project -4. Metrics & evaluation for foundation model/LLM-based apps -5. Hyperparameter tuning for foundation model/LLM-based inference pipelines -6. Data/concept drift detection for ML models \ No newline at end of file +3. Infrastructure and application templates +4. Open Data Hub tier 1 project +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 \ No newline at end of file From 1a7a12285a844648ea5809a10cb507d996f7088a Mon Sep 17 00:00:00 2001 From: Michael Kalantar Date: Tue, 26 Sep 2023 16:48:05 -0400 Subject: [PATCH 11/12] roadmap Signed-off-by: Michael Kalantar --- docs/roadmap.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/docs/roadmap.md b/docs/roadmap.md index 188904ba..61361bd5 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -9,8 +9,11 @@ hide: 1. Stabilizing Iter8 APIs for CNCF sandboxing 2. Autoscaling the metrics service -3. Infrastructure and application templates -4. Open Data Hub tier 1 project -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 \ No newline at end of file +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 \ No newline at end of file From ed3002c4b4de3b52923d421a061d4cec309fac27 Mon Sep 17 00:00:00 2001 From: Michael Kalantar Date: Fri, 29 Sep 2023 09:59:54 -0400 Subject: [PATCH 12/12] refine based on feedback Signed-off-by: Michael Kalantar --- docs/getting-started/concepts.md | 2 +- docs/getting-started/first-abn.md | 7 ++++--- docs/getting-started/first-routing.md | 2 +- docs/tutorials/integrations/kserve-mm/abn.md | 11 ++++++----- docs/tutorials/integrations/kserve-mm/blue-green.md | 2 +- docs/tutorials/integrations/kserve-mm/canary.md | 2 +- docs/tutorials/integrations/kserve/abn-grpc.md | 9 +++++---- docs/tutorials/integrations/kserve/abn-http.md | 9 +++++---- docs/tutorials/integrations/kserve/blue-green.md | 2 +- docs/tutorials/integrations/kserve/canary.md | 2 +- docs/user-guide/topics/install.md | 2 +- docs/user-guide/topics/routemap.md | 12 ++++++------ docs/user-guide/topics/uninstall.md | 2 +- 13 files changed, 34 insertions(+), 30 deletions(-) diff --git a/docs/getting-started/concepts.md b/docs/getting-started/concepts.md index c3ddbbd3..c4fe4515 100644 --- a/docs/getting-started/concepts.md +++ b/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. This includes custom resources; that is, those defined by a custom resource definition (CRD). The identification of the resources that make up a version is declarative. The set of resource types that can be referenced, is easy to [declaratively extend](../user-guide/topics/extensions.md). Note that 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. diff --git a/docs/getting-started/first-abn.md b/docs/getting-started/first-abn.md index 17ac9b7e..986f6039 100644 --- a/docs/getting-started/first-abn.md +++ b/docs/getting-started/first-abn.md @@ -55,7 +55,7 @@ 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 _routemap_ is created to do this. A routemap contains a description of each version of an application and may contain a routing template. To create the routemap: +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 <