Merge pull request #266777 from nshankar13/nshankar/update-asm-docs

Fix typos in Istio docs and add ingress/upgrade guidance

Author: AnnaMHuff

articles/aks/istio-deploy-ingress.md

@@ -13,6 +13,9 @@ ms.author: shasb
 
 This article shows you how to deploy external or internal ingresses for Istio service mesh add-on for Azure Kubernetes Service (AKS) cluster.
 
+> [!NOTE]
+> When performing a [minor revision upgrade](./istio-upgrade.md#minor-revision-upgrades-with-the-ingress-gateway) of the Istio add-on, another deployment for the external / internal gateways will be created for the new control plane revision.
+
 ## Prerequisites
 
 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.

articles/aks/istio-meshconfig.md

@@ -67,7 +67,7 @@ This guide assumes you followed the [documentation][istio-deploy-addon] to enabl
 
 ### Mesh configuration and upgrades
 
-When you're performing [canary upgrade for Istio](./istio-upgrade.md), you need create a separate ConfigMap for the new revision in the `aks-istio-system` namespace **before initiating the canary upgrade**. This way the configuration is available when the new revision's control plane is deployed on cluster. For example, if you're upgrading the mesh from asm-1-18 to asm-1-19, you need to copy changes over from `istio-shared-configmap-asm-1-18` to create a new ConfigMap called `istio-shared-configmap-asm-1-19` in the `aks-istio-system` namespace.
+When you're performing [canary upgrade for Istio](./istio-upgrade.md), you need to create a separate ConfigMap for the new revision in the `aks-istio-system` namespace **before initiating the canary upgrade**. This way the configuration is available when the new revision's control plane is deployed on cluster. For example, if you're upgrading the mesh from asm-1-18 to asm-1-19, you need to copy changes over from `istio-shared-configmap-asm-1-18` to create a new ConfigMap called `istio-shared-configmap-asm-1-19` in the `aks-istio-system` namespace.
 
 After the upgrade is completed or rolled back, you can delete the ConfigMap of the revision that was removed from the cluster.
 
@@ -83,39 +83,39 @@ Mesh configuration and the list of allowed/supported fields are revision specifi
 
 ### MeshConfig
 
-| **Field** | **Supported** |
-|-----------|---------------|
-| proxyListenPort | false |
-| proxyInboundListenPort | false |
-| proxyHttpPort | false |
-| connectTimeout | false |
-| tcpKeepAlive | false |
-| defaultConfig | true |
-| outboundTrafficPolicy | true |
-| extensionProviders | true |
-| defaultProvideres | true |
-| accessLogFile | true |
-| accessLogFormat | true |
-| accessLogEncoding | true |
-| enableTracing | true |
-| enableEnvoyAccessLogService | true |
-| disableEnvoyListenerLog | true |
-| trustDomain | false |
-| trustDomainAliases | false |
-| caCertificates | false |
-| defaultServiceExportTo | false |
-| defaultVirtualServiceExportTo | false |
-| defaultDestinationRuleExportTo | false |
-| localityLbSetting | false |
-| dnsRefreshRate | false |
-| h2UpgradePolicy | false |
-| enablePrometheusMerge | true |
-| discoverySelectors | true |
-| pathNormalization | false |
-| defaultHttpRetryPolicy | false |
-| serviceSettings | false |
-| meshMTLS | false |
-| tlsDefaults | false |
+| **Field** | **Supported** | **Notes** |
+|-----------|---------------|-----------|
+| proxyListenPort | false | - |
+| proxyInboundListenPort | false | - |
+| proxyHttpPort | false | - |
+| connectTimeout | false | Configurable in [DestinationRule](https://istio.io/latest/docs/reference/config/networking/destination-rule/#ConnectionPoolSettings-TCPSettings) |
+| tcpKeepAlive | false | Configurable in [DestinationRule](https://istio.io/latest/docs/reference/config/networking/destination-rule/#ConnectionPoolSettings-TCPSettings) |
+| defaultConfig | true | Used to configure [ProxyConfig](https://istio.io/latest/docs/reference/config/istio.mesh.v1alpha1/#ProxyConfig) |
+| outboundTrafficPolicy | true | Also configurable in [Sidecar CR](https://istio.io/latest/docs/reference/config/networking/sidecar/#OutboundTrafficPolicy) |
+| extensionProviders | false | - |
+| defaultProviders | false | - |
+| accessLogFile | true | - |
+| accessLogFormat | true | - |
+| accessLogEncoding | true | - |
+| enableTracing | true | - |
+| enableEnvoyAccessLogService | true | - |
+| disableEnvoyListenerLog | true | - |
+| trustDomain | false | - |
+| trustDomainAliases | false | - |
+| caCertificates | false | Configurable in [DestinationRule](https://istio.io/latest/docs/reference/config/networking/destination-rule/#ClientTLSSettings) |
+| defaultServiceExportTo | false | Configurable in [ServiceEntry](https://istio.io/latest/docs/reference/config/networking/service-entry/#ServiceEntry) |
+| defaultVirtualServiceExportTo | false | Configurable in [VirtualService](https://istio.io/latest/docs/reference/config/networking/virtual-service/#VirtualService) |
+| defaultDestinationRuleExportTo | false | Configurable in [DestinationRule](https://istio.io/latest/docs/reference/config/networking/destination-rule/#DestinationRule) |
+| localityLbSetting | false | Configurable in [DestinationRule](https://istio.io/latest/docs/reference/config/networking/destination-rule/#LoadBalancerSettings) |
+| dnsRefreshRate | false | - |
+| h2UpgradePolicy | false | Configurable in [DestinationRule](https://istio.io/latest/docs/reference/config/networking/destination-rule/#ConnectionPoolSettings-HTTPSettings) |
+| enablePrometheusMerge | true | - |
+| discoverySelectors | true | - |
+| pathNormalization | false | - |
+| defaultHttpRetryPolicy | false | Configurable in [VirtualService](https://istio.io/latest/docs/reference/config/networking/virtual-service/#HTTPRetry) |
+| serviceSettings | false | - |
+| meshMTLS | false | - |
+| tlsDefaults | false | - |
 
 ### ProxyConfig (meshConfig.defaultConfig)
 
@@ -158,4 +158,4 @@ Fields present in [open source MeshConfig reference documentation][istio-meshcon
 
 [istio-meshconfig]: https://istio.io/latest/docs/reference/config/istio.mesh.v1alpha1/
 [istio-sidecar-race-condition]: https://istio.io/latest/docs/ops/common-problems/injection/#pod-or-containers-start-with-network-issues-if-istio-proxy-is-not-ready
-
+[istio-deploy-addon]: istio-deploy-addon.md

articles/aks/istio-plugin-ca.md

@@ -55,6 +55,9 @@ The add-on requires Azure CLI version 2.57.0 or later installed. You can run `az
     az keyvault set-policy --name $AKV_NAME --object-id $OBJECT_ID --secret-permissions get list
     ```
 
+    > [!NOTE]
+    > If you created your Key Vault with Azure RBAC Authorization for your permission model instead of Vault Access Policy, follow the instructions [here][akv-rbac-guide] to create permissions for the managed identity. Add an Azure role assignment for `Key Vault Reader` for the add-on's user-assigned managed identity. 
+
 ## Set up Istio-based service mesh addon with plug-in CA certificates
 
 1. Enable the Istio service mesh addon for your existing AKS cluster while referencing the Azure Key Vault secrets that were created earlier:
@@ -250,6 +253,7 @@ You may need to periodically rotate the certificate authorities for security or
 
 [akv-quickstart]: ../key-vault/general/quick-create-cli.md
 [akv-addon]: ./csi-secrets-store-driver.md
+[akv-rbac-guide]: ../key-vault/general/rbac-guide.md
 [install-azure-cli]: /cli/azure/install-azure-cli
 [az-feature-register]: /cli/azure/feature#az-feature-register
 [az-feature-show]: /cli/azure/feature#az-feature-show

articles/aks/istio-upgrade.md

@@ -11,11 +11,13 @@ author: shashankbarsin
 
 This article addresses upgrade experiences for Istio-based service mesh add-on for Azure Kubernetes Service (AKS).
 
-## Minor version upgrade
+Announcements about the releases of new minor revisions or patches to the Istio-based service mesh add-on are published in the [AKS release notes][aks-release-notes].
 
-Istio add-on allows upgrading the minor version using [canary upgrade process][istio-canary-upstream]. When an upgrade is initiated, the control plane of the new (canary) revision is deployed alongside the old (stable) revision's control plane. You can then manually roll over data plane workloads while using monitoring tools to track the health of workloads during this process. If you don't observe any issues with the health of your workloads, you can complete the upgrade so that only the new revision remains on the cluster. Else, you can roll back to the previous revision of Istio.
+## Minor revision upgrade
 
-If the cluster is currently using a supported minor version of Istio, upgrades are only allowed one minor version at a time. If the cluster is using an unsupported version of Istio, you must upgrade to the lowest supported minor version of Istio for that Kubernetes version. After that, upgrades can again be done one minor version at a time.
+Istio add-on allows upgrading the minor revision using [canary upgrade process][istio-canary-upstream]. When an upgrade is initiated, the control plane of the new (canary) revision is deployed alongside the old (stable) revision's control plane. You can then manually roll over data plane workloads while using monitoring tools to track the health of workloads during this process. If you don't observe any issues with the health of your workloads, you can complete the upgrade so that only the new revision remains on the cluster. Else, you can roll back to the previous revision of Istio.
+
+If the cluster is currently using a supported minor revision of Istio, upgrades are only allowed one minor revision at a time. If the cluster is using an unsupported revision of Istio, you must upgrade to the lowest supported minor revision of Istio for that Kubernetes version. After that, upgrades can again be done one minor revision at a time.
 
 The following example illustrates how to upgrade from revision `asm-1-18` to `asm-1-19`. The steps are the same for all minor upgrades.
 
@@ -124,6 +126,12 @@ The following example illustrates how to upgrade from revision `asm-1-18` to `as
 > [!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.
 
+### Minor revision upgrades with the ingress gateway
+
+If you're currently using [Istio ingress gateways](./istio-deploy-ingress.md) and are performing a minor revision upgrade, keep in mind that Istio ingress gateway pods / deployments are deployed per-revision. However, we provide a single LoadBalancer service across all ingress gateway pods over multiple revisions, so the external/internal IP address of the ingress gateways will not change throughout the course of an upgrade. 
+
+Thus, during the canary upgrade, when two revisions exist simultaneously on the cluster, incoming traffic will be served by the ingress gateway pods of both revisions. 
+
 ## Patch version upgrade
 
 * Istio add-on patch version availability information is published in [AKS release notes][aks-release-notes].