Merge pull request #233721 from schaffererin/aboutservicemeshesfreshnesspass

Freshness/editing passes for About services meshes and OSM AKS docs

Author: denrea

articles/aks/open-service-mesh-about.md

@@ -1,72 +1,71 @@
 ---
-title: Open Service Mesh
-description: Open Service Mesh (OSM) in Azure Kubernetes Service (AKS)
+title: Open Service Mesh in Azure Kubernetes Service (AKS)
+description: Learn about the Open Service Mesh (OSM) add-on in Azure Kubernetes Service (AKS).
 ms.topic: article
-ms.date: 12/20/2021
+ms.date: 04/06/2023
 ms.author: pgibson
 ---
 
-# Open Service Mesh AKS add-on
+# Open Service Mesh (OSM) add-on in Azure Kubernetes Service (OSM)
 
-[Open Service Mesh (OSM)](https://docs.openservicemesh.io/) is a lightweight, extensible, cloud native service mesh that allows users to uniformly manage, secure, and get out-of-the-box observability features for highly dynamic microservice environments.
+[Open Service Mesh (OSM)](https://docs.openservicemesh.io/) is a lightweight, extensible, cloud native service mesh that allows you to uniformly manage, secure, and get out-of-the-box observability features for highly dynamic microservice environments.
 
-OSM runs an Envoy-based control plane on Kubernetes and can be configured with [SMI](https://smi-spec.io/) APIs. OSM works by injecting an Envoy proxy as a sidecar container with each instance of your application. The Envoy proxy contains and executes rules around access control policies, implements routing configuration, and captures metrics. The control plane continually configures the Envoy proxies to ensure policies and routing rules are up to date and ensures proxies are healthy.
+OSM runs an Envoy-based control plane on Kubernetes and can be configured with [SMI](https://smi-spec.io/) APIs. OSM works by injecting an Envoy proxy as a sidecar container with each instance of your application. The Envoy proxy contains and executes rules around access control policies, implements routing configuration, and captures metrics. The control plane continually configures the Envoy proxies to ensure policies and routing rules are up to date and proxies are healthy.
 
-The OSM project was originated by Microsoft and has since been donated and is governed by the [Cloud Native Computing Foundation (CNCF)](https://www.cncf.io/).
+Microsoft started the OSM project, but it's now governed by the [Cloud Native Computing Foundation (CNCF)](https://www.cncf.io/).
 
-## Installation and version
+## Enable the OSM add-on
 
-OSM can be added to your Azure Kubernetes Service (AKS) cluster by enabling the OSM add-on using the [Azure CLI][osm-azure-cli] or a [Bicep template][osm-bicep]. The OSM add-on provides a fully supported installation of OSM that is integrated with AKS.
+OSM can be added to your Azure Kubernetes Service (AKS) cluster by enabling the OSM add-on using the [Azure CLI][osm-azure-cli] or a [Bicep template][osm-bicep]. The OSM add-on provides a fully supported installation of OSM that's integrated with AKS.
 
 > [!IMPORTANT]
-> Based on the version of Kubernetes your cluster is running, the OSM add-on installs a different version of OSM:
-> - If your cluster is running Kubernetes version 1.24.0 or greater, the OSM add-on installs version *1.2.3* of OSM.
-> - If your cluster is running a version of Kubernetes between 1.23.5 and 1.24.0, the OSM add-on installs version *1.1.3* of OSM.
-> - If your cluster is running a version of Kubernetes below 1.23.5, the OSM add-on installs version *1.0.0* of OSM.
+> Based on the version of Kubernetes your cluster is running, the OSM add-on installs a different version of OSM.
+>
+> |Kubernetes version         | OSM version installed |
+> |---------------------------|-----------------------|
+> | 1.24.0 or greater         | 1.2.3                 |
+> | Between 1.23.5 and 1.24.0 | 1.1.3                 |
+> | Below 1.23.5              | 1.0.0                 |
 
 ## Capabilities and features
 
 OSM provides the following capabilities and features:
 
-- Secure service to service communication by enabling mutual TLS (mTLS).
+- Secure service-to-service communication by enabling mutual TLS (mTLS).
 - Onboard applications onto the OSM mesh using automatic sidecar injection of Envoy proxy.
 - Transparently configure traffic shifting on deployments.
-- Define and execute fine grained access control policies for services.
+- Define and execute fine-grained access control policies for services.
 - Monitor and debug services using observability and insights into application metrics.
-- Integrate with external certificate management.
-- Integrates with existing ingress solutions such as [NGINX][nginx], [Contour][contour], and [Web Application Routing][web-app-routing]. For more details on how ingress works with OSM, see [Using Ingress to manage external access to services within the cluster][osm-ingress]. For an example on integrating OSM with Contour for ingress, see [Ingress with Contour][osm-contour]. For an example on integrating OSM with ingress controllers that use the `networking.k8s.io/v1` API, such as NGINX, see [Ingress with Kubernetes Nginx Ingress Controller][osm-nginx]. For more details on using Web Application Routing, which automatically integrates with OSM, see [Web Application Routing][web-app-routing].
-
-## Example scenarios
-
-OSM can be used to help your AKS deployments in many different ways. For example:
-
 - Encrypt communications between service endpoints deployed in the cluster.
 - Enable traffic authorization of both HTTP/HTTPS and TCP traffic.
 - Configure weighted traffic controls between two or more services for A/B testing or canary deployments.
 - Collect and view KPIs from application traffic.
+- Integrate with external certificate management.
+- Integrate with existing ingress solutions such as [NGINX][nginx], [Contour][contour], and [Web Application Routing][web-app-routing].
+
+For more information on ingress and OSM, see [Using ingress to manage external access to services within the cluster][osm-ingress] and [Integrate OSM with Contour for ingress][osm-contour]. For an example of how to integrate OSM with ingress controllers using the `networking.k8s.io/v1` API, see [Ingress with Kubernetes Nginx ingress controller][osm-nginx]. For more information on using Web Application Routing, which automatically integrates with OSM, see [Web Application Routing][web-app-routing].
 
-## Add-on limitations
+## Limitations
 
 The OSM AKS add-on has the following limitations:
 
-* [Iptables redirection][ip-tables-redirection] for port IP address and port range exclusion must be enabled using `kubectl patch` after installation. For more details, see [iptables redirection][ip-tables-redirection].
-* Pods that are onboarded to the mesh that need access to IMDS, Azure DNS, or the Kubernetes API server must have their IP addresses to the global list of excluded outbound IP ranges using [Global outbound IP range exclusions][global-exclusion].
-* At this time, OSM does not support Windows Server containers.
+- After installation, you must enable Iptables redirection for port IP address and port range exclusion using `kubectl patch`. For more information, see [iptables redirection][ip-tables-redirection].
+- Any pods that need access to IMDS, Azure DNS, or the Kubernetes API server must have their IP addresses added to the global list of excluded outbound IP ranges using [Global outbound IP range exclusions][global-exclusion].
+- OSM doesn't support Windows Server containers.
 
 ## Next steps
 
 After enabling the OSM add-on using the [Azure CLI][osm-azure-cli] or a [Bicep template][osm-bicep], you can:
-* [Deploy a sample application][osm-deploy-sample-app]
-* [Onboard an existing application][osm-onboard-app]
+
+- [Deploy a sample application][osm-deploy-sample-app]
+- [Onboard an existing application][osm-onboard-app]
 
 [ip-tables-redirection]: https://release-v1-2.docs.openservicemesh.io/docs/guides/traffic_management/iptables_redirection/
 [global-exclusion]: https://release-v1-2.docs.openservicemesh.io/docs/guides/traffic_management/iptables_redirection/#global-outbound-ip-range-exclusions
 [osm-azure-cli]: open-service-mesh-deploy-addon-az-cli.md
 [osm-bicep]: open-service-mesh-deploy-addon-bicep.md
 [osm-deploy-sample-app]: https://release-v1-2.docs.openservicemesh.io/docs/getting_started/install_apps/
 [osm-onboard-app]: https://release-v1-2.docs.openservicemesh.io/docs/guides/app_onboarding/
-[ip-tables-redirection]: https://docs.openservicemesh.io/docs/guides/traffic_management/iptables_redirection/
-[global-exclusion]: https://docs.openservicemesh.io/docs/guides/traffic_management/iptables_redirection/#global-outbound-ip-range-exclusions
 [nginx]: https://github.com/kubernetes/ingress-nginx
 [contour]: https://projectcontour.io/
 [osm-ingress]: https://release-v1-2.docs.openservicemesh.io/docs/guides/traffic_management/ingress/

articles/aks/servicemesh-about.md

@@ -3,60 +3,59 @@ title: About service meshes
 description: Obtain an overview of service meshes, supported scenarios, selection criteria, and next steps to explore.
 author: pgibson
 ms.topic: article
-ms.date: 01/04/2022
+ms.date: 04/06/2023
 ms.author: pgibson
 ---
 
 # About service meshes
 
-A service mesh provides capabilities like traffic management, resiliency, policy, security, strong identity, and observability to your workloads. Your application is decoupled from these operational capabilities and the service mesh moves them out of the application layer, and down to the infrastructure layer.
+A service mesh is an infrastructure layer in your application that facilitates communication between services. Service meshes provide capabilities like traffic management, resiliency, policy, security, strong identity, and observability to your workloads. Your application is decoupled from these operational capabilities, while the service mesh moves them out of the application layer and down to the infrastructure layer.
 
 ## Scenarios
 
-These are some of the scenarios that can be enabled for your workloads when you use a service mesh:
+When you use a service mesh, you can enable scenarios such as:
 
-- **Encrypt all traffic in cluster** - Enable mutual TLS between specified services in the cluster. This can be extended to ingress and egress at the network perimeter, and provides a secure by default option with no changes needed for application code and infrastructure.
+- **Encrypting all traffic in cluster**: Enable mutual TLS between specified services in the cluster. This can be extended to ingress and egress at the network perimeter and provides a secure-by-default option with no changes needed for application code and infrastructure.
 
-- **Canary and phased rollouts** - Specify conditions for a subset of traffic to be routed to a set of new services in the cluster. On successful test of canary release, remove conditional routing and phase gradually increasing % of all traffic to new service. Eventually all traffic will be directed to new service.
+- **Canary and phased rollouts**: Specify conditions for a subset of traffic to be routed to a set of new services in the cluster. On successful test of canary release, remove conditional routing and phase gradually increasing % of all traffic to a new service. Eventually, all traffic will be directed to the new service.
 
-- **Traffic management and manipulation** - Create a policy on a service that will rate limit all traffic to a version of a service from a specific origin, or a policy that applies a retry strategy to classes of failures between specified services. Mirror live traffic to new versions of services during a migration or to debug issues. Inject faults between services in a test environment to test resiliency.
+- **Traffic management and manipulation**: Create a policy on a service that rate limits all traffic to a version of a service from a specific origin, or a policy that applies a retry strategy to classes of failures between specified services. Mirror live traffic to new versions of services during a migration or to debug issues. Inject faults between services in a test environment to test resiliency.
 
-- **Observability** - Gain insight into how your services are connected and the traffic that flows between them. Obtain metrics, logs, and traces for all traffic in cluster, including ingress/egress. Add distributed tracing abilities to your applications.
+- **Observability**: Gain insight into how your services are connected and the traffic that flows between them. Gather metrics, logs, and traces for all traffic in the cluster, including ingress/egress. Add distributed tracing abilities to applications.
 
 ## Selection criteria
 
-Before you select a service mesh, ensure that you understand your requirements and the reasons for installing a service mesh. Ask the following questions:
+Before you select a service mesh, make sure you understand your requirements and reasoning for installing a service mesh. Ask the following questions:
 
-- **Is an Ingress Controller sufficient for my needs?** - Sometimes having a capability like A/B testing or traffic splitting at the ingress is sufficient to support the required scenario. Don't add complexity to your environment with no upside.
+- **Is an ingress controller sufficient for my needs?**: Sometimes having a capability like A/B testing or traffic splitting at the ingress is sufficient to support the required scenario. Don't add complexity to your environment with no upside.
 
-- **Can my workloads and environment tolerate the additional overheads?** - All the additional components required to support the service mesh require additional resources like CPU and memory. In addition, all the proxies and their associated policy checks add latency to your traffic. If you have workloads that are very sensitive to latency or cannot provide the additional resources to cover the service mesh components, then re-consider.
+- **Can my workloads and environment tolerate the additional overheads?**: All the components required to support the service mesh require resources like CPU and memory. All the proxies and their associated policy checks add latency to your traffic. If you have workloads that are very sensitive to latency or can't provide extra resources to cover service mesh components, you should reconsider using a service mesh.
 
-- **Is this adding additional complexity unnecessarily?** - If the reason for installing a service mesh is to gain a capability that is not necessarily critical to the business or operational teams, then consider whether the additional complexity of installation, maintenance, and configuration is worth it.
+- **Is this adding unnecessary complexity?**: If you want to install a service mesh to use a capability that isn't critical to the business or operational teams, then consider whether the added complexity of installation, maintenance, and configuration is worth it.
 
-- **Can this be adopted in an incremental approach?** - Some of the service meshes that provide a lot of capabilities can be adopted in a more incremental approach. Install just the components you need to ensure your success. Once you are more confident and additional capabilities are required, then explore those. Resist the urge to install *everything* from the start.
+- **Can this be adopted in an incremental approach?**: Some of the service meshes that provide a lot of capabilities can be adopted in a more incremental approach. Install just the components you need to ensure your success. If you later find that more capabilities are required, explore them at a later time. Resist the urge to install *everything* from the start.
 
 ## Next steps
 
 Open Service Mesh (OSM) is a supported service mesh that runs Azure Kubernetes Service (AKS):
 
 > [!div class="nextstepaction"]
-> [Learn more about OSM ...][osm-about]
+> [Learn more about OSM][osm-about]
 
-There are also service meshes provided by open-source projects and third parties that are commonly used with AKS. These open-source and third-party service meshes are not covered by the [AKS support policy][aks-support-policy].
+There are also service meshes provided by open-source projects and third parties that are commonly used with AKS. These service meshes aren't covered by the [AKS support policy][aks-support-policy].
 
 - [Istio][istio]
 - [Linkerd][linkerd]
 - [Consul Connect][consul]
 
 For more details on the service mesh landscape, see [Layer 5's Service Mesh Landscape][service-mesh-landscape].
 
-For more details service mesh standardization efforts:
+For more details on service mesh standardization efforts, see:
 
 - [Service Mesh Interface (SMI)][smi]
 - [Service Mesh Federation][smf]
 - [Service Mesh Performance (SMP)][smp]
 
-
 <!-- LINKS - external -->
 [istio]: https://istio.io/latest/docs/setup/install/
 [linkerd]: https://linkerd.io/getting-started/