make updates for clarity

Author: SanyaKochhar

articles/aks/istio-about.md

@@ -22,17 +22,17 @@ Service-to-service communication is what makes a distributed application possibl
 
 ## What is Istio?
 
-Istio is an open source service mesh that layers transparently onto existing distributed applications. Istio’s powerful features provide a uniform and more efficient way to secure, connect, and monitor services. Istio enables load balancing, service-to-service authentication, and monitoring – with few or no service code changes. Its powerful control plane brings vital features, including:
+Istio is an open-source service mesh that layers transparently onto existing distributed applications. Istio’s powerful features provide a uniform and more efficient way to secure, connect, and monitor services. Istio enables load balancing, service-to-service authentication, and monitoring – with few or no service code changes. Its powerful control plane brings vital features, including:
 
-* Secure service-to-service communication in a cluster with TLS encryption, strong identity-based authentication and authorization
-* Automatic load balancing for HTTP, gRPC, WebSocket, and TCP traffic
-* Fine-grained control of traffic behavior with rich routing rules, retries, failovers, and fault injection
-* A pluggable policy layer and configuration API supporting access controls, rate limits and quotas
-* Automatic metrics, logs, and traces for all traffic within a cluster, including cluster ingress and egress
+* Secure service-to-service communication in a cluster with TLS encryption, strong identity-based authentication and authorization.
+* Automatic load balancing for HTTP, gRPC, WebSocket, and TCP traffic.
+* Fine-grained control of traffic behavior with rich routing rules, retries, failovers, and fault injection.
+* A pluggable policy layer and configuration API supporting access controls, rate limits and quotas.
+* Automatic metrics, logs, and traces for all traffic within a cluster, including cluster ingress and egress.
 
-## How is the add-on different from open source Istio?
+## How is the add-on different from open-source Istio?
 
-This service mesh add-on uses and builds on top of open source Istio. The add-on flavor provides the following extra benefits:
+This service mesh add-on uses and builds on top of open-source Istio. The add-on flavor provides the following extra benefits:
 
 * Istio versions are tested and verified to be compatible with supported versions of Azure Kubernetes Service.
 * Scaling of Istio control plane configured and handled by Microsoft.

articles/aks/istio-deploy-addon.md

@@ -13,45 +13,44 @@ This article shows you how to install the Istio-based service mesh add-on for Az
 
 For more information on Istio and the service mesh add-on, see [Istio-based service mesh add-on for Azure Kubernetes Service][istio-about].
 
+[!INCLUDE [preview features callout](includes/preview/preview-callout.md)]
+
 ## Before you begin
 
-You need the Azure CLI version 2.44.0 or later installed and configured. Run `az --version` to find the version. If you need to install or upgrade, see [Install Azure CLI][install-azure-cli].
+### Set environment variables:
 
-Set environment variables:
+    ```bash
+    export CLUSTER=<cluster-name>
+    export RESOURCE_GROUP=<resource-group-name>
+    export LOCATION=<location>
+    ```
 
-```bash
-export CLUSTER=<cluster-name>
-export RESOURCE_GROUP=<resource-group-name>
-export LOCATION=<location>
-```
+### Verify Azure CLI and aks-preview extension versions
+* You need the Azure CLI version 2.44.0 or later installed. Run `az --version` to find the version. If you need to install or upgrade, see [Install Azure CLI][install-azure-cli].
+* You need the `aks-preview` Azure CLI extension of version 0.5.133 or later installed. Run `az --version` to find the version.
 
-## Install the aks-preview Azure CLI extension
-
-You need the `aks-preview` Azure CLI extension of version 0.5.133 or later installed and configured. Run `az --version` to find the version.
-
-[!INCLUDE [preview features callout](includes/preview/preview-callout.md)]
 
 To install the aks-preview extension, run the following command:
 
-```azurecli
+```azurecli-interactive
 az extension add --name aks-preview
 ```
 
 Run the following command to update to the latest version of the extension released:
 
-```azurecli
+```azurecli-interactive
 az extension update --name aks-preview
 ```
 
-## Register the 'AzureServiceMeshPreview' feature flag
+### Register the _AzureServiceMeshPreview_ feature flag
 
-Register the `AzureServiceMeshPreview` feature flag by using the [az feature register][az-feature-register] command, as shown in the following example:
+Register the `AzureServiceMeshPreview` feature flag by using the [az feature register][az-feature-register] command below:
 
 ```azurecli-interactive
 az feature register --namespace "Microsoft.ContainerService" --name "AzureServiceMeshPreview"
 ```
 
-It takes a few minutes for the status to show *Registered*. Verify the registration status by using the [az feature show][az-feature-show] command:
+It takes a few minutes for the feature to register. Verify the registration status by using the [az feature show][az-feature-show] command:
 
 ```azurecli-interactive
 az feature show --namespace "Microsoft.ContainerService" --name "AzureServiceMeshPreview"
@@ -65,7 +64,7 @@ az provider register --namespace Microsoft.ContainerService
 
 ## Install Istio add-on at the time of cluster creation
 
-To install the Istio add-on when creating the cluster, use `--enable-asm` or `--enable-azure-service-mesh` parameters.
+To install the Istio add-on when creating the cluster, use the `--enable-azure-service-mesh` or`--enable-asm` parameter.
 
 ```azurecli-interactive
 az group create --name ${RESOURCE_GROUP} --location ${LOCATION}
@@ -82,14 +81,14 @@ The following example enables Istio add-on for an existing AKS cluster:
 
 > [!IMPORTANT]
 > You can't enable the Istio add-on on an existing cluster if an OSM add-on is already on your cluster. [Uninstall OSM add-on on your cluster][uninstall-osm-addon] before enabling the Istio add-on.
-> You can't enable the Istio add-on on an existing cluster if an OSM add-on is already on your cluster. Uninstall the OSM add-on before installing the Istio add-on. For more information, see [uninstall the OSM add-on from your AKS cluster][uninstall-osm-addon].
+> For more information, see [uninstall the OSM add-on from your AKS cluster][uninstall-osm-addon].
 > Istio add-on can only be enabled on AKS clusters of version >= 1.23.
 
 ```azurecli-interactive
 az aks mesh enable --resource-group ${RESOURCE_GROUP} --name ${CLUSTER}
 ```
 
-## Verify add-on was installed successfully
+## Verify successful installation
 
 To verify the Istio add-on is installed on your cluster, run the following command:
 
@@ -135,7 +134,7 @@ kubectl label namespace default istio.io/rev=asm-1-17
 
 ## Deploy sample application
 
-Use `kubectl apply` to deploy sample application on the cluster:
+Use `kubectl apply` to deploy the sample application on the cluster:
 
 ```bash
 kubectl apply -f https://raw.githubusercontent.com/istio/istio/release-1.17/samples/bookinfo/platform/kube/bookinfo.yaml
@@ -194,8 +193,9 @@ 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.
+> Each pod has two containers, one of which 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).
 
 ## Delete resources
 
@@ -214,7 +214,13 @@ az aks mesh disable --resource-group ${RESOURCE_GROUP} --name ${CLUSTER}
 > [!CAUTION]
 > Disabling the service mesh addon will completely remove the Istio control plane from the cluster.
 
-Use `az group delete` to delete your cluster and the associated resources. For example:
+Note that Istio CRDs will not be deleted by default. To clean up CRDs, use:
+
+```azurecli-interactive
+kubectl delete crd $(kubectl get crd -A | grep "istio.io" | awk '{print $1}')
+```
+
+Use `az group delete` to delete your cluster and the associated resources:
 
 ```azurecli-interactive
 az group delete --name ${RESOURCE_GROUP} --yes --no-wait

articles/aks/istio-deploy-ingress.md

@@ -15,11 +15,11 @@ This article shows you how to deploy external or internal ingresses for Istio se
 
 ## Prerequisites
 
-This guide assumes an existing AKS cluster with the Istio add-on enabled and an application deployed. For more information on enabling the Istio add-on in your cluster and deploying a sample application, see [Deploy Istio-based service mesh add-on for AKS][istio-deploy-addon].
+This guide assumes you followed the [documentation][istio-deploy-addon] to enable the Istio add-on on an AKS cluster, deploy a sample application and set environment variables.
 
 ## Enable external ingress gateway
 
-Use `az aks mesh enable-ingress-gateway` to enable an externally accessible Istio ingress on your AKS cluster. For example:
+Use `az aks mesh enable-ingress-gateway` to enable an externally accessible Istio ingress on your AKS cluster:
 
 ```azurecli-interactive
 az aks mesh enable-ingress-gateway --resource-group $RESOURCE_GROUP --name $CLUSTER --ingress-gateway-type external
@@ -31,14 +31,14 @@ Use `kubectl get svc` to check the service mapped to the ingress gateway:
 kubectl get svc aks-istio-ingressgateway-external -n aks-istio-ingress
 ```
 
-Check external IP address of the service. For example:
+Check the external IP address of the service in the output:
 
 ```
 NAME                                TYPE           CLUSTER-IP    EXTERNAL-IP     PORT(S)                                      AGE
 aks-istio-ingressgateway-external   LoadBalancer   10.0.10.249   <EXTERNAL_IP>   15021:30705/TCP,80:32444/TCP,443:31728/TCP   4m21s
 ```
 
-Applications aren't accessible from outside the cluster after enabling the ingress gateway. To make an application accessible, map the deployment's ingress to the Istio Ingress Gate. For example, the following manifest creates this mapping for the sample application:
+Applications aren't accessible from outside the cluster by default after enabling the ingress gateway. To make an application accessible, map the sample deployment's ingress to the Istio ingress gateway using the following manifest:
 
 ```bash
 kubectl apply -f - <<EOF
@@ -112,7 +112,7 @@ curl -s "http://${GATEWAY_URL_EXTERNAL}/productpage" | grep -o "<title>.*</title
 
 ## Enable internal ingress gateway
 
-Use `az aks mesh enable-ingress-gateway` to enable an internal Istio ingress on your AKS cluster. For example:
+Use `az aks mesh enable-ingress-gateway` to enable an internal Istio ingress on your AKS cluster:
 
 ```azurecli-interactive
 az aks mesh enable-ingress-gateway --resource-group $RESOURCE_GROUP --name $CLUSTER --ingress-gateway-type internal
@@ -132,7 +132,7 @@ NAME                                TYPE           CLUSTER-IP    EXTERNAL-IP
 aks-istio-ingressgateway-internal   LoadBalancer   10.0.182.240  <IP>      15021:30764/TCP,80:32186/TCP,443:31713/TCP   87s
 ```
 
-Applications aren't mapped to the Istio Ingress Gateway after enabling the ingress gateway. The following manifest maps the deployment's ingress to the Istio Ingress Gateway. For example, the following manifest creates this mapping for the sample application:
+Applications aren't mapped to the Istio ingress gateway after enabling the ingress gateway. Use the following manifest to map the sample deployment's ingress to the Istio ingress gateway:
 
 ```bash
 kubectl apply -f - <<EOF
@@ -209,15 +209,15 @@ Use `kubectl exec` to confirm application is accessible from inside the cluster'
 kubectl exec "$(kubectl get pod -l app=ratings -o jsonpath='{.items[0].metadata.name}')" -c ratings -- curl -sS  "http://$GATEWAY_URL_INTERNAL/productpage"  | grep -o "<title>.*</title>"
 ```
 
-Confirm you see the sample application's product page is accessible. For example:
+Confirm that the sample application's product page is accessible. The expected output is:
 
 ```html
 <title>Simple Bookstore App</title>
 ```
 
 ## Delete resources
 
-If you want to clean up the Istio service mesh and the ingresses while leaving behind the cluster, run the following command:
+If you want to clean up the Istio service mesh and the ingresses (leaving behind the cluster), run the following command:
 
 ```azurecli-interactive
 az aks mesh disable --resource-group ${RESOURCE_GROUP} --name ${CLUSTER}