docs: Add comprehensive Istio Ambient Mode update and waypoint proxy procedures

README.md

@@ -89,7 +89,7 @@ spec:
 
 ## Getting Started
 
-You’ll need a Kubernetes cluster to run against. You can use [KIND](https://sigs.k8s.io/kind) to get a local cluster for testing, or run against a remote cluster.  
+You’ll need a Kubernetes cluster to run against. You can use [KIND](https://sigs.k8s.io/kind) to get a local cluster for testing, or run against a remote cluster.
 **Note:** Your controller will automatically use the current context in your kubeconfig file (i.e. whatever cluster `kubectl cluster-info` shows).
 
 ### Quick start using a local KIND cluster
@@ -205,9 +205,74 @@ kubectl get istiocni default
 kubectl get ztunnel default
 ```
 
-**Note** - The version can be specified by modifying the `version` field within `Istio` and `IstioCNI` manifests.  
+**Note** - The version can be specified by modifying the `version` field within `Istio` and `IstioCNI` manifests.
 For other deployment options, refer to the [docs](docs) directory.
 
+## Updating Components
+
+### Updating IstioCNI
+
+The Istio Container Network Interface (CNI) update process uses in-place updates. When the IstioCNI resource changes, the daemonset automatically replaces the existing istio-cni-node pods with the specified version of the CNI plugin.
+
+You can use the following field to manage version updates:
+
+**spec.version**: Defines the CNI plugin version to install. Specify the value in the format vX.Y.Z, where X.Y.Z represents the desired version. For example, use v1.26.4 to install the CNI plugin version 1.26.4.
+
+To update the CNI plugin, modify the spec.version field with the target version. The IstioCNI resource also includes a values field that exposes configuration options from the istio-cni chart.
+
+In ambient mode, the IstioCNI component is responsible for traffic redirection. The component is compatible with multiple control plane versions (generally n-1 to n+1 minor versions) during RevisionBased upgrades and continues to handle traffic redirection for both old and new control planes during the migration period.
+
+After updating the Istio control plane, update the IstioCNI component. The Sail Operator deploys a new version of the CNI plugin that replaces the old version. The `istio-cni-node` DaemonSet pods are updated using a rolling update strategy, and traffic redirection rules are maintained during the update process.
+
+**Prerequisites:**
+
+* You have cluster-admin access to your Kubernetes cluster.
+* You have successfully updated the Istio control plane to the desired version (InPlace strategy) or created a new control plane revision (RevisionBased strategy).
+* The IstioCNI resource named `default` is deployed in the `istio-cni` namespace.
+
+**Procedure:**
+
+1. Update the IstioCNI resource version. For example, to update to Istio 1.26.4, set the `spec.version` field to `v1.26.4` by running the following command:
+
+```sh
+kubectl patch istiocni -n istio-cni default --type='merge' -p '{"spec":{"version":"v1.26.4"}}'
+```
+
+2. Wait for the IstioCNI DaemonSet to be updated:
+
+```sh
+kubectl wait --for=condition=Ready istiocnis/default --timeout=5m
+```
+
+3. Verify the IstioCNI resource shows the new version and all pods are running:
+
+```sh
+kubectl get istiocni
+```
+
+Expected output:
+```
+NAME      READY   STATUS    VERSION   AGE
+default   True    Healthy   v1.26.4   7d1h
+```
+
+Check the pods:
+```sh
+kubectl get pods -n istio-cni
+```
+
+Expected output:
+```
+NAME                   READY   STATUS    RESTARTS   AGE
+istio-cni-node-abc12   1/1     Running   0          3m
+istio-cni-node-def34   1/1     Running   0          3m
+istio-cni-node-ghi56   1/1     Running   0          3m
+```
+
+**Note:** When using the RevisionBased strategy, IstioCNI is compatible with multiple control plane versions (generally n-1 to n+1 minor versions) and continues to work with both the old and new control planes during the workload migration.
+
+For detailed information about updating Istio in ambient mode, including control plane updates and ZTunnel updates, see the [Istio Ambient Update Guide](docs/common/istio-ambient-update.adoc).
+
 ### Undeploying the operator
 Undeploy the operator from the cluster:
 

docs/README.adoc

@@ -71,9 +71,11 @@ link:../[Return to Project Root]
 ** link:common/istio-ambient-mode.adoc#visualize-the-application-using-kiali-dashboard[Visualize the application using Kiali dashboard]
 ** link:common/istio-ambient-mode.adoc#troubleshoot-issues[Troubleshoot issues]
 ** link:common/istio-ambient-mode.adoc#cleanup[Cleanup]
+* link:common/istio-ambient-update.adoc#updating-istio-in-ambient-mode[Updating Istio in Ambient Mode]
 * link:common/istio-ambient-waypoint.adoc#introduction-to-istio-waypoint-proxy[Introduction to Istio Waypoint Proxy]
 ** link:common/istio-ambient-waypoint.adoc#core-features[Core features]
 ** link:common/istio-ambient-waypoint.adoc#getting-started[Getting Started]
+** link:common/istio-ambient-waypoint.adoc#update[Update]
 ** link:common/istio-ambient-waypoint.adoc#layer-7-features-in-ambient-mode[Layer 7 Features in Ambient Mode]
 ** link:common/istio-ambient-waypoint.adoc#troubleshoot-issues[Troubleshoot issues]
 ** link:common/istio-ambient-waypoint.adoc#cleanup[Cleanup]
@@ -107,7 +109,7 @@ link:../[Return to Project Root]
 
 Sail Operator manages the lifecycle of your Istio control planes. Instead of creating a new configuration schema, Sail Operator APIs are built around Istio's helm chart APIs. All installation and configuration options that are exposed by Istio's helm charts are available through the Sail Operator CRDs' `values` fields.
 
-Similar to using Istio's Helm charts, the final set of values used to render the charts is determined by a combination of user-provided values, default chart values, and values from selected profiles. 
+Similar to using Istio's Helm charts, the final set of values used to render the charts is determined by a combination of user-provided values, default chart values, and values from selected profiles.
 These profiles can include the user-defined profile, the platform profile, and the compatibility version profile.
 To view the final set of values, inspect the ConfigMap named `values` (or `values-<revision>`) in the namespace where the control plane is installed.
 
@@ -141,7 +143,7 @@ Note: If you need a specific Istio version, you can explicitly set it using `spe
 
 Istio uses a ConfigMap for its global configuration, called the MeshConfig. All of its settings are available through `spec.meshConfig`.
 
-To support canary updates of the control plane, Sail Operator includes support for multiple Istio versions. You can select a version by setting the `version` field in the `spec` to the version you would like to install, prefixed with a `v`. You can then update to a new version just by changing this field. An `vX.Y-latest` alias can be used for the latest z/patch versions of each supported y/minor versions. As per the example above, `{istio_latest_tag}` can be specified in the `version` field. By doing so, the operator will keep the istio version with the latest `z` version of the same `y` version. 
+To support canary updates of the control plane, Sail Operator includes support for multiple Istio versions. You can select a version by setting the `version` field in the `spec` to the version you would like to install, prefixed with a `v`. You can then update to a new version just by changing this field. An `vX.Y-latest` alias can be used for the latest z/patch versions of each supported y/minor versions. As per the example above, `{istio_latest_tag}` can be specified in the `version` field. By doing so, the operator will keep the istio version with the latest `z` version of the same `y` version.
 
 Sail Operator supports two different update strategies for your control planes: `InPlace` and `RevisionBased`. When using `InPlace`, the operator will immediately replace your existing control plane resources with the ones for the new version, whereas `RevisionBased` uses Istio's canary update mechanism by creating a second control plane to which you can migrate your workloads to complete the update.
 
@@ -203,7 +205,7 @@ If you need a specific Istio version, you can explicitly set it using `spec.vers
 [#updating-the-istiocni-resource]
 ==== Updating the IstioCNI resource
 
-Updates for the `IstioCNI` resource are `Inplace` updates, this means that the `DaemonSet` will be updated with the new version of the CNI plugin once the resource is updated and the `istio-cni-node` pods are going to be replaced with the new version. 
+Updates for the `IstioCNI` resource are `Inplace` updates, this means that the `DaemonSet` will be updated with the new version of the CNI plugin once the resource is updated and the `istio-cni-node` pods are going to be replaced with the new version.
 To update the CNI plugin, just change the `version` field to the version you want to install. Just like the `Istio` resource, it also has a `values` field that exposes all of the options provided in the `istio-cni` chart:
 
 . Create the `IstioCNI` resource.

docs/common/istio-ambient-mode.adoc

@@ -21,6 +21,7 @@ link:../README.adoc[Return to Project Root]
 *** <<deploy-a-sample-application>>
 ** <<visualize-the-application-using-kiali-dashboard>>
 ** <<troubleshoot-issues>>
+** <<update>>
 ** <<cleanup>>
 
 [[introduction-to-istio-ambient-mode]]
@@ -99,7 +100,7 @@ kubectl create namespace istio-system
 kubectl label namespace istio-system istio-discovery=enabled
 ----
 
-. Create the `Istio` resource. 
+. Create the `Istio` resource.
 +
 NOTE: The Istio resource `.spec.values.pilot.trustedZtunnelNamespace` value should match the namespace that we will install a `ZTunnel` resource at.
 +
@@ -346,7 +347,7 @@ Next, click and select `Show Badges`, `Security` from the `Display` drop-down. Y
 
 image::images/kiali-security.png[Kiali Security]
 
-In the https://kiali.io/docs/features/ambient/[Kiali documentation] there is a list of all the Ambient features. 
+In the https://kiali.io/docs/features/ambient/[Kiali documentation] there is a list of all the Ambient features.
 
 [[troubleshoot-issues]]
 === Troubleshoot issues
@@ -398,6 +399,25 @@ kubectl -n ztunnel logs -l app=ztunnel | grep -E "inbound|outbound"
 
 Validate the `src.identity` and `dst.identity` values are correct. They are the identities used for the mTLS communication among the source and destination workloads.
 
+[[update]]
+== Update
+
+For detailed information on updating Istio when deployed in ambient mode, see link:./istio-ambient-update.adoc#updating-istio-in-ambient-mode[Updating Istio in Ambient Mode].
+
+IMPORTANT: The **InPlace update strategy is the recommended approach** for ambient mode deployments. While RevisionBased updates are theoretically possible, they require significant manual effort to synchronize CRDs between Istio and ZTunnel revisions and have inherent limitations (only one ztunnel instance can run cluster-wide). See the link:./istio-ambient-update.adoc#updating-with-revisionbased-strategy[RevisionBased Strategy section] for details on these limitations.
+
+This guide covers:
+- Understanding versioning and the update process
+- InPlace update strategy procedures (recommended for ambient mode)
+- RevisionBased update strategy procedures (with limitations in ambient mode)
+- Updating IstioCNI and ZTunnel components
+- Verifying ambient workloads after updates
+- Waypoint proxy compatibility during upgrades
+- Special considerations for ambient mode upgrades
+- Troubleshooting common update issues
+
+For waypoint-specific update procedures, see link:./istio-ambient-waypoint.adoc#update[Waypoint Proxy Update Procedures].
+
 [[cleanup]]
 === Cleanup