mirror of https://github.com/istio/istio.io.git
Tidy up the installation instructions (#3276)
* Tidy up the installation instructions We use our Istio.io charts distribution mechanism extensively in this documentation rework. Helm is a great package manager, and does a pretty decent job of distributing packages. These are not advanced features of helm manifests - but insteead tried and tested CLI operations that have bee around since the dawn of Helm. While we have made a call not to use advanced features of helm manifests, using more advanced workflows (helm cli commands) with Helm are expected by operators. * Fix linting errors
This commit is contained in:
Steven Dake
Martin Taillefer
parent
a146dc4df0
commit
f34ec8f704
|
|
@ -1,3 +1,4 @@
|
|||
|
||||
---
|
||||
title: Installation with Helm
|
||||
description: Install Istio with the included Helm chart.
|
||||
|
|
@ -8,7 +9,6 @@ aliases:
|
|||
- /docs/tasks/integrating-services-into-istio.html
|
||||
icon: helm
|
||||
---
|
||||
|
||||
Quick start instructions for the setup and configuration of Istio using Helm.
|
||||
This is the recommended install method for installing Istio to your
|
||||
production environment as it offers rich customization to the Istio control
|
||||
|
|
@ -16,8 +16,6 @@ plane and the sidecars for the Istio data plane.
|
|||
|
||||
## Prerequisites
|
||||
|
||||
1. [Download the Istio release](/docs/setup/kubernetes/download-release/).
|
||||
|
||||
1. Perform any necessary [platform-specific setup](/docs/setup/kubernetes/platform-setup/).
|
||||
|
||||
1. Check the [Requirements for Pods and Services](/docs/setup/kubernetes/spec-requirements/) on Pods and Services.
|
||||
|
|
@ -31,13 +29,23 @@ plane and the sidecars for the Istio data plane.
|
|||
|
||||
## Installation steps
|
||||
|
||||
The following commands have relative references in the Istio directory. You must execute the commands in Istio's root directory.
|
||||
The following commands may be run from any directory. We use Helm to obtain the charts via a secure
|
||||
HTTPS endpoint hosted in Istio's infrastructure throughout this document.
|
||||
|
||||
1. Update Helm's dependencies:
|
||||
{{< tip >}}
|
||||
The techniques in this document use Istio's daily build of Istio 1.1 Helm packages. These
|
||||
Helm charts may be slightly ahead of any particular snapshot as the project finishes the release
|
||||
candidates prior to 1.1 release. To use a snapshot-specific release, change the repo add URL to
|
||||
the appropriate snapshot. For example, if you want to run with snapshot 6, use the
|
||||
[URL](https://gcsweb.istio.io/gcs/istio-prerelease/prerelease/1.1.0-snapshot.6/charts) in installation step 1 below.
|
||||
{{< /tip >}}
|
||||
|
||||
1. Update Helm's local package cache with the location of the Helm daily release:
|
||||
|
||||
{{< text bash >}}
|
||||
|
||||
$ helm repo add istio.io "https://gcsweb.istio.io/gcs/istio-prerelease/daily-build/release-1.1-latest-daily/charts/"
|
||||
$ helm dep update install/kubernetes/helm/istio
|
||||
|
||||
{{< /text >}}
|
||||
|
||||
1. Choose one of the following two **mutually exclusive** options described below.
|
||||
|
|
@ -53,47 +61,65 @@ The following commands have relative references in the Istio directory. You must
|
|||
|
||||
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. Install all the Istio's [Custom Resource Definitions or CRDs for short](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/#customresourcedefinitions) via `kubectl apply`, and wait a few seconds for the CRDs to be committed to
|
||||
the Kubernetes API server:
|
||||
1. Make an Istio working directory for fetching the charts:
|
||||
|
||||
{{< text bash >}}
|
||||
$ for i in install/kubernetes/helm/istio-init/files/crd*yaml; do kubectl apply -f $i; done
|
||||
|
||||
$ mkdir -p $HOME/istio-fetch
|
||||
|
||||
{{< /text >}}
|
||||
|
||||
1. Render Istio's core components to a Kubernetes manifest called `istio.yaml`:
|
||||
1. Fetch the helm templates needed for installation:
|
||||
|
||||
{{< text bash >}}
|
||||
$ cat @install/kubernetes/namespace.yaml@ > $HOME/istio.yaml
|
||||
$ helm template install/kubernetes/helm/istio --name istio --namespace istio-system >> $HOME/istio.yaml
|
||||
|
||||
$ helm fetch istio.io/istio-init --untar --untardir $HOME/istio-fetch
|
||||
$ helm fetch istio.io/istio --untar --untardir $HOME/istio-fetch
|
||||
|
||||
{{< /text >}}
|
||||
|
||||
If you want to enable [global mutual TLS](/docs/concepts/security/#mutual-tls-authentication), set `global.mtls.enabled` and `global.controlPlaneSecurityEnabled` to `true` for the last command:
|
||||
1. Create a namespace for the `istio-system` components:
|
||||
|
||||
{{< text bash >}}
|
||||
$ helm template install/kubernetes/helm/istio --name istio --namespace istio-system \
|
||||
--set global.mtls.enabled=true --set global.controlPlaneSecurityEnabled=true >> $HOME/istio.yaml
|
||||
|
||||
$ kubectl create namespace istio-system
|
||||
|
||||
{{< /text >}}
|
||||
|
||||
1. Install the components via the manifest:
|
||||
1. Install all the Istio's [Custom Resource Definitions or CRDs for short](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/#customresourcedefinitions) via `kubectl apply`, and wait a few seconds for the CRDs to be committed to the Kubernetes API server:
|
||||
|
||||
{{< text bash >}}
|
||||
$ kubectl apply -f $HOME/istio.yaml
|
||||
|
||||
$ helm template $HOME/istio-fetch/istio-init --name istio-init --namespace istio-system | kubectl apply -f -
|
||||
|
||||
{{< /text >}}
|
||||
|
||||
1. Render and apply Istio's core components:
|
||||
|
||||
{{< text bash >}}
|
||||
|
||||
$ helm template $HOME/istio-fetch/istio --name istio --namespace istio-system | kubectl apply -f -
|
||||
|
||||
{{< /text >}}
|
||||
|
||||
1. Uninstall steps:
|
||||
|
||||
{{< text bash >}}
|
||||
$ kubectl delete -f $HOME/istio.yaml
|
||||
|
||||
$ kubectl delete namespace istio-system
|
||||
|
||||
{{< /text >}}
|
||||
|
||||
1. If desired, run the following command to delete all CRDs:
|
||||
|
||||
{{< warning >}}
|
||||
Deleting CRDs deletes any configuration changes that you have made to Istio.
|
||||
Deleting CRDs permanently deletes any configuration changes that you have made to Istio.
|
||||
{{< /warning >}}
|
||||
|
||||
{{< text bash >}}
|
||||
$ for i in install/kubernetes/helm/istio-init/files/crd*yaml; do kubectl delete -f $i; done
|
||||
|
||||
$ kubectl delete -f $HOME/istio-fetch/istio-init/files
|
||||
|
||||
{{< /text >}}
|
||||
|
||||
### Option 2: Install with Helm and Tiller via `helm install`
|
||||
|
|
@ -105,59 +131,77 @@ to manage the lifecycle of Istio.
|
|||
1. If a service account has not already been installed for Tiller, install one:
|
||||
|
||||
{{< 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
|
||||
|
||||
$ helm install istio.io/istio-init --name istio-init --namespace istio-system
|
||||
|
||||
{{< /text >}}
|
||||
|
||||
1. To verify all Istio's CRDs were committed in the Kubernetes api-server, check the number of CRDs with the specified suffix with the following command. Verify that the number of total CRDs created was `56` for Istio:
|
||||
1. To verify all Istio's CRDs were committed in the Kubernetes api-server, check that all CRDs
|
||||
that Istio uses are instantiated. Verify that the number of total CRDs created was `56` for Istio:
|
||||
|
||||
{{< text bash >}}
|
||||
|
||||
$ kubectl get crds | grep 'istio.io\|certmanager.k8s.io' | wc -l
|
||||
|
||||
{{< /text >}}
|
||||
|
||||
1. Install the `istio` chart:
|
||||
|
||||
{{< text bash >}}
|
||||
$ helm install install/kubernetes/helm/istio --name istio --namespace istio-system
|
||||
{{< /text >}}
|
||||
|
||||
If you want to enable [global mutual TLS](/docs/concepts/security/#mutual-tls-authentication), set `global.mtls.enabled` to `true`:
|
||||
$ helm install iistio --name istio --namespace istio-system
|
||||
|
||||
{{< text bash >}}
|
||||
$ helm install install/kubernetes/helm/istio --name istio --namespace istio-system --set global.mtls.enabled=true
|
||||
{{< /text >}}
|
||||
|
||||
1. Uninstall steps:
|
||||
|
||||
{{< warning >}}
|
||||
Uninstalling this chart does not delete Istio's registered CRDs. Istio, by design, expects
|
||||
CRDs to leak into the Kubernetes environment. As CRDs contain all the runtime configuration
|
||||
data needed to configure Istio. Because of this, we consider it better for operators to
|
||||
explicitly delete the runtime configuration data rather than unexpectedly lose it.
|
||||
{{< /warning >}}
|
||||
|
||||
{{< text bash >}}
|
||||
|
||||
$ helm delete --purge istio
|
||||
$ helm delete --purge istio-init
|
||||
|
||||
{{< /text >}}
|
||||
|
||||
1. If desired, run the following command to delete all CRDs:
|
||||
## Deleting CRDs and Istio Configuration
|
||||
|
||||
{{< warning >}}
|
||||
Deleting CRDs deletes any configuration changes that you have made to Istio.
|
||||
{{< /warning >}}
|
||||
{{< tip >}}
|
||||
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.
|
||||
{{< /tip >}}
|
||||
|
||||
{{< warning >}}
|
||||
Deleting CRDs permanently deletes any configuration changes that you have made to Istio.
|
||||
{{< /warning >}}
|
||||
|
||||
{{< tip >}}
|
||||
The `istio-init` chart contains all raw CRDs in the `istio-init/ifiles` directory. After fetching this
|
||||
chart, you can simply delete the CRDs using `kubectl`.
|
||||
{{< /tip >}}
|
||||
|
||||
1. To permanently delete Istio's CRDs and all Istio configuration:
|
||||
|
||||
{{< text bash >}}
|
||||
$ for i in install/kubernetes/helm/istio-init/files/crd*yaml; do kubectl delete -f $i; done
|
||||
|
||||
$ mkdir -p $HOME/istio-fetch
|
||||
$ helm fetch istio.io/istio-init --untar --untardir $HOME/istio-fetch
|
||||
$ kubectl delete -f $HOME/istio-fetch/istio-init/files
|
||||
|
||||
{{< /text >}}
|
||||
|
|
|
|||
Loading…
Reference in New Issue