mirror of https://github.com/istio/istio.io.git
389 lines
13 KiB
Markdown
389 lines
13 KiB
Markdown
---
|
|
title: Customizable Install with Helm
|
|
description: Install and configure Istio for in-depth evaluation or production use.
|
|
weight: 20
|
|
keywords: [kubernetes,helm]
|
|
aliases:
|
|
- /docs/setup/kubernetes/helm.html
|
|
- /docs/tasks/integrating-services-into-istio.html
|
|
- /docs/setup/kubernetes/helm-install/
|
|
- /docs/setup/kubernetes/install/helm/
|
|
icon: helm
|
|
---
|
|
|
|
{{< warning >}}
|
|
The Helm installation approach will be deprecated in the future.
|
|
We recommend [Installing with {{< istioctl >}}](/docs/setup/install/istioctl/), instead.
|
|
{{< /warning >}}
|
|
|
|
Follow this guide to install and configure an Istio mesh for in-depth evaluation or production use.
|
|
|
|
This installation guide uses [Helm](https://github.com/helm/helm) charts that provide rich
|
|
customization of the Istio control plane and of the sidecars for the Istio data plane.
|
|
You can simply use `helm template` to generate the configuration and then install it
|
|
using `kubectl apply`, or you can choose to use `helm install` and let
|
|
[Tiller](https://helm.sh/docs/topics/architecture/#components)
|
|
completely manage the installation.
|
|
|
|
Using these instructions, you can select any one of Istio's built-in
|
|
[configuration profiles](/docs/setup/additional-setup/config-profiles/)
|
|
and then further customize the configuration for your specific needs.
|
|
|
|
## Prerequisites
|
|
|
|
1. [Download the Istio release](/docs/setup/getting-started/#download).
|
|
|
|
1. Perform any necessary [platform-specific setup](/docs/setup/platform-setup/).
|
|
|
|
1. Check the [Requirements for Pods and Services](/docs/setup/additional-setup/requirements/).
|
|
|
|
1. [Install a Helm client](https://github.com/helm/helm#install) with a version higher than 2.10.
|
|
|
|
## Helm chart release repositories
|
|
|
|
The commands in this guide use the Helm charts that are included in the Istio release image.
|
|
If you want to use the Istio release Helm chart repository instead, adjust the commands accordingly and
|
|
add the Istio release repository as follows:
|
|
|
|
{{< text bash >}}
|
|
$ helm repo add istio.io https://storage.googleapis.com/istio-release/releases/{{< istio_full_version >}}/charts/
|
|
{{< /text >}}
|
|
|
|
## Installation steps
|
|
|
|
Change directory to the root of the release and then
|
|
choose one of the following two **mutually exclusive** options:
|
|
|
|
1. To deploy Istio without using Tiller, follow the instructions for [option 1](/docs/setup/install/helm/#option-1-install-with-helm-via-helm-template).
|
|
1. To use [Helm's Tiller pod](https://helm.sh/) to manage your Istio release, follow the instructions for [option 2](/docs/setup/install/helm/#option-2-install-with-helm-and-tiller-via-helm-install).
|
|
|
|
{{< tip >}}
|
|
Istio, by default, uses `LoadBalancer` service object types. Some platforms do not support `LoadBalancer`
|
|
service objects. For platforms lacking `LoadBalancer` support, install Istio with `NodePort` support
|
|
instead with the flags `--set gateways.istio-ingressgateway.type=NodePort`
|
|
appended to the end of the Helm instructions in the installation steps below.
|
|
{{< /tip >}}
|
|
|
|
### Option 1: Install with Helm via `helm template`
|
|
|
|
Choose this option if your cluster doesn't have [Tiller](https://helm.sh/docs/topics/architecture/#components)
|
|
deployed and you don't want to install it.
|
|
|
|
1. Create a namespace for the `istio-system` components:
|
|
|
|
{{< text bash >}}
|
|
$ kubectl create namespace istio-system
|
|
{{< /text >}}
|
|
|
|
1. Install all the Istio
|
|
[Custom Resource Definitions](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/#customresourcedefinitions)
|
|
(CRDs) using `kubectl apply`:
|
|
|
|
{{< text bash >}}
|
|
$ helm template install/kubernetes/helm/istio-init --name istio-init --namespace istio-system | kubectl apply -f -
|
|
{{< /text >}}
|
|
|
|
1. {{< boilerplate verify-crds >}}
|
|
|
|
1. Select a [configuration profile](/docs/setup/additional-setup/config-profiles/)
|
|
and then render and apply Istio's core components corresponding to your chosen profile.
|
|
The **default** profile is recommended for production deployments:
|
|
|
|
{{< tip >}}
|
|
You can further customize the configuration by adding one or more `--set <key>=<value>`
|
|
[Installation Options](/docs/reference/config/installation-options/) to the helm command.
|
|
{{< /tip >}}
|
|
|
|
{{< tabset cookie-name="helm_profile" >}}
|
|
|
|
{{< tab name="default" cookie-value="default" >}}
|
|
|
|
{{< text bash >}}
|
|
$ helm template install/kubernetes/helm/istio --name istio --namespace istio-system | kubectl apply -f -
|
|
{{< /text >}}
|
|
|
|
{{< /tab >}}
|
|
|
|
{{< tab name="demo" cookie-value="demo" >}}
|
|
|
|
{{< text bash >}}
|
|
$ helm template install/kubernetes/helm/istio --name istio --namespace istio-system \
|
|
--values install/kubernetes/helm/istio/values-istio-demo.yaml | kubectl apply -f -
|
|
{{< /text >}}
|
|
|
|
{{< /tab >}}
|
|
|
|
{{< tab name="minimal" cookie-value="minimal" >}}
|
|
|
|
{{< text bash >}}
|
|
$ helm template install/kubernetes/helm/istio --name istio --namespace istio-system \
|
|
--values install/kubernetes/helm/istio/values-istio-minimal.yaml | kubectl apply -f -
|
|
{{< /text >}}
|
|
|
|
{{< /tab >}}
|
|
|
|
{{< tab name="sds" cookie-value="sds" >}}
|
|
|
|
{{< text bash >}}
|
|
$ helm template install/kubernetes/helm/istio --name istio --namespace istio-system \
|
|
--values install/kubernetes/helm/istio/values-istio-sds-auth.yaml | kubectl apply -f -
|
|
{{< /text >}}
|
|
|
|
{{< /tab >}}
|
|
|
|
{{< tab name="Mutual TLS enabled" cookie-value="mtls" >}}
|
|
|
|
Enable mutual TLS in Istio by setting options `global.controlPlaneSecurityEnabled=true`
|
|
and `global.mtls.enabled=true`, in addition to the specifying the Helm values file
|
|
corresponding to your chosen profile.
|
|
|
|
For example, to configure the `demo` profile with mutual TLS enabled:
|
|
|
|
{{< text bash >}}
|
|
$ helm template install/kubernetes/helm/istio --name istio --namespace istio-system \
|
|
--values install/kubernetes/helm/istio/values-istio-demo.yaml \
|
|
--set global.controlPlaneSecurityEnabled=true \
|
|
--set global.mtls.enabled=true | kubectl apply -f -
|
|
{{< /text >}}
|
|
|
|
{{< /tab >}}
|
|
|
|
{{< tab name="Istio CNI enabled" cookie-value="cni" >}}
|
|
|
|
Install the [Istio CNI](/docs/setup/additional-setup/cni/) components:
|
|
|
|
{{< text bash >}}
|
|
$ helm template install/kubernetes/helm/istio-cni --name=istio-cni --namespace=kube-system | kubectl apply -f -
|
|
{{< /text >}}
|
|
|
|
Enable CNI in Istio by setting `--set istio_cni.enabled=true` in addition to the settings for your chosen profile.
|
|
For example, to configure the **default** profile:
|
|
|
|
{{< text bash >}}
|
|
$ helm template install/kubernetes/helm/istio --name istio --namespace istio-system \
|
|
--set istio_cni.enabled=true | kubectl apply -f -
|
|
{{< /text >}}
|
|
|
|
{{< /tab >}}
|
|
|
|
{{< /tabset >}}
|
|
|
|
### Option 2: Install with Helm and Tiller via `helm install`
|
|
|
|
This option allows Helm and
|
|
[Tiller](https://helm.sh/docs/topics/architecture/#components)
|
|
to manage the lifecycle of Istio.
|
|
|
|
{{< boilerplate helm-security-warning >}}
|
|
|
|
1. Make sure you have a service account with the `cluster-admin` role defined for Tiller.
|
|
If not already defined, create one using following command:
|
|
|
|
{{< text bash >}}
|
|
$ kubectl apply -f @install/kubernetes/helm/helm-service-account.yaml@
|
|
{{< /text >}}
|
|
|
|
1. Install Tiller on your cluster with the service account:
|
|
|
|
{{< text bash >}}
|
|
$ helm init --service-account tiller
|
|
{{< /text >}}
|
|
|
|
1. Install the `istio-init` chart to bootstrap all the Istio's CRDs:
|
|
|
|
{{< text bash >}}
|
|
$ helm install install/kubernetes/helm/istio-init --name istio-init --namespace istio-system
|
|
{{< /text >}}
|
|
|
|
1. {{< boilerplate verify-crds >}}
|
|
|
|
1. Select a [configuration profile](/docs/setup/additional-setup/config-profiles/)
|
|
and then install the `istio` chart corresponding to your chosen profile.
|
|
The **default** profile is recommended for production deployments:
|
|
|
|
{{< tip >}}
|
|
You can further customize the configuration by adding one or more `--set <key>=<value>`
|
|
[Installation Options](/docs/reference/config/installation-options/) to the helm command.
|
|
{{< /tip >}}
|
|
|
|
{{< tabset cookie-name="helm_profile" >}}
|
|
|
|
{{< tab name="default" cookie-value="default" >}}
|
|
|
|
{{< text bash >}}
|
|
$ helm install install/kubernetes/helm/istio --name istio --namespace istio-system
|
|
{{< /text >}}
|
|
|
|
{{< /tab >}}
|
|
|
|
{{< tab name="demo" cookie-value="demo" >}}
|
|
|
|
{{< text bash >}}
|
|
$ helm install install/kubernetes/helm/istio --name istio --namespace istio-system \
|
|
--values install/kubernetes/helm/istio/values-istio-demo.yaml
|
|
{{< /text >}}
|
|
|
|
{{< /tab >}}
|
|
|
|
{{< tab name="minimal" cookie-value="minimal" >}}
|
|
|
|
{{< text bash >}}
|
|
$ helm install install/kubernetes/helm/istio --name istio --namespace istio-system \
|
|
--values install/kubernetes/helm/istio/values-istio-minimal.yaml
|
|
{{< /text >}}
|
|
|
|
{{< /tab >}}
|
|
|
|
{{< tab name="sds" cookie-value="sds" >}}
|
|
|
|
{{< text bash >}}
|
|
$ helm install install/kubernetes/helm/istio --name istio --namespace istio-system \
|
|
--values install/kubernetes/helm/istio/values-istio-sds-auth.yaml
|
|
{{< /text >}}
|
|
|
|
{{< /tab >}}
|
|
|
|
{{< tab name="Mutual TLS enabled" cookie-value="mtls" >}}
|
|
|
|
Enable mutual TLS in Istio by setting options `global.controlPlaneSecurityEnabled=true`
|
|
and `global.mtls.enabled=true`, in addition to the specifying the Helm values file
|
|
corresponding to your chosen profile.
|
|
|
|
For example, to configure the **demo** profile with mutual TLS enabled:
|
|
|
|
{{< text bash >}}
|
|
$ helm install install/kubernetes/helm/istio --name istio --namespace istio-system \
|
|
--values install/kubernetes/helm/istio/values-istio-demo.yaml \
|
|
--set global.controlPlaneSecurityEnabled=true \
|
|
--set global.mtls.enabled=true | kubectl apply -f -
|
|
{{< /text >}}
|
|
|
|
{{< /tab >}}
|
|
|
|
{{< tab name="Istio CNI enabled" cookie-value="cni" >}}
|
|
|
|
Install the [Istio CNI](/docs/setup/additional-setup/cni/) chart:
|
|
|
|
{{< text bash >}}
|
|
$ helm install install/kubernetes/helm/istio-cni --name istio-cni --namespace kube-system
|
|
{{< /text >}}
|
|
|
|
Enable CNI in Istio by setting `--set istio_cni.enabled=true` in addition to the settings for your chosen profile.
|
|
For example, to configure the **default** profile:
|
|
|
|
{{< text bash >}}
|
|
$ helm install install/kubernetes/helm/istio --name istio --namespace istio-system --set istio_cni.enabled=true
|
|
{{< /text >}}
|
|
|
|
{{< /tab >}}
|
|
|
|
{{< /tabset >}}
|
|
|
|
## Verifying the installation
|
|
|
|
1. Referring to components table in
|
|
[configuration profiles](/docs/setup/additional-setup/config-profiles/),
|
|
verify that the Kubernetes services corresponding to your selected profile have been deployed.
|
|
|
|
{{< text bash >}}
|
|
$ kubectl get svc -n istio-system
|
|
{{< /text >}}
|
|
|
|
1. Ensure the corresponding Kubernetes pods are deployed and have a `STATUS` of `Running`:
|
|
|
|
{{< text bash >}}
|
|
$ kubectl get pods -n istio-system
|
|
{{< /text >}}
|
|
|
|
## Uninstall
|
|
|
|
- If you installed Istio using the `helm template` command, uninstall with these commands:
|
|
|
|
{{< tabset cookie-name="helm_profile" >}}
|
|
|
|
{{< tab name="default" cookie-value="default" >}}
|
|
|
|
{{< text bash >}}
|
|
$ helm template install/kubernetes/helm/istio --name istio --namespace istio-system | kubectl delete -f -
|
|
$ kubectl delete namespace istio-system
|
|
{{< /text >}}
|
|
|
|
{{< /tab >}}
|
|
|
|
{{< tab name="demo" cookie-value="demo" >}}
|
|
|
|
{{< text bash >}}
|
|
$ helm template install/kubernetes/helm/istio --name istio --namespace istio-system \
|
|
--values install/kubernetes/helm/istio/values-istio-demo.yaml | kubectl delete -f -
|
|
$ kubectl delete namespace istio-system
|
|
{{< /text >}}
|
|
|
|
{{< /tab >}}
|
|
|
|
{{< tab name="minimal" cookie-value="minimal" >}}
|
|
|
|
{{< text bash >}}
|
|
$ helm template install/kubernetes/helm/istio --name istio --namespace istio-system \
|
|
--values install/kubernetes/helm/istio/values-istio-minimal.yaml | kubectl delete -f -
|
|
$ kubectl delete namespace istio-system
|
|
{{< /text >}}
|
|
|
|
{{< /tab >}}
|
|
|
|
{{< tab name="sds" cookie-value="sds" >}}
|
|
|
|
{{< text bash >}}
|
|
$ helm template install/kubernetes/helm/istio --name istio --namespace istio-system \
|
|
--values install/kubernetes/helm/istio/values-istio-sds-auth.yaml | kubectl delete -f -
|
|
$ kubectl delete namespace istio-system
|
|
{{< /text >}}
|
|
|
|
{{< /tab >}}
|
|
|
|
{{< tab name="Mutual TLS enabled" cookie-value="mtls" >}}
|
|
|
|
Follow the instructions corresponding to your selected configuration profile.
|
|
|
|
{{< /tab >}}
|
|
|
|
{{< tab name="Istio CNI enabled" cookie-value="cni" >}}
|
|
|
|
Follow the instructions corresponding to your selected configuration profile
|
|
and then execute the following command to uninstall the CNI plug-in:
|
|
|
|
{{< text bash >}}
|
|
$ helm template install/kubernetes/helm/istio-cni --name=istio-cni --namespace=kube-system | kubectl delete -f -
|
|
{{< /text >}}
|
|
|
|
{{< /tab >}}
|
|
|
|
{{< /tabset >}}
|
|
|
|
- If you installed Istio using Helm and Tiller, uninstall with these commands:
|
|
|
|
{{< text bash >}}
|
|
$ helm delete --purge istio
|
|
$ helm delete --purge istio-init
|
|
$ helm delete --purge istio-cni
|
|
$ kubectl delete namespace istio-system
|
|
{{< /text >}}
|
|
|
|
## Deleting CRDs and Istio Configuration
|
|
|
|
Istio, by design, expects Istio's Custom Resources contained within CRDs to leak into the
|
|
Kubernetes environment. CRDs contain the runtime configuration set by the operator.
|
|
Because of this, we consider it better for operators to explicitly delete the runtime
|
|
configuration data rather than unexpectedly lose it.
|
|
|
|
{{< warning >}}
|
|
Deleting CRDs permanently deletes any configuration changes that you have made to Istio.
|
|
{{< /warning >}}
|
|
|
|
The `istio-init` chart contains all raw CRDs in the `istio-init/files` directory.
|
|
You can simply delete the CRDs using `kubectl`.
|
|
To permanently delete Istio's CRDs and the entire Istio configuration, run:
|
|
|
|
{{< text bash >}}
|
|
$ kubectl delete -f install/kubernetes/helm/istio-init/files
|
|
{{< /text >}}
|