From 84b4ed2ed3500f23daf7a827f9766ebf8ba1b4fb Mon Sep 17 00:00:00 2001 From: Michael Kalantar Date: Tue, 23 Jun 2020 13:30:17 -0400 Subject: [PATCH] prepare release v0.2.0 --- doc_files/iter8_bookinfo_istio.md | 28 ++++++++++++------------- doc_files/iter8_install.md | 20 +++++++++++------- doc_files/metrics.md | 2 +- doc_files/platforms/redhat_openshift.md | 10 ++++----- doc_files/service_tutorial.md | 8 +++---- 5 files changed, 36 insertions(+), 32 deletions(-) diff --git a/doc_files/iter8_bookinfo_istio.md b/doc_files/iter8_bookinfo_istio.md index 4a024951e..f437fb2f4 100644 --- a/doc_files/iter8_bookinfo_istio.md +++ b/doc_files/iter8_bookinfo_istio.md @@ -13,7 +13,7 @@ The tutorial is based on the [Bookinfo sample application](https://istio.io/docs ## YAML files used in the tutorial -All Kubernetes YAML files you will need in this tutorial are in the _iter8-controller_ repository [here](https://github.com/iter8-tools/iter8-controller/tree/v0.2/doc/tutorials/istio/bookinfo). +All Kubernetes YAML files you will need in this tutorial are in the _iter8-controller_ repository [here](https://github.com/iter8-tools/iter8-controller/tree/v0.2.0/doc/tutorials/istio/bookinfo). ## Part 1: Successful canary release: _reviews-v2_ to _reviews-v3_ @@ -24,13 +24,13 @@ At this point, we assume that you have already followed the [instructions](iter8 First, let us create a `bookinfo-iter8` namespace configured to enable auto-injection of the Istio sidecar: ```bash -kubectl apply -f https://raw.githubusercontent.com/iter8-tools/iter8-controller/v0.2/doc/tutorials/istio/bookinfo/namespace.yaml +kubectl apply -f https://raw.githubusercontent.com/iter8-tools/iter8-controller/v0.2.0/doc/tutorials/istio/bookinfo/namespace.yaml ``` Next, let us deploy the Bookinfo application: ```bash -kubectl apply -n bookinfo-iter8 -f https://raw.githubusercontent.com/iter8-tools/iter8-controller/v0.2/doc/tutorials/istio/bookinfo/bookinfo-tutorial.yaml +kubectl apply -n bookinfo-iter8 -f https://raw.githubusercontent.com/iter8-tools/iter8-controller/v0.2.0/doc/tutorials/istio/bookinfo/bookinfo-tutorial.yaml ``` You should see the following pods in the `bookinfo-iter8` namespace. Make sure the pods' status is "Running." Also, note that there should be 2 containers in each pod, since the Istio sidecar was injected. @@ -49,7 +49,7 @@ We have deployed "version 2" of the _reviews_ microservice, and version 1 of all Let us now expose the edge _productpage_ service by creating an Istio Gateway for it. ```bash -kubectl apply -n bookinfo-iter8 -f https://raw.githubusercontent.com/iter8-tools/iter8-controller/v0.2/doc/tutorials/istio/bookinfo/bookinfo-gateway.yaml +kubectl apply -n bookinfo-iter8 -f https://raw.githubusercontent.com/iter8-tools/iter8-controller/v0.2.0/doc/tutorials/istio/bookinfo/bookinfo-gateway.yaml ``` You should now see the Istio Gateway and VirtualService for _productpage_, as below: @@ -135,7 +135,7 @@ In the example above, we specified only one success criterion. In particular, we The next step of this tutorial is to actually create the configuration above. To that end, you can either copy and paste the yaml above to a file and then run `kubectl apply -n bookinfo-iter8 -f` on it, or you can run the following command: ```bash -kubectl apply -n bookinfo-iter8 -f https://raw.githubusercontent.com/iter8-tools/iter8-controller/v0.2/doc/tutorials/istio/bookinfo/canary_reviews-v2_to_reviews-v3.yaml +kubectl apply -n bookinfo-iter8 -f https://raw.githubusercontent.com/iter8-tools/iter8-controller/v0.2.0/doc/tutorials/istio/bookinfo/canary_reviews-v2_to_reviews-v3.yaml ``` You can verify that the `Experiment` object has been created as shown below: @@ -153,7 +153,7 @@ As you can see, _iter8_ is reporting that 100% of the traffic is sent to the bas As soon as we deploy _reviews-v3_, _iter8-controller_ will start the rollout. To deploy _reviews-v3_, you can run the following command: ```bash -kubectl apply -n bookinfo-iter8 -f https://raw.githubusercontent.com/iter8-tools/iter8-controller/v0.2/doc/tutorials/istio/bookinfo/reviews-v3.yaml +kubectl apply -n bookinfo-iter8 -f https://raw.githubusercontent.com/iter8-tools/iter8-controller/v0.2.0/doc/tutorials/istio/bookinfo/reviews-v3.yaml ``` Now, if you check the state of the `Experiment` object corresponding to this rollout, you should see that the rollout is in progress, and that 20% of the traffic is now being sent to _reviews-v3_: @@ -233,7 +233,7 @@ The configuration above is pretty much the same we used in part 1, except that n To create the above `Experiment` object, run the following command: ```bash -kubectl apply -n bookinfo-iter8 -f https://raw.githubusercontent.com/iter8-tools/iter8-controller/v0.2/doc/tutorials/istio/bookinfo/canary_reviews-v3_to_reviews-v4.yaml +kubectl apply -n bookinfo-iter8 -f https://raw.githubusercontent.com/iter8-tools/iter8-controller/v0.2.0/doc/tutorials/istio/bookinfo/canary_reviews-v3_to_reviews-v4.yaml ``` You can list all `Experiment` objects like so: @@ -254,7 +254,7 @@ As you have already seen, as soon as we deploy the candidate version, _iter8-con To deploy _reviews-v4_, run the following command: ```bash -kubectl apply -n bookinfo-iter8 -f https://raw.githubusercontent.com/iter8-tools/iter8-controller/v0.2/doc/tutorials/istio/bookinfo/reviews-v4.yaml +kubectl apply -n bookinfo-iter8 -f https://raw.githubusercontent.com/iter8-tools/iter8-controller/v0.2.0/doc/tutorials/istio/bookinfo/reviews-v4.yaml ``` Now, if you check the state of the `Experiment` object corresponding to this rollout, you should see that the rollout is in progress, and that 20% of the traffic is now being sent to _reviews-v4_. @@ -340,7 +340,7 @@ The configuration above differs from the previous ones as follows. We added a se To create the above `Experiment` object, run the following command: ```bash -kubectl apply -n bookinfo-iter8 -f https://raw.githubusercontent.com/iter8-tools/iter8-controller/v0.2/doc/tutorials/istio/bookinfo/canary_reviews-v3_to_reviews-v5.yaml +kubectl apply -n bookinfo-iter8 -f https://raw.githubusercontent.com/iter8-tools/iter8-controller/v0.2.0/doc/tutorials/istio/bookinfo/canary_reviews-v3_to_reviews-v5.yaml ``` ### 2. Deploy _reviews-v5_ and start the rollout @@ -350,7 +350,7 @@ As you already know, as soon as we deploy the candidate version, _iter8-controll To deploy _reviews-v5_, run the following command: ```bash -kubectl apply -n bookinfo-iter8 -f https://raw.githubusercontent.com/iter8-tools/iter8-controller/v0.2/doc/tutorials/istio/bookinfo/reviews-v5.yaml +kubectl apply -n bookinfo-iter8 -f https://raw.githubusercontent.com/iter8-tools/iter8-controller/v0.2.0/doc/tutorials/istio/bookinfo/reviews-v5.yaml ``` If you check the state of the `Experiment` object corresponding to this rollout, you should see that the rollout is in progress, and that 20% of the traffic is now being sent to _reviews-v5_. @@ -411,13 +411,13 @@ $ kubectl get configmap iter8config-metrics -n iter8 -oyaml In principle, any metric that can be derived from the data you have in your Prometheus database that might be meaningful to you in assessing the health of a service version can be used by _iter8_. Next, we are going to make _iter8_ aware of a metric that we will call _iter8_90_perc_latency_, which measures the 90th percentile latency of a service. In order to make _iter8_ aware of a new metric we need to add it to the _iter8config-metrics_ config map. For the purposes of this tutorial, we will do so by running the following command: ```bash -kubectl apply -n iter8 -f https://raw.githubusercontent.com/iter8-tools/iter8-controller/v0.2/doc/tutorials/istio/bookinfo/iter8_metrics_extended.yaml +kubectl apply -n iter8 -f https://raw.githubusercontent.com/iter8-tools/iter8-controller/v0.2.0/doc/tutorials/istio/bookinfo/iter8_metrics_extended.yaml ``` Or, if using a newer version of Istio (1.5 or greater) with telemetry v2: ```bash -kubectl apply -n iter8 -f https://raw.githubusercontent.com/iter8-tools/iter8-controller/v0.2/doc/tutorials/istio/bookinfo/iter8_metrics_extended_telemetry-v2.yaml +kubectl apply -n iter8 -f https://raw.githubusercontent.com/iter8-tools/iter8-controller/v0.2.0/doc/tutorials/istio/bookinfo/iter8_metrics_extended_telemetry-v2.yaml ``` #### Note: @@ -466,7 +466,7 @@ The configuration uses the newly extended metric _iter8_90_perc_latency_. The su To create the above `Experiment` object, run the following command: ```bash -kubectl apply -n bookinfo-iter8 -f https://raw.githubusercontent.com/iter8-tools/iter8-controller/v0.2/doc/tutorials/istio/bookinfo/canary_reviews-v3_to_reviews-v6.yaml +kubectl apply -n bookinfo-iter8 -f https://raw.githubusercontent.com/iter8-tools/iter8-controller/v0.2.0/doc/tutorials/istio/bookinfo/canary_reviews-v3_to_reviews-v6.yaml ``` As usual, iter8 is waiting for the candidate version to be deployed: @@ -487,7 +487,7 @@ As soon as we deploy the candidate version, _iter8-controller_ will start the ro To deploy _reviews-v6_, run the following command: ```bash -kubectl apply -n bookinfo-iter8 -f https://raw.githubusercontent.com/iter8-tools/iter8-controller/v0.2/doc/tutorials/istio/bookinfo/reviews-v6.yaml +kubectl apply -n bookinfo-iter8 -f https://raw.githubusercontent.com/iter8-tools/iter8-controller/v0.2.0/doc/tutorials/istio/bookinfo/reviews-v6.yaml ``` If you check the state of the `Experiment` object corresponding to this rollout, you should see that the rollout is in progress, and that 20% of the traffic is now being sent to _reviews-v6_. diff --git a/doc_files/iter8_install.md b/doc_files/iter8_install.md index d75b5714f..2310f24ba 100644 --- a/doc_files/iter8_install.md +++ b/doc_files/iter8_install.md @@ -10,14 +10,14 @@ These instructions show you how to set up iter8 on Kubernetes with Istio. ## Install iter8 on Kubernetes -iter8 has two components, _iter8_analytics_ and _iter8_controller_. To install them, follow the instructions below. For additional considerations when installing iter8 on Red Hat OpenShift, check out [these instructions](https://github.com/iter8-tools/docs/blob/v0.2/doc_files/platforms/redhat_openshift.md). +iter8 has two components, _iter8_analytics_ and _iter8_controller_. To install them, follow the instructions below. For additional considerations when installing iter8 on Red Hat OpenShift, check out [these instructions](https://github.com/iter8-tools/docs/blob/v0.2.0/doc_files/platforms/redhat_openshift.md). ### Quick installation To install iter8 with the default settings, you can run the following install script: ```bash -curl -L -s https://raw.githubusercontent.com/iter8-tools/iter8-controller/v0.2/install/install.sh \ +curl -L -s https://raw.githubusercontent.com/iter8-tools/iter8-controller/v0.2.0/install/install.sh \ | /bin/bash - ``` @@ -25,13 +25,17 @@ curl -L -s https://raw.githubusercontent.com/iter8-tools/iter8-controller/v0.2/i In case you need to customize the installation of iter8, use the Helm charts listed below: -* _iter8-analytics_: [ https://github.com/iter8-tools/iter8-analytics/releases/download/v0.1.1/iter8-analytics-helm-chart.tar](https://github.com/iter8-tools/iter8-analytics/releases/download/v0.1.1/iter8-analytics-helm-chart.tar) +* _iter8-analytics_: [ https://github.com/iter8-tools/iter8-analytics/releases/download/v0.2.0/iter8-analytics-helm-chart.tar](https://github.com/iter8-tools/iter8-analytics/releases/download/v0.2.0/iter8-analytics-helm-chart.tar) -* _iter8-controller_: [https://github.com/iter8-tools/iter8-controller/releases/download/v0.1.1/iter8-controller-helm-chart.tar](https://github.com/iter8-tools/iter8-controller/releases/download/v0.1.1/iter8-controller-helm-chart.tar) +* _iter8-controller_: [https://github.com/iter8-tools/iter8-controller/releases/download/v0.2.0/iter8-controller-helm-chart.tar](https://github.com/iter8-tools/iter8-controller/releases/download/v0.2.0/iter8-controller-helm-chart.tar) -**Note on Prometheus:** In order to make assessments, _iter8_analytics_ needs to query metrics collected by Istio and stored on Prometheus. The default values for the helm chart parameters (used in the quick installation) point _iter8_analytics_ to Prometheus at `http://prometheus.istio-system:9090` (the default internal Kubernetes URL of Prometheus installed as an Istio addon) without specifying the need for authentication. If your Istio installation is shipping metrics to a different Prometheus installation, or if you need to configure authentication to access Prometheus, you need to set appropriate _iter8-analytics_ Helm chart parameters. Look for the Prometheus-related parameters in the _iter8-analytics_ Helm chart's `values.yaml` file. +**Note on Prometheus:** In order to make assessments, _iter8-analytics_ needs to query metrics collected by Istio and stored on Prometheus. The default values for the helm chart parameters (used in the quick installation) point _iter8-analytics_ to the Prometheus server at `http://prometheus.istio-system:9090` (the default internal Kubernetes URL of Prometheus installed as an Istio addon) without specifying any need for authentication. If your Istio installation is shipping metrics to a different Prometheus service, or if you need to configure authentication to access Prometheus, you need to set appropriate _iter8-analytics_ Helm chart parameters. Look in the section `metricsBackend` of the Helm chart's `values.yaml` file for details. -**Note on Istio Telemetry:** Make sure to set the parameter `istioTelemetry` in the Helm chart to conform with your environment. Possible values are `v1` or `v2`. +**Note on Istio Telemetry:** When deploying _iter8-controller_ using helm, make sure to set the parameter `istioTelemetry` is set to conform with your environment. Possible values are `v1` or `v2`. Use `v1` if the Istio mixer is not disabled. You can determine whether or not the mixer is disabled using this command: + +```bash +kubectl -n $ISTIO_NAMESPACE get cm istio -o json | jq .data.mesh | grep -o 'disableMixerHttpReports: [A-Za-z]\+' | cut -d ' ' -f2 +``` ### Verify the installation @@ -62,7 +66,7 @@ kubectl -n istio-system port-forward $(kubectl -n istio-system get pod -l app=gr After running that command, you can access Grafana's UI at `http://localhost:3000`.Iter8 dashboard can be imported by: ```bash -curl -L -s https://raw.githubusercontent.com/iter8-tools/iter8-controller/v0.2/hack/grafana_install_dashboard.sh \ +curl -L -s https://raw.githubusercontent.com/iter8-tools/iter8-controller/v0.2.0/hack/grafana_install_dashboard.sh \ | /bin/bash - ``` @@ -71,7 +75,7 @@ curl -L -s https://raw.githubusercontent.com/iter8-tools/iter8-controller/v0.2/h If you want to uninstall all _iter8_ components from your Kubernetes cluster, first delete all instances of `Experiment` from all namespaces. Then, you can delete iter8 by running the following command: ```bash -kubectl delete -f https://raw.githubusercontent.com/iter8-tools/iter8-controller/v0.2/install/iter8-controller.yaml +kubectl delete -f https://raw.githubusercontent.com/iter8-tools/iter8-controller/v0.2.0/install/iter8-controller.yaml ``` Note that this command will delete the `Experiment` CRD and wipe out the `iter8` namespace, but it will not remove the iter8 Grafana dashboard if created. diff --git a/doc_files/metrics.md b/doc_files/metrics.md index c36d5572b..97ad23df4 100644 --- a/doc_files/metrics.md +++ b/doc_files/metrics.md @@ -16,7 +16,7 @@ In particular, the following metrics are available out-of-the-box from iter8. Th 3. _iter8_error_rate_: error rate, that is, (total error count / total number of HTTP requests). -When iter8 is installed, a Kubernetes `ConfigMap` named _iter8config-metrics_ is populated with a definition for each of the above metrics. You can see the metric definitions in [this file](https://raw.githubusercontent.com/iter8-tools/iter8-controller/v0.1.1/install/helm/iter8-controller/templates/metrics/iter8_metrics.yaml). A few things to note in the definitions: +When iter8 is installed, a Kubernetes `ConfigMap` named _iter8config-metrics_ is populated with a definition for each of the above metrics. You can see the metric definitions in [this file](https://raw.githubusercontent.com/iter8-tools/iter8-controller/v0.2.0/install/helm/iter8-controller/templates/metrics/iter8_metrics.yaml). A few things to note in the definitions: - Each metric is defined under the `metrics` section. diff --git a/doc_files/platforms/redhat_openshift.md b/doc_files/platforms/redhat_openshift.md index eb61325a4..8010bd595 100644 --- a/doc_files/platforms/redhat_openshift.md +++ b/doc_files/platforms/redhat_openshift.md @@ -12,7 +12,7 @@ By default, iter8 uses the Prometheus service installed as part of the Red Hat O ### Install the iter8 analytics service -Download and untar the [helm chart](https://github.com/iter8-tools/iter8-analytics/releases/download/v0.1.1/iter8-analytics-helm-char.tar) for the iter8-analytics service. The following options can be used to generate the needed yaml: +Download and untar the [helm chart](https://github.com/iter8-tools/iter8-analytics/releases/download/v0.2.0/iter8-analytics-helm-char.tar) for the iter8-analytics service. The following options can be used to generate the needed yaml: ```bash REPO=iter8/iter8-analytics @@ -22,7 +22,7 @@ PROMETHEUS_PASSWORD= helm template install/kubernetes/helm/iter8-analytics \ --name iter8-analytics \ --set image.repository=${REPO} \ - --set image.tag=v0.1.1 \ + --set image.tag=v0.2.0 \ --set iter8Config.authentication.type=basic \ --set iter8Config.authentication.username=${PROMETHEUS_USERNAME} \ --set iter8Config.authentication.password=${PROMETHEUS_PASSWORD} \ @@ -39,14 +39,14 @@ PROMETHEUS_PASSWORD=$(kubectl -n istio-system get secret htpasswd -o jsonpath='{ ### Install the iter8 controller -The [quick install instructions](https://github.com/iter8-tools/docs/blob/v0.1.1/doc_files/iter8_install.md#quick-installation) can be used to install the iter8 controller. The Service Mesh currently uses Istio telemetry version `v1`: +The [quick install instructions](https://github.com/iter8-tools/docs/blob/v0.2.0/doc_files/iter8_install.md#quick-installation) can be used to install the iter8 controller. The Service Mesh currently uses Istio telemetry version `v1`: ```bash -kubectl apply -f https://raw.githubusercontent.com/iter8-tools/iter8-controller/v0.1.1/install/iter8-controller.yaml +kubectl apply -f https://raw.githubusercontent.com/iter8-tools/iter8-controller/v0.2.0/install/iter8-controller.yaml ``` ## Target Services The Red Hat OpenShift Service Mesh is restricted to the set of namespaces defined in the `ServiceMeshMemberRoll` resource. In particular, if you will be trying the tutorials, add the namespace `bookinfo-iter8` to the `ServiceMeshMemberRoll`. -Istio relies a sidecar injected into each pod to provide its capabilities. Istio provides several ways this sidecar can be [injected](https://istio.io/docs/setup/additional-setup/sidecar-injection/). Red Hat recommends the use of the annotation `sidecar.istio.io/inject: "true"` in the deployment yaml. Examples can be found in the yaml for the tutorial: +Istio relies a sidecar injected into each pod to provide its capabilities. Istio provides several ways this sidecar can be [injected](https://istio.io/docs/setup/additional-setup/sidecar-injection/). Red Hat recommends the use of the annotation `sidecar.istio.io/inject: "true"` in the deployment yaml. Examples can be found in the yaml for the tutorial: diff --git a/doc_files/service_tutorial.md b/doc_files/service_tutorial.md index ab3b2f090..d97a8dfef 100644 --- a/doc_files/service_tutorial.md +++ b/doc_files/service_tutorial.md @@ -21,13 +21,13 @@ kubectl label ns $NAMESPACE istio-injection=enabled Deploy the bookinfo application to a new namespace. In particular, we create the service _productpage-v1_ to access the _productpage_ application. ```bash -kubectl -n $NAMESPACE apply -f https://raw.githubusercontent.com/iter8-tools/iter8-controller/v0.2/doc/tutorials/istio/bookinfo/bookinfo-tutorial.yaml -f https://raw.githubusercontent.com/iter8-tools/iter8-controller/v0.2/doc/tutorials/istio/bookinfo/service/productpage-v1.yaml +kubectl -n $NAMESPACE apply -f https://raw.githubusercontent.com/iter8-tools/iter8-controller/v0.2.0/doc/tutorials/istio/bookinfo/bookinfo-tutorial.yaml -f https://raw.githubusercontent.com/iter8-tools/iter8-controller/v0.2.0/doc/tutorials/istio/bookinfo/service/productpage-v1.yaml ``` Create an Istio gateway for the external host `productpage.example.com`: ```bash -kubectl -n $NAMESPACE apply -f https://raw.githubusercontent.com/iter8-tools/iter8-controller/v0.2/doc/tutorials/istio/bookinfo/service/bookinfo-gateway.yaml +kubectl -n $NAMESPACE apply -f https://raw.githubusercontent.com/iter8-tools/iter8-controller/v0.2.0/doc/tutorials/istio/bookinfo/service/bookinfo-gateway.yaml ``` ****** @@ -52,7 +52,7 @@ It identifies the type of the baseline and candidate as services using `kind: Se You can create the `Experiment` using: ```bash -kubectl -n $NAMESPACE apply -f https://raw.githubusercontent.com/iter8-tools/iter8-controller/v0.2/doc/tutorials/istio/bookinfo/service/canary_productpage-v1_to_productpage-v2.yaml +kubectl -n $NAMESPACE apply -f https://raw.githubusercontent.com/iter8-tools/iter8-controller/v0.2.0/doc/tutorials/istio/bookinfo/service/canary_productpage-v1_to_productpage-v2.yaml ``` You can verify that the `Experiment` has been created: @@ -78,7 +78,7 @@ watch -x -n 0.1 curl -Is -H 'Host: productpage.example.com' "http://${GATEWAY_UR To start the rollout of the new version of the product page application, deploy the new version: ```bash -kubectl -n $NAMESPACE apply -f https://raw.githubusercontent.com/iter8-tools/iter8-controller/v0.2/doc/tutorials/istio/bookinfo/productpage-v2.yaml -f https://raw.githubusercontent.com/iter8-tools/iter8-controller/v0.2/doc/tutorials/istio/bookinfo/service/productpage-v2.yaml +kubectl -n $NAMESPACE apply -f https://raw.githubusercontent.com/iter8-tools/iter8-controller/v0.2.0/doc/tutorials/istio/bookinfo/productpage-v2.yaml -f https://raw.githubusercontent.com/iter8-tools/iter8-controller/v0.2.0/doc/tutorials/istio/bookinfo/service/productpage-v2.yaml ``` You can verify the experiment has started: