istio
/
istio.io
mirror of https://github.com/istio/istio.io.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
istio.io/content/docs/setup/kubernetes/quick-start/index.md

16 KiB
Raw Blame History

title description weight keywords
Quick Start Quick start instructions to setup the Istio service mesh in a Kubernetes cluster. 10
kubernetes

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

Prerequisites

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

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

Minikube

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

Select a VM driver and substitute the below your_vm_driver_choice with the installed VM driver.

For Kubernetes 1.9

{{< text bash >}} $ minikube start --memory=4096 --kubernetes-version=v1.9.4 --vm-driver=your_vm_driver_choice {{< /text >}}

For Kubernetes 1.10

{{< text bash >}} $ minikube start --memory=4096 --kubernetes-version=v1.10.0 --vm-driver=your_vm_driver_choice {{< /text >}}

Google Kubernetes Engine

Create a new cluster.

{{< text bash >}} $ gcloud container clusters create
--cluster-version=1.10.4-gke.0
--zone
--project {{< /text >}}

Retrieve your credentials for kubectl.

{{< text bash >}} $ gcloud container clusters get-credentials
--zone
--project {{< /text >}}

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

{{< text bash >}} $ kubectl create clusterrolebinding cluster-admin-binding
--clusterrole=cluster-admin
--user=$(gcloud config get-value core/account) {{< /text >}}

IBM Cloud Kubernetes Service (IKS)

Create a new lite cluster.

{{< text bash >}} $ bx cs cluster-create --name --kube-version 1.9.7 {{< /text >}}

Or create a new paid cluster:

{{< text bash >}} $ bx cs cluster-create --location location --machine-type u2c.2x4 --name --kube-version 1.9.7 {{< /text >}}

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

{{< text bash >}} $(bx cs cluster-config |grep "export KUBECONFIG") {{< /text >}}

IBM Cloud Private

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

OpenShift Origin

OpenShift by default does not allow containers running with UID 0. Enable containers running with UID 0 for Istio's service accounts:

{{< text bash >}} $ 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 default -n istio-system $ oc adm policy add-scc-to-user anyuid -z prometheus -n istio-system $ oc adm policy add-scc-to-user anyuid -z istio-egressgateway-service-account -n istio-system $ oc adm policy add-scc-to-user anyuid -z istio-citadel-service-account -n istio-system $ oc adm policy add-scc-to-user anyuid -z istio-ingressgateway-service-account -n istio-system $ oc adm policy add-scc-to-user anyuid -z istio-cleanup-old-ca-service-account -n istio-system $ oc adm policy add-scc-to-user anyuid -z istio-mixer-post-install-account -n istio-system $ oc adm policy add-scc-to-user anyuid -z istio-mixer-service-account -n istio-system $ oc adm policy add-scc-to-user anyuid -z istio-pilot-service-account -n istio-system $ oc adm policy add-scc-to-user anyuid -z istio-sidecar-injector-service-account -n istio-system {{< /text >}}

The list above covers the default Istio service accounts. If you enabled other Istio services (e.g. Grafana) you will need to cover its service account in a similar command.

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

{{< text bash >}} $ oc adm policy add-scc-to-user privileged -z default -n {{< /text >}}

Check for SELINUX in this discussion with respect to Istio in case you see issues bringing up the Envoy.

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.

{{< text bash >}} $ kops edit cluster $YOURCLUSTER {{< /text >}}

Add the following in the configuration file:

{{< text yaml >}} kubeAPIServer: admissionControl: - NamespaceLifecycle - LimitRanger - ServiceAccount - PersistentVolumeLabel - DefaultStorageClass - DefaultTolerationSeconds - MutatingAdmissionWebhook - ValidatingAdmissionWebhook - ResourceQuota - NodeRestriction - Priority {{< /text >}}

Perform the update

{{< text bash >}} $ kops update cluster $ kops update cluster --yes {{< /text >}}

Launch the rolling update

{{< text bash >}} $ kops rolling-update cluster $ kops rolling-update cluster --yes {{< /text >}}

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

{{< text bash >}} $ 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 {{< /text >}}

Output should be:

{{< text plain >}} [...] --admission-control=NamespaceLifecycle,LimitRanger,ServiceAccount,PersistentVolumeLabel,DefaultStorageClass,DefaultTolerationSeconds,MutatingAdmissionWebhook,ValidatingAdmissionWebhook,ResourceQuota,NodeRestriction,Priority [...] {{< /text >}}

Azure

You need to use ACS-Engine to deploy you cluster. After following these instructions to get and install the acs-engine binary, use the following command to download Istio api model definition:

{{< text bash >}} $ wget https://raw.githubusercontent.com/Azure/acs-engine/master/examples/service-mesh/istio.json {{< /text >}}

Use the following command to deploy your cluster using the istio.json template. You can find references to the parameters in the official docs.

Parameter Expected value
subscription_id Azure Subscription Id
dns_prefix Cluster DNS Prefix
location Cluster Location

{{< text bash >}} $ acs-engine deploy --subscription-id <subscription_id> --dns-prefix <dns_prefix> --location --auto-suffix --api-model istio.json {{< /text >}}

After a few minutes you should find your cluster on your Azure subscription in a resource group called <dns_prefix>-<id>. Let's say my dns-prefix is myclustername, a valid resource group and unique cluster id would be mycluster-5adfba82. Using this <dns_prefix>-<id> cluster id you can copy your kubeconfig file to your machine from the _output folder generated by acs-engine:

{{< text bash >}} $ cp _output/<dns_prefix>-/kubeconfig/kubeconfig..json ~/.kube/config {{< /text >}}

For example:

{{< text bash >}} $ cp _output/mycluster-5adfba82/kubeconfig/kubeconfig.westus2.json ~/.kube/config {{< /text >}}

To check if the right Istio flags were deployed, use:

{{< text bash >}} kubectl describe pod --namespace kube-system(kubectl get pods --namespace kube-system | grep api | cut -d ' ' -f 1) | grep admission-control {{< /text >}}

You should see MutatingAdmissionWebhook and ValidatingAdmissionWebhook flags:

{{< text plain >}} --admission-control=...,MutatingAdmissionWebhook,...,ValidatingAdmissionWebhook,... {{< /text >}}

Download and prepare for the installation

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:

    {{< text bash >}} $ curl -L https://git.io/getLatestIstio | sh - {{< /text >}}

  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 the istio package. For example, if the package is istio-{{< istio_version >}}.0:

    {{< text bash >}} $ cd istio-{{< istio_version >}}.0 {{< /text >}}

  4. Add the istioctl client to your PATH. For example, run the following command on a macOS or Linux system:

    {{< text bash >}} $ export PATH=$PWD/bin:$PATH {{< /text >}}

Installation steps

Install Istio's core components. Choose one of the four mutually exclusive options below for quick installation. However, we recommend you to install with the Helm Chart for production installations of Istio to leverage all the options to configure and customize Istio to your needs.

  • 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 liveness and readiness probes, headless services, or StatefulSets.

{{< text bash >}} $ kubectl apply -f install/kubernetes/istio.yaml {{< /text >}}

OR

  • Install Istio and enforce mutual TLS authentication between sidecars by default. Use this option only on a fresh kubernetes cluster where newly deployed workloads are guaranteed to have Istio sidecars installed.

{{< text bash >}} $ kubectl apply -f install/kubernetes/istio-auth.yaml {{< /text >}}

OR

OR

Verifying the installation

  1. Ensure the following Kubernetes services are deployed: istio-pilot, istio-ingressgateway, istio-policy, istio-telemetry, prometheus, istio-galley and, optionally, istio-sidecar-injector.

    {{< text bash >}} $ kubectl get svc -n istio-system NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE istio-citadel ClusterIP 10.47.247.12 8060/TCP,9093/TCP 7m istio-egressgateway ClusterIP 10.47.243.117 80/TCP,443/TCP 7m istio-galley ClusterIP 10.47.254.90 443/TCP 7m istio-ingress LoadBalancer 10.47.244.111 35.194.55.10 80:32000/TCP,443:30814/TCP 7m istio-ingressgateway LoadBalancer 10.47.241.20 130.211.167.230 80:31380/TCP,443:31390/TCP,31400:31400/TCP 7m istio-pilot ClusterIP 10.47.250.56 15003/TCP,15005/TCP,15007/TCP,15010/TCP,15011/TCP,8080/TCP,9093/TCP 7m istio-policy ClusterIP 10.47.245.228 9091/TCP,15004/TCP,9093/TCP 7m istio-sidecar-injector ClusterIP 10.47.245.22 443/TCP 7m istio-statsd-prom-bridge ClusterIP 10.47.252.184 9102/TCP,9125/UDP 7m istio-telemetry ClusterIP 10.47.250.107 9091/TCP,15004/TCP,9093/TCP,42422/TCP 7m prometheus ClusterIP 10.47.253.148 9090/TCP 7m {{< /text >}}

    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 are up and running: istio-pilot-*, istio-ingressgateway-*, istio-egressgateway-*, istio-policy-*, istio-telemtry-*, istio-citadel-*, prometheus-*, istio-galley-* and, optionally, istio-sidecar-injector-*.

    {{< text bash >}} $ kubectl get pods -n istio-system NAME READY STATUS RESTARTS AGE istio-citadel-75c88f897f-zfw8b 1/1 Running 0 1m istio-egressgateway-7d8479c7-khjvk 1/1 Running 0 1m istio-galley-6c749ff56d-k97n2 1/1 Running 0 1m istio-ingress-7f5898d74d-t8wrr 1/1 Running 0 1m istio-ingressgateway-7754ff47dc-qkrch 1/1 Running 0 1m istio-policy-74df458f5b-jrz9q 2/2 Running 0 1m istio-sidecar-injector-645c89bc64-v5n4l 1/1 Running 0 1m istio-statsd-prom-bridge-949999c4c-xjz25 1/1 Running 0 1m istio-telemetry-676f9b55b-k9nkl 2/2 Running 0 1m prometheus-86cb6dd77c-hwvqd 1/1 Running 0 1m {{< /text >}}

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

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

{{< text bash >}} $ kubectl label namespace istio-injection=enabled $ kubectl create -n -f .yaml {{< /text >}}

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

{{< text bash >}} $ istioctl kube-inject -f .yaml | kubectl apply -f - {{< /text >}}

Uninstalling

  • Uninstall Istio core components. For this 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 istio.yaml:

{{< text bash >}} $ kubectl delete -f install/kubernetes/istio.yaml {{< /text >}}

otherwise uninstall Istio with Helm.