This guide shows you how to get started with the Istio on GKE add-on, including
installation options for new and existing clusters. You can install the add-on
using either the gcloud command line tool or the Google Cloud Platform Console.
You can find out more about the Istio on GKE add-on and whether it's right for you in the Overview.
Before you start
Take the following steps to enable the Kubernetes Engine API:
- Visit the Kubernetes Engine page in the Google Cloud Platform Console.
- Create or select a project.
- Wait for the API and related services to be enabled. This can take several minutes.
-
确保您的 Google Cloud Platform 项目已启用结算功能。
Ensure you have the following command line tools installed:
-
gcloudis used to create and delete Kubernetes Engine clusters, including creating and updating clusters with the Istio on GKE add-on.gcloudis included in the Google Cloud SDK: follow the instructions to install and initialize it to work with your GCP projects. If you have an existinggcloudinstallation, verify that it's at least version 208.0.0:gcloud version
Note that you don't have to installgcloudto create a new Istio-enabled cluster, as you can use the Google Cloud Platform Console instead, but it's still useful for managing existing clusters and installing other tools likekubectl. -
kubectlis used to manage Kubernetes, the cluster orchestration system used by GKE. You can installkubectlusinggcloud: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]
Choose a security option
There are two possible default mesh-wide security options to choose from when creating or updating a cluster with Istio on GKE. Which one you choose depends on your initial application needs.
- Strict mTLS: In this security mode, Istio enforces mutual TLS (mTLS) encryption between all services and control plane components in the mesh by default, unless you override it with destination-specific rules. All calls within the mesh are encrypted and services will not accept unencrypted traffic.
- Permissive mTLS: In this security mode, by default Istio allows services in the mesh to accept both encrypted and unencrypted traffic, and all services send unencrypted calls by default. As with strict mTLS, you can override this for specific services. Use this option if you have services that still need to accept unencrypted traffic, for example if you have not fully migrated your services to Istio and have traffic coming from legacy clients outside the mesh. Istio on GKE provides this mode rather than simply installing Istio with no security enabled, as it makes it easier to migrate to strict mTLS later for added security.
You can find out how to update your security defaults and further configure Istio security in Updating security defaults, below.
Supported GKE cluster versions
The version of Istio on GKE installed when you create or update a cluster with Istio on GKE depends on the cluster version. We recommend that you use a version with the latest version of Istio (1.0.6-gke.3). Other GKE versions that have older but still supported versions of Istio are listed below. Check the release notes if you plan to use an older version to ensure you are not affected by known issues for that version.
The table lists the minimum GKE versions that are recommended or supported. So
if 1.10.11-gke.1 is supported, then 1.10.11-gke.1,2,3… are also supported.
| Istio version | GKE versions |
|---|---|
1.1.7-gke.0 (recommended)
|
1.13.7-gke.8
See the following for more information: |
1.1.3-gke.0 (supported)
|
1.13.6-gke.0
See the following for more information: |
1.0.6-gke.3 (recommended)
|
1.10.12-gke.14
|
1.0.6-gke.1 (supported)
|
1.11.7-gke.15
|
1.0.3-gke.3b (supported)
|
1.10.12-gke.10
|
1.0.3-gke.3a (supported)
|
1.10.12-gke.7
|
Creating a cluster with Istio on GKE
We suggest creating at least a 4 node cluster with the 2 vCPU machine type when using this add-on. You can deploy Istio itself with the default GKE new cluster setup but this may not provide enough resources to explore sample applications.
To create a cluster using Istio on GKE:
Console
- Go to the Kubernetes page in the GCP Console and select Create Cluster.
- Using the default Standard Cluster dialog, choose your preferred number of nodes and machines, bearing in mind the minimum recommended cluster size for Istio.
- In the Master Version drop-down, select an Istio on GKE recommended cluster version (or a supported version if you can't use the recommended version).
- Select Advanced Options to display additional configuration options, including Istio on GKE.
- Select Enable Istio (beta).
- Select the mTLS security mode you want to use for your cluster from the drop-down.
- Click Create to create your cluster.
Command line
To create a GKE cluster with Istio enabled and with mutual TLS enforced by default, run this command, replacing istio-demo with your chosen cluster name, and [cluster-version] with a compatible cluster version:
gcloud beta container clusters create istio-demo \
--addons=Istio --istio-config=auth=MTLS_STRICT \
--cluster-version=[cluster-version] \
--machine-type=n1-standard-2 \
--num-nodes=4
Or to create a GKE cluster with Istio enabled and with mTLS in permissive mode:
gcloud beta container clusters create istio-demo \
--addons=Istio --istio-config=auth=MTLS_PERMISSIVE \
--cluster-version=[cluster-version] \
--machine-type=n1-standard-2 \
--num-nodes=4
Adding Istio on GKE to an existing cluster
If you want to update a cluster with the add-on, you may need to first resize your cluster to ensure that you have enough resources for Istio. As when creating a new cluster, we suggest at least a 4 node cluster with the 2 vCPU machine type.
Your cluster must also be running a supported cluster master version to use the add-on.
To update an existing cluster with the Istio on GKE add-on:
Console
- Go to the Kubernetes clusters page in the GCP Console and select the cluster you want to update
- Select Edit.
- Select Add-ons to display possible add-ons, including Istio on GKE.
- Select Enabled under Istio (beta)
- Select the mTLS security mode you want to use for your cluster from the drop-down.
- Click Save to update your cluster.
Command line
To add Istio with mutual TLS enforced by default to an existing cluster, run this command, replacing istio-demo with the cluster name:
gcloud beta container clusters update istio-demo \
--update-addons=Istio=ENABLED --istio-config=auth=MTLS_STRICT
Or to add Istio with mTLS in permissive mode to an existing cluster:
gcloud beta container clusters update istio-demo \
--update-addons=Istio=ENABLED --istio-config=auth=MTLS_PERMISSIVE
Note that the clusters update command may require other parameters, depending
on your actual cluster configuration.
If you have an existing application on the cluster, you can find out how to migrate it so it's managed by Istio in the Istio documentation.
Verifying installation
To verify that your Istio on GKE installation was successful:
- If you've just created rather than updated a cluster, check that it's up and
running with a GKE version of 1.10.6 or higher:
gcloud container clusters list
Output:NAME LOCATION MASTER_VERSION MASTER_IP MACHINE_TYPE NODE_VERSION NUM_NODES STATUS istio-demo us-central1-b 1.11.2-gke.15 35.239.252.38 n1-standard-2 1.11.2-gke.15 4 RUNNING
- Get the credentials for your new cluster so you can interact with it with
kubectl.gcloud container clusters get-credentials istio-demo --project=$PROJECT
- Ensure the following Kubernetes services are deployed:
istio-citadel,istio-egressgateway,istio-pilot,istio-ingressgateway,istio-policy,istio-sidecar-injector, andistio-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 10.47.245.92 <none> 8060/TCP,9093/TCP 12s istio-egressgateway ClusterIP 10.47.248.129 <none> 80/TCP,443/TCP 12s istio-galley ClusterIP 10.47.248.109 <none> 443/TCP,9093/TCP 12s istio-ingressgateway LoadBalancer 10.47.248.117 <pending> 80:31380/TCP,443:31390/TCP,31400:31400/TCP,15011:30221/TCP,8060:32445/TCP,853:30663/TCP,15030:32010/TCP,15031:32633/TCP 12s istio-pilot ClusterIP 10.47.251.133 <none> 15010/TCP,15011/TCP,8080/TCP,9093/TCP 12s istio-policy ClusterIP 10.47.255.244 <none> 9091/TCP,15004/TCP,9093/TCP 12s istio-sidecar-injector ClusterIP 10.47.240.36 <none> 443/TCP 12s istio-statsd-prom-bridge ClusterIP 10.47.247.135 <none> 9102/TCP,9125/UDP 12s istio-telemetry ClusterIP 10.47.242.73 <none> 9091/TCP,15004/TCP,9093/TCP,42422/TCP 12s promsd ClusterIP 10.47.241.188 <none> 9090/TCP 12s
Ensure the corresponding Kubernetes pods are deployed and all containers are up and running:
istio-pilot-*,istio-policy-*,istio-telemetry-*,istio-egressgateway-*,istio-ingressgateway-*,istio-sidecar-injector-*, andistio-citadel-*.kubectl get pods -n istio-system
NAME READY STATUS RESTARTS AGE istio-citadel-555d845b65-xfdmj 1/1 Running 0 2d istio-cleanup-secrets-8x2pl 0/1 Completed 0 2d istio-egressgateway-667d854c49-9q5dl 1/1 Running 0 2d istio-galley-6c9cd5b8bb-4j4jk 1/1 Running 0 2d istio-ingressgateway-6c796c5594-f972p 1/1 Running 0 2d istio-pilot-77f74fc6f-rpbfj 2/2 Running 0 2d istio-policy-655b87fff-4wbwq 2/2 Running 0 2d istio-security-post-install-tm2rm 0/1 Completed 1 2d istio-sidecar-injector-668c9fb4db-p6lwt 1/1 Running 0 2d istio-statsd-prom-bridge-5b645f6f4d-6pbgf 1/1 Running 0 2d istio-telemetry-d9848f498-wf6kh 2/2 Running 0 2d promsd-6b989699d8-l7jxt 1/1 Running 0 2d
Enabling sidecar injection
To let Istio actually manage your services, each service in your application needs to have an Envoy sidecar proxy running in its pod to proxy network traffic between it and other services, and to communicate with the Istio control plane. You can inject these manually by updating your pods' Kubernetes configuration, or (the simpler option) you can use Istio's webhooks-based automatic sidecar injection. By default, Istio sidecar auto-injection is disabled for all namespaces. To enable auto-injection in your-namespace, run:
kubectl label namespace your-namespace istio-injection=enabled
Any running pods must be restarted for the change to take effect, as the sidecar is added at pod creation time. To disable auto-injection in the namespace, remove the label and restart pods to remove their sidecars.
You can find out how to add sidecars manually in Installing the sidecar.
Updating security defaults
Switching the default Istio mTLS security mode in a running cluster from Strict to Permissive, or vice versa, uses the same command as adding Istio to a cluster:
Console
- Go to the Kubernetes clusters page in the GCP Console and select the cluster you want to update
- Select Edit.
- Select Add-ons to display possible add-ons, including Istio on GKE.
- Select the mTLS security mode you want to use for your cluster from the drop-down.
- Click Save to update your cluster.
Command line
To change your cluster to use Istio with mutual TLS enforced by default, run this command, replacing istio-demo with the cluster name:
$ gcloud beta container clusters update istio-demo \
--update-addons=Istio=ENABLED --istio-config=auth=MTLS_STRICT
Or to change your cluster to mTLS in permissive mode:
$ gcloud beta container clusters update istio-demo \
--update-addons=Istio=ENABLED --istio-config=auth=MTLS_PERMISSIVE
Be aware that if you enable strict mTLS while you still have services that need to send or receive unencrypted traffic, your application may break! You can find out more about migrating to strict mTLS in Mutual TLS Migration. You can also specify more fine-grained destination-specific authentication policies. Destination-specific authentication policies will always override any global default mTLS setting, even if you switch from Strict to Permissive or vice versa.
You can find out much more about configuring and working with Istio security, including setting up role based authorization, in the Istio site.
Adding Prometheus
If you want to install your own instance of Prometheus
for metrics collection, install the following manifest (which you may edit as
needed before applying). Replace istio-version with your current
Istio version,for example, 1.0.3-gke.3.
curl https://storage.googleapis.com/gke-release/istio/release/istio-version/patches/install-prometheus.yaml | kubectl apply -n istio-system -f -
Installing this manifest creates a new Prometheus service and deployment to collect user metrics.
Adding adapters
Istio uses backend adapters that let your services send telemetry information to tools like Stackdriver, Grafana, and ServiceGraph. You can find out more about using these tools in the Istio telemetry documentation and the Stackdriver Monitoring documentation.
The only adapter that Istio on GKE installs by default is the Stackdriver adapter. If you need other adapters, you can use Helm to install them after your cluster is created.
To get set up to add adapters:
- Install the Helm client.
- Download the Helm charts, which are included in the Istio installation file. Because the Helm charts might differ between Istio versions, make sure you download the version of the Istio installation file that matches the Istio for GKE addon version.
To add an adapter:
- Select the adapter options you want to install.
- Run Helm and specify the selected options to include the YAML for the adapter in the generated Istio manifest.
Delete everything from the generated Istio manifest except the YAML for the adapter.
Apply the Istio manifest:
kubectl apply -f MANIFEST_FILE
For example, to install the Grafana adapter, you can run the following commands to create a unified diff file that includes only the YAML that pertains to Grafana.
helm template --set grafana.enabled=false --namespace istio-system install/kubernetes/helm/istio > off.yaml helm template --set grafana.enabled=true --namespace istio-system install/kubernetes/helm/istio > on.yaml diff -u off.yaml on.yaml > grafana.patch
You must manually edit the unified diff file to resolve the differences and create the Istio manifest. After you apply the Istio manifest, refer to Visualizing Metrics with Grafana for details on viewing the Istio Dashboard in Grafana.
Adding gateways
An ingress and egress gateway are provided as part of your Istio on GKE installation. These are suitable for deployments where the installed resources (RBAC, Service, Deployment) do not need customization beyond adding fields. For more complex scenarios where customization is required, we recommend creating new ingress/egress resources following the instructions in Istio.io. Any ingress and egress resources that you add yourself are under user control and are not reconciled or auto upgraded.
Accessing external services
By default, Istio blocks all outbound requests from inside the cluster. To allow outbound requests, create ServiceEntries for permitted destinations.
Stackdriver tracing and logging
By default, a mesh installed with Istio on GKE can send logging and metrics data to Stackdriver, provided you have enabled the relevant Stackdriver features for your project and cluster. Versions of Istio on GKE earlier than 1.1.7 also send trace data by default. You can find out more about this in Stackdriver Support.
Both tracing and logging may incur additional costs to use, especially with a large volume of data coming from your mesh. If you would like to disable this feature without disabling the Stackdriver APIs entirely for your project, update your Istio on GKE configuration as follows.
To disable Stackdriver logging for Istio on GKE
Open the
stackdriver-logrule for editing:kubectl edit -n istio-system rule stackdriver-log
Replace the
matchcondition(context.protocol == "http" || context.protocol == "grpc") && (context.reporter.kind | "inbound" == "inbound")with"false".Save and close the rule.
Open the
stackdriver-log-tcprule.kubectl edit -n istio-system rule stackdriver-log-tcp
Replace the
matchcondition(context.protocol == "tcp") && (context.reporter.kind | "inbound" == "inbound")with"false".Save and close the rule.
To disable Stackdriver tracing for Istio on GKE
If you have Istio on GKE version 1.1.3-gke.0 or earlier, or if you have manually enabled Stackdriver tracing, you can disable it as follows:
Open the
stackdriver-tracing-rulerule for editing:kubectl edit -n istio-system rule stackdriver-tracing-rule
Replace the
matchconditioncontext.protocol == "http" || context.protocol == "grpc"with"false".Save and close the rule.
To enable Stackdriver tracing for Istio on GKE
If you are using version 1.1.7 or later and would like to enable Stackdriver tracing:
Open the
stackdriver-tracing-rulerule for editing:kubectl edit -n istio-system rule stackdriver-tracing-rule
Replace the
matchcondition"false"withcontext.protocol == "http" || context.protocol == "grpc".Save and close the rule.
What's next?
- Try installing and exploring the Bookinfo example to see what Istio can do.
To get the sample app and the
istioctltool, go to the Istio release page to download the installation file corresponding to the OS where you're running your commands. Then follow the instructions to deploy and test the application (you don't need to deploy Istio itself) in the GKE Installing Istio tutorial. - Find out lots more about Istio in the open source documentation.
- If you need to remove the Istio add-on from a cluster, see Uninstalling Istio on GKE.
