istio
/
istio.io
mirror of https://github.com/istio/istio.io.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

update bookinfo.md (#511) 

* update bookinfo.md

* fix intelligent-routing guide and related tasks

* minor fixes

* nits

* fix broken links
This commit is contained in:
Frank Budinsky 2017-09-26 14:04:47 -04:00 committed by GitHub
parent 9d4dc380cf
commit b11d3a3724
6 changed files with 238 additions and 128 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

135
_docs/guides/bookinfo.md
View File

@ -1,6 +1,6 @@
--- ---
title: Bookinfo on Kubernetes title: Bookinfo Sample Application
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. 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 order: 10
@ -10,18 +10,12 @@ redirect_from: "/docs/samples/bookinfo.html"
--- ---
{% include home.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. 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 ## 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 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 on the page is a description of the book, book details (ISBN, number of
pages, and so on), and a few book reviews. pages, and so on), and a few book reviews.
@ -45,34 +39,63 @@ The end-to-end architecture of the application is shown below.
<figcaption>BookInfo Application without Istio</figcaption></figure> <figcaption>BookInfo Application without Istio</figcaption></figure>
This application is polyglot, i.e., the microservices are written in different languages. 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:
<figure><img src="./img/bookinfo/withistio.svg" alt="BookInfo Application" title="BookInfo Application" />
<figcaption>BookInfo Application</figcaption></figure>
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. Change directory to the root of the Istio installation directory.
1. Bring up the application containers: 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 ```bash
kubectl apply -f <(istioctl kube-inject -f samples/bookinfo/kube/bookinfo.yaml) kubectl apply -f <(istioctl kube-inject -f samples/bookinfo/kube/bookinfo.yaml)
``` ```
The above command launches four microservices and creates the gateway The `istioctl kube-inject` command is used to manually modify the `bookinfo.yaml`
ingress resource as illustrated in the diagram below. file before creating the deployments as documented [here]({{home}}/docs/reference/commands/istioctl.html#istioctl-kube-inject).
The reviews microservice has 3 versions: v1, v2, and v3.
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 > Note that in a realistic deployment, new versions of a microservice are deployed
over time instead of deploying all versions simultaneously. 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:
<figure><img src="./img/bookinfo/withistio.svg" alt="BookInfo Application" title="BookInfo Application" />
<figcaption>BookInfo Application</figcaption></figure>
1. Confirm all services and pods are correctly defined and running: 1. Confirm all services and pods are correctly defined and running:
```bash ```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}') 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 ```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 ```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 ## Cleanup
When you're finished experimenting with the BookInfo sample, you can 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 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 kubectl get pods #-- the BookInfo pods should be deleted
``` ```
If you are using the Docker Compose version of the demo, run the following ### Uninstall from Docker environment
command to clean up:
1. Showdown the application
```bash ```bash
docker-compose -f samples/bookinfo/consul/docker-compose.yaml down 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.. TBD
```
To get started, check out the [request routing task]({{home}}/docs/tasks/request-routing.html).

70
_docs/guides/intelligent-routing.md
View File

@ -1,59 +1,55 @@
--- ---
title: Intelligent Routing 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 order: 20
draft: true
layout: docs layout: docs
type: markdown type: markdown
--- ---
{% include home.html %} {% include home.html %}
This sample demonstrates how to use various traffic management capabilities This guide demonstrates how to use various traffic management capabilities
of Istio service mesh running on Kubernetes. of an Istio service mesh.
## 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).
## Overview ## 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 ## 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 ## Cleanup
When you're finished experimenting with the BookInfo sample, you can When you're finished experimenting with the BookInfo sample, you can
uninstall it as follows in a Kubernetes environment: uninstall it by following the
[Bookinfo cleanup instructions]({{home}}/docs/guides/bookinfo.html#cleanup)
1. Delete the routing rules and terminate the application pods corresponding to your environment.
```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
```

8
_docs/setup/kubernetes/quick-start.md
View File

@ -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). 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. 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 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 in your application pods: `kubectl create`. The Istio-Initializer will automatically inject Envoy containers into your application pods:
```bash ```bash
kubectl create -f <your-app-spec>.yaml kubectl create -f <your-app-spec>.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 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 ```bash
kubectl create -f <(istioctl kube-inject -f <your-app-spec>.yaml) kubectl create -f <(istioctl kube-inject -f <your-app-spec>.yaml)

4
_docs/tasks/traffic-management/fault-injection.md
View File

@ -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 However, we already have this fix running in v3 of the reviews service, so we can simply
fix the problem by migrating all 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 (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.) 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). * 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 * If you are not planning to explore any follow-on tasks, refer to the
[BookInfo cleanup]({{home}}/docs/guides/bookinfo.html#cleanup) instructions [BookInfo cleanup]({{home}}/docs/guides/bookinfo.html#cleanup) instructions
to shutdown the application and cleanup the associated rules. to shutdown the application and cleanup the associated rules.

59
_docs/tasks/traffic-management/request-routing.md
View File

@ -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. * 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 ## Content-based routing
Because the BookInfo sample deploys 3 versions of the reviews microservice, 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 This is because without an explicit default version set, Istio will
route requests to all available versions of a service in a random fashion. 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. 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` > Note: In a Kubernetes deployment of Istio, you can replace `istioctl`
> with `kubectl` in the above, and for all other CLI commands. > 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: 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 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: Confirm the rule is created:
```bash ```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. 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 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 all users to v2, optionally in a gradual fashion. We'll explore this in a separate task.
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.
## What's next ## What's next

90
_docs/tasks/traffic-management/version-migration.md Normal file
View File

@ -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.