[release-1.24] Explicitly document how to template manifests with both helm and istioctl and remove references to istioctl manifest diff

content/en/about/faq/setup/install-method-selection.md

@@ -23,34 +23,37 @@ 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.
+    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. Apply a generated Kubernetes manifest
 
-1. [Install using Helm](/docs/setup/install/helm/)
+    - [Generating Kubernetes manifests with `istioctl`](/docs/setup/install/istioctl/#generate-a-manifest-before-installation)
+    - [Generating Kubernetes manifests with `helm`](/docs/setup/install/helm/#generate-a-manifest-before-installation)
 
-    Using Helm charts allows easy integration with Helm based workflows and automated resource pruning during upgrades.
+    This method is suitable where strict auditing or augmentation of output manifests is required, or there are third-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 during 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/ambient/install/helm/index.md

@@ -199,3 +199,49 @@ installed above.
     {{< text syntax=bash snip_id=delete_system_namespace >}}
     $ kubectl delete namespace istio-system
     {{< /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, to generate a manifest that can be installed with `kubectl` 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.
+
+{{< tip >}}
+Any additional flags or custom values overrides you would normally use for installation should also be supplied to the `helm template` command.
+{{< /tip >}}
+
+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 >}}
+
+{{< 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. Resources may not be installed with the same sequencing of dependencies as
+`helm install`
+
+1. This method is not tested as part of Istio releases.
+
+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/ambient/install/istioctl/index.md

@@ -81,3 +81,50 @@ If no longer needed, use the following command to remove it:
 {{< text syntax=bash snip_id=remove_namespace >}}
 $ kubectl delete namespace istio-system
 {{< /text >}}
+
+## Generate a manifest before installation
+
+You can generate the manifest before installing Istio using the `manifest generate`
+sub-command.
+For example, use the following command to generate a manifest for the `default` profile that can be installed with `kubectl`:
+
+{{< text syntax=bash snip_id=none >}}
+$ istioctl manifest generate > $HOME/generated-manifest.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. 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.
+
+{{< tip >}}
+Any additional flags or custom values overrides you would normally use for installation should also be supplied to the `istioctl manifest generate` command.
+{{< /tip >}}
+
+{{< warning >}}
+If attempting to install and manage Istio using `istioctl manifest generate`, please note the following caveats:
+
+1. The Istio namespace (`istio-system` by default) must be created manually.
+
+1. Istio validation will not be enabled by default. Unlike `istioctl install`, the `manifest generate` command will
+not create the `istiod-default-validator` validating webhook configuration unless `values.defaultRevision` is set:
+
+    {{< text syntax=bash snip_id=none >}}
+    $ istioctl manifest generate --set values.defaultRevision=default
+    {{< /text >}}
+
+1. Resources may not be installed with the same sequencing of dependencies as
+`istioctl install`.
+
+1. This method is not tested as part of Istio releases.
+
+1. 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. 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 requires network access to your running cluster.
+
+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. `istioctl 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 `istio manifest generate` with `kubectl` and these
+resources must be removed manually.
+
+{{< /warning >}}

content/en/docs/setup/install/helm/index.md

@@ -216,3 +216,49 @@ 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, to generate a manifest that can be installed with `kubectl` 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.
+
+{{< tip >}}
+Any additional flags or custom values overrides you would normally use for installation should also be supplied to the `helm template` command.
+{{< /tip >}}
+
+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 >}}
+
+{{< 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. Resources may not be installed with the same sequencing of dependencies as
+`helm install`
+
+1. This method is not tested as part of Istio releases.
+
+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

@@ -110,20 +110,17 @@ $ istioctl install --set profile=demo
 
 You can generate the manifest before installing Istio using the `manifest generate`
 sub-command.
-For example, use the following command to generate a manifest for the `default` profile:
+For example, use the following command to generate a manifest for the `default` profile that can be installed with `kubectl`:
 
 {{< text bash >}}
 $ istioctl manifest generate > $HOME/generated-manifest.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. 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.
+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.
 
-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.
+{{< tip >}}
+Any additional flags or custom values overrides you would normally use for installation should also be supplied to the `istioctl manifest generate` command.
+{{< /tip >}}
 
 {{< warning >}}
 If attempting to install and manage Istio using `istioctl manifest generate`, please note the following caveats:
@@ -137,10 +134,15 @@ not create the `istiod-default-validator` validating webhook configuration unles
     $ istioctl manifest generate --set values.defaultRevision=default
     {{< /text >}}
 
+1. Resources may not be installed with the same sequencing of dependencies as
+`istioctl install`.
+
+1. This method is not tested as part of Istio releases.
+
 1. 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.
+Kubernetes environment does not support third party service account tokens. 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 requires network access to your running cluster.
 
 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