mirror of https://github.com/istio/istio.io.git
321 lines
11 KiB
Markdown
321 lines
11 KiB
Markdown
---
|
|
title: Customizable Install with Helm
|
|
description: Instructions to install Istio using a Helm chart.
|
|
weight: 20
|
|
keywords: [kubernetes,helm]
|
|
aliases:
|
|
- /docs/setup/kubernetes/helm.html
|
|
- /docs/tasks/integrating-services-into-istio.html
|
|
- /docs/setup/kubernetes/helm-install/
|
|
icon: helm
|
|
---
|
|
|
|
Follow this flow to install and configure an Istio mesh for in-depth evaluation or production use.
|
|
|
|
This installation flow 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://github.com/kubernetes/helm/blob/master/docs/architecture.md#components)
|
|
completely manage the installation.
|
|
|
|
Using these instructions, you can select any one of Istio's built-in
|
|
[configuration profiles](/docs/setup/kubernetes/additional-setup/config-profiles/)
|
|
and then further customize the configuration for your specific needs.
|
|
|
|
## Prerequisites
|
|
|
|
1. [Download the Istio release](/docs/setup/kubernetes/download/).
|
|
|
|
1. Perform any necessary [platform-specific setup](/docs/setup/kubernetes/prepare/platform-setup/).
|
|
|
|
1. Check the [Requirements for Pods and Services](/docs/setup/kubernetes/prepare/requirements/).
|
|
|
|
1. [Install a Helm client](https://github.com/helm/helm/blob/master/docs/install.md) with a version higher than 2.10.
|
|
|
|
{{< tip >}}
|
|
These instructions assume the `istio-init` container will be used to setup `iptables` to redirect network traffic
|
|
to/from Envoy sidecars. If you plan to customize the configuration to use `--set istio_cni.enabled=true`, you also
|
|
need to ensure that a CNI plugin is deployed. Refer to [CNI Setup](/docs/setup/kubernetes/additional-setup/cni/)
|
|
for details.
|
|
{{< /tip >}}
|
|
|
|
## Installation steps
|
|
|
|
The following commands use the Helm charts that are included in the Istio release image.
|
|
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/kubernetes/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/kubernetes/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://github.com/kubernetes/helm/blob/master/docs/architecture.md#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`, and wait a few seconds for the CRDs to be committed in the Kubernetes API-server:
|
|
|
|
{{< 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/kubernetes/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="demo-auth" cookie-value="demo-auth" >}}
|
|
|
|
{{< text bash >}}
|
|
$ helm template install/kubernetes/helm/istio --name istio --namespace istio-system \
|
|
--values install/kubernetes/helm/istio/values-istio-demo-auth.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 >}}
|
|
|
|
{{< /tabset >}}
|
|
|
|
### Option 2: Install with Helm and Tiller via `helm install`
|
|
|
|
This option allows Helm and
|
|
[Tiller](https://github.com/kubernetes/helm/blob/master/docs/architecture.md#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/kubernetes/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="demo-auth" cookie-value="demo-auth" >}}
|
|
|
|
{{< text bash >}}
|
|
$ helm install install/kubernetes/helm/istio --name istio --namespace istio-system \
|
|
--values install/kubernetes/helm/istio/values-istio-demo-auth.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 >}}
|
|
|
|
{{< /tabset >}}
|
|
|
|
## Verifying the installation
|
|
|
|
1. Referring to components table in
|
|
[configuration profiles](/docs/setup/kubernetes/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="demo-auth" cookie-value="demo-auth" >}}
|
|
|
|
{{< text bash >}}
|
|
$ helm template install/kubernetes/helm/istio --name istio --namespace istio-system \
|
|
--values install/kubernetes/helm/istio/values-istio-demo-auth.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 >}}
|
|
|
|
{{< /tabset >}}
|
|
|
|
* If you installed Istio using Helm and Tiller, uninstall with these commands:
|
|
|
|
{{< text bash >}}
|
|
$ helm delete --purge istio
|
|
$ helm delete --purge istio-init
|
|
{{< /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 >}}
|