Quick Start with Kubernetes

Istio 1.1 has been tested with these Kubernetes releases: 1.10, 1.11, 1.12.

To install and configure Istio in a Kubernetes cluster, follow these instructions:

Prerequisites

  1. Download the Istio release.

  2. Kubernetes platform setup:

  3. Check the Requirements for Pods and Services.

Installation steps

  1. Install Istio’s Custom Resource Definitions via kubectl apply, and wait a few seconds for the CRDs to be committed in the kube-apiserver:

    $ kubectl apply -f install/kubernetes/helm/istio/templates/crds.yaml
  2. To install Istio’s core components you can choose any of the following four mutually exclusive options described below. However, for a production setup of Istio, we recommend installing with the Helm Chart, to use all the configuration options. This permits customization of Istio to operator specific requirements.

Option 1: Install Istio with mutual TLS enabled and set to use permissive mode between sidecars

Visit our mutual TLS permissive mode page for more information.

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,
  • Applications that use liveness and readiness probes,
  • Headless services, or
  • StatefulSets

To install Istio with mutual TLS enabled and set to use permissive mode between sidecars:

$ kubectl apply -f install/kubernetes/istio-demo.yaml

In this option, all services, as servers, can accept both plain text and mutual TLS traffic. However, all services, as clients, will send plain text traffic. Visit mutual migration for how to configure clients behavior.

Option 2: Install Istio with default mutual TLS authentication

Use this option only on a fresh Kubernetes cluster where newly deployed workloads are guaranteed to have Istio sidecars installed.

To Install Istio and enforce mutual TLS authentication between sidecars by default:

$ kubectl apply -f install/kubernetes/istio-demo-auth.yaml

Option 3: Render Kubernetes manifest with Helm and deploy with kubectl

Follow our setup instructions to render the Kubernetes manifest with Helm and deploy with kubectl.

Option 4: Use Helm and Tiller to manage the Istio deployment

Follow our instructions on how to use Helm and Tiller to manage the Istio deployment.

Verifying the installation

  1. To ensure the following Kubernetes services are deployed: istio-citadel, istio-engressgateway, istio-galley, istio-ingress, istio-ingressgateway, istio-pilot, istio-policy, istio-statsd-prom-bridge, istio-telemetry, prometheus, and optionally, istio-sidecar-injector, verify they all have an appropriate CLUSTER-IP:

    $ kubectl get svc -n istio-system

    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 and istio-ingressgateway will say <pending>. You will need to access it using the service NodePort, or use port-forwarding instead.

  2. Ensure the corresponding Kubernetes pods are deployed and all containers: istio-citadel-*, istio-engressgateway-*, istio-galley-*, istio-ingress-*, istio-ingressgateway-*, istio-pilot-*, istio-policy-*, istio-statsd-prom-bridge-*, istio-telemetry-*, prometheus-*, and, optionally, istio-sidecar-injector-*, have a STATUS of Running:

    $ kubectl get pods -n istio-system

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, you can deploy the application directly using kubectl apply.

The Istio-Sidecar-injector will automatically inject Envoy containers into your application pods. The injector assumes the application pods are 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 don’t have the Istio-sidecar-injector installed, you must use istioctl kube-inject to manually inject Envoy containers in your application pods before deploying them:

$ istioctl kube-inject -f <your-app-spec>.yaml | kubectl apply -f -

Uninstall Istio core components

The uninstall deletes the RBAC permissions, the istio-system namespace, and all resources hierarchically under it. It is safe to ignore errors for non-existent resources because they may have been deleted hierarchically.

  • If you installed Istio with istio-demo.yaml:

    $ kubectl delete -f install/kubernetes/istio-demo.yaml
  • If you installed Istio with istio-demo-auth.yaml:

    $ kubectl delete -f install/kubernetes/istio-demo-auth.yaml
  • If you installed Istio with Helm, follow the uninstall Istio with Helm steps.

  • If desired, delete the CRDs:

    $ kubectl delete -f install/kubernetes/helm/istio/templates/crds.yaml -n istio-system

See also

Instructions to download the Istio release.

Instructions for integrating VMs and bare metal hosts into an Istio mesh deployed on Kubernetes.

Instructions for installing the Istio sidecar in application pods automatically using the sidecar injector webhook or manually using istioctl CLI.

Example multicluster between IBM Cloud Kubernetes Service & IBM Cloud Private.

Install an Istio mesh across multiple Kubernetes clusters with direct network access to remote pods.

Install an Istio mesh across multiple Kubernetes clusters using Istio Gateway to reach remote pods.