diff --git a/content/en/about/faq/setup/install-method-selection.md b/content/en/about/faq/setup/install-method-selection.md index 6926d1fffae8d..861fdf716cdaa 100644 --- a/content/en/about/faq/setup/install-method-selection.md +++ b/content/en/about/faq/setup/install-method-selection.md @@ -23,34 +23,38 @@ The following lists some of the pros and cons of each of the available methods: - The `istioctl` command can set values automatically based on your running environment, thereby producing varying installations in different Kubernetes environments. -1. [istioctl manifest generate](/docs/setup/install/istioctl/#generate-a-manifest-before-installation) +1. [Install using Helm](/docs/setup/install/helm/) - Generate the Kubernetes manifest and then apply with `kubectl apply --prune`. - This method is suitable where strict auditing or augmentation of output manifests is needed. + Using Helm charts allows easy integration with Helm based workflows and automated resource pruning during upgrades. Pros: - - Resources are generated from the same `IstioOperator` API as used in `istioctl install`. - - Uses the `IstioOperator` API which provides extensive configuration/customization options. + - Familiar approach using industry standard tooling. + - Helm native release and upgrade management. Cons: - - Some checks performed in `istioctl install` are not done. - - UX is less streamlined compared to `istioctl install`. - - Error reporting is not as robust as `istioctl install` for the apply step. + - Fewer checks and validations compared to `istioctl install`. + - Some administrative tasks require more steps and have higher complexity. -1. [Install using Helm](/docs/setup/install/helm/) +1. Pregenerated Kubernetes manifest - Using Helm charts allows easy integration with Helm based workflows and automated resource pruning during upgrades. + - [Pregenerating Kubernetes manifests with `istioctl`](/docs/setup/install/istioctl/#generate-a-manifest-before-installation) + - [Pregenerating Kubernetes manifests with `helm`](/docs/setup/install/helm/#generate-a-manifest-before-installation) + + This method is suitable where strict auditing or augmentation of output manifests is required, or there are 3rd party tooling constraints. Pros: - - Familiar approach using industry standard tooling. - - Helm native release and upgrade management. + - Easier to integrate with tooling that doesn't use `helm` or `istioctl`. + - No installation tools required other than `kubectl`. Cons: - - Fewer checks and validations compared to `istioctl install`. - - Some administrative tasks require more steps and have higher complexity. + - No install-time checks, environment detection, or validations supported by either of the above methods are performed. + - No installation management or upgrade capability is supported. + - UX is less streamlined. + - Error reporting duirng installation is not as robust. + Installation instructions for all of these methods are available on the [Istio install page](/docs/setup/install). diff --git a/content/en/docs/setup/install/helm/index.md b/content/en/docs/setup/install/helm/index.md index 9e3df4c6f381b..0995db8804942 100644 --- a/content/en/docs/setup/install/helm/index.md +++ b/content/en/docs/setup/install/helm/index.md @@ -225,3 +225,42 @@ 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 >}} + +## Generate a manifest before installation + +You can generate the manifests for each component before installing Istio using the `helm template` +sub-command. +For example, use the following command to generate a `kubectl`-installable manifest for the `istiod` component: + +{{< text bash snip_id=none >}} +$ helm template istiod istio/istiod -n istio-system --kube-version > istiod.yaml +{{< /text >}} + +The generated manifest can be used to inspect what exactly is installed as well as to track changes to the manifest over time. Note that any additional flags or values overrides you would normally use for installation should also be supplied to the `helm template` command. + +The following can be used to install the manifest generated above, which will create the `istiod` component in the target cluster: + +{{< text bash snip_id=none >}} +$ kubectl apply -f istiod.yaml +{{< /text >}} + +Note that this alternative installation method may not apply the resources with the same sequencing of dependencies as `helm install` and is not tested in Istio releases. + +{{< warning >}} +If attempting to install and manage Istio using `helm template`, please note the following caveats: + +1. The Istio namespace (`istio-system` by default) must be created manually. + +1. While `helm install` will automatically detect environment specific settings from your Kubernetes context, +`helm template` cannot as it runs offline, which may lead to unexpected results. In particular, you must ensure +that you follow [these steps](/docs/ops/best-practices/security/#configure-third-party-service-account-tokens) if your +Kubernetes environment does not support third party service account tokens. + +1. `kubectl apply` of the generated manifest may show transient errors due to resources not being available in the +cluster in the correct order. + +1. `helm install` automatically prunes any resources that should be removed when the configuration changes (e.g. +if you remove a gateway). This does not happen when you use `helm template` with `kubectl`, and these +resources must be removed manually. + +{{< /warning >}} diff --git a/content/en/docs/setup/install/istioctl/index.md b/content/en/docs/setup/install/istioctl/index.md index 5e9f07e820907..ebfa4cd2f6899 100644 --- a/content/en/docs/setup/install/istioctl/index.md +++ b/content/en/docs/setup/install/istioctl/index.md @@ -142,6 +142,8 @@ not create the `istiod-default-validator` validating webhook configuration unles that you follow [these steps](/docs/ops/best-practices/security/#configure-third-party-service-account-tokens) if your Kubernetes environment does not support third party service account tokens. +Note that it is recommended to append `--cluster-specific` to your `istio manifest generate` command to detect the target cluster's environment, which will embed those cluster-specific environment settings into the generated manifests. This does require network access to a live cluster, however. + 1. `kubectl apply` of the generated manifest may show transient errors due to resources not being available in the cluster in the correct order. @@ -151,38 +153,6 @@ resources must be removed manually. {{< /warning >}} -## Show differences in manifests - -You can show the differences in the generated manifests in a YAML style diff between the default profile and a -customized install using these commands: - -{{< text bash >}} -$ istioctl manifest generate > 1.yaml -$ istioctl manifest generate -f samples/operator/pilot-k8s.yaml > 2.yaml -$ istioctl manifest diff 1.yaml 2.yaml -Differences in manifests are: - - -Object Deployment:istio-system:istiod has diffs: - -spec: - template: - spec: - containers: - '[#0]': - resources: - requests: - cpu: 500m -> 1000m - memory: 2048Mi -> 4096Mi - - -Object HorizontalPodAutoscaler:istio-system:istiod has diffs: - -spec: - maxReplicas: 5 -> 10 - minReplicas: 1 -> 2 -{{< /text >}} - ## Verify a successful installation You can check if the Istio installation succeeded using the `verify-install` command