Istio is an open source framework for connecting, securing, and managing microservices, including services running on Container Engine. It lets you create a network of deployed services with load balancing, service-to-service authentication, monitoring, and more, without requiring any changes in service code.

You add Istio support to services by deploying a special Envoy sidecar proxy to each of your application's pods in your environment that intercepts all network communication between microservices, configured and managed using Istio's control plane functionality.

This codelab shows you how to install and configure Istio on Container Engine, deploy an Istio-enabled multi-service application, and dynamically change request routing.

Self-paced environment setup

If you don't already have a Google Account (Gmail or G Suite), you must create one. Sign-in to Google Cloud Platform console (console.cloud.google.com) and create a new project from the Manage resources page :

Remember the project ID, a unique name across all Google Cloud projects (the name above has already been taken and will not work for you, sorry!). It will be referred to later in this codelab as PROJECT_ID.

Next, you'll need to enable billing in the Developers Console in order to use Google Cloud resources.

Running through this codelab shouldn't cost you more than a few dollars, but it could be more if you decide to use more resources or if you leave them running (see "cleanup" section at the end of this document). The Google Cloud Platform pricing calculator is available here.

New users of Google Cloud Platform are eligible for a $300 free trial.

Google Cloud Shell

While Google Cloud and Kubernetes can be operated remotely from your laptop, in this codelab we will be using Google Cloud Shell, a command line environment running in the Cloud.

This Debian-based virtual machine is loaded with all the development tools you'll need. It offers a persistent 5GB home directory, and runs on the Google Cloud, greatly enhancing network performance and authentication. This means that all you will need for this codelab is a browser (yes, it works on a Chromebook).

To activate Google Cloud Shell, from the developer console simply click the button on the top right-hand side (it should only take a few moments to provision and connect to the environment):

Then accept the terms of service and click the "Start Cloud Shell" link:

Once connected to the cloud shell, you should see that you are already authenticated and that the project is already set to your PROJECT_ID :

gcloud auth list

Command output

Credentialed accounts:
 - <myaccount>@<mydomain>.com (active)
gcloud config list project

Command output

[core]
project = <PROJECT_ID>

If for some reason the project is not set, simply issue the following command :

gcloud config set project <PROJECT_ID>

Looking for your PROJECT_ID? Check out what ID you used in the setup steps or look it up in the console dashboard:

IMPORTANT: Finally, set the default zone and project configuration:

gcloud config set compute/zone us-central1-f

You can choose a variety of different zones. Learn more in the Regions & Zones documentation.

The requirements for this Istio codelab are as follows:

To create a new cluster that meets these requirements, including alpha features, run the following commands (this assumes that you have correctly set a zone as indicated in the setup) :

gcloud container clusters create hello-istio \
    --enable-kubernetes-alpha \
    --machine-type=n1-standard-2 \
    --num-nodes=4 \
    --no-enable-legacy-authorization

Now, grant cluster admin permissions to the current user. You need these permissions to create the necessary RBAC rules for Istio.

kubectl create clusterrolebinding cluster-admin-binding \
    --clusterrole=cluster-admin \
    --user=$(gcloud config get-value core/account)

If you navigate in the GCP console to Container Engine clusters you should see a screen similar to this:

Now, let's install Istio. Istio is installed in its own Kubernetes istio-system namespace, and can manage microservices from all other namespaces. The installation includes Istio core components, tools, and samples.

The Istio release page offers download artifacts for several OSs. In our case, with CloudShell we'll be using this command to download and extract the latest release automatically:

curl -L https://git.io/getLatestIstio | sh -

The installation directory contains the following:

Change to the istio install directory:

cd ./istio-*

Add the istioctl client to your PATH:

export PATH=$PWD/bin:$PATH

Let's now install Istio's core components. We will install the Istio Auth components which enable mutual TLS authentication between sidecars:

kubectl apply -f install/kubernetes/istio-auth.yaml

This creates the istio-system namespace along with the required RBAC permissions, and deploys Istio-Pilot, Istio-Mixer, Istio-Ingress, Istio-Egress, and Istio-CA (Certificate Authority).

To automatically inject sidecar proxies into a pod before deployment, install the Istio-Initializer:

kubectl apply -f install/kubernetes/istio-initializer.yaml

First, ensure the following Kubernetes services are deployed: istio-pilot, istio-mixer, istio-ingress, and istio-egress.

kubectl get svc -n istio-system

NAME            CLUSTER-IP      EXTERNAL-IP       PORT(S)                       AGE
istio-egress    10.83.247.89    <none>            80/TCP                        3m
istio-ingress   10.83.245.171   35.184.245.62     80:32730/TCP,443:30574/TCP    3m
istio-pilot     10.83.251.173   <none>            8080/TCP,8081/TCP             3m
istio-mixer     10.83.244.253   <none>            9091/TCP,9094/TCP,42422/TCP   3m

Then make sure that the corresponding Kubernetes pods are deployed and all containers are up and running: istio-pilot-*, istio-mixer-*, istio-ingress-*, istio-egress-*, istio-ca-*, and, optionally, istio-initializer-*.

kubectl get pods -n istio-system

NAME                                READY     STATUS    RESTARTS   AGE
istio-ca-3657790228-j21b9           1/1       Running   0          3m
istio-egress-1684034556-fhw89       1/1       Running   0          3m
istio-ingress-1842462111-j3vcs      1/1       Running   0          3m
istio-initializer-184129454-zdgf5   1/1       Running   0          3m
istio-pilot-2275554717-93c43        1/1       Running   0          3m
istio-mixer-2104784889-20rm8        2/2       Running   0          3m

When all the pods are running, you can proceed.

Now Istio is installed and verified, you can deploy one of the sample applications provided with the installation — BookInfo. This is a simple mock bookstore application made up of four services that provide a web product page, book details, reviews (with several versions of the review service), and ratings - all managed using Istio.

You will find the source code and all the other files used in this example in your Istio samples/bookinfo directory. These steps will deploy the BookInfo application's services in an Istio-enabled environment, with Envoy sidecar proxies injected alongside each service to provide Istio functionality.

Because we installed the Istio Initializer component, we deploy our application directly using kubectl create and its regular YAML deployment file. The Istio-Initializer automatically injects Envoy containers into your application pods:

kubectl create -f samples/bookinfo/kube/bookinfo.yaml

Finally, confirm that the application has been deployed correctly by running the following commands:

kubectl get services

NAME                       CLUSTER-IP   EXTERNAL-IP   PORT(S)              AGE
details                    10.0.0.31    <none>        9080/TCP             6m
kubernetes                 10.0.0.1     <none>        443/TCP              21m
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
kubectl get pods

NAME                                        READY     STATUS    RESTARTS   AGE
details-v1-1520924117-48z17                 2/2       Running   0          6m
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

Now that it's deployed, let's see the BookInfo application in action.

First you need to get the ingress IP and port, as follows:

kubectl get ingress -o wide

NAME      HOSTS     ADDRESS                 PORTS     AGE
gateway   *         130.211.10.121          80        3m

Based on this information, set the GATEWAY_URL environment variable:

export GATEWAY_URL=130.211.10.121:80

Once you have the address and port, check that the BookInfo app is running with curl:

curl -o /dev/null -s -w "%{http_code}\n" http://${GATEWAY_URL}/productpage
200

Then 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 the product page, presented in a round robin style (red stars, black stars, no stars), since we haven't yet used Istio to control the version routing.

The BookInfo sample deploys three versions of the reviews microservice. When you accessed the application several times, you will have noticed that the output sometimes contains star ratings and sometimes it does not. This is because without an explicit default version set, Istio will route requests to all available versions of a service in a random fashion.

We use the istioctl command line tool to control routing, adding a route rule that says all traffic should go to the v1 service. First, confirm there are no route rules installed :

istioctl get routerules -o yaml

Now, create the rule (check out the source yaml file it you'd like to understand how rules are specified) :

istioctl create -f samples/bookinfo/kube/route-rule-all-v1.yaml -n default

Created config route-rule/default/productpage-default at revision 136126
Created config route-rule/default/reviews-default at revision 136127
Created config route-rule/default/ratings-default at revision 136128
Created config route-rule/default/details-default at revision 136130

Look at the rule you've just created:

istioctl get routerules -o yaml

Go back to the Bookinfo application (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.

To test reviews:v2, but only for a certain user, let's create this rule:

istioctl create -f samples/bookinfo/kube/route-rule-reviews-test-v2.yaml -n default

Check out the route-rule-reviews-test-v2.yaml file to see how this rule is specified :

$ cat samples/bookinfo/kube/route-rule-reviews-test-v2.yaml

apiVersion: config.istio.io/v1alpha2
kind: RouteRule
metadata:
  name: reviews-test-v2
spec:
  destination:
    name: reviews
  precedence: 2
  match:
    request:
      headers:
        cookie:
          regex: "^(.*?;)?(user=jason)(;.*)?$"
  route:
  - labels:
      version: v2

Look at the rule you've just created :

istioctl get routerule reviews-test-v2 -o yaml

We now have a way to route some requests to use the reviews:v2 service. Can you guess how? (Hint: no passwords are needed) See how the page behaviour changes if you are logged in as no-one, 'jason', or 'kylie'.

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.

For now, let's clean up the routing rules:

istioctl delete -f samples/bookinfo/kube/route-rule-all-v1.yaml -n default
istioctl delete -f samples/bookinfo/kube/route-rule-reviews-test-v2.yaml -n default

Istio-enabled applications can be configured to collect trace spans using Zipkin or Jaeger. Distributed tracing lets you see the flow of requests a user makes through your system, and Istio's model allows this regardless of what language/framework/platform you use to build your application.

First, install the Zipkin addon :

kubectl apply -f install/kubernetes/addons/zipkin.yaml

Istio is now configured to send request information.

Configure port forwarding :

kubectl port-forward -n istio-system $(kubectl get pod -n istio-system -l app=zipkin -o jsonpath='{.items[0].metadata.name}') 9411:9411 &

Open your browser at http://localhost:9411.

Load the Bookinfo application again (http://$GATEWAY_URL/productpage).

Select a trace from the list, and you will now see something similar to the following:

You can see how long each microservice call took, including the Istio checks.

Here's how to uninstall Istio.

kubectl delete -f samples/bookinfo/kube/bookinfo.yaml

service "details" deleted
deployment "details-v1" deleted
service "ratings" deleted
deployment "ratings-v1" deleted
service "reviews" deleted
deployment "reviews-v1" deleted
deployment "reviews-v2" deleted
deployment "reviews-v3" deleted
service "productpage" deleted
deployment "productpage-v1" deleted
ingress "gateway" deleted
kubectl delete -f install/kubernetes/istio-initializer.yaml
kubectl delete -f install/kubernetes/istio-auth.yaml

In addition to uninstalling Istio, you should also delete the Kubernetes cluster created in the setup phase (to save on cost and to be a good cloud citizen):

gcloud container clusters delete hello-istio

The following clusters will be deleted.
 - [hello-istio] in [us-central1-f]
Do you want to continue (Y/n)?  Y
Deleting cluster hello-istio...done.                                                                                                                                                                                            
Deleted [https://container.googleapis.com/v1/projects/codelab-test/zones/us-central1-f/clusters/hello-istio].

Of course, you can also delete the entire project but you would lose any billing setup you have done (disabling project billing first is required). Additionally, deleting a project will only stop all billing after the current billing cycle ends.

The Istio site contains guides and samples with fully working example uses for Istio that you can experiment with. These include: