istio.io/install-kubernetes.md at b81f59566bc07a7b80bf400fbdc3322ef95e4cdf

12 KiB

Raw Blame History

title	overview	order	layout	type
Istio Quick Start - Kubernetes	Quick Start instructions to setup the Istio service mesh in a Kubernetes cluster.	20	docs	markdown

{% include home.html %}

Quick Start instructions to install and configure Istio in a Kubernetes cluster.

Prerequisites

The following instructions assume you have access to a Kubernetes 1.7.4 or newer cluster with RBAC (Role-Based Access Control) enabled.

Note: If you installed Istio 0.1.x, uninstall it completely before installing the newer version (including the Istio sidecar for all Istio enabled application pods).

Depending on your Kubernetes provider:
- To install Istio locally, install the latest version of Minikube (version 0.22.1 or later).
- If you are using Google Container Engine, find out your cluster name and zone, and fetch credentials for kubectl:
```
gcloud container clusters get-credentials <cluster-name> --zone <zone> --project <project-name>
```
- If you are using IBM Bluemix Container Service, find out your cluster name, and fetch credentials for kubectl:
```
$(bx cs cluster-config <cluster-name>|grep "export KUBECONFIG")
```
- If you are using Openshift Origin version 3.7 or later, Openshift by default does not allow containers running with uid 0, you can enable this for Istio's service accounts for ingress and egress as follows:
```
oc adm policy add-scc-to-user anyuid -z istio-ingress-service-account -n istio-system
oc adm policy add-scc-to-user anyuid -z istio-egress-service-account -n istio-system
```
Install or upgrade the Kubernetes CLI kubectl to match the version supported by your cluster (version 1.7 or newer for CRD support).

Installation steps

Starting with the {{ site.data.istio.version }} release, Istio is installed in its own istio-system namespace, and can manage micro-services from all other namespaces.

Go to the Istio release page, to download the installation file corresponding to your OS or run
```
curl -L https://git.io/getIstio | sh -
```
to download and extract the latest stable release automatically (on MacOS and Ubuntu).
Extract the installation file, and change directory to the location where the files were extracted. The following instructions are relative to this installation directory. The installation directory contains:
- Installation .yaml files for Kubernetes in install/
- Sample applications in samples/
- The istioctl client binary in the bin/ directory. istioctl is used when manually injecting Envoy as a sidecar proxy, and useful for creating routing rules and policies.
- The istio.VERSION configuration file.
Add the istioctl client to your PATH. For example, run the following commands on a Linux or MacOS system:
```
export PATH=$PWD/bin:$PATH
```
Install Istio's core components. Choose one of the two mutually exclusive options below:

a. Install Istio without enabling authentication between sidecars with mutual TLS authentication. We recommend this option for clusters with existing applications, applications where services with Istio sidecar need to be able to communicate with other non-Istio Kubernetes services, as well as applications that use liveliness and readiness probes, headless services, or statefulsets.
```
kubectl apply -f install/kubernetes/istio.yaml
```
OR

b. Install Istio and enable authentication between sidecars with mutual TLS authentication:
```
kubectl apply -f install/kubernetes/istio-auth.yaml
```
Both options create the istio-system namespace along with the required RBAC permissions, and deploy Istio-Pilot, Istio-Mixer, Istio-Ingress, Istio-Egress, and Istio-CA (Certificate Authority).
Optional: If your cluster has Kubernetes alpha features enabled, and you wish to enable transparent injection of sidecar, please install the Istio-Initializer:
```
 kubectl apply -f install/kubernetes/istio-initializer.yaml
```
Optional: Install addons for metric collection and/or request tracing as described in the following sections.

Enabling metrics collection

To collect and view metrics provided by Mixer, install Prometheus, as well as the Grafana and/or ServiceGraph addons.

kubectl apply -f install/kubernetes/addons/prometheus.yaml
kubectl apply -f install/kubernetes/addons/grafana.yaml
kubectl apply -f install/kubernetes/addons/servicegraph.yaml

You can find out more about how to use these tools in Collecting Metrics and Logs.

Verifying the Grafana dashboard

The Grafana addon provides an Istio dashboard visualization of the metrics (request rates, success/failure rates) in the cluster. Once you've installed Grafana, check that you can access the dashboard.

Configure port-forwarding for the grafana service, as follows:

kubectl port-forward $(kubectl get pod -l app=grafana -o jsonpath='{.items[0].metadata.name}') 3000:3000 &

Then point your web browser to http://localhost:3000/dashboard/db/istio-dashboard. The dashboard should look something like this:

Verifying the ServiceGraph service

The ServiceGraph addon provides a textual (JSON) representation and a graphical visualization of the service interaction graph for the cluster. Like Grafana, you can access the servicegraph service using port-forwarding, service nodePort, or (if external load balancing is available) external IP. In this case the service name is servicegraph and the port to access is 8088:

kubectl port-forward $(kubectl get pod -l app=servicegraph -o jsonpath='{.items[0].metadata.name}') 8088:8088 &

The ServiceGraph service provides both a textual (JSON) representation (via /graph) and a graphical visualization (via /dotviz) of the underlying service graph. To view the graphical visualization (assuming that you have configured port forwarding as per the previous snippet), open your browser at: http://localhost:8088/dotviz.

After running some services -- for example, after installing the BookInfo sample application and generating some load on the application (e.g., executing curl requests in a while loop) -- the resulting service graph should look something like this:

Verifying the installation

Ensure the following Kubernetes services were deployed: "istio-pilot", "istio-mixer", "istio-ingress", "istio-egress", "istio-ca", and, optionally, "grafana", "prometheus' and "servicegraph".

kubectl get svc -n istio-system

NAME            CLUSTER-IP      EXTERNAL-IP       PORT(S)                       AGE
grafana         10.83.252.16    <none>            3000:30432/TCP                5h
istio-egress    10.83.247.89    <none>            80/TCP                        5h
istio-ingress   10.83.245.171   35.184.245.62     80:32730/TCP,443:30574/TCP    5h
istio-pilot     10.83.251.173   <none>            8080/TCP,8081/TCP             5h
istio-mixer     10.83.244.253   <none>            9091/TCP,9094/TCP,42422/TCP   5h
kubernetes      10.83.240.1     <none>            443/TCP                       36d
prometheus      10.83.247.221   <none>            9090:30398/TCP                5h
servicegraph    10.83.242.48    <none>            8088:31928/TCP                5h

Note that if your cluster is running in an environment that does not support an external load balancer (e.g., minikube), the EXTERNAL-IP of istio-ingress will say <pending> and you will need to access the application using the service NodePort, or use port-forwarding instead.

Check the corresponding Kubernetes pods were deployed and all containers are up and running: "istio-pilot-*", "istio-mixer-*", "istio-ingress-*", "istio-egress-*", "istio-ca-*" , and, optionally, "grafana-*", "prometheus-*' and "servicegraph-*".

kubectl get pods -n istio-system

grafana-3836448452-vhc1v         1/1       Running   0          5h
istio-ca-3657790228-j21b9        1/1       Running   0          5h
istio-egress-1684034556-fhw89    1/1       Running   0          5h
istio-ingress-1842462111-j3vcs   1/1       Running   0          5h
istio-pilot-2275554717-93c43     2/2       Running   0          5h
istio-mixer-2104784889-20rm8     1/1       Running   0          5h
prometheus-3067433533-wlmt2      1/1       Running   0          5h
servicegraph-3127588006-pc5z3    1/1       Running   0          5h

Deploy your application

You can now deploy your own application, or one of the sample applications provided with the installation, for example BookInfo. Note that the application should use HTTP/1.1 or HTTP/2.0 protocol for all its HTTP traffic; HTTP/1.0 is not supported.

Unless you installed the Istio-Initializer as shown above, when deploying the application, you must use istioctl kube-inject to automatically inject Envoy containers in your application pods:

kubectl create -f <(istioctl kube-inject -f <your-app-spec>.yaml)

Uninstalling

If you installed Istio addons, uninstall them:

kubectl delete -f install/kubernetes/addons/

Uninstall Istio core components. For the {{ site.data.istio.version }} release, the uninstall will delete the RBAC permissions, the istio-system namespace, and hierarchically all resources under it. It is safe to ignore errors for non-existent resources, since they may have been deleted hierarchically.
- If Istio was installed with mutual TLS authentication disabled:
```
kubectl delete -f install/kubernetes/istio.yaml
```
- If Istio was installed with mutual TLS authentication enabled:
```
kubectl delete -f install/kubernetes/istio-auth.yaml
```

Delete Istio's Kubernetes CRDs:

kubectl get crd -o 'jsonpath={.items[*].metadata.name}' | grep config\.istio\.io | xargs kubectl delete crd

What's next

See the sample BookInfo application.
See how to test Istio Auth.

12 KiB Raw Blame History