Few clarifications, add revision

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

@@ -56,6 +56,13 @@ configures the proxies to route traffic within the mesh.
 $ helm install istiod istio/istiod --namespace istio-system --set profile=ambient --wait
 {{< /text >}}
 
+You can also install Istiod with a specific revision, allowing multiple installs for safe upgrade and config canary.
+This should also be used if you have a 'default' istiod already installed.
+
+{{< text syntax=bash snip_id=install_discovery_revision >}}
+$ helm install istiod istio/istiod --namespace istio-system --set profile=ambient --set revision=ambient --wait
+{{< /text >}}
+
 ### Install the ztunnel component
 
 The `ztunnel` chart installs the ztunnel DaemonSet, which is the node proxy component of Istio's ambient mode.
@@ -64,6 +71,12 @@ The `ztunnel` chart installs the ztunnel DaemonSet, which is the node proxy comp
 $ helm install ztunnel istio/ztunnel -n istio-system --wait
 {{< /text >}}
 
+For using ztunnel with a specific revision of Istiod:
+
+{{< text syntax=bash snip_id=install_ztunnel_revision >}}
+$ helm install ztunnel istio/ztunnel -n istio-system --set revision=ambient --wait
+{{< /text >}}
+
 ### Install an ingress gateway (optional)
 
 To install an ingress gateway, run the command below:
@@ -74,6 +87,8 @@ $ helm install istio-ingress istio/gateway -n istio-ingress --create-namespace -
 
 If your Kubernetes cluster doesn't support the `LoadBalancer` service type (`type: LoadBalancer`) with a proper external IP assigned, run the above command without the `--wait` parameter to avoid the infinite wait. See [Installing Gateways](/docs/setup/additional-setup/gateway/) for in-depth documentation on gateway installation.
 
+You can use the [K8S Gateway](/docs/tasks/traffic-management/ingress/gateway-api/) resource - Istiod will automatically create and remove the gateway deployment as needed.
+
 ## Configuration
 
 To view supported configuration options and documentation, run:

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

@@ -37,10 +37,18 @@ snip_install_discovery() {
 helm install istiod istio/istiod --namespace istio-system --set profile=ambient --wait
 }
 
+snip_install_discovery_revision() {
+helm install istiod istio/istiod --namespace istio-system --set profile=ambient --set revision=ambient --wait
+}
+
 snip_install_ztunnel() {
 helm install ztunnel istio/ztunnel -n istio-system --wait
 }
 
+snip_install_ztunnel_revision() {
+helm install ztunnel istio/ztunnel -n istio-system --set revision=ambient --wait
+}
+
 snip_install_ingress() {
 helm install istio-ingress istio/gateway -n istio-ingress --create-namespace --wait
 }

content/en/docs/ambient/usage/add-workloads/index.md

@@ -30,13 +30,10 @@ For example, setting a `PeerAuthentication` policy with mTLS mode set to `STRICT
 
 ### Pods inside the mesh using sidecar mode
 
-Istio supports East-West interoperability between a pod with a sidecar and a pod using ambient mode, within the same mesh. The sidecar proxy knows to use the HBONE protocol since the destination has been discovered to be an HBONE destination.
+Istio supports interoperability between a pod with a sidecar and a pod using ambient mode, within the same mesh. The sidecar proxy knows to use the same protocol as the ambient nodes. The control plane for sidecars needs to be installed
+with the `ambient` profile.
 
-{{< tip >}}
-For sidecar proxies to use the HBONE/mTLS signaling option when communicating with ambient destinations, they need to be configured with `ISTIO_META_ENABLE_HBONE` set to `true` in the proxy metadata. This is the default in `MeshConfig` when using the `ambient` profile, hence you do not have to do anything else when using this profile.
-{{< /tip >}}
-
-A `PeerAuthentication` policy with mTLS mode set to `STRICT` will allow traffic from a pod with an Istio sidecar proxy.
+A `PeerAuthentication` policy with mTLS mode set to `STRICT` will allow traffic from a pod with an Istio sidecar proxy or from pods using ambient mode.
 
 ### Ingress and egress gateways and ambient mode pods
 

content/en/docs/ambient/usage/l4-policy/index.md

@@ -8,7 +8,7 @@ test: no
 
 The layering of {{< gloss >}}ztunnel{{< /gloss >}} and {{< gloss >}}waypoint{{< /gloss >}} proxies in Istio's ambient mode gives you a choice on whether or not you want to enable Layer 7 (L7) processing for a given workload.
 
-The Layer 4 (L4) features of Istio's [security policies](/docs/concepts/security) are supported by ztunnel, and are available in ambient mode. [Kubernetes Network Policies](https://kubernetes.io/docs/concepts/services-networking/network-policies/) also continue to work if your cluster has a {{< gloss >}}CNI{{< /gloss >}} plugin that supports them, and can be used to provide defense-in-depth.
+The Layer 4 (L4) features of Istio's [security policies](/docs/concepts/security) are supported by ztunnel, and are available in ambient mode. [Kubernetes Network Policies](https://kubernetes.io/docs/concepts/services-networking/network-policies/) also continue to work if your cluster has a {{< gloss >}}CNI{{< /gloss >}} plugin that supports them, and can be used to provide defense-in-depth. When using Kubernetes Network Policies, an ambient workload receives traffic multiplexed on port 15008 from ambient client and waypoints.
 
 To use L7 policies, and Istio's traffic routing features, you can [deploy a waypoint](/docs/ambient/usage/waypoint) for your workloads.
 
@@ -38,7 +38,7 @@ spec:
 EOF
 {{< /text >}}
 
-The behavior of the L4 `AuthorizationPolicy` API has the same functional behavior in Istio ambient mode as in sidecar mode. When there is no `AuthorizationPolicy` provisioned, then the default action is `ALLOW`. Once a policy is provisioned, pods matching the selector in the policy only allow traffic which is explicitly allowed. In this example, pods with the label `app: httpbin` only allow traffic from sources with an identity principal of `cluster.local/ns/ambient-demo/sa/sleep`. Traffic from all other sources will be denied.
+The behavior of the L4 `AuthorizationPolicy` API has the same functional behavior in Istio ambient mode as in sidecar mode. When there is no `AuthorizationPolicy` provisioned, then the default action is `ALLOW`. Once a policy is provisioned, pods matching the selector in the policy only allow traffic which is explicitly allowed. In this example, pods with the label `app: httpbin` only allow traffic from sources with an identity principal of `cluster.local/ns/ambient-demo/sa/sleep`. Traffic from all other sources, including non-ambient clients will be denied.
 
 ### Layer 7 authorization policies without waypoints installed