Merge pull request #269566 from SanyaKochhar/kochhars/asm/docs-improvements

asm: clarify installation and upgrade docs based on feedback

Author: prmerger-automator[bot]

articles/aks/istio-deploy-addon.md

@@ -29,7 +29,23 @@ export LOCATION=<location>
 
 The add-on requires Azure CLI version 2.57.0 or later installed. You can run `az --version` to verify version. To install or upgrade, see [Install Azure CLI][azure-cli-install].
 
-## Install Istio add-on at the time of cluster creation
+## Get available Istio add-on revisions
+To find information about which Istio add-on revisions are available in a region and their compatibility with AKS cluster versions, use:
+
+```azurecli-interactive
+az aks mesh get-revisions --location <location> -o table
+```
+
+
+## Install Istio add-on
+### Revision selection
+If you enable the add-on without specifying a revision, a default supported revision is installed for you.
+
+If you wish to specify the revision instead:
+1. Use the `get-revisions` command in the [previous step](#get-available-istio-add-on-revisions) to check which revisions are available for different AKS cluster versions in a region.
+1. Based on the available revisions, you can include the `--revision asm-X-Y` (ex: `--revision asm-1-20`) flag in the enable command you use for mesh installation.
+
+### Install mesh during cluster creation
 
 To install the Istio add-on when creating the cluster, use the `--enable-azure-service-mesh` or`--enable-asm` parameter.
 
@@ -42,7 +58,7 @@ az aks create \
 --enable-asm
 ```
 
-## Install Istio add-on for existing cluster
+### Install mesh for existing cluster
 
 The following example enables Istio add-on for an existing AKS cluster:
 
@@ -86,23 +102,44 @@ istiod-asm-1-18-74f7f7c46c-xfdtl   1/1     Running   0          2m
 
 ## Enable sidecar injection
 
-To automatically install sidecar to any new pods, annotate your namespaces:
+To automatically install sidecar to any new pods, you will need to annotate your namespaces with the revision label corresponding to the control plane revision currently installed. 
+
+If you're unsure which revision is installed, use:
+```bash
+az aks show --resource-group ${RESOURCE_GROUP} --name ${CLUSTER}  --query 'serviceMeshProfile.istio.revisions'
+```
 
+Apply the revision label:
 ```bash
-kubectl label namespace default istio.io/rev=asm-1-18
+kubectl label namespace default istio.io/rev=asm-X-Y
 ```
 
 > [!IMPORTANT]
->  The default `istio-injection=enabled` labeling doesn't work. Explicit versioning (`istio.io/rev=asm-1-18`) is required.
+>  The default `istio-injection=enabled` labeling doesn't work. Explicit versioning matching the control plane revision (ex: `istio.io/rev=asm-1-18`) is required. 
 
+For manual injection of sidecar using `istioctl kube-inject`, you need to specify extra parameters for `istioNamespace` (`-i`) and `revision` (`-r`). For example:
 
-For manual injection of sidecar using `istioctl kube-inject`, you need to specify extra parameters for `istioNamespace` (`-i`) and `revision` (`-r`). Example:
+```bash
+kubectl apply -f <(istioctl kube-inject -f sample.yaml -i aks-istio-system -r asm-X-Y) -n foo
+```
+
+## Trigger sidecar injection
+You can either deploy the sample application provided for testing, or trigger sidecar injection for existing workloads.
+
+### Existing applications
+If you have existing applications to be added to the mesh, ensure their namespaces are labeled as in the previous step, and then restart their deployments to trigger sidecar injection:
+```bash
+kubectl rollout restart -n <namespace> <deployment name>
+```
 
+Verify that sidecar injection succeeded by ensuring all containers are ready and looking for the `istio-proxy` container in the `kubectl describe` output, for example:
 ```bash
-kubectl apply -f <(istioctl kube-inject -f sample.yaml -i aks-istio-system -r asm-1-18) -n foo
+kubectl describe pod -n namespace <pod name>
 ```
 
-## Deploy sample application
+The `istio-proxy` container is the Envoy sidecar. Your application is now part of the data plane.
+
+### Deploy sample application
 
 Use `kubectl apply` to deploy the sample application on the cluster:
 
@@ -150,10 +187,8 @@ reviews       ClusterIP   10.0.73.95     <none>        9080/TCP   86s
 kubectl get pods
 ```
 
-Confirm that all the pods have status of `Running`.
-
 ```
-NAME          TYPE        CLUSTER-IP     EXTERNAL-IP   PORT(S)    AGE
+NAME                              READY   STATUS    RESTARTS   AGE
 details-v1-558b8b4b76-2llld       2/2     Running   0          2m41s
 productpage-v1-6987489c74-lpkgl   2/2     Running   0          2m40s
 ratings-v1-7dc98c7588-vzftc       2/2     Running   0          2m41s
@@ -162,8 +197,8 @@ reviews-v2-7d79d5bd5d-8zzqd       2/2     Running   0          2m41s
 reviews-v3-7dbcdcbc56-m8dph       2/2     Running   0          2m41s
 ```
 
-> [!NOTE]
-> Each pod has two containers, one of which is the Envoy sidecar injected by Istio and the other is the application container.
+
+Confirm that all the pods have status of `Running` with 2 containers in the `READY` column. The second container (`istio-proxy`) added to each pod is the Envoy sidecar injected by Istio, and the other is the application container.
 
 To test this sample application against ingress, check out [next-steps](#next-steps).
 

articles/aks/istio-upgrade.md

@@ -32,7 +32,7 @@ The following example illustrates how to upgrade from revision `asm-1-18` to `as
 1. Initiate a canary upgrade from revision `asm-1-18` to `asm-1-19` using [az aks mesh upgrade start](/cli/azure/aks/mesh#az-aks-mesh-upgrade-start):
 
     ```bash
-    az aks mesh upgrade start --resource-group $RESOURCE_GROUP --name $CLUSTER --revision asm-1-18
+    az aks mesh upgrade start --resource-group $RESOURCE_GROUP --name $CLUSTER --revision asm-1-19
     ```
 
     A canary upgrade means the 1.18 control plane is deployed alongside the 1.17 control plane. They continue to coexist until you either complete or roll back the upgrade.
@@ -101,7 +101,7 @@ The following example illustrates how to upgrade from revision `asm-1-18` to `as
 
     * **Rollback the canary upgrade**: In case you observe any issues with the health of your workloads, you can roll back to the previous revision of Istio:
 
-      * Relabel the namespace to the previous revision
+      * Relabel the namespace to the previous revision:
 
           ```bash
           kubectl label namespace default istio.io/rev=asm-1-18 --overwrite
@@ -119,7 +119,7 @@ The following example illustrates how to upgrade from revision `asm-1-18` to `as
           az aks mesh upgrade rollback --resource-group $RESOURCE_GROUP --name $CLUSTER
           ```
 
-1. If [mesh configuration][meshconfig] was set up for the revisions in previous steps, you can now delete the ConfigMap for the revision that was removed from the cluster on completing or rolling back the upgrade.
+1. If [mesh configuration][meshconfig] was previously set up for the revisions, you can now delete the ConfigMap for the revision that was removed from the cluster during complete/rollback.
 
 > [!NOTE]
 > Manually relabeling namespaces when moving them to a new revision can be tedious and error-prone. [Revision tags](https://istio.io/latest/docs/setup/upgrade/canary/#stable-revision-labels) solve this problem. Revision tags are stable identifiers that point to revisions and can be used to avoid relabeling namespaces. Rather than relabeling the namespace, a mesh operator can simply change the tag to point to a new revision. All namespaces labeled with that tag will be updated at the same time. However, note that you still need to restart the workloads to make sure the correct version of `istio-proxy` sidecars are injected.