add istioctl install page for ambient and improve install docs experience

.spelling

@@ -1163,6 +1163,7 @@ topologySpreadConstraints
 touchpoints
 tradeoff
 tradeoffs
+Traefik
 TrafficPolicy
 Trendyol
 Trivedi

content/en/docs/ambient/install/_index.md

@@ -1,10 +1,18 @@
 ---
 title: Install
-description: Installation guide for Istio ambient mode.
+description: Installation guides for Istio in ambient mode.
 weight: 5
 aliases:
   - /docs/ops/ambient/install
   - /latest/docs/ops/ambient/install
 owner: istio/wg-environment-maintainers
 test: n/a
+list_below: yes
 ---
+
+{{< tip >}}
+Want to quickly try out Istio in ambient mode? [Read our Getting Started guide](/docs/ambient/getting-started/)!
+{{< /tip >}}
+
+There are two different options for installing Istio. Which one you should choose will depend on your production requirements, and how you install other software. If you need help choosing, refer to our
+[which Istio installation method should I use?](/about/faq/#install-method-selection) FAQ page.

content/en/docs/ambient/install/helm-installation/index.md → content/en/docs/ambient/install/helm/index.md

@@ -1,17 +1,23 @@
 ---
 title: Install with Helm
-description: Install Istio in Ambient mode with Helm.
+description: Install Istio with support for ambient mode with Helm.
 weight: 4
 aliases:
   - /docs/ops/ambient/install/helm-installation
   - /latest/docs/ops/ambient/install/helm-installation
+  - /docs/ambient/install/helm-installation
+  - /latest/docs/ambient/install/helm-installation
 owner: istio/wg-environments-maintainers
 test: yes
 ---
 
-This guide shows you how to install Istio in ambient mode with Helm.
-Aside from following the demo in [Getting Started with Ambient Mode](/docs/ambient/getting-started/),
-we encourage the use of Helm to install Istio for use in ambient mode. Helm helps you manage components separately, and you can easily upgrade the components to the latest version.
+{{< tip >}}
+Follow this guide to install and configure an Istio mesh with support for ambient mode.
+If you are new to Istio, and just want to try it out, follow the
+[quick start instructions](/docs/ambient/getting-started) instead.
+{{< /tip >}}
+
+We encourage the use of Helm to install Istio for production use in ambient mode. To allow controlled upgrades, the control plane and data plane components are packaged and installed separately. (Because the ambient data plane is split across [two components](/docs/ambient/architecture/data-plane), the ztunnel and waypoints, upgrades involve separate steps for these components.)
 
 ## Prerequisites
 
@@ -26,11 +32,19 @@ we encourage the use of Helm to install Istio for use in ambient mode. Helm help
     $ helm repo update
     {{< /text >}}
 
-*See [helm repo](https://helm.sh/docs/helm/helm_repo/) for command documentation.*
+## Install the control plane
+
+Default configuration values can be changed using one or more `--set <parameter>=<value>` arguments. Alternatively, you can specify several parameters in a custom values file using the `--values <file>` argument.
+
+{{< tip >}}
+You can display the default values of configuration parameters using the `helm show values <chart>` command or refer to Artifact Hub chart documentation for the [base](https://artifacthub.io/packages/helm/istio-official/base?modal=values), [istiod](https://artifacthub.io/packages/helm/istio-official/istiod?modal=values), [CNI](https://artifacthub.io/packages/helm/istio-official/cni?modal=values), [ztunnel](https://artifacthub.io/packages/helm/istio-official/ztunnel?modal=values) and [Gateway](https://artifacthub.io/packages/helm/istio-official/gateway?modal=values) chart configuration parameters.
+{{< /tip >}}
+
+Full details on how to use and customize Helm installations are available in [the sidecar installation documentation](/docs/setup/install/helm/).
 
-## Install the components
+Unlike [istioctl](/docs/ambient/install/istioctl/) profiles, which group together components to be installed or removed, Helm profiles simply set groups of configuration values.
 
-### Install the base component
+### Base components
 
 The `base` chart contains the basic CRDs and cluster roles required to set up Istio.
 This should be installed prior to any other Istio component.
@@ -39,32 +53,34 @@ This should be installed prior to any other Istio component.
 $ helm install istio-base istio/base -n istio-system --create-namespace --wait
 {{< /text >}}
 
-### Install the CNI component
+### istiod control plane
 
-The `cni` chart installs the Istio CNI plugin. It is responsible for detecting the pods that belong to the ambient mesh, and configuring the traffic redirection between pods and the ztunnel node proxy (which will be installed later).
+The `istiod` chart installs a revision of Istiod. Istiod is the control plane component that manages and
+configures the proxies to route traffic within the mesh.
 
-{{< text syntax=bash snip_id=install_cni >}}
-$ helm install istio-cni istio/cni -n istio-system --set profile=ambient --wait
+{{< text syntax=bash snip_id=install_istiod >}}
+$ helm install istiod istio/istiod --namespace istio-system --set profile=ambient --wait
 {{< /text >}}
 
-### Install the Istiod component
+### CNI node agent
 
-The `istiod` chart installs a revision of Istiod. Istiod is the control plane component that manages and
-configures the proxies to route traffic within the mesh.
+The `cni` chart installs the Istio CNI node agent. It is responsible for detecting the pods that belong to the ambient mesh, and configuring the traffic redirection between pods and the ztunnel node proxy (which will be installed later).
 
-{{< text syntax=bash snip_id=install_discovery >}}
-$ helm install istiod istio/istiod --namespace istio-system --set profile=ambient --wait
+{{< text syntax=bash snip_id=install_cni >}}
+$ helm install istio-cni istio/cni -n istio-system --set profile=ambient --wait
 {{< /text >}}
 
-### Install the ztunnel component
+## Install the data plane
+
+### ztunnel DaemonSet
 
 The `ztunnel` chart installs the ztunnel DaemonSet, which is the node proxy component of Istio's ambient mode.
 
 {{< text syntax=bash snip_id=install_ztunnel >}}
 $ helm install ztunnel istio/ztunnel -n istio-system --wait
 {{< /text >}}
 
-### Install an ingress gateway (optional)
+### Ingress gateway (optional)
 
 To install an ingress gateway, run the command below:
 
@@ -135,21 +151,21 @@ installed above.
     $ kubectl delete namespace istio-ingress
     {{< /text >}}
 
-1. Delete the Istio CNI chart:
+1. Delete the ztunnel chart:
 
-    {{< text syntax=bash snip_id=delete_cni >}}
-    $ helm delete istio-cni -n istio-system
+    {{< text syntax=bash snip_id=delete_ztunnel >}}
+    $ helm delete ztunnel -n istio-system
     {{< /text >}}
 
-1. Delete the Istio ztunnel chart:
+1. Delete the Istio CNI chart:
 
-    {{< text syntax=bash snip_id=delete_ztunnel >}}
-    $ helm delete ztunnel -n istio-system
+    {{< text syntax=bash snip_id=delete_cni >}}
+    $ helm delete istio-cni -n istio-system
     {{< /text >}}
 
-1. Delete the Istio discovery chart:
+1. Delete the istiod control plane chart:
 
-    {{< text syntax=bash snip_id=delete_discovery >}}
+    {{< text syntax=bash snip_id=delete_istiod >}}
     $ helm delete istiod -n istio-system
     {{< /text >}}
 

content/en/docs/ambient/install/helm-installation/snips.sh → content/en/docs/ambient/install/helm/snips.sh

@@ -17,7 +17,7 @@
 
 ####################################################################################################
 # WARNING: THIS IS AN AUTO-GENERATED FILE, DO NOT EDIT. PLEASE MODIFY THE ORIGINAL MARKDOWN FILE:
-#          docs/ambient/install/helm-installation/index.md
+#          docs/ambient/install/helm/index.md
 ####################################################################################################
 
 snip_configure_helm() {
@@ -29,12 +29,12 @@ snip_install_base() {
 helm install istio-base istio/base -n istio-system --create-namespace --wait
 }
 
-snip_install_cni() {
-helm install istio-cni istio/cni -n istio-system --set profile=ambient --wait
+snip_install_istiod() {
+helm install istiod istio/istiod --namespace istio-system --set profile=ambient --wait
 }
 
-snip_install_discovery() {
-helm install istiod istio/istiod --namespace istio-system --set profile=ambient --wait
+snip_install_cni() {
+helm install istio-cni istio/cni -n istio-system --set profile=ambient --wait
 }
 
 snip_install_ztunnel() {
@@ -89,15 +89,15 @@ helm delete istio-ingress -n istio-ingress
 kubectl delete namespace istio-ingress
 }
 
-snip_delete_cni() {
-helm delete istio-cni -n istio-system
-}
-
 snip_delete_ztunnel() {
 helm delete ztunnel -n istio-system
 }
 
-snip_delete_discovery() {
+snip_delete_cni() {
+helm delete istio-cni -n istio-system
+}
+
+snip_delete_istiod() {
 helm delete istiod -n istio-system
 }
 

content/en/docs/ambient/install/helm-installation/test.sh → content/en/docs/ambient/install/helm/test.sh

@@ -25,7 +25,7 @@ set -o pipefail
 snip_configure_helm
 _rewrite_helm_repo snip_install_base
 
-_rewrite_helm_repo snip_install_discovery
+_rewrite_helm_repo snip_install_istiod
 _wait_for_deployment istio-system istiod
 
 _rewrite_helm_repo snip_install_cni
@@ -41,9 +41,9 @@ _verify_like snip_show_components "$snip_show_components_out"
 _verify_like snip_check_pods "$snip_check_pods_out"
 
 # @cleanup
-snip_delete_cni
+snip_delete_ingress
 snip_delete_ztunnel
-snip_delete_discovery
+snip_delete_cni
+snip_delete_istiod
 snip_delete_base
 snip_delete_system_namespace
-snip_delete_ingress

content/en/docs/ambient/install/istioctl/index.md

@@ -0,0 +1,83 @@
+---
+title: Install with istioctl
+description: Install Istio with support for ambient mode using the istioctl command line tool.
+weight: 10
+keywords: [istioctl,ambient]
+owner: istio/wg-environments-maintainers
+test: yes
+---
+
+{{< tip >}}
+Follow this guide to install and configure an Istio mesh with support for ambient mode.
+If you are new to Istio, and just want to try it out, follow the
+[quick start instructions](/docs/ambient/getting-started) instead.
+{{< /tip >}}
+
+This installation guide uses the [istioctl](/docs/reference/commands/istioctl/) command-line
+tool. `istioctl`, like other installation methods, exposes many customization options. Additionally,
+it offers has user input validation to help prevent installation errors, and includes many
+post-installation analysis and configuration tools.
+
+Using these instructions, you can select any one of Istio's built-in
+[configuration profiles](/docs/setup/additional-setup/config-profiles/)
+and then further customize the configuration for your specific needs.
+
+The `istioctl` command supports the full [`IstioOperator` API](/docs/reference/config/istio.operator.v1alpha1/)
+via command-line options for individual settings, or passing a YAML file containing an `IstioOperator`
+{{<gloss CRDs>}}custom resource{{</gloss>}}.
+
+## Prerequisites
+
+Before you begin, check the following prerequisites:
+
+1. [Download the Istio release](/docs/setup/additional-setup/download-istio-release/).
+1. Perform any necessary [platform-specific setup](/docs/ambient/install/platform-prerequisites/).
+
+## Install or upgrade the Kubernetes Gateway API CRDs
+
+{{< boilerplate gateway-api-install-crds >}}
+
+## Install Istio using the ambient profile
+
+`istioctl` supports a number of [configuration profiles](/docs/setup/additional-setup/config-profiles/) that include different default options,
+and can be customized for your production needs. Support for ambient mode is included in the `ambient` profile. Install Istio with the
+following command:
+
+{{< text syntax=bash snip_id=install_ambient >}}
+$ istioctl install --set profile=ambient --skip-confirmation
+{{< /text >}}
+
+This command installs the `ambient` profile on the cluster defined by your
+Kubernetes configuration.
+
+## Configure and modify profiles
+
+Istio's installation API is documented in the [`IstioOperator` API reference](/docs/reference/config/istio.operator.v1alpha1/). You
+can use the `--set` option to `istioctl install` to modify individual installation parameters, or specify your own configuration file with `-f`.
+
+Full details on how to use and customize `istioctl` installations are available in [the sidecar installation documentation](/docs/setup/install/istioctl/).
+
+## Uninstall Istio
+
+To completely uninstall Istio from a cluster, run the following command:
+
+{{< text syntax=bash snip_id=uninstall >}}
+$ istioctl uninstall --purge -y
+{{< /text >}}
+
+{{< warning >}}
+The optional `--purge` flag will remove all Istio resources, including cluster-scoped resources that may be shared with other Istio control planes.
+{{< /warning >}}
+
+Alternatively, to remove only a specific Istio control plane, run the following command:
+
+{{< text syntax=bash snip_id=none >}}
+$ istioctl uninstall <your original installation options>
+{{< /text >}}
+
+The control plane namespace (e.g., `istio-system`) is not removed by default.
+If no longer needed, use the following command to remove it:
+
+{{< text syntax=bash snip_id=remove_namespace >}}
+$ kubectl delete namespace istio-system
+{{< /text >}}

content/en/docs/ambient/install/istioctl/snips.sh

@@ -0,0 +1,34 @@
+#!/bin/bash
+# shellcheck disable=SC2034,SC2153,SC2155,SC2164
+
+# Copyright Istio Authors. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+####################################################################################################
+# WARNING: THIS IS AN AUTO-GENERATED FILE, DO NOT EDIT. PLEASE MODIFY THE ORIGINAL MARKDOWN FILE:
+#          docs/ambient/install/istioctl/index.md
+####################################################################################################
+source "content/en/boilerplates/snips/gateway-api-install-crds.sh"
+
+snip_install_ambient() {
+istioctl install --set values.pilot.env.PILOT_ENABLE_CONFIG_DISTRIBUTION_TRACKING=true --set profile=ambient --skip-confirmation
+}
+
+snip_uninstall() {
+istioctl uninstall --purge -y
+}
+
+snip_remove_namespace() {
+kubectl delete namespace istio-system
+}

content/en/docs/ambient/install/istioctl/test.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# shellcheck disable=SC2154
+
+# Copyright Istio Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+set -e
+set -u
+
+set -o pipefail
+
+# @setup profile=none
+
+snip_install_ambient
+
+_wait_for_deployment istio-system istiod
+_wait_for_daemonset istio-system istio-cni-node
+_wait_for_daemonset istio-system ztunnel
+
+# @cleanup
+snip_uninstall
+snip_remove_namespace