rev 1

Author: bugbiteme

documentation/modules/ROOT/assets/images/mesh-cover-page.png

@@ -2,6 +2,8 @@
 
 **Canary Deployment with Traffic Splitting**
 
+image::canary-01.png[width=75%]
+
 **Objective**: Safely roll out a new version of a microservice while monitoring its performance.
 
 A retail company has an application running on OpenShift that handles online orders. The development team wants to deploy a new version (`v2`) of their `hello-service` RestAPI without disrupting users of the current version (`v1`).
@@ -11,7 +13,7 @@ A retail company has an application running on OpenShift that handles online ord
 
 Using OpenShift Service Mesh 3 with the Kubernetes Gateway API, they configure a traffic-splitting policy to direct 90% of traffic to `v1` and 10% to `v2`.
 
-With integrated observability tools like **Jaeger** and **Kiali**, the team monitors traffic flow, latency, and error rates in real-time for v2.
+With integrated observability tools like **Jaeger** and **Kiali**, the team monitors traffic flow, latency, and error rates in real-time for `v2`.
 
 Once performance metrics confirm stability, they incrementally increase traffic to `v2` until it handles 100% of requests, ensuring a smooth transition.
 

documentation/modules/ROOT/assets/images/mesh-diagram-01.png

@@ -26,25 +26,25 @@ Now imagine having to custom-build and manage this operational overhead for ever
 image::ossm-use-cases.png[width=100%]
 
 
-OpenShift Service Mesh addresses these challenges by providing a platform-native, unified solution that abstracts away the operational complexities of microservices architectures. It allows developers to focus solely on the business logic of their services while enabling platform teams to:
+**OpenShift Service Mesh** addresses these challenges by providing a platform-native, unified solution that abstracts away the operational complexities of microservices architectures. It allows developers to focus solely on the business logic of their services while enabling platform teams to:
 
 - **Enforce Consistent Security Policies**: Mutual TLS (mTLS) encryption and fine-grained access controls are implemented out of the box, ensuring all services adhere to a uniform security baseline.
-- **Enable Seamless Observability**: Built-in tools like Jaeger, Kiali, and Prometheus provide centralized tracing, visualization, and monitoring, giving teams actionable insights across the service mesh.
+- **Enable Seamless Observability**: Built-in platform tools like **Distributed Tracing**, **Kiali**, and **Prometheus** provide centralized tracing, visualization, and monitoring, giving teams actionable insights across the service mesh.
 - **Streamline Traffic Management**: Intelligent traffic routing, load balancing, and support for advanced deployment strategies (e.g., canary releases) simplify managing and optimizing service-to-service communication.
 - **Enhance Reliability and Resilience**: Features like automatic retries, circuit breakers, and failover mechanisms ensure high availability even under challenging network conditions.
 - **Support Kubernetes-Native Standards**: OpenShift Service Mesh 3's support for the Kubernetes Gateway API allows for modern, scalable management of ingress and egress traffic across clusters.
 
 With few or no service code changes.
 
-OpenShift Service Mesh uses a proxy container (Envoy) to manage all network traffic for your applications. This proxy allows you to enable powerful features, like traffic control, security, and monitoring, based on the settings you define.
+OpenShift Service Mesh uses a proxy container (Envoy) that is injected into a pod to intercept and manage all network traffic for your applications. This proxy allows you to enable powerful features, like traffic control, security, and monitoring, based on the settings you define in the Service Mesh control plane in a way that is decoupled from the application code.
 
 image::ossm-01.png[width=50%]
 
-The control plane takes your desired configuration, and its view of the services, and dynamically programs the proxy, updating them as the rules or the environment changes.
+The control plane takes your desired configuration, and its view of the services, and dynamically manages the proxy mesh, updating them as the rules or the environment changes.
 
 image::ossm-02.png[width=75%]
 
-The data plane is the communication between services. 
+The data plane is the communication between services within the mesh itself. 
 
 [#tech_stack]
 == Technology Stack used in this Solution Pattern
@@ -78,7 +78,7 @@ a|image::ossm-logo-04.png[width=100, height=100]
 [#in_depth]
 == An in-depth look at the solution's architecture 
 
-OpenShift Service Mesh 3, leveraging the Kubernetes Gateway API, provides a Kubernetes-native and efficient approach to canary deployments. Here’s how it addresses the challenges:
+OpenShift Service Mesh 3, leveraging the Kubernetes Gateway API, provides a Kubernetes-native and efficient approach to managing cluster ingress and canary deployments. Here’s how it addresses the challenges:
 
 image::flow-diagram-01.png[width=100%]
 
@@ -124,10 +124,11 @@ OpenShift Service Mesh 3 is built on a modular, Kubernetes-native architecture d
 *** Policy enforcement and telemetry collection.
 ** Can express capabilities like HTTP header manipulation, traffic weighting & mirroring, TCP/UDP routing
 ** May be attached to one or more Route references which serve to direct traffic for a subset of traffic to a specific service
+** Uses Istio for ingress traffic management.
 
 * **HTTPRoute** (Gateway API)
-** Enables advanced routing capabilities for Ingress.
-** Specifies routing behavior of HTTP requests from a Gateway listener to an API object, i.e. Service.
+** Enables advanced routing capabilities for service ingress.
+** Specifies routing behavior of HTTP requests from a Gateway listener to an kubernetes `Service` resource associated with a pod.
 ** Each Route includes a way to reference the parent resources it wants to attach to.
 
 * **Distributed Tracing (via Tempo)**
@@ -150,7 +151,7 @@ OpenShift Service Mesh 3 is built on a modular, Kubernetes-native architecture d
 ** Purpose: Metrics collection and visualization.
 ** Key Features:
 *** Collect and store time-series data for service mesh metrics.
-*** Provide dashboards for performance and health monitoring.
+*** Provide dashboards in the OpenShift Web console for performance and health monitoring.
 *** Utilizes `SystemMonitor` and `PodMonitor` CRDs to gather Service Mesh controle plane and namespace-level metrics
 
 * **Ingress/Egress Gateways**

documentation/modules/ROOT/assets/images/mesh-diagram-02.png

@@ -9,7 +9,7 @@ Before walking through the solution, ensure all necessary prerequisites are in p
 [#before_getting_started]
 == Prerequisites 
 
-To provision the demo, you will perform the following steps—each explained in detail in the next sections:
+To provision the demo, you will perform the following steps, each explained in detail in the next sections:
 
 * You will need an OpenShift cluster with cluster-admin privileges. This solution pattern has been tested on OpenShift 4.17.
 * Ensure you have the OpenShift CLI tool `oc` installed and the ability to run shell scripts in your local environment, such as your laptop.
@@ -192,8 +192,6 @@ metadata:
 
 The label `istio-injection: enabled` on a Namespace is critical because it enables automatic sidecar injection for all pods deployed within that namespace. This label is a core part of Istio's architecture and is essential for integrating services into the service mesh.
 
-The label istio-injection: enabled on a Namespace is critical because it enables automatic sidecar injection for all pods deployed within that namespace. This label is a core part of Istio's architecture and is essential for integrating services into the service mesh.
-
 **Why is `istio-injection: enabled` Important?**
 
 * Automatic Sidecar Injection
@@ -213,6 +211,7 @@ The label istio-injection: enabled on a Namespace is critical because it enables
 
 The output of `oc get pods -n bookinfo` shows that the Bookinfo application is running in the `bookinfo` namespace with multiple services and versions. The key observation here is that each pod has 2/2 containers running, indicating that Istio sidecar injection is enabled in this namespace.
 
+[source,bash]
 ----
 oc get pods -n bookinfo
 
@@ -254,6 +253,8 @@ image::bookinfo-03.png[width=75%]
 We can get a better view of how our services are interacting with one another when we use the Istio observability tool Kiali.
 
 To obtain the Kiali URL, you can run the following commands:
+
+[source,bash]
 ----
 export KIALI_HOST=$(oc get route kiali -n istio-system -o=jsonpath='{.spec.host}')
 echo https://${KIALI_HOST}
@@ -328,6 +329,8 @@ The Distributed Tracing option opens up a new window (Jaeger Console). Distribut
 [NOTE]
 ====
 Distributed Tracing is not covered in this Solution Pattern, but feel free to explore this console on your own. 
+
+If the Distributed Tracing page does not disply properly, ensure the URL is using `http` rather than `https`
 ====
 
 [#walkthrough_guide]
@@ -499,6 +502,7 @@ For the `Display` options, select:
 
 - `Traffic Distribution`
 - `Idle Nodes`
+- `Security`
 - `Traffic Animation` (optional, but helpful)
 
 image::rest-03.png[width=100%] 

documentation/modules/ROOT/pages/01-pattern.adoc

@@ -4,13 +4,17 @@
 :sectlinks:
 :doctype: book
 
+image::mesh-cover-page.png[width=75%] 
 Red Hat OpenShift Service Mesh adds a transparent layer on existing distributed applications without requiring any changes to the application code. The mesh introduces an easy way to create a network of deployed services that provides discovery, load balancing, service-to-service authentication, failure recovery, metrics, and monitoring. A service mesh also provides more complex operational functionality, including A/B testing, canary releases, access control, and end-to-end authentication.
 
-Microservice architectures split the work of enterprise applications into modular services, which can make scaling and maintenance easier. However, as an enterprise application built on a microservice architecture grows in size and complexity, it becomes difficult to understand and manage. Service Mesh can address those architecture problems by capturing or intercepting traffic between services and can modify, redirect, or create new requests to other services.
+Microservice architectures split the work of enterprise applications into modular services (deployed as pods in Kuberntetes), which can make scaling and maintenance easier. However, as an enterprise application built on a microservice architecture grows in size and complexity, it can potentially become difficult to understand and manage. Service Mesh can address those architecture problems by capturing or intercepting traffic between services and can modify, redirect, or create new requests to other services in a way that is independant from business logic.
 
+image::mesh-diagram-01.png[width=100%]
 
 **Included with OpenShift Container Platform Subscription**
 
+image::mesh-diagram-02.png[width=75%]
+
 A key benefit of OpenShift Service Mesh is that it, along with most of its critical dependencies (e.g., Istio, Jaeger, Kiali, Prometheus), is included and fully supported with the OpenShift Container Platform subscription. This integration ensures:
 
 - **Enterprise Support**: Comprehensive support from Red Hat for both OpenShift Service Mesh and its dependencies.
@@ -26,7 +30,7 @@ This solution brief demonstrates how OpenShift Service Mesh 3 empowers platform
 ++++
 [IMPORTANT]
 ====
-**OpenShift Service Mesh 3.0** and **Gateway API** in OpenShift are Technology Preview features only. 
+**OpenShift Service Mesh 3.0** and **Gateway API** in OpenShift are Technology Preview features only at this time. 
 
 Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process. 
 
@@ -35,7 +39,7 @@ link:https://access.redhat.com/support/offerings/techpreview[More details about
 This Solution Pattern will update as supported releases become generally available (GA).
 ====
 
-*Contributors:* link:https://github.com/bugbiteme[Leon Levy]
+*Contributors:* link:https://github.com/bugbiteme[Leon Levy] - Red Hat OpenShift Specialist Solution Architect
 
 ++++
  <br>