Installing Istio on a GKE cluster

Istio is an open source framework for connecting, monitoring, and securing microservices, including services running on GKE. 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. The Envoy proxy intercepts all network communication between microservices, and is configured and managed using Istio's control plane functionality.

This guide shows you how to install open source Istio on a GKE cluster using Helm, and walks you through deploying a demo Istio-enabled multi-service application.

Before you begin

Take the following steps to enable the Kubernetes Engine API:
  1. Visit the Kubernetes Engine page in the Google Cloud Console.
  2. Create or select a project.
  3. Wait for the API and related services to be enabled. This can take several minutes.
  4. 請確認您已啟用 Google Cloud Platform 專案的計費功能。瞭解如何確認您已啟用專案的計費功能

Install the following command-line tools used in this tutorial:

  • gcloud is used to create and delete Kubernetes Engine clusters. gcloud is included in the Google Cloud SDK.
  • kubectl is used to manage Kubernetes, the cluster orchestration system used by Kubernetes Engine. You can install kubectl using gcloud:
    gcloud components install kubectl

Set defaults for the gcloud command-line tool

To save time typing your project ID and Compute Engine zone options in the gcloud command-line tool, you can set the defaults:
gcloud config set project [PROJECT_ID]
gcloud config set compute/zone [COMPUTE_ENGINE_ZONE]

Install Helm

For installing Istio, we recommend using Helm with one of Istio's configurable profiles.

If you haven't installed Helm already, follow the instructions in the Helm README to install the helm v2.x binary on the machine where you have your cluster credentials. Note that Helm v3 isn't currently supported.

Cluster setup

You need a suitable GKE cluster to install Istio and the demo application.

  • To create a new cluster, use gcloud container clusters create. In this example the cluster is called istio-tutorial:

    gcloud container clusters create istio-tutorial \
        --machine-type=n1-standard-2 \
  • If you want to use an existing cluster instead, ensure that it is using the GKE default version of Kubernetes and has role based access control (RBAC) enabled. RBAC is enabled by default on all clusters running Kubernetes version 1.6 or later. To enable RBAC on an older version, update your cluster with the option --no-enable-legacy-authorization.

Credentials and permissions

  1. Especially if you are using an existing cluster, ensure that you have cluster credentials for kubectl on the machine where you want to run the installation commands. For example, the following command gets the credentials for a cluster called istio-tutorial:

    gcloud container clusters get-credentials istio-tutorial
  2. Ensure that the kubectl version is the same or more recent than your cluster. You can verify that you are using the latest version by running kubectl version.

  3. Grant cluster admin permissions to the current user. You need these permissions to create the necessary role based access control (RBAC) rules for Istio:

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

    Although you can run the demo app without granting cluster admin permissions, the permissions are required if you want to access telemetry data and other Istio features.

Download Istio

Follow these steps on the same machine where you have your cluster credentials: this is your cluster admin machine.

  1. Run the following command to download and extract the installation file corresponding to your OS where you want to run the Istio client:

    curl -L | sh -

    The command creates an installation directory in your current working directory named istio-VERSION that contains:

    • Installation .yaml files for Kubernetes in install/
    • Sample applications in samples/
    • The istioctl client binary in the bin/ directory. You can use istioctl to manually inject Envoy as a sidecar proxy and to create routing rules and policies.
    • The istio.VERSION configuration file.
  2. Ensure that you're in the Istio installation's root directory:

    cd istio-VERSION
  3. Add the istioctl client to your PATH:

    export PATH=$PWD/bin:$PATH

Install Istio

Before installing Istio itself, do the following to set up the istio-system namespace for Istio's control plane components:

kubectl create namespace istio-system

Now you're ready to install Istio. Istio is installed in the istio-system namespace you just created, and can manage microservices from all other namespaces. The installation includes Istio core components, tools, and samples.

  1. Ensure that you're in the Istio installation's root directory.

  2. Install the Istio Custom Resource Definitions (CRDs):

    helm template install/kubernetes/helm/istio-init \
      --name istio-init --namespace istio-system | kubectl apply -f -
  3. Wait a few seconds for all the CRDs to be committed in the Kubernetes API server.

  4. Install Istio with the default profile. Although you can choose another profile, we recommend the default profile for production deployments.

    helm template install/kubernetes/helm/istio \
      --name istio --namespace istio-system | kubectl apply -f -

    This deploys the core Istio components:

    • Istio-Pilot, which is responsible for service discovery and for configuring the Envoy sidecar proxies in an Istio service mesh.
    • The Mixer components Istio-Policy and Istio-Telemetry, which enforce usage policies and gather telemetry data across the service mesh.
    • Istio-Ingressgateway, which provides an ingress point for traffic from outside the cluster.
    • Istio-Citadel, which automates key and certificate management for Istio.

Verify Istio installation

  1. Ensure the following Kubernetes Services are deployed: istio-citadel, istio-pilot, istio-ingressgateway, istio-policy, and istio-telemetry (you'll also see the other deployed services):

    kubectl get service -n istio-system
    NAME                       TYPE           CLUSTER-IP      EXTERNAL-IP   PORT(S)                                                               AGE
    istio-citadel              ClusterIP            8060/TCP,9093/TCP                                                     37s
    istio-galley               ClusterIP             443/TCP,15014/TCP,9901/TCP                                            37s
    istio-ingressgateway       LoadBalancer        80:31380/TCP,443:31390/TCP,31400:31400/TCP                            40s
    istio-pilot                ClusterIP            15003/TCP,15005/TCP,15007/TCP,15010/TCP,15011/TCP,8080/TCP,9093/TCP   38s
    istio-policy               ClusterIP           9091/TCP,15004/TCP,9093/TCP                                           39s
    istio-sidecar-injector     ClusterIP           443/TCP                                                               37s
    istio-statsd-prom-bridge   ClusterIP            9102/TCP,9125/UDP                                                     39s
    istio-telemetry            ClusterIP            9091/TCP,15004/TCP,9093/TCP,42422/TCP                                 39s
  2. Ensure the corresponding Kubernetes Pods are deployed and all containers are up and running: istio-pilot-*, istio-policy-*, istio-telemetry-*, istio-ingressgateway-*, and istio-citadel-*.

    kubectl get pods -n istio-system
    NAME                                        READY     STATUS      RESTARTS   AGE
    istio-citadel-54f4678f86-4549b              1/1       Running     0          12m
    istio-cleanup-secrets-5pl77                 0/1       Completed   0          12m
    istio-galley-7bd8b5f88f-nhwlc               1/1       Running     0          12m
    istio-ingressgateway-665699c874-l62rg       1/1       Running     0          12m
    istio-pilot-68cbbcd65d-l5298                2/2       Running     0          12m
    istio-policy-7c5b5bb744-k6vm9               2/2       Running     0          12m
    istio-security-post-install-g9l9p           0/1       Completed   3          12m
    istio-sidecar-injector-85ccf84984-2hpfm     1/1       Running     0          12m
    istio-telemetry-5b6c57fffc-9j4dc            2/2       Running     0          12m
    istio-tracing-77f9f94b98-jv8vh              1/1       Running     0          12m
    prometheus-7456f56c96-7hrk5                 1/1       Running     0          12m

Deploy the sample application

Once Istio is installed and all its components are running, you can try deploying one of the sample applications provided with the installation. In this tutorial, we'll install 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 can find the source code and all the other files used in this example in your Istio installation's samples/bookinfo directory.

Following these steps deploys the BookInfo application's services in an Istio-enabled environment, with Envoy sidecar proxies injected alongside each service to provide Istio functionality.

  1. Ensure you're still in the root of the Istio installation directory on your cluster admin machine.

  2. Deploy the application using kubectl apply and istioctl kube-inject. The kube-inject command updates the BookInfo deployment so that a sidecar is deployed in each application Pod along with the service.

    kubectl apply -f <(istioctl kube-inject -f samples/bookinfo/platform/kube/bookinfo.yaml)
  3. 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              <none>        9080/TCP             6m
    kubernetes            <none>        443/TCP              7d
    productpage         <none>        9080/TCP             6m
    ratings              <none>        9080/TCP             6m
    reviews             <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
  4. Finally, define the ingress gateway routing for the application:

    kubectl apply -f samples/bookinfo/networking/bookinfo-gateway.yaml

Validate the application deployment

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

Getting the ingress address

To see if the BookInfo application is working, you need to send traffic to the ingress gateway. Get the external IP address of the ingress gateway as follows:

kubectl get svc istio-ingressgateway -n istio-system
NAME                   TYPE           CLUSTER-IP      EXTERNAL-IP   PORT(S)                                      AGE
istio-ingressgateway   LoadBalancer   80:31380/TCP,443:31390/TCP,31400:31400/TCP   27m

In this example, the address of the ingress service is


Trying the application

  1. Check that the BookInfo app is running with curl:

    curl -I http://${GATEWAY_URL}/productpage

    If the response shows 200, it means the application is working properly with Istio.

  2. Now 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.

Deploying your own application

If you want to try deploying one of your own applications, just follow the same procedure with your own YAML deployment: Istio requires no changes to the application itself. Note that the application must use HTTP/1.1 or HTTP/2.0 protocol for all its HTTP traffic because the Envoy proxy doesn't support HTTP/1.0: it relies on headers that aren't present in HTTP/1.0 for routing.

You can either use kube-inject to add the sidecars when deploying the application, as in our example, or enable Istio's automatic sidecar injection for the namespace where your application is running.

Enabling Stackdriver Monitoring

If the Stackdriver Monitoring API is enabled in your Google Cloud project, you can configure Istio to send metrics related to your services (such as the number of bytes received by a particular service) to Stackdriver Monitoring, where they appear in the Metrics Explorer. You can use these metrics to create charts and alerts, letting you monitor your services over time and receive alerts when, for example, a service is nearing a specified number of requests. You can also combine these metrics using filters and aggregations with Stackdriver Monitoring's built-in metrics to get new insights into your service behavior.

To view the metrics for a monitored resource using Metrics Explorer, do the following:

  1. In the Google Cloud Console, go to Monitoring or use the following button:
    Go to Monitoring
  2. If Metrics Explorer is shown in the navigation pane, click Metrics Explorer. Otherwise, select Resources and then select Metrics Explorer.
  3. Enter the monitored resource name in the Find resource type and metric text box.

If you want to send the default metrics to Stackdriver Monitoring, follow the steps below. If you need to make any customizations, you can generate your own manifest as described in the README for the Stackdriver adapter.

To enable Stackdriver Monitoring:

  1. Ensure that Stackdriver Kubernetes Engine Monitoring is enabled for your cluster.

  2. Download istio-stackdriver-metrics.yaml.

  3. Configure the Stackdriver metrics adapter:

    kubectl apply -n istio-system -f istio-stackdriver-metrics.yaml

For a full list of Istio metrics, see the Stackdriver Monitoring documentation.


To uninstall Istio, run the following commands from your cluster admin machine:

helm template install/kubernetes/helm/istio --name istio --namespace istio-system | kubectl delete -f -
kubectl delete namespace istio-system

What's next?

Learn more about Istio on the Istio site.