Quick Start

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

Prerequisites

The following instructions require you have access to a Kubernetes 1.7.3 or newer cluster with RBAC (Role-Based Access Control) enabled. You will also need kubectl 1.7.3 or newer installed.

If you wish to enable automatic sidecar injection or server-side configuration validation, you need Kubernetes version 1.9 or greater.

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).

  • Install or upgrade the Kubernetes CLI kubectl to match the version supported by your cluster (version 1.7 or later for CRD support).

  • Depending on your Kubernetes provider:

Minikube

To install Istio locally, install the latest version of Minikube (version 0.25.0 or later).

  minikube start \
	--extra-config=controller-manager.ClusterSigningCertFile="/var/lib/localkube/certs/ca.crt" \
	--extra-config=controller-manager.ClusterSigningKeyFile="/var/lib/localkube/certs/ca.key" \
	--extra-config=apiserver.Admission.PluginNames=NamespaceLifecycle,LimitRanger,ServiceAccount,PersistentVolumeLabel,DefaultStorageClass,DefaultTolerationSeconds,MutatingAdmissionWebhook,ValidatingAdmissionWebhook,ResourceQuota \
	--kubernetes-version=v1.9.0

Google Kubernetes Engine

Create a new cluster.

gcloud container clusters create <cluster-name> \
    --cluster-version=1.9.4-gke.1 
    --zone <zone>
    --project <project-name>

Retrieve your credentials for kubectl.

gcloud container clusters get-credentials <cluster-name> \
    --zone <zone> \
    --project <project-name>

Grant cluster admin permissions to the current user (admin permissions are required to create the necessary RBAC rules for Istio).

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

IBM Cloud Container Service

Retrieve your credentials for kubectl (replace <cluster-name> with the name of the cluster you want to use):

$(bx cs cluster-config <cluster-name>|grep "export KUBECONFIG")

IBM Cloud Private (version 2.1 or later)

Configure kubectl CLI based on steps here for how to access the IBM Cloud Private Cluster.

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 as well the Prometheus and Grafana addons:

  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-grafana-service-account -n istio-system
  oc adm policy add-scc-to-user anyuid -z istio-prometheus-service-account -n istio-system

Service account that runs application pods need privileged security context constraints as part of sidecar injection.

  oc adm policy add-scc-to-user privileged -z default -n <target-namespace>

AWS (w/Kops)

When you install a new cluster with Kubernetes version 1.9, prerequisite for admissionregistration.k8s.io/v1beta1 enabled is covered.

Nevertheless the list of admission controllers needs to be updated.

kops edit cluster $YOURCLUSTER

Add following in the configuration file just openned:

kubeAPIServer:
    admissionControl:
    - NamespaceLifecycle
    - LimitRanger
    - ServiceAccount
    - PersistentVolumeLabel
    - DefaultStorageClass
    - DefaultTolerationSeconds
    - MutatingAdmissionWebhook
    - ValidatingAdmissionWebhook
    - ResourceQuota
    - NodeRestriction
    - Priority

Perform the update

kops update cluster
kops update cluster --yes

Launch the rolling update

kops rolling-update cluster
kops rolling-update cluster --yes

Validate with kubectl client on kube-api pod, you should see new admission controller:

for i in `kubectl get pods -nkube-system | grep api | awk '{print $1}'` ; do  kubectl describe pods -nkube-system $i | grep "/usr/local/bin/kube-apiserver"  ; done

Ouput should be:

[...] --admission-control=NamespaceLifecycle,LimitRanger,ServiceAccount,PersistentVolumeLabel,DefaultStorageClass,DefaultTolerationSeconds,MutatingAdmissionWebhook,ValidatingAdmissionWebhook,ResourceQuota,NodeRestriction,Priority [...]

Installation steps

Starting with the 0.2 release, Istio is installed in its own istio-system namespace, and can manage services from all other namespaces.

  1. 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 -
  2. 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
  3. Change directory to istio package. For example, if the package is istio-0.6
    cd istio-0.6
  4. Add the istioctl client to your PATH. For example, run the following command on a MacOS or Linux system:
    export PATH=$PWD/bin:$PATH

  5. Install Istio’s core components. Choose one of the two mutually exclusive options below or alternately install with the Helm Chart:

    a) Install Istio without enabling mutual TLS authentication between sidecars. 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 mutual TLS authentication between sidecars.:

    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, and Istio-CA (Certificate Authority).

  6. Optional: If your cluster has Kubernetes version 1.9 or greater, and you wish to enable automatic proxy injection, install the sidecar injector webhook.

Verifying the installation

  1. Ensure the following Kubernetes services are deployed: istio-pilot, istio-mixer, istio-ingress.
    kubectl get svc -n istio-system

    NAME            CLUSTER-IP      EXTERNAL-IP       PORT(S)                       AGE
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

    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.

  2. Ensure the corresponding Kubernetes pods are deployed and all containers are up and running: istio-pilot-*, istio-mixer-*, istio-ingress-*, istio-ca-*, and, optionally, istio-sidecar-injector-*.
    kubectl get pods -n istio-system

    istio-ca-3657790228-j21b9                1/1       Running   0          5h
istio-ingress-1842462111-j3vcs           1/1       Running   0          5h
istio-sidecar-injector-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

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-sidecar-injector, as shown above, you can deploy the application directly using kubectl create.

The Istio-Sidecar-injector will automatically inject Envoy containers into your application pods assuming running in namespaces labeled with istio-injection=enabled

kubectl label namespace <namespace> istio-injection=enabled
kubectl create -n <namespace> -f <your-app-spec>.yaml

If you do not have the Istio-sidecar-injector 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 Istio sidecar injector:

    If you installed Istio with sidecar injector enabled, uninstall it:

    kubectl delete -f install/kubernetes/istio-sidecar-injector-with-ca-bundle.yaml

  • Uninstall Istio core components. For the 0.6 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.

    a) If you installed Istio with mutual TLS authentication disabled:

    kubectl delete -f install/kubernetes/istio.yaml

    OR

    b) If you installed Istio with mutual TLS authentication enabled:

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

What’s next