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/en/docs/setup/install/helm/index.md

9.8 KiB
Raw Blame History

title linktitle description weight keywords owner test
Install with Helm Install with Helm Instructions to install and configure Istio in a Kubernetes cluster using Helm. 30
kubernetes
helm
istio/wg-environments-maintainers yes

Follow this guide to install and configure an Istio mesh using Helm.

{{< 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 --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, Istiod chart configuration parameters and Gateway chart configuration parameters. {{< /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 >}}

  2. 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 >}}

  3. 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 ... ... ... ... deployed base-1.16.1 1.16.1 {{< /text >}}

    In the output locate the entry for istio-base and make sure the status is set to deployed.

  4. If you intend to use Istio CNI chart you must do so now. See Install Istio with the CNI plugin for more info.

  5. 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 >}}

  6. 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 ... ... ... ... deployed base-1.16.1 1.16.1 istiod istio-system 1 ... ... ... ... deployed istiod-1.16.1 1.16.1 {{< /text >}}

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

    For further documentation see https://istio.io website

    Tell us how your install/upgrade experience went at https://forms.gle/99uiMML96AmsXY5d6 {{< /text >}}

  8. 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:1.16.1 istio=pilot {{< /text >}}

  9. (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 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 for more info. {{< /warning >}}

{{< tip >}} See Advanced Helm Chart Customization 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 or Operator uninstall guide 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 ... ... ... ... deployed base-1.0.0 1.0.0 istiod istio-system 1 ... ... ... ... deployed istiod-1.0.0 1.0.0 {{< /text >}}

  2. (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 >}}

  3. Delete Istio discovery chart:

    {{< text syntax=bash snip_id=helm_delete_discovery_chart >}} $ helm delete istiod -n istio-system {{< /text >}}

  4. 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 >}}

  5. 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 >}}