diff --git a/_docs/guides/bookinfo.md b/_docs/guides/bookinfo.md
index 8c1bede422..3300709cab 100644
--- a/_docs/guides/bookinfo.md
+++ b/_docs/guides/bookinfo.md
@@ -1,6 +1,6 @@
---
-title: Bookinfo on Kubernetes
-overview: This sample deploys a simple application composed of four separate microservices which will be used to demonstrate various features of the Istio service mesh.
+title: Bookinfo Sample Application
+overview: This guide deploys a sample application composed of four separate microservices which will be used to demonstrate various features of the Istio service mesh.
order: 10
@@ -10,18 +10,12 @@ redirect_from: "/docs/samples/bookinfo.html"
---
{% include home.html %}
-This sample deploys a simple application composed of four separate microservices which will be used
+This guide deploys a sample application composed of four separate microservices which will be used
to demonstrate various features of the Istio service mesh.
-## Before you begin
-* If you use GKE, please ensure your cluster has at least 4 standard GKE nodes.
-
-* Setup Istio by following the instructions in the
-[Installation guide]({{home}}/docs/setup/kubernetes/quick-start.html).
-
## Overview
-In this sample we will deploy a simple application that displays information about a
+In this guide we will deploy a simple application that displays information about a
book, similar to a single catalog entry of an online book store. Displayed
on the page is a description of the book, book details (ISBN, number of
pages, and so on), and a few book reviews.
@@ -45,34 +39,63 @@ The end-to-end architecture of the application is shown below.
BookInfo Application without Istio
This application is polyglot, i.e., the microservices are written in different languages.
+It’s worth noting that these services have no dependencies on Istio, but make an interesting
+sevice mesh example, particularly because of the multitude of services, languages and versions
+for the reviews service.
-## Start the application
+## Deploying the application
+
+To run the sample with Istio requires no changes to the
+application itself. Instead, we simply need to configure and run the services in an
+Istio-enabled environment, with Envoy sidecars injected along side each service.
+The needed commands and configuration vary depending on the runtime environment
+although in all cases the resulting deployment will look like this:
+
+
+BookInfo Application
+
+All of the microservices will be packaged with an Envoy sidecar that intercepts incoming
+and outgoing calls for the services, providing the hooks needed to externally control,
+via the Istio control plane, routing, telemetry collection, and policy enforcement
+for the application as a whole.
+
+Before you begin, if you haven't already done so, setup Istio by following the instructions
+corresponding to your platform [installation guide]({{home}}/docs/setup/) and then
+run the application using the instructions in one of the following sections.
+
+### Running on Kubernetes
+
+> Note: If you use GKE, please ensure your cluster has at least 4 standard GKE nodes.
1. Change directory to the root of the Istio installation directory.
1. Bring up the application containers:
+ If you are using a cluster with
+ [automatic sidecar injection]({{home}}/docs/setup/kubernetes/automatic-sidecar-inject.html)
+ enabled, simply deploy the services using `kubectl`:
+
+ ```bash
+ kubectl apply -f samples/bookinfo/kube/bookinfo.yaml
+ ```
+
+ If you are using [manual sidecar injection]({{home}}/docs/setup/kubernetes/manual-sidecar-inject.html),
+ use the folloiwng command instead:
+
```bash
kubectl apply -f <(istioctl kube-inject -f samples/bookinfo/kube/bookinfo.yaml)
```
- The above command launches four microservices and creates the gateway
- ingress resource as illustrated in the diagram below.
- The reviews microservice has 3 versions: v1, v2, and v3.
+ The `istioctl kube-inject` command is used to manually modify the `bookinfo.yaml`
+ file before creating the deployments as documented [here]({{home}}/docs/reference/commands/istioctl.html#istioctl-kube-inject).
+
+ Either of the above commands launches all four microservices and creates the gateway
+ ingress resource as illustrated in the above diagram.
+ All 3 versions of the reviews service, v1, v2, and v3, are started.
> Note that in a realistic deployment, new versions of a microservice are deployed
over time instead of deploying all versions simultaneously.
- Notice that the `istioctl kube-inject` command is used to modify the `bookinfo.yaml`
- file before creating the deployments. This injects Envoy into Kubernetes resources
- as documented [here]({{home}}/docs/reference/commands/istioctl.html#istioctl-kube-inject).
- Consequently, all of the microservices are now packaged with an Envoy sidecar
- that manages incoming and outgoing calls for the service. The updated diagram looks
- like this:
-
-
- BookInfo Application
-
1. Confirm all services and pods are correctly defined and running:
```bash
@@ -142,19 +165,59 @@ This application is polyglot, i.e., the microservices are written in different l
export GATEWAY_URL=$(kubectl get po -n istio-system -l istio=ingress -o 'jsonpath={.items[0].status.hostIP}'):$(kubectl get svc istio-ingress -n istio-system -o 'jsonpath={.spec.ports[0].nodePort}')
```
-1. Confirm that the BookInfo application is running with the following `curl` command:
+### Running on Docker with Consul
+
+1. Change directory to the root of the Istio installation directory.
+
+1. Bring up the Istio control plane and the application containers:
+
+ ```bash
+ docker-compose -f samples/bookinfo/consul/docker-compose.yaml up -d
+ ```
+
+1. Confirm that all docker containers are running:
```bash
- curl -o /dev/null -s -w "%{http_code}\n" http://${GATEWAY_URL}/productpage
+ docker ps -a
```
+
+ > If the `Istio-Pilot` container terminates, re-run the command from the previous step.
+
+1. Set the GATEWAY_URL:
+
```bash
- 200
+ export GATEWAY_URL=localhost:9081
```
-
+
+## What's next
+
+To confirm that the BookInfo application is running, run the following `curl` command:
+
+```bash
+curl -o /dev/null -s -w "%{http_code}\n" http://${GATEWAY_URL}/productpage
+```
+```bash
+200
+```
+
+You can also point your browser to `http://$GATEWAY_URL/productpage`
+to view the Bookinfo web page. If you refresh the page several times, you should
+see different versions of reviews shown in productpage, presented in a round robin style (red
+stars, black stars, no stars), since we haven't yet used Istio to control the
+version routing.
+
+You can now use this sample to experiment with Istio's features for
+traffic routing, fault injection, rate limitting, etc..
+To proceed, refer to one or more of the [Istio Guides]({{home}}/docs/guides),
+depending on your interest. [Intelligent Routing]({{home}}/docs/guides/intelligent-routing.html)
+is a good place to start for beginners.
+
## Cleanup
When you're finished experimenting with the BookInfo sample, you can
-uninstall it in a Kubernetes environment as follows:
+uninstall and clean it up using the following instructions.
+
+### Uninstall from Kubernetes environment
1. Delete the routing rules and terminate the application pods
@@ -169,16 +232,16 @@ uninstall it in a Kubernetes environment as follows:
kubectl get pods #-- the BookInfo pods should be deleted
```
-If you are using the Docker Compose version of the demo, run the following
-command to clean up:
+### Uninstall from Docker environment
+
+1. Showdown the application
```bash
docker-compose -f samples/bookinfo/consul/docker-compose.yaml down
```
-## What's next
+2. Cleanup rules
-Now that you have the BookInfo sample up and running, you can point your browser to `http://$GATEWAY_URL/productpage`
-to see the running application and use Istio to control traffic routing, inject faults, rate limit services, etc..
-
-To get started, check out the [request routing task]({{home}}/docs/tasks/request-routing.html).
+ ```
+ TBD
+ ```
diff --git a/_docs/guides/intelligent-routing.md b/_docs/guides/intelligent-routing.md
index 50c085f21b..a278c16545 100644
--- a/_docs/guides/intelligent-routing.md
+++ b/_docs/guides/intelligent-routing.md
@@ -1,59 +1,55 @@
---
title: Intelligent Routing
-overview: This sample demonstrates how to use various traffic management capabilities of Istio service mesh running on Kubernetes.
+overview: This guide demonstrates how to use various traffic management capabilities of an Istio service mesh.
order: 20
-draft: true
layout: docs
type: markdown
---
{% include home.html %}
-This sample demonstrates how to use various traffic management capabilities
-of Istio service mesh running on Kubernetes.
-
-## Before you begin
-* Describe installation options.
-
-* Install Istio control plane in a Kubernetes cluster by following the quick start instructions in the
-[Installation guide]({{home}}/docs/setup/kubernetes/quick-start.html).
+This guide demonstrates how to use various traffic management capabilities
+of an Istio service mesh.
## Overview
-Placeholder.
+Deploying a microservice-based application in an Istio service mesh allows one
+to externally control service monitoring and tracing, request (version) routing, resiliency testing,
+security and policy enforcement, etc., in a consistent way across the services,
+for the application as a whole.
-## Application Setup
+In this guide, we will use the [Bookinfo sample application]({{home}}/docs/guides/bookinfo.html)
+to show how operators can dynamically configure request routing and fault injection
+for a running application.
-1. Steps
+## Before you begin
+
+* Install the Istio control plane by following the instructions
+ corresponding to your platform [installation guide]({{home}}/docs/setup/).
+
+* Run the Bookinfo sample application by following the applicable
+ [application deployment instructions]({{home}}/docs/guides/bookinfo.html#deploying-the-application).
## Tasks
-1. [Request routing]({{home}}/docs/tasks/request-routing.html).
+1. [Request routing]({{home}}/docs/tasks/traffic-management/request-routing.html) This task will first
+ direct all incoming traffic for the Bookinfo application to the v1 version of the
+ `reviews` service. It will then send traffic only from a specific test user to version v2,
+ leaving all other users unaffected.
-1. [Fault injection]({{home}}/docs/tasks/fault-injection.html).
+1. [Fault injection]({{home}}/docs/tasks/traffic-management/fault-injection.html) We will now use Istio to
+ test the resiliency of the Bookinfo application by injecting an artificial delay in
+ requests between the `reviews:v2` and `ratings` services. Observing the resulting behavior
+ as the test user, we will notice that the v2 version of the `reviews` service has a bug.
+ Note that all other users are unaware of this testing against the live system.
+
+1. [Version migration]({{home}}/docs/tasks/traffic-management/version-migration.html) Finally, we will
+ use Istio to gradually migrate traffic for all users from to a v3 version of
+ the `reviews` service, one which includes the fix for the bug discovered in v2.
## Cleanup
When you're finished experimenting with the BookInfo sample, you can
-uninstall it as follows in a Kubernetes environment:
-
-1. Delete the routing rules and terminate the application pods
-
- ```bash
- samples/bookinfo/kube/cleanup.sh
- ```
-
-1. Confirm shutdown
-
- ```bash
- istioctl get route-rules #-- there should be no more routing rules
- kubectl get pods #-- the BookInfo pods should be deleted
- ```
-
-If you are using the Docker Compose version of the demo, run the following
-command to clean up:
-
- ```bash
- docker-compose -f samples/bookinfo/consul/docker-compose.yaml down
- ```
-
+uninstall it by following the
+[Bookinfo cleanup instructions]({{home}}/docs/guides/bookinfo.html#cleanup)
+corresponding to your environment.
diff --git a/_docs/setup/kubernetes/quick-start.md b/_docs/setup/kubernetes/quick-start.md
index d21720e661..349710e84a 100644
--- a/_docs/setup/kubernetes/quick-start.md
+++ b/_docs/setup/kubernetes/quick-start.md
@@ -219,16 +219,16 @@ You can now deploy your own application or one of the sample applications provid
installation like [BookInfo]({{home}}/docs/guides/bookinfo.html).
Note: the application must use HTTP/1.1 or HTTP/2.0 protocol for all its HTTP traffic because HTTP/1.0 is not supported.
-If you have the Istio-Initializer as shown above installed, you can deploy the application directly via
-`kubectl create`, the Istio-Initializer will automatically inject Envoy containers in your application pods:
+If you started the Istio-Initializer, as shown above, you can deploy the application directly using
+`kubectl create`. The Istio-Initializer will automatically inject Envoy containers into your application pods:
```bash
kubectl create -f .yaml
```
-If you do not have the Istio-Initializer as shown above installed, when deploying the application, you must
+If you do not have the Istio-Initializer installed, you must
use [istioctl kube-inject]({{home}}/docs/reference/commands/istioctl.html#istioctl-kube-inject) to
-automatically inject Envoy containers in your application pods:
+manuallly inject Envoy containers in your application pods before deploying them:
```bash
kubectl create -f <(istioctl kube-inject -f .yaml)
diff --git a/_docs/tasks/traffic-management/fault-injection.md b/_docs/tasks/traffic-management/fault-injection.md
index dfa606661c..f59b0bfd5f 100644
--- a/_docs/tasks/traffic-management/fault-injection.md
+++ b/_docs/tasks/traffic-management/fault-injection.md
@@ -105,7 +105,7 @@ continue without any errors.
However, we already have this fix running in v3 of the reviews service, so we can simply
fix the problem by migrating all
- traffic to `reviews:v3` as described in the [request routing task](./request-routing.html).
+ traffic to `reviews:v3` as described in the [version migration](./version-migration.html).
(Left as an exercise for the reader - change the delay rule to
use a 2.8 second delay and then run it against the v3 version of reviews.)
@@ -114,8 +114,6 @@ continue without any errors.
* Learn more about [fault injection]({{home}}/docs/concepts/traffic-management/fault-injection.html).
-* Limit requests to the BookInfo `ratings` service with Istio [rate limiting]({{home}}/docs/tasks/policy-enforcement/rate-limiting.html).
-
* If you are not planning to explore any follow-on tasks, refer to the
[BookInfo cleanup]({{home}}/docs/guides/bookinfo.html#cleanup) instructions
to shutdown the application and cleanup the associated rules.
diff --git a/_docs/tasks/traffic-management/request-routing.md b/_docs/tasks/traffic-management/request-routing.md
index ec938a6c07..f93394289b 100644
--- a/_docs/tasks/traffic-management/request-routing.md
+++ b/_docs/tasks/traffic-management/request-routing.md
@@ -19,6 +19,13 @@ This task shows you how to configure dynamic request routing based on weights an
* Deploy the [BookInfo]({{home}}/docs/guides/bookinfo.html) sample application.
+> Note: This task assumes you are deploying the application on Kubernetes.
+ All of the example commands are using the Kubernetes version of the rule yaml files
+ (e.g., `samples/bookinfo/kube/route-rule-all-v1.yaml`). If you are running this
+ task in a different environment, change `kube` to the directory that corresponds
+ to your runtime (e.g., samples/bookinfo/consul/route-rule-all-v1.yaml for
+ the Consul-based runtime).
+
## Content-based routing
Because the BookInfo sample deploys 3 versions of the reviews microservice,
@@ -28,7 +35,8 @@ star ratings.
This is because without an explicit default version set, Istio will
route requests to all available versions of a service in a random fashion.
-> Note: This task assumes you don't have any routes set yet. If you've already created conflicting route rules for the sample, you'll need to use `replace` rather than `create` in one or both of the following commands.
+> Note: This task assumes you don't have any routes set yet. If you've already created conflicting route rules for the sample,
+ you'll need to use `replace` rather than `create` in one or both of the following commands.
1. Set the default version for all microservices to v1.
@@ -38,6 +46,7 @@ route requests to all available versions of a service in a random fashion.
> Note: In a Kubernetes deployment of Istio, you can replace `istioctl`
> with `kubectl` in the above, and for all other CLI commands.
+ > Note, however, that `kubectl` currently does not provide input validation.
You can display the routes that are defined with the following command:
@@ -120,11 +129,6 @@ route requests to all available versions of a service in a random fashion.
istioctl create -f samples/bookinfo/kube/route-rule-reviews-test-v2.yaml
```
- > Note: In a Consul-based setup, use the following command:
- ```bash
- istioctl create -f samples/bookinfo/consul/consul-reviews-v1.yaml
- ```
-
Confirm the rule is created:
```bash
@@ -163,48 +167,7 @@ services. You then set a rule to selectively send traffic to version v2 of the r
on a header (i.e., a user cookie) in a request.
Once the v2 version has been tested to our satisfaction, we could use Istio to send traffic from
-all users to v2, optionally in a gradual fashion by using a sequence of rules with weights less
-than 100 to migrate traffic in steps, for example 10, 20, 30, ... 100%.
-
-If you now proceed to the [fault injection task](./fault-injection.html), you will see
-that with simple testing, the v2 version of the reviews service has a bug, which is fixed in v3.
-So after exploring that task, you can route all user traffic from `reviews:v1`
-to `reviews:v3` in two steps as follows:
-
-1. First, transfer 50% of traffic from `reviews:v1` to `reviews:v3` with the following command:
-
- ```bash
- istioctl replace -f samples/bookinfo/kube/route-rule-reviews-50-v3.yaml
- ```
-
- Notice that we are using `istioctl replace` instead of `create`.
-
-2. To see the new version you need to either Log out as test user "jason" or delete the test rules
-that we created exclusively for him:
-
- ```bash
- istioctl delete routerule reviews-test-v2
- ```
-
- You should now see *red* colored star ratings approximately 50% of the time when you refresh
- the `productpage`.
-
- > Note: With the Envoy sidecar implementation, you may need to refresh the `productpage` multiple times
- > to see the proper distribution. You can modify the rules to route 90% of the traffic to v3 to see red stars more often.
-
-3. When version v3 of the reviews microservice is stable, route 100% of the traffic to `reviews:v3`:
-
- ```bash
- istioctl replace -f samples/bookinfo/kube/route-rule-reviews-v3.yaml
- ```
-
- > Note: In a Consul-based setup, use the following command:
- ```bash
- istioctl replace -f samples/bookinfo/consul/consul-reviews-v3.yaml
- ```
-
- You can now log in to the `productpage` as any user and you should always see book reviews
- with *red* colored star ratings for each review.
+all users to v2, optionally in a gradual fashion. We'll explore this in a separate task.
## What's next
diff --git a/_docs/tasks/traffic-management/version-migration.md b/_docs/tasks/traffic-management/version-migration.md
new file mode 100644
index 0000000000..467051d010
--- /dev/null
+++ b/_docs/tasks/traffic-management/version-migration.md
@@ -0,0 +1,90 @@
+---
+title: Configuring Request Routing
+overview: This task shows you how to configure dynamic request routing based on weights and HTTP headers.
+
+order: 10
+
+layout: docs
+type: markdown
+---
+{% include home.html %}
+
+This task shows you how to gradually migrate traffic from an old to new version of a service.
+With Istio, we can migrate the traffic in a gradual fashion by using a sequence of rules
+with weights less than 100 to migrate traffic in steps, for example 10, 20, 30, ... 100%.
+For simplicity this task will migrate the traffic from `reviews:v1` to `reviews:v3` in just
+two steps: 50%, 100%.
+
+## Before you begin
+
+* Setup Istio by following the instructions in the
+ [Installation guide]({{home}}/docs/setup/).
+
+* Deploy the [BookInfo]({{home}}/docs/guides/bookinfo.html) sample application.
+
+> Note: This task assumes you are deploying the application on Kubernetes.
+ All of the example commands are using the Kubernetes version of the rule yaml files
+ (e.g., `samples/bookinfo/kube/route-rule-all-v1.yaml`). If you are running this
+ task in a different environment, change `kube` to the directory that corresponds
+ to your runtime (e.g., samples/bookinfo/consul/route-rule-all-v1.yaml for
+ the Consul-based runtime).
+
+## Weight-based version routing
+
+1. Set the default version for all microservices to v1.
+
+ ```bash
+ istioctl create -f samples/bookinfo/kube/route-rule-all-v1.yaml
+ ```
+
+1. Confirm v1 is the active version of the `reviews` service by opening http://$GATEWAY_URL/productpage in your browser.
+
+ You should see the BookInfo application productpage displayed.
+ Notice that the `productpage` is displayed with no rating stars since `reviews:v1` does not access the ratings service.
+
+ > Note: If you previously ran the [request routing](./request-routing.html) task, you may need to either log out
+ as test user "jason" or delete the test rules that were created exclusively for him:
+
+ ```bash
+ istioctl delete routerule reviews-test-v2
+ ```
+
+1. First, transfer 50% of the traffic from `reviews:v1` to `reviews:v3` with the following command:
+
+ ```bash
+ istioctl replace -f samples/bookinfo/kube/route-rule-reviews-50-v3.yaml
+ ```
+
+ Notice that we are using `istioctl replace` instead of `create`.
+
+1. Refresh the `productpage` in your browser and you should now see *red* colored star ratings approximately 50% of the time.
+
+ > Note: With the current Envoy sidecar implementation, you may need to refresh the `productpage` very many times
+ > to see the proper distribution. You can modify the rules to route 90% of the traffic to v3 to see red stars more often.
+
+1. When version v3 of the `reviews` microservice is considered stable, we can route 100% of the traffic to `reviews:v3`:
+
+ ```bash
+ istioctl replace -f samples/bookinfo/kube/route-rule-reviews-v3.yaml
+ ```
+
+ You can now log into the `productpage` as any user and you should always see book reviews
+ with *red* colored star ratings for each review.
+
+## Understanding what happened
+
+In this task we migrated traffic from an old to new version of the `reviews` service using Istio's
+weighted routing feature. Note that this is very different than version migration using deployment features
+of container orchestration platforms, which use instance scaling to manage the traffic.
+With Istio, we can allow the two versions of the `reviews` service to scale up and down independently,
+without affecting the traffic distribution between them.
+For more about version routing with autoscaling, check out [Canary Deployments using Istio]({{home}}/blog/canary-deployments-using-istio.html).
+
+
+## What's next
+
+* Learn more about [request routing]({{home}}/docs/concepts/traffic-management/rules-configuration.html).
+
+* If you are not planning to explore any follow-on tasks, refer to the
+ [BookInfo cleanup]({{home}}/docs/guides/bookinfo.html#cleanup) instructions
+ to shutdown the application and cleanup the associated rules.
+