prereq and install procedures done. placeholder for the rest

Author: bugbiteme

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

@@ -9,17 +9,17 @@
 ** xref:02-architecture.adoc#more_tech[{module}.{counter:submodule2}. More about the technology stack]
 
 * xref:03-demo.adoc[{counter:module}. See the Solution in Action]
-** xref:03-demo.adoc#_demonstration[{module}.{counter:submodule3}. Demonstration]
-** xref:03-demo.adoc#_run_the_demonstration[{module}.{counter:submodule3}. Run this demonstration]
-*** xref:03-demo.adoc#_before_getting_started[{module}.{counter:submodule3}. Pre-requisites]
-*** xref:03-demo.adoc#_installing_the_demo[{module}.{counter:submodule3}. Installing the demo]
-*** xref:03-demo.adoc#_walkthrough_guide[{module}.{counter:submodule3}. Walkthrough guide]
+// ** xref:03-demo.adoc#_demonstration[{module}.{counter:submodule3}. Prerequisites]
+// ** xref:03-demo.adoc#_run_the_demonstration[{module}.{counter:submodule2}. Run this demonstration]
+// ** xref:03-demo.adoc#_before_getting_started[{module}.{counter:submodule2}. Pre-requisites]
+// ** xref:03-demo.adoc#_installing_the_demo[{module}.{counter:submodule2}. Installing the demo]
+// ** xref:03-demo.adoc#_walkthrough_guide[{module}.{counter:submodule2}. Walkthrough guide]
 
-* xref:04-workshop.adoc[{counter:module}. Workshop]
-** xref:04-workshop.adoc#_installing_the_workshop_environment[{module}.{counter:submodule4}. Installing the workshop environment]
-*** xref:04-workshop.adoc#_before_getting_started[{module}.{counter:submodule4}. Pre-requisites]
-*** xref:04-workshop.adoc#_installing_the_environment[{module}.{counter:submodule4}. Installing the environment]
-** xref:04-workshop.adoc#deliver_wksp[{module}.{counter:submodule4}. Delivering the workshop]
+// * xref:04-workshop.adoc[{counter:module}. Workshop]
+// ** xref:04-workshop.adoc#_installing_the_workshop_environment[{module}.{counter:submodule4}. Installing the workshop environment]
+// *** xref:04-workshop.adoc#_before_getting_started[{module}.{counter:submodule4}. Pre-requisites]
+// *** xref:04-workshop.adoc#_installing_the_environment[{module}.{counter:submodule4}. Installing the environment]
+// ** xref:04-workshop.adoc#deliver_wksp[{module}.{counter:submodule4}. Delivering the workshop]
 
 * xref:developer-resources.adoc[{counter:module}. Developer Resources]
 

documentation/modules/ROOT/nav.adoc

@@ -19,7 +19,7 @@ Now imagine having to custom-build and manage this operational overhead for ever
 - **Decreased Developer Productivity**: Engineers spend more time on operational concerns than on delivering business value, reducing overall velocity.
 - **Loss of Agility in Microservices**: The promised agility of microservices gets undermined by the fragmented, ad-hoc implementation of cross-cutting concerns.
 
-**How OpenShift Service Mesh Solves These Challenges**
+=== How OpenShift Service Mesh Solves These Challenges
 
 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:
 
@@ -46,13 +46,38 @@ OpenShift Service Mesh addresses these challenges by providing a platform-native
 ** https://kustomize.io/[Kustomize]
 ** https://gateway-api.sigs.k8s.io//[k8s Gatway API]
 
-
 [#in_depth]
-== An in-depth look at the solution's architecture
+== 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:
+
+image::flow-diagram-01.png[width=100%]
+
+=== **Traffic Splitting with Virtual Services**:
+** The team defines a Virtual Service within OpenShift Service Mesh to split traffic dynamically between `v1` and `v2` of the back-end-service. Initially, 90% of traffic is routed to `v1`, while 10% is routed to `v2`.
+** This setup ensures that most users experience the stable `v1` while `v2` is tested under real-world conditions with a small subset of traffic.
+
+=== **Real-Time Observability**:
+** Integrated tools like Distributed Tracing and Kiali enable the team to visualize request flows and monitor key performance indicators (KPIs) such as latency, error rates, and success rates for `v2` of the back-end-service.
+** The Red Hat build of OpenTelemetry provides detailed traces of user requests, helping identify performance bottlenecks or errors in `v2`.
+
+=== **Progressive Rollout**:
+** Once the team confirms that `v2` is stable, they gradually increase the traffic percentage directed to it—e.g., moving to 50/50 and eventually 100% for `v2`.
+** If issues are detected, traffic can be instantly shifted back to `v1` of the back-end-service using the Virtual Service configuration, ensuring no user impact.
+
+=== **Secure Communication with mTLS**:
+** All service-to-service communication between `v1`, `v2`, and other dependent services is encrypted by default with mutual TLS (mTLS). This ensures that sensitive customer data remains protected throughout the deployment process.
+
+=== **Platform Integration**:
+** Since OpenShift Service Mesh is included with the OpenShift Container Platform subscription, the team can leverage enterprise support and seamless integration with OpenShift Observability, minimizing operational overhead.
+
+
+[#more_tech]
+== About the Technology Stack
 
 OpenShift Service Mesh 3 is built on a modular, Kubernetes-native architecture designed to address the complexities of managing microservices communication, security, traffic management, and observability. It integrates tightly with Red Hat OpenShift, leveraging Kubernetes-native APIs and tools.
 
-**Core Components**
+=== **Core Components**
 
 * **Istio**
 ** Purpose: Core of the service mesh, responsible for service-to-service communication, traffic management, and policy enforcement.
@@ -62,6 +87,20 @@ OpenShift Service Mesh 3 is built on a modular, Kubernetes-native architecture d
 *** Resiliency features like retries, circuit breaking, and failover.
 ** Deployment: Control plane components (`istiod`, `istio-cni`) run in dedicated namespaces (`istio-system`, `istio-cni`).
 
+* **Gateway** (Gateway API)
+** ** Purpose: Handle external traffic entering the mesh and secure egress traffic leaving the mesh.
+** Describes how traffic can be translated to Services within the cluster
+** Key Features:
+*** Centralized traffic entry/exit point.
+*** 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
+
+* **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.
+** Each Route includes a way to reference the parent resources it wants to attach to.
+
 * **Distributed Tracing (via Tempo)**
 ** Purpose: Distributed tracing for monitoring and debugging service interactions.
 ** Key Features:
@@ -91,7 +130,7 @@ OpenShift Service Mesh 3 is built on a modular, Kubernetes-native architecture d
 *** Centralized traffic entry/exit point.
 *** Policy enforcement and telemetry collection.
 
-**Key Architectural Decisions**
+=== **Key Architectural Decisions**
 
 * **Kubernetes Gateway API Support**
 ** OpenShift Service Mesh 3 incorporates the Kubernetes Gateway API to modernize ingress and egress traffic management. This provides better scalability and integration compared to legacy Service Mesh (OSSM 2.x) ingress/egress configurations.

documentation/modules/ROOT/pages/02-architecture.adoc

@@ -5,30 +5,154 @@
 
 = See the Solution in Action
 
-== Demonstration
+Before walking though the solution, let's ensure all the necessary prerequisites are in place to set up the environment.
 
-Include here content related to potential existing demos: blogs, articles, recorded videos, walkthrough guides, tutorials.
+== Prerequisites
 
-[#demo-video]
-=== Watch a demonstration
+To provision the demo you will perform the following steps - each of which is explained in detail in the next sections:
 
-In this video you can see xpto:
+* You will need an OpenShift cluster with cluster-admin privileges. This solution pattern has been tested on OpenShift 4.17
 
-video::3yULVMdqJ98[youtube, width=800, height=480]
+* Ensure you have the OpenShift CLI tool `oc` installed and the ability to run shell scripts in your local environment such as your laptop
 
-Next, you can learn how to walkthrough this demo.
+=== CLI Tools
 
-== Run the demonstration
+To check if you have the cli tools, you can open your terminal and use following command:
 
-=== Before getting started
-To run this demo, you will need xpto. Adding to that, make sure to have:
+[.console-input]
+[source,shell script]
+----
+oc version #openshift cli client
+----
 
-* ABC
-* XYZ
-* XPTO
+== Setup
 
-=== Installing the demo
-Installation guide and basic test of the demo installation if needed
+In this demo, the deployment scripts uses the OpenShift CLI to:
 
-=== Walkthrough guide
+* Install the following OpenShift Operators:
+** OpenShift Service Mesh 3 (Tech Preview)
+** Kiali 
+** OpenTelemetry
+** Tempo 
+
+* Enable Gateway API (Tech Preview)
+
+* Implement an OpenShift Service Mesh solution
+** Provision and configure OpenShift Service Mesh control plane and other Istio supporting components (CRs namespaces)
+*** Istio (istiod)
+*** Istio-CNI (pod networking)
+*** Ingress-Gateway (for Gateway API and Istio Gateway)
+*** Kiali
+*** OpenShift Service Mesh Console Plugin
+** Provision and configure a `tracing-system` via a TemoStack for distributed tracing
+*** MinIO for persisent s3 storage
+*** Tempo 
+*** OpenTelemetry CRs
+**** OpenTelemetryCollector 
+**** Telemetry
+** Monitoring Configuration
+*** Enable User Monitoring with OpenShift Observability (Prometheus)
+*** Enable SystemMonitor in `istio-system` namespace
+*** Enable PodMonitor in all istio-related namespaces as well as application namespaces
+**** `istio-system`
+**** `istio-ingress`
+**** `bookinfo` 
+**** `rest-api-with-mesh`
+*** Label all istio-releated and application namespaces with `istio-injection=enabled`
+** Sample Applications for Demo and Use-cases
+*** `bookinfo` - A sample multi-service application to demonstrate OSSM observability
+*** `rest-api-with-mesh` - A simple RestAPI application that contains a front end API that calls our back-end API that we are going to deploy via Canary deployment
+
+There is also a set of scripts we will use to test and deploy our RestAPI backend from `v1` to `v2`
+
+=== Get the deployment scripts
+* Login to your OpenShift cluster as cluster-admin (because a number of operators will need to be installed) via the OpenShift web console
+* Click on the username on the top right hand, and then click on Copy login command. This will open another tab and you will need to login again
+* Click on *Display token* link, and copy the command under *Log in with this token*. This command will look like this:
+
+[source,shell script]
+----
+oc login --token=<token> --server=<server>
+----
+
+* Clone the following git repo
+
+[.console-input]
+[source,shell script]
+----
+git clone https://github.com/bugbiteme/ossm-3-demo.git
+----
+
+=== Install Operators and enable Gateway API
+
+Ensure you are in the top-level directory of the project: `./ossm-3-demo`.
+
+Run the following script to install the above listed Operators and Gateway API and wait for it to complete
+
+[.console-input]
+[source,shell script]
+----
+sh ./install_operators.sh
+----
+
+=== Install OSSM solution and example applications 
+
+Ensure you are in the top-level directory of the project: `./ossm-3-demo`.
+
+Run the following script to implement Service Mesh and the example applications and wait for it to complete:
+
+[.console-input]
+[source,shell script]
+----
+sh ./install_ossm3_demo.sh
+----
+
+Expected final output:
+[source,shell script]
+----
+====================================================================================================
+Ingress route for bookinfo is: http://istio-ingressgateway-istio-ingress.apps.<domain>/productpage
+To test RestAPI: sh ./scripts/test-api.sh
+Kiali route is: https://kiali-istio-system.apps.<domain>
+====================================================================================================
+----
+
+
+== Walkthrough guide
 How to run through the demo
+
+=== Exploring the bookinfo application
+
+==== OpenShift Web Console View
+From the OpenShift web console, when looking at the topology of the `bookinfo` namespace, we see a number of deployments. But 
+
+==== Kiali View
+We can see the traffic flow
+
+===== Overview
+
+===== Traffic Graphic
+
+===== Workloads
+
+===== Service
+
+===== Istio Config
+
+===== Mesh
+
+===== Distributed Tracing 
+
+=== Exploring the RestAPI (`rest-api-with-mesh`)
+
+==== OpenShift Web Console View
+From the OpenShift web console, when looking at the topology of the `bookinfo` namespace, we see a number of deployments. But 
+
+==== Kiali View via The OpenShift Service Mesh Console Plugin (OpenShift Web Console)
+We can see the traffic flow
+
+===== Overview
+
+===== Traffic Graphic
+
+=== Performing a Canary Deployment (`rest-api-with-mesh`)