mirror of https://github.com/istio/istio.io.git
232 lines
10 KiB
Markdown
232 lines
10 KiB
Markdown
---
|
|
title: Install with Helm
|
|
linktitle: Install with Helm
|
|
description: Instructions to install and configure Istio in a Kubernetes cluster using Helm.
|
|
weight: 30
|
|
keywords: [kubernetes,helm]
|
|
owner: istio/wg-environments-maintainers
|
|
test: yes
|
|
---
|
|
|
|
Follow this guide to install and configure an Istio mesh using
|
|
[Helm](https://helm.sh/docs/).
|
|
|
|
{{< boilerplate helm-preamble >}}
|
|
|
|
{{< boilerplate helm-prereqs >}}
|
|
|
|
## Installation steps
|
|
|
|
This section describes the procedure to install Istio using Helm. The general syntax for helm installation is:
|
|
|
|
{{< text syntax=bash snip_id=none >}}
|
|
$ helm install <release> <chart> --namespace <namespace> --create-namespace [--set <other_parameters>]
|
|
{{< /text >}}
|
|
|
|
The variables specified in the command are as follows:
|
|
* `<chart>` A path to a packaged chart, a path to an unpacked chart directory or a URL.
|
|
* `<release>` A name to identify and manage the Helm chart once installed.
|
|
* `<namespace>` The namespace in which the chart is to be installed.
|
|
|
|
Default configuration values can be changed using one or more `--set <parameter>=<value>` arguments. Alternatively, you can specify several parameters in a custom values file using the `--values <file>` argument.
|
|
|
|
{{< tip >}}
|
|
You can display the default values of configuration parameters using the `helm show values <chart>` command or refer to `artifacthub` chart documentation at [Custom Resource Definition parameters](https://artifacthub.io/packages/helm/istio-official/base?modal=values), [Istiod chart configuration parameters](https://artifacthub.io/packages/helm/istio-official/istiod?modal=values) and [Gateway chart configuration parameters](https://artifacthub.io/packages/helm/istio-official/gateway?modal=values).
|
|
{{< /tip >}}
|
|
|
|
1. Create the namespace, `istio-system`, for the Istio components:
|
|
{{< tip >}}
|
|
This step can be skipped if using the `--create-namespace` argument in step 2.
|
|
{{< /tip >}}
|
|
|
|
{{< text syntax=bash snip_id=create_istio_system_namespace >}}
|
|
$ kubectl create namespace istio-system
|
|
{{< /text >}}
|
|
|
|
1. Install the Istio base chart which contains cluster-wide Custom Resource Definitions (CRDs) which must be installed prior to the deployment of the Istio control plane:
|
|
|
|
{{< warning >}}
|
|
When performing a revisioned installation, the base chart requires the `--set defaultRevision=<revision>` value to be set for resource
|
|
validation to function. Below we install the `default` revision, so `--set defaultRevision=default` is configured.
|
|
{{< /warning >}}
|
|
|
|
{{< text syntax=bash snip_id=install_base >}}
|
|
$ helm install istio-base istio/base -n istio-system --set defaultRevision=default
|
|
{{< /text >}}
|
|
|
|
1. Validate the CRD installation with the `helm ls` command:
|
|
|
|
{{< text syntax=bash >}}
|
|
$ helm ls -n istio-system
|
|
NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION
|
|
istio-base istio-system 1 2024-04-17 22:14:45.964722028 +0000 UTC deployed base-{{< istio_full_version >}} {{< istio_full_version >}}
|
|
{{< /text >}}
|
|
|
|
In the output locate the entry for `istio-base` and make sure the status is set to `deployed`.
|
|
|
|
1. If you intend to use Istio CNI chart you must do so now. See [Install Istio with the CNI plugin](/docs/setup/additional-setup/cni/#installing-with-helm) for more info.
|
|
|
|
1. Install the Istio discovery chart which deploys the `istiod` service:
|
|
|
|
{{< text syntax=bash snip_id=install_discovery >}}
|
|
$ helm install istiod istio/istiod -n istio-system --wait
|
|
{{< /text >}}
|
|
|
|
1. Verify the Istio discovery chart installation:
|
|
|
|
{{< text syntax=bash >}}
|
|
$ helm ls -n istio-system
|
|
NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION
|
|
istio-base istio-system 1 2024-04-17 22:14:45.964722028 +0000 UTC deployed base-{{< istio_full_version >}} {{< istio_full_version >}}
|
|
istiod istio-system 1 2024-04-17 22:14:45.964722028 +0000 UTC deployed istiod-{{< istio_full_version >}} {{< istio_full_version >}}
|
|
{{< /text >}}
|
|
|
|
1. Get the status of the installed helm chart to ensure it is deployed:
|
|
|
|
{{< text syntax=bash >}}
|
|
$ helm status istiod -n istio-system
|
|
NAME: istiod
|
|
LAST DEPLOYED: Fri Jan 20 22:00:44 2023
|
|
NAMESPACE: istio-system
|
|
STATUS: deployed
|
|
REVISION: 1
|
|
TEST SUITE: None
|
|
NOTES:
|
|
"istiod" successfully installed!
|
|
|
|
To learn more about the release, try:
|
|
$ helm status istiod
|
|
$ helm get all istiod
|
|
|
|
Next steps:
|
|
* Deploy a Gateway: https://istio.io/latest/docs/setup/additional-setup/gateway/
|
|
* Try out our tasks to get started on common configurations:
|
|
* https://istio.io/latest/docs/tasks/traffic-management
|
|
* https://istio.io/latest/docs/tasks/security/
|
|
* https://istio.io/latest/docs/tasks/policy-enforcement/
|
|
* https://istio.io/latest/docs/tasks/policy-enforcement/
|
|
* Review the list of actively supported releases, CVE publications and our hardening guide:
|
|
* https://istio.io/latest/docs/releases/supported-releases/
|
|
* https://istio.io/latest/news/security/
|
|
* https://istio.io/latest/docs/ops/best-practices/security/
|
|
|
|
For further documentation see https://istio.io website
|
|
|
|
Tell us how your install/upgrade experience went at https://forms.gle/99uiMML96AmsXY5d6
|
|
{{< /text >}}
|
|
|
|
1. Check `istiod` service is successfully installed and its pods are running:
|
|
|
|
{{< text syntax=bash >}}
|
|
$ kubectl get deployments -n istio-system --output wide
|
|
NAME READY UP-TO-DATE AVAILABLE AGE CONTAINERS IMAGES SELECTOR
|
|
istiod 1/1 1 1 10m discovery docker.io/istio/pilot:{{< istio_full_version >}} istio=pilot
|
|
{{< /text >}}
|
|
|
|
1. (Optional) Install an ingress gateway:
|
|
|
|
{{< text syntax=bash snip_id=install_ingressgateway >}}
|
|
$ kubectl create namespace istio-ingress
|
|
$ helm install istio-ingress istio/gateway -n istio-ingress --wait
|
|
{{< /text >}}
|
|
|
|
See [Installing Gateways](/docs/setup/additional-setup/gateway/) for in-depth documentation on gateway installation.
|
|
|
|
{{< warning >}}
|
|
The namespace the gateway is deployed in must not have a `istio-injection=disabled` label.
|
|
See [Controlling the injection policy](/docs/setup/additional-setup/sidecar-injection/#controlling-the-injection-policy) for more info.
|
|
{{< /warning >}}
|
|
|
|
{{< tip >}}
|
|
See [Advanced Helm Chart Customization](/docs/setup/additional-setup/customize-installation-helm/) for in-depth documentation on how to use
|
|
Helm post-renderer to customize the Helm charts.
|
|
{{< /tip >}}
|
|
|
|
## Updating your Istio configuration
|
|
|
|
You can provide override settings specific to any Istio Helm chart used above
|
|
and follow the Helm upgrade workflow to customize your Istio mesh installation.
|
|
The available configurable options can be found by using `helm show values istio/<chart>`;
|
|
for example `helm show values istio/gateway`.
|
|
|
|
### Migrating from non-Helm installations
|
|
|
|
If you're migrating from a version of Istio installed using `istioctl` or
|
|
Operator to Helm (Istio 1.5 or earlier), you need to delete your current Istio
|
|
control plane resources and re-install Istio using Helm as described above. When
|
|
deleting your current Istio installation, you must not remove the Istio Custom Resource
|
|
Definitions (CRDs) as that can lead to loss of your custom Istio resources.
|
|
|
|
{{< warning >}}
|
|
It is highly recommended to take a backup of your Istio resources using steps
|
|
described above before deleting current Istio installation in your cluster.
|
|
{{< /warning >}}
|
|
|
|
You can follow steps mentioned in the
|
|
[Istioctl uninstall guide](/docs/setup/install/istioctl#uninstall-istio) or
|
|
[Operator uninstall guide](/docs/setup/install/operator/#uninstall)
|
|
depending upon your installation method.
|
|
|
|
## Uninstall
|
|
|
|
You can uninstall Istio and its components by uninstalling the charts
|
|
installed above.
|
|
|
|
1. List all the Istio charts installed in `istio-system` namespace:
|
|
|
|
{{< text syntax=bash snip_id=helm_ls >}}
|
|
$ helm ls -n istio-system
|
|
NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION
|
|
istio-base istio-system 1 2024-04-17 22:14:45.964722028 +0000 UTC deployed base-{{< istio_full_version >}} {{< istio_full_version >}}
|
|
istiod istio-system 1 2024-04-17 22:14:45.964722028 +0000 UTC deployed istiod-{{< istio_full_version >}} {{< istio_full_version >}}
|
|
{{< /text >}}
|
|
|
|
1. (Optional) Delete any Istio gateway chart installations:
|
|
|
|
{{< text syntax=bash snip_id=delete_delete_gateway_charts >}}
|
|
$ helm delete istio-ingress -n istio-ingress
|
|
$ kubectl delete namespace istio-ingress
|
|
{{< /text >}}
|
|
|
|
1. Delete Istio discovery chart:
|
|
|
|
{{< text syntax=bash snip_id=helm_delete_discovery_chart >}}
|
|
$ helm delete istiod -n istio-system
|
|
{{< /text >}}
|
|
|
|
1. Delete Istio base chart:
|
|
|
|
{{< tip >}}
|
|
By design, deleting a chart via Helm doesn't delete the installed Custom
|
|
Resource Definitions (CRDs) installed via the chart.
|
|
{{< /tip >}}
|
|
|
|
{{< text syntax=bash snip_id=helm_delete_base_chart >}}
|
|
$ helm delete istio-base -n istio-system
|
|
{{< /text >}}
|
|
|
|
1. Delete the `istio-system` namespace:
|
|
|
|
{{< text syntax=bash snip_id=delete_istio_system_namespace >}}
|
|
$ kubectl delete namespace istio-system
|
|
{{< /text >}}
|
|
|
|
## Uninstall stable revision label resources
|
|
|
|
If you decide to continue using the old control plane, instead of completing the update,
|
|
you can uninstall the newer revision and its tag by first issuing
|
|
`helm template istiod istio/istiod -s templates/revision-tags.yaml --set revisionTags={prod-canary} --set revision=canary -n istio-system | kubectl delete -f -`.
|
|
You must then uninstall the revision of Istio that it pointed to by following the uninstall procedure above.
|
|
|
|
If you installed the gateway(s) for this revision using in-place upgrades, you must also reinstall the gateway(s) for the previous revision manually.
|
|
Removing the previous revision and its tags will not automatically revert the previously upgraded gateway(s).
|
|
|
|
### (Optional) Deleting CRDs installed by Istio
|
|
|
|
Deleting CRDs permanently removes any Istio resources you have created in your cluster.
|
|
To delete Istio CRDs installed in your cluster:
|
|
|
|
{{< text syntax=bash snip_id=delete_crds >}}
|
|
$ kubectl get crd -oname | grep --color=never 'istio.io' | xargs kubectl delete
|
|
{{< /text >}}
|