From 3d7ab4ade89cb7cea1fe13d3083a958d38bdcbea Mon Sep 17 00:00:00 2001 From: Frank Budinsky Date: Mon, 9 Nov 2020 12:08:21 -0500 Subject: [PATCH] Install approach FAQ (#8455) * Install approach FAQ * lint * tweak * address review comments * cleanup * more review comments --- .../en/docs/setup/getting-started/index.md | 6 +- .../en/faq/setup/consul-app-not-working.md | 6 -- content/en/faq/setup/consul-unset-context.md | 8 --- .../en/faq/setup/install-method-selection.md | 72 +++++++++++++++++++ content/en/faq/setup/k8s-migrating.md | 6 -- 5 files changed, 75 insertions(+), 23 deletions(-) delete mode 100644 content/en/faq/setup/consul-app-not-working.md delete mode 100644 content/en/faq/setup/consul-unset-context.md create mode 100644 content/en/faq/setup/install-method-selection.md delete mode 100644 content/en/faq/setup/k8s-migrating.md diff --git a/content/en/docs/setup/getting-started/index.md b/content/en/docs/setup/getting-started/index.md index 9b1e803b4e..093c2edb86 100644 --- a/content/en/docs/setup/getting-started/index.md +++ b/content/en/docs/setup/getting-started/index.md @@ -13,9 +13,9 @@ test: yes This guide lets you quickly evaluate Istio. If you are already familiar with Istio or interested in installing other configuration profiles or -advanced [deployment models](/docs/ops/deployment/deployment-models/), see -[Customizable Install with `istioctl`](/docs/setup/install/istioctl/) -instead. +advanced [deployment models](/docs/ops/deployment/deployment-models/), refer to our +[which Istio installation method should I use?](/faq/setup/#install-method-selection) +FAQ page. These steps require you to have a {{< gloss >}}cluster{{< /gloss >}} running a compatible version of Kubernetes ({{< supported_kubernetes_versions >}}). You can use any supported platform, for diff --git a/content/en/faq/setup/consul-app-not-working.md b/content/en/faq/setup/consul-app-not-working.md deleted file mode 100644 index 22ff00fc99..0000000000 --- a/content/en/faq/setup/consul-app-not-working.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Consul - My application isn't working, where can I troubleshoot this? -weight: 40 ---- - -Please ensure all required containers are running: `etcd`, `istio-apiserver`, `consul`, `registrator`, `pilot`. If one of them is not running, you may find the {containerID} using `docker ps -a` and then use `docker logs {containerID}` to read the logs. diff --git a/content/en/faq/setup/consul-unset-context.md b/content/en/faq/setup/consul-unset-context.md deleted file mode 100644 index 58b333165f..0000000000 --- a/content/en/faq/setup/consul-unset-context.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: Consul - How do I unset the context changed by kubectl at the end? -weight: 50 ---- - -Your `kubectl` is switched to use the Istio context at the end of the `kubectl use-context istio` command. -You can use `kubectl config get-contexts` to obtain the list of contexts and -`kubectl config use-context {desired-context}` to switch to use your desired context. diff --git a/content/en/faq/setup/install-method-selection.md b/content/en/faq/setup/install-method-selection.md new file mode 100644 index 0000000000..776672cff0 --- /dev/null +++ b/content/en/faq/setup/install-method-selection.md @@ -0,0 +1,72 @@ +--- +title: Which Istio installation method should I use? +weight: 10 +--- + +In addition to the simple [getting started](/docs/setup/getting-started) evaluation install, there are several different +methods you can use to install Istio. Which one you should use depends on your production requirements. +The following lists some of the pros and cons of each of the available methods: + +1. [istioctl install](/docs/setup/install/istioctl/) + + The simplest and most qualified installation and management path with high security. + This is the community recommended method for most use cases. + + Pros: + + - Thorough configuration validation and health verification. + - Uses the `IstioOperator` API which provides extensive configuration/customization options. + - No in-cluster privileged pods needed. Changes are actuated by running the `istioctl` command. + + Cons: + + - Multiple binaries must be managed, one per Istio minor version. + - The `istioctl` command can set values like `JWT_POLICY` based on your running environment, + thereby producing varying installations in different Kubernetes environments. + +1. [Istio Operator](/docs/setup/install/operator/) + + Simple installation path without `istioctl` binaries. This is a recommended approach + for simplified upgrade workflows where running an in-cluster privileged controller is not a concern. + + Pros: + + - Same API as `istioctl install` but actuation is through a controller pod in the cluster with a fully declarative operation. + - Uses the `IstioOperator` API which provides extensive configuration/customization options. + - No need to manage multiple `istioctl` binaries. + + Cons: + + - High privilege controller running in the cluster poses security risks. + +1. [istioctl manifest generate](/docs/setup/install/istioctl/#generate-a-manifest-before-installation) + + 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. + + Pros: + + - Charts are generated from the same `IstioOperator` API as used in `istioctl install` and Operator. + - Uses the `IstioOperator` API which provides extensive configuration/customization options. + + Cons: + + - Some checks performed in `istioctl install` and Operator are not done. + - UX is less streamlined compared to `istioctl install`. + - Error reporting is not as robust as `istioctl install` for the apply step. + +1. [Install using Helm (alpha)](/docs/setup/install/helm/) + + Using Helm charts allows easy integration with Helm based workflows and automated resource pruning during upgrades. + + Pros: + + - Familiar approach using industry standard tooling. + - Helm native release and upgrade management. + + Cons: + + - Fewer checks and validations compared to `istioctl install` and Operator. + - Some administrative tasks require more steps and have higher complexity. + +Installation instructions for all of these methods are available on the [Istio install page](/docs/setup/install). diff --git a/content/en/faq/setup/k8s-migrating.md b/content/en/faq/setup/k8s-migrating.md deleted file mode 100644 index 068d8a449f..0000000000 --- a/content/en/faq/setup/k8s-migrating.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Kubernetes - Can I migrate an existing installation from Istio 0.1.x to 0.2.x? -weight: 30 ---- - -Upgrading from Istio 0.1.x to 0.2.x is not supported. You must uninstall Istio 0.1, _including pods with Istio sidecars_ and start with a fresh install of Istio 0.2.