mirror of https://github.com/istio/istio.io.git
284 lines
9.0 KiB
Markdown
284 lines
9.0 KiB
Markdown
---
|
|
title: Kubernetes platform setup
|
|
description: Instructions to setup the Kubernetes cluster for Istio.
|
|
weight: 10
|
|
keywords: [kubernetes]
|
|
---
|
|
|
|
Follow these instructions to setup the Kubernetes cluster for Istio.
|
|
|
|
## Prerequisites
|
|
|
|
The following instructions require:
|
|
|
|
* Access to a Kubernetes **1.9 or newer** cluster with
|
|
[RBAC (Role-Based Access Control)](https://kubernetes.io/docs/reference/access-authn-authz/rbac/)
|
|
enabled.
|
|
* [`kubectl`](https://kubernetes.io/docs/tasks/tools/install-kubectl/) **1.9 or
|
|
newer** installed. Version **1.10** is recommended.
|
|
|
|
> If you installed Istio 0.2.x,
|
|
> [uninstall](https://archive.istio.io/v0.2/docs/setup/kubernetes/quick-start#uninstalling)
|
|
> it completely before installing the newer version. Remember to uninstall
|
|
> the Istio sidecar for all Istio enabled application pods too.
|
|
|
|
## Platform setup
|
|
|
|
This section describes the setup in different Kubernetes providers.
|
|
|
|
### Minikube
|
|
|
|
1. To run Istio locally, install the latest version of
|
|
[Minikube](https://kubernetes.io/docs/setup/minikube/), version **0.28.0 or
|
|
later**.
|
|
|
|
1. Select a
|
|
[VM driver](https://kubernetes.io/docs/setup/minikube/#quickstart)
|
|
and substitute `your_vm_driver_choice` below with the installed virtual
|
|
machine (VM) driver.
|
|
|
|
On Kubernetes **1.9**:
|
|
|
|
{{< text bash >}}
|
|
$ minikube start --memory=4096 --kubernetes-version=v1.9.4 \
|
|
--vm-driver=`your_vm_driver_choice`
|
|
{{< /text >}}
|
|
|
|
On Kubernetes **1.10**:
|
|
|
|
{{< text bash >}}
|
|
$ minikube start --memory=4096 --kubernetes-version=v1.10.0 \
|
|
--vm-driver=`your_vm_driver_choice`
|
|
{{< /text >}}
|
|
|
|
### Google Kubernetes Engine
|
|
|
|
1. Create a new cluster.
|
|
|
|
{{< text bash >}}
|
|
$ gcloud container clusters create <cluster-name> \
|
|
--cluster-version=1.10.5-gke.0 \
|
|
--zone <zone> \
|
|
--project <project-id>
|
|
{{< /text >}}
|
|
|
|
1. Retrieve your credentials for `kubectl`.
|
|
|
|
{{< text bash >}}
|
|
$ gcloud container clusters get-credentials <cluster-name> \
|
|
--zone <zone> \
|
|
--project <project-id>
|
|
{{< /text >}}
|
|
|
|
1. Grant cluster administrator (admin) permissions to the current user. To
|
|
create the necessary RBAC rules for Istio, the current user requires admin
|
|
permissions.
|
|
|
|
{{< text bash >}}
|
|
$ kubectl create clusterrolebinding cluster-admin-binding \
|
|
--clusterrole=cluster-admin \
|
|
--user=$(gcloud config get-value core/account)
|
|
{{< /text >}}
|
|
|
|
### IBM Cloud Kubernetes Service (IKS)
|
|
|
|
1. Create a new lite cluster.
|
|
|
|
{{< text bash >}}
|
|
$ bx cs cluster-create --name <cluster-name> --kube-version 1.9.7
|
|
{{< /text >}}
|
|
|
|
Alternatively, you can create a new paid cluster:
|
|
|
|
{{< text bash >}}
|
|
$ bx cs cluster-create --location location --machine-type u2c.2x4 \
|
|
--name <cluster-name> --kube-version 1.9.7
|
|
{{< /text >}}
|
|
|
|
1. Retrieve your credentials for `kubectl`. Replace `<cluster-name>` with the
|
|
name of the cluster you want to use:
|
|
|
|
{{< text bash >}}
|
|
$(bx cs cluster-config <cluster-name>|grep "export KUBECONFIG")
|
|
{{< /text >}}
|
|
|
|
### IBM Cloud Private
|
|
|
|
[Configure the kubectl CLI](https://www.ibm.com/support/knowledgecenter/SSBS6K_2.1.0/manage_cluster/cfc_cli.html)
|
|
to access the IBM Cloud Private Cluster.
|
|
|
|
### OpenShift Origin
|
|
|
|
By default, OpenShift doesn't allow containers running with user ID (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 accounts for the default Istio service accounts. If you enabled
|
|
other Istio services, like _Grafana_ for example, you need to enable its
|
|
service account with a similar command.
|
|
|
|
A service account that runs application pods needs privileged security context
|
|
constraints as part of sidecar injection.
|
|
|
|
{{< text bash >}}
|
|
$ oc adm policy add-scc-to-user privileged -z default -n <target-namespace>
|
|
{{< /text >}}
|
|
|
|
> Check for `SELINUX` in this [discussion](https://github.com/istio/issues/issues/34)
|
|
> with respect to Istio in case you see issues bringing up the Envoy.
|
|
|
|
### AWS with Kops
|
|
|
|
When you install a new cluster with Kubernetes version 1.9, the prerequisite to
|
|
enable `admissionregistration.k8s.io/v1beta1` is covered.
|
|
|
|
Nevertheless, you must update the list of admission controllers.
|
|
|
|
1. Open the configuration file:
|
|
|
|
{{< text bash >}}
|
|
$ kops edit cluster $YOURCLUSTER
|
|
{{< /text >}}
|
|
|
|
1. Add the following in the configuration file:
|
|
|
|
{{< text yaml >}}
|
|
kubeAPIServer:
|
|
admissionControl:
|
|
- NamespaceLifecycle
|
|
- LimitRanger
|
|
- ServiceAccount
|
|
- PersistentVolumeLabel
|
|
- DefaultStorageClass
|
|
- DefaultTolerationSeconds
|
|
- MutatingAdmissionWebhook
|
|
- ValidatingAdmissionWebhook
|
|
- ResourceQuota
|
|
- NodeRestriction
|
|
- Priority
|
|
{{< /text >}}
|
|
|
|
1. Perform the update:
|
|
|
|
{{< text bash >}}
|
|
$ kops update cluster
|
|
$ kops update cluster --yes
|
|
{{< /text >}}
|
|
|
|
1. Launch the rolling update:
|
|
|
|
{{< text bash >}}
|
|
$ kops rolling-update cluster
|
|
$ kops rolling-update cluster --yes
|
|
{{< /text >}}
|
|
|
|
1. Validate the update with the `kubectl` client on the `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 >}}
|
|
|
|
1. Review the output:
|
|
|
|
{{< text plain >}}
|
|
[...]
|
|
--admission-control=NamespaceLifecycle,LimitRanger,ServiceAccount,
|
|
PersistentVolumeLabel,DefaultStorageClass,DefaultTolerationSeconds,
|
|
MutatingAdmissionWebhook,ValidatingAdmissionWebhook,ResourceQuota,
|
|
NodeRestriction,Priority
|
|
[...]
|
|
{{< /text >}}
|
|
|
|
### Azure
|
|
|
|
You must use `ACS-Engine` to deploy your cluster.
|
|
|
|
1. Follow the instructions to get and install the `acs-engine` binary with
|
|
[their instructions](https://github.com/Azure/acs-engine/blob/master/docs/acsengine.md#install).
|
|
|
|
1. Download Istio's `api model definition`:
|
|
|
|
{{< text bash >}}
|
|
$ wget https://raw.githubusercontent.com/Azure/acs-engine/master/examples/service-mesh/istio.json
|
|
{{< /text >}}
|
|
|
|
1. Deploy your cluster using the `istio.json` template. You can find references
|
|
to the parameters in the
|
|
[official docs](https://github.com/Azure/acs-engine/blob/master/docs/kubernetes/deploy.md#step-3-edit-your-cluster-definition).
|
|
|
|
| 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 <location> --auto-suffix \
|
|
--api-model istio.json
|
|
{{< /text >}}
|
|
|
|
> After a few minutes, you can find your cluster on your Azure subscription
|
|
> in a resource group called `<dns_prefix>-<id>`. Assuming `dns_prefix` has
|
|
> the value `myclustername`, a valid resource group with a unique cluster
|
|
> ID is `mycluster-5adfba82`. The `acs-engine` generates your `kubeconfig`
|
|
> file in the `_output` folder.
|
|
|
|
1. Use the `<dns_prefix>-<id>` cluster ID, to copy your `kubeconfig` to your
|
|
machine from the `_output` folder:
|
|
|
|
{{< text bash >}}
|
|
$ cp _output/<dns_prefix>-<id>/kubeconfig/kubeconfig.<location>.json \
|
|
~/.kube/config
|
|
{{< /text >}}
|
|
|
|
For example:
|
|
|
|
{{< text bash >}}
|
|
$ cp _output/mycluster-5adfba82/kubeconfig/kubeconfig.westus2.json \
|
|
~/.kube/config
|
|
{{< /text >}}
|
|
|
|
1. Check if the right Istio flags were deployed:
|
|
|
|
{{< text bash >}}
|
|
$ kubectl describe pod --namespace kube-system
|
|
$(kubectl get pods --namespace kube-system | grep api | cut -d ' ' -f 1) \
|
|
| grep admission-control
|
|
{{< /text >}}
|
|
|
|
1. Confirm the `MutatingAdmissionWebhook` and `ValidatingAdmissionWebhook`
|
|
flags are present:
|
|
|
|
{{< text plain >}}
|
|
--admission-control=...,MutatingAdmissionWebhook,...,
|
|
ValidatingAdmissionWebhook,...
|
|
{{< /text >}}
|