OSSM 3.0 TP1 OSSM-8153 [DOC] OSSM 3.x Concepts

_topic_maps/_topic_map.yml

@@ -12,6 +12,8 @@ Distros: openshift-service-mesh
 Topics:
 - Name: About OpenShift Service Mesh
   File: ossm-about-openshift-service-mesh
+- Name: Understanding Service Mesh
+  File: ossm-about-concepts-assembly
 ---
 Name: Installing
 Dir: install

about/ossm-about-concepts-assembly.adoc

@@ -0,0 +1,46 @@
+:_content-type: ASSEMBLY
+[id=ossm-understanding-service-mesh-assembly_{context}]
+= Understanding OpenShift Service Mesh
+include::_attributes/common-attributes.adoc[]
+:context: ossm-about-concepts-assembly
+
+//Conceptual information that is needed for users moving from 2.x to 3, and for new users to understand and orient themselves OSSM 3.x.
+//Customers who are using 3.O TP1 have expressed a need for this content.
+//Did not like calling it "Service Mesh Concepts", though not sold on "Understanding Service Mesh" but like it better than "Service Mesh concepts".
+//TP1 content so likely all info architecture, content, etc will change by GA
+//Kiali attributes are influx
+
+toc::[]
+
+{SMProductName} is composed of two parts:
+
+* {SMProductName} resources
+* Kiali provided by Red Hat
+
+Kali provided by Red Hat is composed of three parts:
+
+* {KialiProduct}
+* Kiali Server
+* {SMPlugin}
+
+{SMProduct} integrates with the following:
+
+* Observability components such as:
+** OpenShift Monitoring
+** {DTProductname}
+** {OTELOperator}
+* cert-manager
+* Argo rollouts
+// * Integration of {SMProduct} with 3rd party components that support community Istio integrations --> commented out as none are currently documented in prod docs that are not supported by Red Hat, but support may change for GA so leaving as place holder.
+
+include::modules/ossm-about-concepts-resources.adoc[leveloffset=+1]
+
+include::modules/ossm-about-concepts-kiali.adoc[leveloffset=+1]
+
+include::modules/ossm-about-concepts-observability.adoc[leveloffset=+1]
+
+include::modules/ossm-about-concepts-cert-manager.adoc[leveloffset=+1]
+
+include::modules/ossm-about-concepts-argo-rollouts.adoc[leveloffset=+1]
+
+//The order of modules is likely to change. Info architecture is a WIP so everything may change by GA.

modules/ossm-about-concepts-argo-rollouts.adoc

@@ -0,0 +1,26 @@
+// Module included in the following assemblies:
+// about/ossm-about-concepts-assembly.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="ossm-about-concepts-argo-rollouts_{context}"]
+= {SMProductName} and Argo Rollouts
+
+{SMProductName}, when used with Argo Rollouts, provides more advanced routing capabilities by using Istio, and does not require the configuration of a sidecar container.
+
+You can use {SMProduct} to split traffic between two application versions.
+
+* *Canary version*: A new version of an application where you gradually route the traffic.
+* *Stable version*: The current version of an application. After the canary version is stable and has all the user traffic directed to it, it becomes the new stable version. The previous stable version is discarded.
+
+The Istio-support within Argo Rollouts uses the `Gateway` and `VirtualService` resources to handle traffic routing.
+
+* *Gateway*: You can use a Gateway to manage inbound and outbound traffic for your mesh. The gateway is the entry point of {SMProduct} and handles traffic requests sent to an application.
+
+* *VirtualService*: `VirtualService` defines traffic routing rules and the percentage of traffic that goes to underlying services, such as the stable and canary services.
+
+[role="_additional-resources"]
+[id="ossm-concepts-additional-resources_{context}"]
+== Additional resources
+* link:https://docs.openshift.com/gitops/1.14/argo_rollouts/routing-traffic-by-using-argo-rollouts-for-openshift-service-mesh.html[Routing traffic by using Argo Rollouts for {SMProductName}]
+
+//TP1 content. IA influx, likely everything will change for GA.

modules/ossm-about-concepts-cert-manager.adoc

@@ -0,0 +1,14 @@
+// Module included in the following assemblies:
+// about/ossm-about-concepts-assembly.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="ossm-about-concepts-cert-manager_{context}"]
+= {SMProductName} and cert-manager
+
+The cert-manager tool is a solution for X.509 certificate management on Kubernetes. It delivers a unified API to integrate applications with private or public key infrastructure (PKI), such as Vault, Google Cloud Certificate Authority Service, Let's Encrypt, and other providers.
+
+The cert-manager tool ensures that the certificates are valid and up-to-date by attempting to renew the certificates at a configured time before they expire.
+
+For Istio users, cert-manager also provides integration with `istio-csr`, which is a certificate authority (CA) server that handles certificate signing requests (CSR) from Istio proxies. The server then delegates signing to cert-manager, which forwards CSRs to the configured CA server.
+
+//TP1 content. IA influx, likely everything will change for GA.

modules/ossm-about-concepts-kiali.adoc

@@ -0,0 +1,71 @@
+// Module included in the following assemblies:
+// about/ossm-about-concepts-assembly.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="ossm-about-concepts-kiali_{context}"]
+= {SMProductName} and Kiali
+
+//Kiali attributes are in the works, and possible {KialiProduct} will refer to Kiali provided by Red Hat, and not Kiali Operator provided by Red Hat.
+//Kiali attributes are outside the scope of this PR.
+//TP1 content. IA influx, likely everything will change for GA.
+
+Kiali is based on the open source Kiali project. See link:https://kiali.io/[Kiali project]. Kiali provided by Red{nbsp}Hat is composed of three parts:
+
+* {KialiProduct}
+* Kiali Server
+* {SMPlugin}
+
+Working together, they form the user interface (UI) for {SMProduct}. Kiali provides visibility into your service mesh by showing you the microservices and how they are connected.
+
+Kiali helps you define, validate, and observe your Istio service mesh. It helps you to understand the structure of your service mesh by inferring the topology, and also provides information about the health of your service mesh.
+
+Kiali provides an interactive graph view of your mesh namespaces in near real time that provides visibility into features like circuit breakers, request rates, latency, and even graphs of traffic flows. Kiali offers insights about components at different levels, such as applications, services, workloads, and can display the interactions with contextual information and charts on the selected graph node or edge.
+
+Kiali also provides the ability to validate your Istio configurations, such as gateways, destination rules, virtual services, mesh policies, and so on. Kiali provides detailed metrics, and a basic Grafana integration is available for advanced queries. Distributed tracing is provided by integrating {TempoName} and {OTELName} into the Kiali console.
+
+[id="kiali-architecture_{context}"]
+== Kiali architecture
+
+Kiali Server (back end):: This component runs in the container application platform and communicates with the service mesh components, retrieves and processes data, and exposes this data to the console. The Kiali Server does not need storage. When deploying the Server to a cluster, configurations are set in config maps and secrets.
+
+Kiali console (front end):: The Kiali console is a web application. The console queries the Kiali Server for data to present it to the user.
+
+In addition, Kiali depends on external services and components provided by the container application platform and Istio.
+
+Red Hat Service Mesh (Istio):: Istio is a Kiali requirement. Istio is the component that provides and controls the service mesh. Although Kiali and Istio can be installed separately, Kiali depends on Istio and will not work if it is not present. Kiali needs to retrieve Istio data and configurations, which are exposed through Prometheus and the {product-title} cluster API.
+
+Prometheus:: A dedicated Prometheus instance is optional. When Istio telemetry is enabled, metrics data are stored in Prometheus. Kiali uses this Prometheus data to determine the mesh topology, display metrics, calculate health, show possible problems, and so on. Kiali communicates directly with Prometheus and assumes the data schema used by Istio Telemetry. Prometheus is an Istio dependency and a hard dependency for Kiali, and many of Kiali's features will not work without Prometheus.
+
+{ocp-product-title} API:: Kiali uses the {ocp-product-title} API to fetch and resolve service mesh configurations. For example, Kiali queries the cluster API to retrieve definitions for namespaces, services, deployments, pods, and other entities. Kiali also makes queries to resolve relationships between the different cluster entities. The cluster API is also queried to retrieve Istio configurations like virtual services, destination rules, route rules, gateways, quotas, and so on.
+
+Tracing:: Tracing is optional, but when you install {DTProductName} and Kiali is configured, the Kiali console includes a tab to display distributed tracing data, and tracing integration on the graph itself. Note that tracing data will not be available if you disable Istio’s distributed tracing feature. Also note that the user must have access to the namespace where the user needs to see tracing data.
+
+Grafana:: Grafana is optional. When available, the metrics pages of Kiali display links to direct the user to the same metric in Grafana. Note that Grafana is not supported as part of {ocp-product-title} or {SMProduct}.
+
+[id="kiali-features_{context}"]
+== Kiali features
+
+The Kiali console is integrated with {SMProduct} and provides the following capabilities:
+
+Health:: Quickly identify issues with applications, services, or workloads.
+
+Topology:: Visualize how your applications, services, or workloads communicate through the Kiali graph.
+
+Metrics::  Predefined metrics dashboards let you chart service mesh and application performance for Go, Node.js. Quarkus, Spring Boot, Thorntail and Vert.x. You can also create your own custom dashboards.
+
+Tracing:: Integration with {TempoName} lets you follow the path of a request through various microservices that make up an application.
+
+Validations:: Perform advanced validations on the most common Istio objects (Destination Rules, Service Entries, Virtual Services, and so on).
+
+Configuration:: Optional ability to create, update, and delete Istio routing configuration using wizards or directly in the YAML editor in the Kiali Console.
+
+[id="openshift-service-mesh-console-plugin_{context}"]
+== {SMPlugin}
+
+The {SMPlugin} is an {ocp-product-title} plugin for {SMProductName}. It integrates much of the {KialiProduct} interface into the OpenShift Console, injecting both a *Service Mesh* main menu option with dedicated screens, as well as integrating *Service Mesh* tabs throughout console.
+
+The {SMPluginShort} is installed using {KialiProduct}, and requires the Kiali Server component. {SMPluginShort} has its own Custom Resource (CR) configuration.
+
+//[role=_additional-resources]
+//== Additional resources
+//Return here to add xref to OSSMC plugin content when that content has been published.

modules/ossm-about-concepts-observability.adoc

@@ -0,0 +1,29 @@
+// Module included in the following assemblies:
+// about/ossm-about-concepts-assembly.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="ossm-about-concepts-observability_{context}"]
+= {SMProductName} and Observability
+
+{SMProductName} integrates with Red Hat Observability components, including:
+
+OpenShift Monitoring:: Monitoring stack components are deployed by default in every {ocp-product-title} installation and are managed by the Cluster Monitoring Operator (CMO). These components include Prometheus, Alertmanager, Thanos Querier, and so on. The CMO also deploys the Telemeter Client, which sends a subset of data from platform Prometheus instances to Red{nbsp}Hat to facilitate Remote Health Monitoring for clusters.
++
+When you have added your application to the mesh, you can monitor the in-cluster health and performance of your applications running on {ocp-product-title} with metrics and customized alerts for CPU and memory usage, network connectivity, and other resource usage.
+
+{DTProductName}:: {SMProductName} uses {DTProductName} to allow developers to view call flows in a microservice application.
++
+Integrating {DTProductName} with {SMProductName} is made of up two parts: {TempoName} and {OTELName}.
++
+{TempoName}:: Provides distributed tracing to monitor and troubleshoot transactions in complex distributed systems. It is based on the open source link:https://grafana.com/oss/tempo/[Grafana Tempo] project.
++
+For more information about {temposhortname}, its features, installation, and configuration, see: link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.16/html/distributed_tracing/distributed-tracing-platform-tempo[{TempoName}].
++
+{OTELName}:: Is based on the open source OpenTelemetry project, which aims to provide unified, standardized, and vendor-neutral telemetry data collection for cloud-native software. {OTELName} product provides support for deploying and managing the OpenTelemetry Collector and simplifying the workload instrumentation. See link:https://opentelemetry.io/[OpenTelemetry project]
++
+The OpenTelemetry Collector can receive, process, and forward telemetry data in multiple formats, making it the ideal component for telemetry processing and interoperability between telemetry systems. The Collector provides a unified solution for collecting and processing metrics, traces, and logs. See link:https://opentelemetry.io/docs/collector/[OpenTelemetry Collector].
++
+For more information about {OTELShortName}, its features, installation, and configuration, see: link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.16/html/red_hat_build_of_opentelemetry/index[{OTELName}].
+
+// If there is an attribute for Cluster Monitoring Operator, and OpenShift Monitoring, they are not part of the common-attributes file for service-mesh-docs-main as of 10/22/2024. If it is added before Aug 30, 2024, this will be updated accordingly. Due to time constraints, it may be a post-TP1/in-time-for GA update.
+//TP1 content. IA influx, likely everything will change for GA.

modules/ossm-about-concepts-resources.adoc

@@ -0,0 +1,113 @@
+// Module included in the following assemblies:
+// about/ossm-about-concepts-assembly.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="ossm-about-concepts-resources_{context}"]
+= {SMProductName} resources
+
+{SMProductName} Operator manages the lifecycle of your Istio control planes. Instead of creating a new configuration schema, {SMProduct} Operator APIs are built around Istio's Helm chart APIs.
+
+//All installation and configuration options that are exposed by Istio's Helm charts are available through the {SMProduct} Operator Custom Resource Definition (CRD) `values` fields.
+
+[NOTE]
+====
+* Though {SMProductName} APIs are built around Istio's Helm chart APIs, Helm charts are not supported.
+* All installation and configuration options that are exposed by Istio's Helm charts are available through the {SMProductName} Custom Resource Definition (CRD) `values` fields.
+====
+
+[id="istio-resource_{context}"]
+== Istio resource
+
+The `Istio` resource is used to manage your Istio control planes. It is a cluster-wide resource, because the Istio control plane operates in and requires access to the entire cluster.
+
+To select a namespace to run the control plane pods in, you can use the `spec.namespace` field.
+
+[NOTE]
+====
+The `spec.namespace` field is immutable: in order to move a control plane to another namespace, you must remove the `Istio` resource and recreate it with a different `spec.namespace`.
+====
+
+You can access all `Istio` custom resource definition (CRD) options through `spec.values` fields:
+
+.Example `Istio` resource CRD
+[source,yaml]
+----
+apiVersion: sailoperator.io/v1alpha1
+kind: Istio
+metadata:
+  name: default
+spec:
+  version: v1.22.3
+  namespace: istio-system
+  updateStrategy:
+    type: InPlace
+  values:
+    pilot:
+      resources:
+        requests:
+          cpu: 100m
+          memory: 1024Mi
+----
+
+You can run the following command to see all the customization options:
+
+[source, terminal]
+----
+$ oc explain istios.spec.values
+----
+//Helm charts can only be used with istio-csr and Helm charts are a temporary work around for istio-csr. This might get confusing for users, so a NOTE was added.
+
+To support canary updates of the control plane, {SMProduct} includes support for multiple Istio versions. You can select a version by setting  `spec.version` to the version you would like to install, prefixed with a `v`. You can update to a new version just by changing this field.
+
+{SMProduct} supports two different update strategies for your control planes:
+
+`InPlace`:: The {SMProduct} Operator immediately replaces your existing control plane resources with the ones for the new version.
+
+`RevisionBased`:: Uses Istio's canary update mechanism by creating a second control plane to which you can migrate your workloads to complete the update.
+
+After creating an Istio resource, {SMProduct} generates a revision name for the resource based on the `updateStrategy`, and creates a corresponding `IstioRevision`.
+
+[id="istiorevision-resource_{context}"]
+== IstioRevision resource
+
+The `IstioRevision` is a cluster-wide resource and the lowest-level API {SMProduct} provides. It is usually not created by the user, but by the Operator itself. Its schema closely resembles that of the `Istio` resource - but instead of representing the state of a control plane you want to be present in your cluster, it represents a revision of that control plane.
+
+A revision of the control plane you want to be present in your cluster is an instance of Istio with a specific version and revision name, and its revision name can be used to add workloads or entire namespaces to the mesh. For example: by using the `istio.io/rev=<REVISION_NAME>` label.
+
+You can think of the relationship between the `Istio` and `IstioRevision` resources as similar to the relationship between Kubernetes' replica set and pod: a replica set can be created by users and results in the automatic creation of pods, which will trigger the instantiation of your containers.
+
+Similarly, users create an `Istio` resource which instructs the {SMProduct} Operator to create a matching `IstioRevision` resource, which then in turn triggers the creation of the Istio control plane. To do that, the {SMProduct} Operator will copy all of your relevant configuration from the `Istio` resource to the `IstioRevision` resource.
+
+[id="istiocni-resource_{context}"]
+== IstioCNI resource
+
+The lifecycle of Istio's Container Network Interface (CNI) plugin is managed separately when using {SMProduct} Operator. To install Istio's CNI plugin, you create an `IstioCNI` resource.
+
+The `IstioCNI` resource is a cluster-wide resource as it installs a daemon set that operates on all nodes of your cluster. You can select a version by setting the `spec.version` field, as you can see in the example that follows. To update the CNI plugin, change the version field to the version you want to install. Like the `Istio` resource, it also has a `values` field that exposes all of the options provided in the `istio-cni` chart:
+
+.Example `IstioCNI` resource
+[source,yaml]
+----
+apiVersion: sailoperator.io/v1alpha1
+kind: IstioCNI
+metadata:
+  name: default
+spec:
+  version: v1.22.3
+  namespace: istio-cni
+  values:
+    cni:
+      cniConfDir: /etc/cni/net.d
+      excludeNamespaces:
+      - kube-system
+----
+
+//[role=_additional-resources]
+//== Additional resources
+//builds keep failing due to xrefs so removed until this gets merged. May return to this prior to OSSM 3.x GA.
+
+//== Kiali --> own module
+//== Tracing --> own module
+//== Metrics --> own module
+//== cert-manager --> own module
+//== Argo rollouts -- own module