From 77c8566cccd9fff2e24e550198be1fc0cfc20bf4 Mon Sep 17 00:00:00 2001 From: Martin Ostrowski Date: Thu, 11 Jun 2020 06:42:05 -0700 Subject: [PATCH] Update istioctl docs (#7502) * Update istioctl docs * Lint * Update content/en/docs/setup/install/istioctl/index.md Co-authored-by: Frank Budinsky * Update content/en/docs/setup/install/istioctl/index.md Co-authored-by: Frank Budinsky * Update content/en/docs/setup/install/istioctl/index.md Co-authored-by: Frank Budinsky * Update content/en/docs/setup/install/istioctl/index.md Co-authored-by: Frank Budinsky * Update content/en/docs/setup/install/istioctl/index.md Co-authored-by: Frank Budinsky Co-authored-by: Frank Budinsky --- .../en/docs/setup/install/istioctl/index.md | 35 +++++++++++-------- .../install/standalone-operator/index.md | 3 +- 2 files changed, 21 insertions(+), 17 deletions(-) diff --git a/content/en/docs/setup/install/istioctl/index.md b/content/en/docs/setup/install/istioctl/index.md index 5e6423bcd0..0dcb09acb1 100644 --- a/content/en/docs/setup/install/istioctl/index.md +++ b/content/en/docs/setup/install/istioctl/index.md @@ -40,6 +40,11 @@ using the following command: $ istioctl install {{< /text >}} +{{< tip >}} +Note that `istioctl install` and `istioctl manifest apply` are exactly the same command. In Istio 1.6, the simpler `install` +command replaces `manifest apply`, which is deprecated and will be removed in 1.7. +{{< /tip >}} + This command installs the `default` profile on the cluster defined by your Kubernetes configuration. The `default` profile is a good starting point for establishing a production environment, unlike the larger `demo` profile that @@ -83,6 +88,13 @@ to install the `demo` profile: $ istioctl install --set profile=demo {{< /text >}} +## Check what's installed + +The `istioctl` command saves the `IstioOperator` CR that was used to install Istio in a copy of the CR named `installed-state`. +You can inspect this CR if you lose track of what is installed in a cluster. + +The `installed-state` CR is also used to perform checks in some `istioctl` commands and should therefore not be removed. + ## Display the list of available profiles You can display the names of Istio configuration profiles that are @@ -182,28 +194,21 @@ $ istioctl profile diff default demo ## Generate a manifest before installation You can generate the manifest before installing Istio using the `manifest generate` -sub-command, instead of `istioctl install`. +sub-command. For example, use the following command to generate a manifest for the `default` profile: {{< text bash >}} $ istioctl manifest generate > $HOME/generated-manifest.yaml {{< /text >}} -Inspect the manifest as needed, then apply the manifest using this command: +The generated manifest can be used to inspect what exactly is installed as well as to track changes to the manifest +over time. While the `IstioOperator` CR represents the full user configuration and is sufficient for tracking it, +the output from `manifest generate` also captures possible changes in the underlying charts and therefore can be +used to track the actual installed resources. -{{< text bash >}} -$ kubectl create ns istio-system -$ kubectl apply -f $HOME/generated-manifest.yaml -{{< /text >}} - -{{< warning >}} -While `istioctl install` will automatically detect environment specific settings from your Kubernetes context, `manifest generate` 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. -{{< /warning >}} - -{{< tip >}} -This command might show transient errors due to resources not being available in -the cluster in the correct order. -{{< /tip >}} +The output from `manifest generate` can also be used to install Istio using `kubectl apply` or equivalent. However, +these alternative installation methods may not apply the resources with the same sequencing of dependencies as +`istioctl install` and are not tested in an Istio release. ## Show differences in manifests diff --git a/content/en/docs/setup/install/standalone-operator/index.md b/content/en/docs/setup/install/standalone-operator/index.md index 01f4b3e7db..402e683608 100644 --- a/content/en/docs/setup/install/standalone-operator/index.md +++ b/content/en/docs/setup/install/standalone-operator/index.md @@ -11,8 +11,7 @@ This guide installs Istio using the standalone Istio [operator](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/). The only dependencies required are a supported Kubernetes cluster, the `kubectl` command at the version to match the cluster, and the `istioctl` command at the desired release version. -To install Istio for production use, we recommend [installing with {{< istioctl >}}](/docs/setup/install/istioctl/) -instead. +The operator is beta in 1.6 and suitable for production use. ## Prerequisites