Explicitly document how to template manifests with both helm and `i…

…stioctl` and remove references to `istioctl manifest diff`

Signed-off-by: Benjamin Leggett <[email protected]>

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

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 syntax=bash snip_id=none >}}
+$ helm template istiod istio/istiod -n istio-system --kube-version <Kubernetes version of target cluster> > 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 syntax=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 >}}

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