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

  • 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:

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

    • Google Kubernetes Engine

      • Retrieve your credentials for kubectl (replace <cluster-name> with the name of the cluster you want to use, and <zone> with the zone where that cluster is located):
        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

      • Config 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 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
oc adm policy add-scc-to-user anyuid -z default -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>

Installation steps

Starting with the 0.2 release, Istio is installed in its own istio-system namespace, and can manage micro-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.3
      cd istio-0.3
  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:

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

  1. Optional: If your cluster has Kubernetes alpha features enabled, and you wish to enable a automatic injection of sidecar, install the Istio-Initializer:
      kubectl apply -f install/kubernetes/istio-initializer.yaml

Verifying the installation

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

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

    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-egress-*, istio-ca-*, and, optionally, istio-initializer-*.
      kubectl get pods -n istio-system

      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

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 Istio initializer:

    If you installed Istio with initializer enabled, uninstall it:

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

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