Install

mkdocs/docs/concepts/features.md

@@ -20,4 +20,4 @@ Iter8 makes it easy to achieve the following goals.
 
 
 [^1]: An initial version of Iter8 for KFServing is available [here](https://github.com/iter8-tools/iter8-kfserving). An updated version is coming soon.
-[^2]: An earlier version of Iter8 for Istio is available [here](https://github.com/iter8-tools/iter8). An updated version is coming soon.
+[^2]: An earlier version of Iter8 for Istio is available [here](https://github.com/iter8-tools/iter8-istio). An updated version is coming soon.

mkdocs/docs/contributing.md

@@ -5,7 +5,6 @@ hide:
 ---
 
 # Contributing
-
 We are delighted that you are considering a contribution to Iter8!
 
 Please discuss the change you wish to make using [issues](https://github.com/iter8-tools/iter8/issues), [discussions](https://github.com/iter8-tools/iter8/discussions), or the [Iter8 slack workspace](https://iter8-tools.slack.com) before submitting your PR.
@@ -15,43 +14,27 @@ Iter8 documentation is built using [mkdocs for material](https://squidfunk.githu
 
 **Pre-requisite:** [Node.js 15+](https://nodejs.org/en/)
 
-**Note:** Fork the Iter8 repo, clone your fork, and `npm run build`. This step is usually required only for the first time you work with Iter8 docs locally.
+**Note:** Fork Iter8 repo, clone your fork, and run the commands below. This step is required to build Iter8 docs for the first time. This step is required after you change static assets like images. This step is *not* required if you only change .md files or `mkdocs.yml`.
 
 ```shell
-git clone [email protected]:<your-github-account>/iter8.git
 cd iter8/mkdocs
 git update-index --assume-unchanged package-lock.json
 npm run build
 ```
 
 ## Locally serving Iter8 docs
-
-**Pre-requisite:** Python 3+. You may find it useful to setup and activate a Python 3+ virtual environment as follows. The `.venv` folder contains the virtual environment.
+**Pre-requisite:** Python 3+. Setup, activate, and use a Python 3+ virtual environment as follows.
 
 ```shell
 python3 -m venv .venv
 source .venv/bin/activate
-```
-
-**Note:** the pip install below is usually required only for the first time you serve Iter8 docs locally.
-
-```shell
 pip install -r requirements.txt
-```
-
-```shell
 mkdocs serve -s
 ```
 
 Browse [http://localhost:8000](http://localhost:8000) to view your local Iter8 docs.
 
-<!-- ### Process for updating code artifacts
-YAMLs, scripts and other code artifacts that are part of code-samples are located under the `iter8/samples` folder. Changes to code artifacts are followed by a tagged release, so that versioned artifacts are available. -->
-
 ## Locally viewing live changes to Iter8 docs
-
-<!-- 1. While referring to code artifacts in docs (for example, a remote `kustomize` resource referenced in an experiment), use versioned artifacts. -->
-
 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.
 
 2. The markdown files for Iter8 docs are located under the `iter8/mkdocs/docs` folder.
@@ -63,4 +46,3 @@ All iter8 tutorials include e2e tests, either as [part of GitHub Actions workflo
 
 ## 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/getting-started/install.md

@@ -1,49 +1,91 @@
 ---
 template: overrides/main.html
-title: Install Iter8
+title: Installation
 ---
 
-=== "Iter8 for Knative"
-    Follow these steps to install Iter8 for Knative. 
+# Installation
 
+## Iter8
 
-    !!! example "Prerequisites"
-        1. Kubernetes cluster with [Knative Serving](https://knative.dev/docs/install/any-kubernetes-cluster/#installing-the-serving-component)
-        2. [`kubectl`](https://kubernetes.io/docs/tasks/tools/install-kubectl/)
-        3. [Kustomize v3](https://kubectl.docs.kubernetes.io/installation/kustomize/), and 
-        4. [Go 1.13+](https://golang.org/doc/install)
+!!! example "Prerequisites"
 
-    ## Step 1: Export TAG
-    ```shell
-    export TAG=v0.3.0-pre.4
-    ```
+    1. A Kubernetes cluster
+    2. [kubectl CLI](https://kubernetes.io/docs/tasks/tools/install-kubectl/)
+
+Install Iter8 in your Kubernetes cluster as follows.
 
-    ## Step 2: Install iter8-monitoring
+```shell
+export TAG=v0.3.0-pre.5
+curl -s https://raw.githubusercontent.com/iter8-tools/iter8-install/main/install.sh | bash
+```
+
+??? info "Look inside install.sh"
     ```shell
-    kustomize build github.com/iter8-tools/iter8/install/monitoring/prometheus-operator/?ref=${TAG} | kubectl apply -f -
+    #!/bin/bash
+
+    set -e
+
+    # Step 0: Export TAG
+    export TAG="${TAG:-v0.3.0-pre.5}"
+
+    # Step 1: Install Iter8
+    echo "Installing Iter8"
+    kubectl apply -f https://raw.githubusercontent.com/iter8-tools/iter8-install/${TAG}/core/build.yaml
     kubectl wait crd -l creator=iter8 --for condition=established --timeout=120s
-    kustomize build github.com/iter8-tools/iter8/install/monitoring/prometheus/?ref=${TAG} | kubectl apply -f - 
-    ```
+    kubectl apply -f https://raw.githubusercontent.com/iter8-tools/iter8-install/${TAG}/metrics/build.yaml
+
+    echo "Verifying Iter8 installation"
+    kubectl wait --for condition=ready --timeout=300s pods --all -n iter8-system
+
+    set +e
+    ```        
+
+## (Optional) Prometheus add-on
+
+Install Iter8's Prometheus add-on in your cluster as follows.
 
-    ## Step 3: Install Iter8
+```shell
+export TAG=v0.3.0-pre.5
+curl -s https://raw.githubusercontent.com/iter8-tools/iter8-install/main/install-prom-add-on.sh | bash
+```
+
+??? info "Look inside install-prom-add-on.sh"
     ```shell
-    kustomize build github.com/iter8-tools/iter8/install/?ref=${TAG} | kubectl apply -f -
+    #!/bin/bash
+
+    set -e
+
+    # Step 0: Export TAG
+    export TAG="${TAG:-v0.3.0-pre.5}"
+
+    # Step 1: Install Prometheus add-on
+    # This step assumes you have installed Iter8 using install.sh
+    echo "Installing Prometheus add-on"
+    kubectl apply -f https://raw.githubusercontent.com/iter8-tools/iter8-install/${TAG}/prometheus-add-on/prometheus-operator/build.yaml
     kubectl wait crd -l creator=iter8 --for condition=established --timeout=120s
-    kustomize build github.com/iter8-tools/iter8/install/iter8-metrics/?ref=${TAG} | kubectl apply -f -
-    ```
+    kubectl apply -f https://raw.githubusercontent.com/iter8-tools/iter8-install/${TAG}/prometheus-add-on/prometheus/build.yaml
+    kubectl apply -f https://raw.githubusercontent.com/iter8-tools/iter8-install/${TAG}/prometheus-add-on/service-monitors/build.yaml
 
-    ## Step 4: Install iter8ctl
-    ```shell
-    GO111MODULE=on GOBIN=/usr/local/bin go get github.com/iter8-tools/[email protected]
-    ```
+    echo "Verifying Prometheus-addon installation"
+    kubectl wait --for condition=ready --timeout=300s pods --all -n iter8-system
 
-    ## Optional: Customizing Iter8 install
+    set +e
+    ```
 
-    ### Prometheus URL
-    The URL of the Prometheus metrics backend is supplied as part of [this configmap](https://github.com/iter8-tools/iter8/blob/v0.2.5/install/iter8-analytics/config.yaml) during the install process. This URL is intended to match the location of the [iter8-monitoring install](#step-2-install-iter8-monitoring) above. To use your own Prometheus backend, replace the value of the metrics backend URL in the configmap during the install process with the URL of your Prometheus backend. You can use Kustomize or `sed` or any tool of your choice for this customization.
+??? note "Running Iter8 tutorials without this add-on"
+    When you installed Iter8 in the first step above, you also installed several *out-of-the-box* Iter8 metric resources. They are required for running the tutorials documented on this site. 
+
+    The out-of-the-box metric resources have a urlTemplate field. This field is configured as the URL of the Prometheus instance created in this step. 
 
-=== "Iter8 for KFServing"
-    An initial version of Iter8 for KFServing is available [here](https://github.com/iter8-tools/iter8-kfserving) along with installation instructions. An updated version is coming soon and will be documented here.
+    You can skip this step and still run Iter8 tutorials using your own Prometheus instance. To do so, ensure that your Prometheus instance scrapes the end-points that would have been scraped by the Prometheus instance created in this step, and configure the urlTemplate fields of Iter8 metric resources to the URL of your Prometheus instance.
+
+## (Optional) iter8ctl
+The iter8ctl CLI enables real-time observability of Iter8 experiments. 
+
+!!! example "Prerequisites"
+
+    Go 1.13+
 
-=== "Iter8 for Istio"
-    An earlier version of Iter8 for Istio is available [here](https://github.com/iter8-tools/iter8) along with installation instructions. An updated version is coming soon and will be documented here.
+```shell
+GO111MODULE=on GOBIN=/usr/local/bin go get github.com/iter8-tools/[email protected]
+```

mkdocs/docs/getting-started/quick-start/with-knative.md

@@ -19,8 +19,7 @@ template: overrides/main.html
 ???+ warning "Before you begin, you will need... "
     1. **Kubernetes cluster.** You can also install [Minikube](https://minikube.sigs.k8s.io/docs/) or [Kind](https://kind.sigs.k8s.io/).
     2. The **kubectl** CLI. Install [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/).
-    3. **Kustomize v3+**. Install [Kustomize](https://kubectl.docs.kubernetes.io/installation/kustomize/).
-    4. **Go 1.13+** (recommended; required for using `iter8ctl` in [Step 7](/getting-started/quick-start/with-knative/#7-observe-experiment)). Install [Go](https://golang.org/doc/install). 
+    3. **Go 1.13+** (recommended; required for using `iter8ctl` in [Step 7](/getting-started/quick-start/with-knative/#7-observe-experiment)). Install [Go](https://golang.org/doc/install).
 
 ## 1. Create Kubernetes cluster
 

samples/knative/canaryfixedsplit/check.sh

@@ -67,5 +67,3 @@ else
 fi
 
 set +e
-
-return 0

samples/knative/canaryprogressive/check.sh

@@ -67,5 +67,3 @@ else
 fi
 
 set +e
-
-return 0

samples/knative/conformance/check.sh

@@ -39,5 +39,3 @@ fi
 # Check if winner is baseline?
 
 set +e
-
-return 0

samples/knative/mirroring/check.sh

@@ -25,5 +25,3 @@ fi
 # check for winner?
 
 set +e
-
-return 0

samples/knative/quickstart/check.sh

@@ -67,5 +67,3 @@ else
 fi
 
 set +e
-
-return 0

samples/knative/quickstart/platformsetup.sh

@@ -21,19 +21,7 @@ else
     echo "Kubernetes cluster is available"
 fi
 
-
-## 0(c). Ensure Kustomize v3 or v4 is available
-KUSTOMIZE_VERSION=$(kustomize version | cut -f 1 | cut -d/ -f 2 | cut -d. -f 1)
-if [[ $KUSTOMIZE_VERSION == "v3" || $KUSTOMIZE_VERSION == "v4" ]]; then
-    echo "Kustomize ${KUSTOMIZE_VERSION} is available"
-else
-    echo "Kustomize Version found: $KUSTOMIZE_VERSION"
-    echo "Kustomize v3 or v4 is not available"
-    echo "Get Kustomize v4 from https://kubectl.docs.kubernetes.io/installation/kustomize/"
-    exit 1
-fi
-
-## 0(d). Ensure network layer is supported
+## 0(c). Ensure network layer is supported
 NETWORK_LAYERS="istio contour gloo kourier"
 if [[ ! " ${NETWORK_LAYERS[@]} " =~ " ${1} " ]]; then
     echo "Network Layer ${1} unsupported"
@@ -42,7 +30,7 @@ if [[ ! " ${NETWORK_LAYERS[@]} " =~ " ${1} " ]]; then
 fi
 
 # Step 1: Export correct tags for install artifacts
-export TAG="${TAG:-v0.3.0-pre.4}"
+export TAG="${TAG:-v0.3.0-pre.5}"
 export KNATIVE_TAG="${KNATIVE_TAG:-v0.21.0}"
 echo "TAG = $TAG"
 echo "KNATIVE_TAG = $KNATIVE_TAG"
@@ -61,7 +49,7 @@ echo "Installing Knative core components"
 kubectl apply --filename https://github.com/knative/serving/releases/download/${KNATIVE_TAG}/serving-core.yaml
 
 
-# Step 3: Monitor the Knative components until all of the components are `Running` or `Completed`:
+# Step 3: Ensure readiness of Knative-serving pods
 echo "Waiting for all Knative-serving pods to be running..."
 sleep 10 # allowing enough time for resource creation
 kubectl wait --for condition=ready --timeout=300s pods --all -n knative-serving
@@ -123,18 +111,15 @@ elif [[ "kourier" == ${1} ]]; then
     echo "Kourier installed successfully"
 fi
 
+### Note: the preceding steps perform domain install; following steps perform Iter8 install
+
 # Step 5: Install Iter8
 echo "Installing Iter8"
-kustomize build github.com/iter8-tools/iter8-install/core/?ref=${TAG} | kubectl apply -f -
-kubectl wait crd -l creator=iter8 --for condition=established --timeout=120s
-kustomize build github.com/iter8-tools/iter8-install/metrics/?ref=${TAG} | kubectl apply -f -
-
-# Step 5: Install iter8-monitoring
-echo "Installing iter8-monitoring"
-kustomize build github.com/iter8-tools/iter8-install/prometheus-add-on/prometheus-operator?ref=${TAG} | kubectl apply -f -
-kubectl wait crd -l creator=iter8 --for condition=established --timeout=120s
-kustomize build github.com/iter8-tools/iter8-install/prometheus-add-on/prometheus/?ref=${TAG} | kubectl apply -f - 
-kustomize build github.com/iter8-tools/iter8-install/prometheus-add-on/service-monitors/?ref=${TAG} | kubectl apply -f - 
+curl -s https://raw.githubusercontent.com/iter8-tools/iter8-install/main/install.sh | bash
+
+# Step 6: Install Iter8's Prometheus add-on
+echo "Installing Iter8's Prometheus add-on"
+curl -s https://raw.githubusercontent.com/iter8-tools/iter8-install/main/install-prom-add-on.sh | bash
 
 # Step 7: Verify Iter8 installation
 echo "Verifying installation"

samples/knative/requestrouting/check.sh

@@ -33,5 +33,3 @@ else
 fi
 
 set +e
-
-return 0