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

Added Istio installation and modified bookinfo (#45) 

* First draft getting started

* Added istio-installation and changed bookinfo

* Fix display issue

* Addressed code review comments

* Address more review comments, istio-ca not part of the install

* Use local files instead of raw github files

* Addressed more review comments

* Added note about istioctl and renamed istio-ingress-controller to istio-ingress
This commit is contained in:
Andra Cismaru 2017-04-24 11:39:06 -07:00 committed by GitHub
parent c3ae3612e3
commit 507257e870
2 changed files with 246 additions and 295 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

435
_docs/samples/bookinfo.md
View File

@ -30,136 +30,71 @@ There are 3 versions of the reviews microservice:
The end-to-end architecture of the application is shown below.
![Bookinfo app_noistio](./img/bookinfo/noistio.svg)
![Bookinfo app_noistio]({{site.bareurl}}/docs/samples/img/bookinfo/noistio.svg)
This application is polyglot, i.e., the microservices are written in different languages.
## Before you begin
_Note: The following instructions assume that you have access to a kubernetes cluster. To install kubernetes locally, checkout [minikube](https://github.com/kubernetes/minikube)_
1. Clone the istio GitHub repository and start the core Istio services (the istio-manager, the [Mixer](https://istio.io/docs/concepts/mixer.html), and the istio ingress controller).
```bash
git clone https://github.com/istio/istio
cd istio
kubectl apply -f ./kubernetes/istio-install
```
_Note: the current version of the bookinfo application MUST use the `default` Kubernetes namespace._
1. If you would like to view the metrics collected by Istio proxies, you need to install the [Prometheus](https://prometheus.io/) addon and start a [Grafana](https://grafana.com/) service as well.
```bash
kubectl apply -f ./kubernetes/addons/
```
The Grafana image provided as part of this sample contains a built-in Istio-dashboard that you can access from:
```
http://<grafana-svc-external-IP>:3000/dashboard/db/istio-dashboard
```
> The addons yaml files contain services configured as type LoadBalancer. If services are deployed with type NodePort,
> start kubectl proxy, and edit Grafana's Istio-dashboard to use the Envoy proxy. Access Grafana via kubectl proxy:*
```
http://127.0.0.1:8001/api/v1/proxy/namespaces/<ns>/services/grafana:3000/dashboard/db/istio-dashboard
```
1. Install the [istioctl](../reference/istioctl.html) CLI, which provides a
convenient way to apply routing rules and policies for upstreams. The
[istio.VERSION](https://github.com/istio/istio/blob/master/istio.VERSION) file includes the download location of
three OS-specific binaries: `istioctl-osx`, `istioctl-win.exe`,
`istioctl-linux` targeted at Mac, Windows and Linux users
respectively. Download the tool appropriate to your platform. For
example, when running istioctl on a Mac, run the following commands:
```bash
source ./istio.VERSION # set ISTIOCTL env variable
curl ${ISTIOCTL_URL}/istioctl-osx > /usr/local/bin/istioctl
chmod +x /usr/local/bin/istioctl
```
> Note: If you already have a previously installed version of `istioctl`, make sure that
> it is compatible with the manager image used in `demos/kubernetes/istio-manager.yaml`.
> If in doubt, download again or add the `--tag` option when running `istioctl kube-inject`.
> Invoke `istioctl kube-inject --help` for more details.
1. Follow the Istio [Installation]({{site.bareurl}}/docs/tasks/istio-installation.html) guide.
## Start the Application
1. Change your current working directory to the bookinfo application directory:
```bash
cd demos/apps/bookinfo
```
```bash
cd demos/apps/bookinfo
```
1. Bring up the application containers:
```bash
kubectl create -f <(istioctl kube-inject -f bookinfo.yaml)
```
The above command creates the gateway ingress resource and launches
the 4 microservices as described in the diagram above. The reviews
microservice has 3 versions: v1, v2, and v3. Note that in a
```bash
kubectl apply -f <(istioctl kube-inject -f bookinfo.yaml)
```
The above command launches four microservices and creates the gateway
ingress resource and as illustrated in the diagram above.
The reviews microservice has 3 versions: v1, v2, and v3. 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 the istio runtime proxy
into kubernetes resources as documented [here](../reference/istioctl.html#kube-inject).
Consequently, all of the microservices are now packaged with an Istio sidecar
file before creating the deployments. This injects Envoy into kubernetes resources
as documented [here]({{site.bareurl}}/docs/reference/istioctl.html#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 app](./img/bookinfo/withistio.svg)
1. Confirm that all services and pods are correctly defined and running:
```bash
$ kubectl get services
NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE
details 10.0.0.31 <none> 9080/TCP 6m
istio-ingress-controller 10.0.0.122 <pending> 80:32000/TCP 8m
istio-manager 10.0.0.189 <none> 8080/TCP 8m
istio-mixer 10.0.0.132 <none> 9091/TCP,42422/TCP 8m
kubernetes 10.0.0.1 <none> 443/TCP 14d
productpage 10.0.0.120 <none> 9080/TCP 6m
ratings 10.0.0.15 <none> 9080/TCP 6m
reviews 10.0.0.170 <none> 9080/TCP 6m
```
![Bookinfo app]({{site.bareurl}}/docs/samples/img/bookinfo/withistio.svg)
1. Confirm all services and pods are correctly defined and running:
```bash
$ kubectl get services
NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE
details 10.0.0.31 <none> 9080/TCP 6m
istio-ingress 10.0.0.122 <pending> 80:32000/TCP 8m
istio-manager 10.0.0.189 <none> 8080/TCP 8m
istio-mixer 10.0.0.132 <none> 9091/TCP,42422/TCP 8m
kubernetes 10.0.0.1 <none> 443/TCP 14d
productpage 10.0.0.120 <none> 9080/TCP 6m
ratings 10.0.0.15 <none> 9080/TCP 6m
reviews 10.0.0.170 <none> 9080/TCP 6m
```
and
```bash
$ kubectl get pods
NAME READY STATUS RESTARTS AGE
details-v1-1520924117-48z17 2/2 Running 0 6m
istio-ingress-controller-3181829929-xrrk5 1/1 Running 0 8m
istio-manager-175173354-d6jm7 2/2 Running 0 8m
istio-mixer-3883863574-jt09j 2/2 Running 0 8m
productpage-v1-560495357-jk1lz 2/2 Running 0 6m
ratings-v1-734492171-rnr5l 2/2 Running 0 6m
reviews-v1-874083890-f0qf0 2/2 Running 0 6m
reviews-v2-1343845940-b34q5 2/2 Running 0 6m
reviews-v3-1813607990-8ch52 2/2 Running 0 6m
```
1. Determine the Gateway ingress URL
```bash
$ export GATEWAY_URL=$(kubectl get po -l infra=istio-ingress-controller -o jsonpath={.items[0].status.hostIP}):$(kubectl get svc istio-ingress-controller -o jsonpath={.spec.ports[0].nodePort})
$ echo $GATEWAY_URL
192.168.99.100:32567
```
1. If you open the Bookinfo URL (http://$GATEWAY_URL/productpage) in your browser, you should see the bookinfo application productpage displayed.
```bash
$ kubectl get pods
NAME READY STATUS RESTARTS AGE
details-v1-1520924117-48z17 2/2 Running 0 6m
istio-ingress-3181829929-xrrk5 1/1 Running 0 8m
istio-manager-175173354-d6jm7 2/2 Running 0 8m
istio-mixer-3883863574-jt09j 2/2 Running 0 8m
productpage-v1-560495357-jk1lz 2/2 Running 0 6m
ratings-v1-734492171-rnr5l 2/2 Running 0 6m
reviews-v1-874083890-f0qf0 2/2 Running 0 6m
reviews-v2-1343845940-b34q5 2/2 Running 0 6m
reviews-v3-1813607990-8ch52 2/2 Running 0 6m
```
1. Determine the ingress' URL:
```bash
$ kubectl get ingress
NAME HOSTS ADDRESS PORTS AGE
gateway * 130.211.10.121 80 1d
$export GATEWAY_URL=130.211.10.121:80
```
If you open your browser and point to the URL http://$GATEWAY_URL/productpage, you should see the bookinfo application productpage displayed.
## Traffic Management
@ -171,99 +106,79 @@ star ratings. This is because without an explicit default version set, Istio wil
route requests to all available versions of a service in a random fashion.
1. Set the default version for all microservices to v1.
```bash
$ istioctl create -f route-rule-all-v1.yaml
```
You can display the routes that are defined with the following command:
```bash
$ istioctl get route-rules -o yaml
kind: route-rule
name: ratings-default
namespace: default
spec:
destination: ratings.default.svc.cluster.local
precedence: 1
route:
- tags:
version: v1
weight: 100
---
kind: route-rule
name: reviews-default
namespace: default
spec:
destination: reviews.default.svc.cluster.local
precedence: 1
route:
- tags:
version: v1
weight: 100
---
kind: route-rule
name: details-default
namespace: default
spec:
destination: details.default.svc.cluster.local
precedence: 1
route:
- tags:
version: v1
weight: 100
---
kind: route-rule
name: productpage-default
namespace: default
spec:
destination: productpage.default.svc.cluster.local
precedence: 1
route:
- tags:
version: v1
weight: 100
---
```
> Note: In the current Kubernetes implemention of Istio, the rules are stored in ThirdPartyResources.
> You can look directly at the stored rules in Kubernetes using the `kubectl` command. For example,
> the following command will display all defined rules:
> ```bash
> $ kubectl get istioconfig -o yaml
> ```
```bash
istioctl create -f route-rule-all-v1.yaml
```
You can display the routes that are defined with the following command:
```yaml
$ istioctl get route-rules -o yaml
kind: route-rule
name: ratings-default
namespace: default
spec:
destination: ratings.default.svc.cluster.local
precedence: 1
route:
- tags:
version: v1
weight: 100
---
kind: route-rule
name: reviews-default
namespace: default
spec:
destination: reviews.default.svc.cluster.local
precedence: 1
route:
- tags:
version: v1
weight: 100
---
kind: route-rule
name: details-default
namespace: default
spec:
destination: details.default.svc.cluster.local
precedence: 1
route:
- tags:
version: v1
weight: 100
---
kind: route-rule
name: productpage-default
namespace: default
spec:
destination: productpage.default.svc.cluster.local
precedence: 1
route:
- tags:
version: v1
weight: 100
---
```
Since rule propagation to the proxies is asynchronous, you should wait a few seconds for the rules
to propagate to all pods before attempting to access the application.
If you open the Bookinfo URL (`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.
Notice that the `productpage` is displayed with no rating stars since `reviews:v1` does not access the ratings service.
1. Route a specific user to `reviews:v2`
Lets enable the ratings service for test user "jason" by routing productpage traffic to
`reviews:v2` instances.
```bash
$ istioctl create -f route-rule-reviews-test-v2.yaml
```
```bash
istioctl create -f route-rule-reviews-test-v2.yaml
```
Confirm the rule is created:
```bash
$ istioctl get route-rule reviews-test-v2
destination: reviews.default.svc.cluster.local
match:
httpHeaders:
Cookie:
regex: ^(.*?;)?(user=jason)(;.*)?$
precedence: 2
route:
- tags:
version: v2
```
```yaml
$ istioctl get route-rule reviews-test-v2
destination: reviews.default.svc.cluster.local
match:
httpHeaders:
Cookie:
regex: ^(.*?;)?(user=jason)(;.*)?$
precedence: 2
route:
- tags:
version: v2
```
Log in as user "jason" at the `productpage` web page. You should now see ratings (1-5 stars) next
to each review.
@ -275,36 +190,29 @@ route requests to all available versions of a service in a random fashion.
continue without any errors.
1. Inject the delay
Create a fault injection rule, to delay traffic coming from user "jason" (our test user).
```bash
$ istioctl create -f destination-ratings-test-delay.yaml
```
```bash
istioctl create -f destination-ratings-test-delay.yaml
```
Confirm the rule is created:
```bash
$ istioctl get route-rule ratings-test-delay
destination: ratings.default.svc.cluster.local
httpFault:
delay:
fixedDelaySeconds: 7
percent: 100
match:
httpHeaders:
Cookie:
regex: "^(.*?;)?(user=jason)(;.*)?$"
precedence: 2
route:
- tags:
version: v1
```
```yaml
$ istioctl get route-rule ratings-test-delay
destination: ratings.default.svc.cluster.local
httpFault:
delay:
fixedDelaySeconds: 7
percent: 100
match:
httpHeaders:
Cookie:
regex: "^(.*?;)?(user=jason)(;.*)?$"
precedence: 2
route:
- tags:
version: v1
```
Allow several seconds to account for rule propagation delay to all pods.
1. Observe application behavior
If the application's front page was set to correctly handle delays, we expect it
to load within approximately 7 seconds. To see the web page response times, open the
*Developer Tools* menu in IE, Chrome or Firefox (typically, key combination _Ctrl+Shift+I_
@ -339,34 +247,25 @@ Now that we have tested the reviews service, fixed the bug and deployed a
new version (`reviews:v3`), lets route all user traffic from `reviews:v1`
to `reviews:v3` in two steps.
First, transfer 50% of traffic from `reviews:v1` to `reviews:v3` with the following command:
1. First, transfer 50% of traffic from `reviews:v1` to `reviews:v3` with the following command:
```bash
$ istioctl replace -f route-rule-reviews-50-v3.yaml
istioctl replace -f route-rule-reviews-50-v3.yaml
```
> Notice that we are using `istioctl replace` instead of `create`.
To see the new version you need to either Log out as test user "jason" or delete the test rules
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 route-rule reviews-test-v2
$ istioctl delete route-rule ratings-test-delay
istioctl delete route-rule reviews-test-v2
istioctl delete route-rule ratings-test-delay
```
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` 100 times
> to see the proper distribution.
When we are confident that our Bookinfo app is stable, we route 100% of the traffic to `reviews:v3`:
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 route-rule-reviews-v3.yaml
istioctl replace -f route-rule-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.
@ -374,45 +273,27 @@ with *red* colored star ratings for each review.
### Rate Limiting [WIP]
Now we'll pretend that `ratings` is an external service for which we are paying (like going to rotten tomatoes),
1. Now we'll pretend that `ratings` is an external service for which we are paying (like going to rotten tomatoes),
so we will set a rate limit on the service such that the load remains under the Free quota (5q/s):
```bash
$ # (TODO) istioctl create -f mixer-rule-ratings-ratelimit.yaml
$ kubectl apply -f ../../mixer-config-quota-bookinfo.yaml
# (TODO) istioctl create -f mixer-rule-ratings-ratelimit.yaml
kubectl apply -f ../../mixer-config-quota-bookinfo.yaml
```
We now generate load on the `productpage` with the following command:
2. We now generate load on the `productpage` with the following command:
```bash
$ while true; do curl -s -o /dev/null http://$GATEWAY_URL/productpage; done
while true; do curl -s -o /dev/null http://$GATEWAY_URL/productpage; done
```
If you now refresh the `productpage` you'll see that while the load generator is running
(i.e., generating more than 5 req/s), we stop seeing stars.
## Cleanup
1. Delete the routing rules and terminate the application and control plane pods
```bash
$ ./cleanup.sh
```
1. Optionally shut down the control plane services
```bash
$ kubectl delete -f ./kubernetes/istio-install
$ kubectl delete -f ./kubernetes/addons
```
1. Delete the routing rules and terminate the application pods:
```bash
./cleanup.sh
```
1. Confirm shutdown
```bash
$ istioctl get route-rules #-- there should be no more routing rules
$ kubectl get pods #-- the bookinfo, and (optionally) control plane services, should be deleted
No resources found.
```
```bash
istioctl get route-rules #-- there should be no more routing rules
kubectl get pods #-- the bookinfo pods should be deleted
```

106
_docs/tasks/istio-installation.md
View File

@ -8,30 +8,100 @@ bodyclass: docs
layout: docs
type: markdown
---
This page shows how to install and configure Istio in a Kubernetes cluster.
This task shows how to install Istio in a Kubernetes cluster. You'll learn
how to install Istio and get it initially configured and running.
## Prerequisites
* The following instructions assume you have access to a Kubernetes cluster. To install Kubernetes locally, try [minikube](https://kubernetes.io/docs/getting-started-guides/minikube/).
* If you are using [Google Container Engine](https://cloud.google.com/container-engine), please make sure you are using static client certificates before fetching cluster credentials:
```bash
gcloud config set container/use_client_certificate True
gcloud container clusters get-credentials <cluster-name> --zone <zone> --project <project-name>
```
* Ensure the curl command is present.
## Installing on an existing cluster
For the Alpha release, Istio must be installed in the same Kubernetes namespace as the applications. Instructions below will deploy Istio in the default namespace. They can be modified for deployment in a different namespace.
## Before you begin
* Do this.
* Do this too.
1. Download and extract the [istio installation files](https://raw.githubusercontent.com/istio/istio/master/releases/istio-alpha.tar.gz), or
clone the github [istio](https://github.com/istio/istio) repository:
```bash
git clone https://github.com/istio/istio
```
1. Change directory to istio:
```bash
cd istio
```
2. Install the Istio core components (Istio-Manager, Mixer, and Ingress-Controller):
```bash
kubectl apply -f ./kubernetes/istio.yaml
```
1. Source the Istio configuration file:
```bash
source istio.VERSION
```
3. Download one of the [`istioctl`]({{site.bareurl}}/docs/reference/istioctl.html) client binaries corresponding to your OS: `istioctl-osx`, `istioctl-win.exe`,
`istioctl-linux`, targeted at Mac, Windows or Linux users respectively. For example, run the following commands on a Mac system:
```bash
curl ${ISTIOCTL_URL}/istioctl-osx > /usr/local/bin/istioctl
chmod +x /usr/local/bin/istioctl
```
Istioctl is needed to inject Envoy as a sidecar proxy. It also provides a convenient CLI for creating routing rules and policies.
Note: If you already have a previously installed version of `istioctl`, make sure that
it is compatible with the manager image used in `istio.yaml`.
If in doubt, download again or add the `--tag` option when running `istioctl kube-inject`.
Invoke `istioctl kube-inject --help` for more details.
4. Deploy your application with Envoy:
```bash
kubectl create -f <(istioctl kube-inject -f <your-app-spec>.yaml)
```
The [kube-inject]({{site.bareurl}}/docs/reference/istioctl.html##kube-inject) tool will automatically inject an Envoy container in the pod running the application.
Alternatively, deploy one of the samples applications, for instance [bookinfo]({{site.bareurl}}/docs/samples/bookinfo.html).
5. Optionally: to view metrics collected by Mixer, install [Prometheus](https://prometheus.io), [Grafana](http://staging.grafana.org) and ServiceGraph addons:
```bash
kubectl apply -f ./kubernetes/addons/grafana.yaml
kubectl apply -f ./kubernetes/addons/prometheus.yaml
kubectl apply -f ./kubernetes/addons/servicegraph.yaml
```
The Grafana image provided as part of this sample contains a built-in Istio dashboard that you can access from:
```bash
http://<grafana-svc-external-IP>:3000/dashboard/db/istio-dashboard
```
The addons yaml files contain services configured as type LoadBalancer. If services are deployed with type NodePort,
start kubectl proxy, and edit Grafana's Istio-dashboard to use the proxy. Access Grafana via kubectl proxy:
```bash
http://127.0.0.1:8001/api/v1/proxy/namespaces/default/services/grafana:3000/dashboard/db/istio-dashboard
```
## Doing ...
## Verify the installation
1. Do this.
1. Do this next. Possibly read this [related explanation](...).
1. Ensure the following Kubernetes services were deployed: "istio-manager", "istio-mixer", and "istio-ingress".
```bash
kubectl get svc
NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE
istio-ingress 10.83.241.84 35.184.70.168 80:30583/TCP 39m
istio-manager 10.83.251.26 <none> 8080/TCP 39m
istio-mixer 10.83.242.1 <none> 9091/TCP,42422/TCP 39m
```
2. Check the corresponding Kubernetes pods were deployed: "istio-manager-\*", "istio-mixer-\*", "istio-ingress-\*".
```bash
kubectl get pods
NAME READY STATUS RESTARTS AGE
istio-ingress-594763772-j7jbz 1/1 Running 0 49m
istio-manager-373576132-p2t9k 1/1 Running 0 49m
istio-mixer-1154414227-56q3z 1/1 Running 0 49m
```
## Understanding ...
Here's an interesting thing to know about the steps you just did.
## Uninstall
1. Uninstall Istio:
```bash
kubectl delete -f ./kubernetes/istio.yaml
```
2. Delete the istioctl client:
```bash
rm /usr/local/bin/istioctl
```
## What's next
* Learn more about [this](...).
* See this [related task](...).
* Learn more about how to enable [authentication]({{site.bareurl}}/docs/tasks/istio-auth.html).
* See the sample [bookinfo]({{site.bareurl}}/docs/samples/bookinfo.html) application.