istio.io/quick-start.md at b11d3a3724424f3d5ac2a0efce5edcf36c0f1df5

12 KiB

Raw Blame History

title	overview	order	layout	type
Quick Start	Quick Start instructions to setup the Istio service mesh in a Kubernetes cluster.	10	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. If you wish to enable transparent injection of sidecar, you need to turn on Kubernetes alpha features in your cluster.

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, retrieve your credentials for kubectl:
```
gcloud container clusters get-credentials <cluster-name> --zone <zone> --project <project-name>
```
  Replace <cluster-name> with the name of the cluster you want to use and <zone> with the zone that cluster is in.
- If you are using IBM Bluemix Container Service, retrieve your credentials for kubectl:
```
$(bx cs cluster-config <cluster-name>|grep "export KUBECONFIG")
```
  where <cluster-name> is the name of the cluster you want to use.
- If you are using Openshift Origin version 3.7 or later, Openshift by default does not allow containers running with UID 0. Enable containers running with UID 0 for Istio's service accounts for ingress and egress:
```
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 later 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. If you are using a MacOS or Linux system, you can also run the following command to download and extract the latest release automatically:
```
curl -L https://git.io/getLatestIstio | sh -
```
Extract the installation file and change the directory to the file location. 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 for creating routing rules and policies.
- The istio.VERSION configuration file
Add the istioctl client to your PATH. For example, run the following command on a MacOS or Linux 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. Choose this option for clusters with existing applications, applications where services with an Istio sidecar need to be able to communicate with other non-Istio Kubernetes services, and 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 a transparent injection of sidecar, install the Istio-Initializer:
```
 kubectl apply -f install/kubernetes/istio-initializer.yaml
```
Optional: Install add-ons 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 add-ons.

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 add-on provides an Istio dashboard visualization of the metrics in the cluster such as request rates and success or failure rates. After you install Grafana, check that you can access the dashboard.

Configure port-forwarding for the grafana service:

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

Point your web browser to http://localhost:3000/dashboard/db/istio-dashboard. The dashboard looks similar to the following:

Verifying the ServiceGraph service

The ServiceGraph add-on 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 example the service name is servicegraph and the port to access is 8088:

kubectl port-forward -n istio-system $(kubectl get pod -n istio-system -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. If you configured port forwarding using the above command, you can view the graphical visualization by opening your browser at http://localhost:8088/dotviz. You will see an empty page initially before you have any microservices deployed.

After you run some services, a service graph builds. 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 looks similar to the following:

Verifying the installation

Ensure the following Kubernetes services are deployed: istio-pilot, istio-mixer, istio-ingress, istio-egress, 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
prometheus      10.83.247.221   <none>            9090:30398/TCP                5h
servicegraph    10.83.242.48    <none>            8088:31928/TCP                5h

Note: 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 says <pending>. You must access the application using the service NodePort, or use port-forwarding instead.

Ensure 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-\*, 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-initializer-184129454-zdgf5   1/1       Running   0          5h
istio-pilot-2275554717-93c43        1/1       Running   0          5h
istio-mixer-2104784889-20rm8        2/2       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 like BookInfo. Note: the application must use HTTP/1.1 or HTTP/2.0 protocol for all its HTTP traffic because HTTP/1.0 is not supported.

If you started the Istio-Initializer, as shown above, you can deploy the application directly using kubectl create. The Istio-Initializer will automatically inject Envoy containers into your application pods:

kubectl create -f <your-app-spec>.yaml

If you do not have the Istio-Initializer installed, you must use istioctl kube-inject to manuallly inject Envoy containers in your application pods before deploying them:

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

Uninstalling

Uninstall any Istio add-ons:

kubectl delete -f install/kubernetes/addons/

Uninstall Istio core components. For the {{ site.data.istio.version }} release, the uninstall deletes the RBAC permissions, the istio-system namespace, and hierarchically all resources under it. It is safe to ignore errors for non-existent resources because they may have been deleted hierarchically.
- If you installed Istio with mutual TLS authentication disabled:
```
kubectl delete -f install/kubernetes/istio.yaml
```
- If you installed Istio 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}' | xargs -n 1 | fgrep 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