OSSM-6063 [DOC] OpenShift Service Mesh Console (OSSMC) plugin Integration

_attributes/common-attributes.adoc

@@ -28,7 +28,9 @@
 :KialiServer: Kiali Server
 //Kiali Console
 :SMPlugin: OpenShift Service Mesh Console (OSSMC) plugin
+:sm-plugin-full: OpenShift Service Mesh Console plugin
 :SMPluginShort: OSSMC plugin
+:ossmc-full: OpenShift Service Mesh Console
 //cert-manager
 :cert-manager-operator: cert-manager Operator for Red{nbsp}Hat OpenShift
 //observability
@@ -105,3 +107,6 @@
 :JaegerName: Red{nbsp}Hat OpenShift distributed tracing platform (Jaeger)
 :JaegerShortName: distributed tracing platform (Jaeger)
 :JaegerVersion: 1.47.0
+//CLI
+:oc-first: pass:quotes[OpenShift CLI (`oc`)]
+

_topic_maps/_topic_map.yml

@@ -113,6 +113,8 @@ Topics:
   Topics:
   - Name: Using Kiali Operator provided by Red Hat
     File: ossm-kiali-assembly
+  - Name: Using OpenShift Service Mesh Console plugin
+    File: ossm-console-plugin
 ---
 Name: Uninstalling
 Dir: uninstalling

modules/ossm-about-console-plugin.adoc

@@ -0,0 +1,42 @@
+// Module included in the following assemblies:
+//
+// * service-mesh-docs-main/observability/kiali/ossm-console-plugin.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="ossm-about-console-plugin_{context}"]
+= About {sm-plugin-full}
+
+The {SMPlugin} is an extension to {ocp-product-title} web console that provides visibility into your {SMProductShortName}.
+
+[WARNING]
+====
+The {SMPluginShort} supports only one Kiali instance, regardless of its project access scope.
+====
+
+The {SMPluginShort} provides a new category, *{SMProductShortName}*, in the main {ocp-product-title} web console navigation with the following menu options:
+
+Overview:: Provides a summary of your mesh, displayed as cards that represent the namespaces in the mesh.
+
+Traffic Graph:: Provides a full topology view of your mesh, represented by nodes and edges. Each node represents a component of the mesh and each edge represents traffic flowing through the mesh between components.
+
+{istio} config:: Provides a list of all {istio} configuration files in your mesh, with a column that provides a quick way to know if the configuration for each resource is valid.
+
+Mesh:: Provides detailed information about the {istio} infrastructure status. It shows an infrastructure topology view with core and add-on components, their health, and how they are connected to each other.
+
+In the web console *Workloads* details page, the {SMPluginShort} adds a *{SMProductShortName}* tab that has the following subtabs:
+
+Overview:: Shows a summary of the selected workload, including a localized topology graph showing the workload with all inbound and outbound edges and nodes.
+
+Traffic:: Shows information about all inbound and outbound traffic to the workload.
+
+Logs:: Shows the logs for the workload's containers. You can see container logs individually ordered by log time and how the Envoy sidecar proxy logs relate to your workload's application logs. You can enable the tracing span integration, which allows you to see which logs correspond to trace spans.
+
+Metrics:: Shows inbound and outbound metric graphs in the corresponding subtabs. All the workload metrics are here, providing a detailed view of the performance of your workload. You can enable the tracing span integration, which allows you to see which spans occurred at the same time as the metrics. With the span marker in the graph, you can see the specific spans associated with that timeframe.
+
+Traces:: Provides a chart showing the trace spans collected over the given timeframe. The trace spans show the most low-level detail within your workload application. The trace details further show heatmaps that provide a comparison of one span in relation to other requests and spans in the same timeframe.
+
+Envoy:: Shows information about the Envoy sidecar configuration.
+
+In the web console *Networking* details page, the {SMPluginShort} adds a *{SMProductShortName}* tab similar to the *Workloads* details page.
+
+In the web console *Projects* details page, the {SMPluginShort} adds a *{SMProductShortName}* tab that provides traffic graph information about that project. It is the same information shown in the *Traffic Graph* page but specific to that project.

modules/ossm-install-console-plugin-ocp-cli.adoc

@@ -0,0 +1,66 @@
+// Module included in the following assemblies:
+//
+// * service-mesh-docs-main/observability/kiali/ossm-console-plugin.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="ossm-install-console-plugin-ocp-cli_{context}"]
+= Installing {SMPluginShort} by using the CLI
+
+You can install the {SMPlugin} by using the {ocp-short-name} CLI.
+
+.Prerequisites
+
+* You have access to the {oc-first} on the cluster as an administrator.
+* You have installed the {SMProduct} (OSSM).
+* You have installed the `{istio}` control plane from OSSM 3.0.
+* You have installed the {KialiServer} 2.4.
+
+.Procedure
+
+. Create a `OSSMConsole` custom resource (CR) to install the plugin by running the following command:
++
+[source,yaml,subs="attributes,verbatim"]
+----
+$ cat <<EOM | oc apply -f -
+apiVersion: kiali.io/v1alpha1
+kind: OSSMConsole
+metadata:
+  namespace: openshift-operators
+  name: ossmconsole
+spec:
+  version: default
+EOM
+----
++
+[NOTE]
+====
+The {ossmc-full} (OSSMC) version must match with the {KialiServer} version. If `spec.version` field value is the string `default` or is not specified, the Kiali Operator installs OSSMC with the same version as the operator. The `spec.version` field requires the `v` prefix in the version number. The version number must only include the major and minor version numbers (not the patch number); for example: `v1.73`.
+====
++
+The plugin resources deploy in the same namespace as the `OSSMConsole` CR.
+
+. Optional: If more than one {KialiServer} is installed in the cluster, specify the `spec.kiali` setting in the OSSMC CR by running a command similar to the following example:
++
+[source,yaml,subs="attributes,verbatim"]
+----
+$ cat <<EOM | oc apply -f -
+apiVersion: kiali.io/v1alpha1
+kind: OSSMConsole
+metadata:
+  namespace: openshift-operators
+  name: ossmconsole
+spec:
+  kiali:
+    serviceName: kiali
+    serviceNamespace: istio-system-two
+    servicePort: 20001
+EOM
+----
+
+.Verification
+
+. Go to the {ocp-product-title} web console.
+
+. Verify that the *{SMProductShortName}* category is added in the main {ocp-product-title} web console navigation.
+
+. If the {SMPluginShort} is not installed yet, wait until the web console notifies you that the {SMPluginShort} is installed and prompts you to refresh.

modules/ossm-install-console-plugin-ocp-web-console.adoc

@@ -0,0 +1,39 @@
+// Module included in the following assemblies:
+//
+// * service-mesh-docs-main/observability/kiali/ossm-console-plugin.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="ossm-install-console-plugin-ocp-web-console_{context}"]
+= Installing {SMPluginShort} by using the {ocp-product-title} web console
+
+You can install the {SMPlugin} by using the {ocp-product-title} web console.
+
+.Prerequisites
+
+* You have the administrator access to the {ocp-product-title} web console.
+* You have installed the {SMProduct} (OSSM).
+* You have installed the `{istio}` control plane from OSSM 3.0.
+* You have installed the {KialiServer} 2.4.
+
+.Procedure
+
+. Navigate to *Installed Operators*.
+
+. Click *{KialiProduct}*.
+
+. Click *Create instance* on the *{SMProductName} Console* tile. You can also click *Create OSSMConsole* button under the *{SMProduct} Console* tab.
+
+. Use the *Create OSSMConsole* form to create an instance of the `OSSMConsole` custom resource (CR). *Name* and *Version* are the required fields.
++
+[NOTE]
+====
+The *Version* field must match with the `spec.version` field in your Kiali custom resource (CR). If *Version* value is the string `default`, the Kiali Operator installs {ossmc-full} (OSSMC) with the same version as the operator. The `spec.version` field requires the `v` prefix in the version number. The version number must only include the major and minor version numbers (not the patch number); for example: `v1.73`.
+====
+
+. Click *Create*.
+
+.Verification
+
+. Wait until the web console notifies you that the {SMPluginShort} is installed and prompts you to refresh.
+
+. Verify that the *{SMProductShortName}* category is added in the main {ocp-product-title} web console navigation.

modules/ossm-uninstall-console-plugin-ocp-cli.adoc

@@ -0,0 +1,27 @@
+// Module included in the following assemblies:
+//
+// * service-mesh-docs-main/observability/kiali/ossm-console-plugin.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="ossm-uninstall-console-plugin-ocp-cli_{context}"]
+= Uninstalling {SMPluginShort} by using the CLI
+
+You can uninstall the {SMPlugin} by using the {oc-first}.
+
+.Procedure
+
+* Remove the OSSMC custom resource (CR) by running the following command:
++
+[source,terminal]
+----
+$ oc delete ossmconsoles <custom_resource_name> -n <custom_resource_namespace>
+----
+
+.Verification
+
+* Verify all the CRs are deleted from all namespaces by running the following command:
++
+[source,terminal]
+----
+$ for r in $(oc get ossmconsoles --ignore-not-found=true --all-namespaces -o custom-columns=NS:.metadata.namespace,N:.metadata.name --no-headers | sed 's/  */:/g'); do oc delete ossmconsoles -n $(echo $r|cut -d: -f1) $(echo $r|cut -d: -f2); done
+----

modules/ossm-uninstall-console-plugin-ocp-web-console.adoc

@@ -0,0 +1,21 @@
+// Module included in the following assemblies:
+//
+// * service-mesh-docs-main/observability/kiali/ossm-console-plugin.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="ossm-uninstall-console-plugin-ocp-web-console_{context}"]
+= Uninstalling {SMPluginShort} by using the web console
+
+You can uninstall the {SMPlugin} by using the {ocp-product-title} web console.
+
+.Procedure
+
+. Navigate to *Installed Operators*.
+
+. Click *Kiali Operator*.
+
+. Select the *{ossmc-full}* tab.
+
+. Click *Delete OSSMConsole* option from the entry menu.
+
+. Confirm that you want to delete the plugin.

observability/kiali/ossm-console-plugin.adoc

@@ -0,0 +1,60 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="ossm-console-plugin"]
+= Using OpenShift Service Mesh Console plugin
+include::_attributes/common-attributes.adoc[]
+:context: ossm-console-plugin
+
+toc::[]
+
+The {SMPlugin} extends the {ocp-product-title} web console with a {SMProductShortName} menu and enhanced tabs for workloads and services.
+
+include::modules/ossm-about-console-plugin.adoc[leveloffset=+1]
+
+[id="ossm-install-console-plugin_{context}"]
+== Installing {sm-plugin-full}
+
+You can install the {SMPluginShort} with the Kiali Operator by creating a `OSSMConsole` resource with the corresponding plugin settings. It is recommended to install the latest version of the Kiali Operator, even while installing a previous {SMPluginShort} version, as it includes the latest z-stream release.
+
+.OSSM version compatibility
+[options="header"]
+|===
+|OSSM version |Kiali Server version |OSSMC plugin version |OCP version
+
+|3.0 |v2.4 |v2.4 |4.15+
+
+|2.6 |v1.73 |v1.73 |4.15-4.18
+
+|2.5 |v1.73 |v1.73 |4.14-4.18
+|===
+
+[NOTE]
+====
+{SMPluginShort} is only supported on {ocp-product-title} 4.15 and above. For {ocp-product-title} 4.14 users, only the standalone Kiali console is accessible.
+====
+
+You can install the {SMPluginShort} by using the {ocp-product-title} web console or the {oc-first}.
+
+include::modules/ossm-install-console-plugin-ocp-web-console.adoc[leveloffset=+2]
+
+include::modules/ossm-install-console-plugin-ocp-cli.adoc[leveloffset=+2]
+
+:_mod-docs-content-type: PROCEDURE
+[id="ossm-uninstall-console-plugin_{context}"]
+== Uninstalling {sm-plugin-full}
+
+You can uninstall the {SMPluginShort} by using the {ocp-product-title} web console or the {oc-first}.
+
+You must uninstall the {SMPluginShort} before removing the Kiali Operator. Deleting the Operator first may leave OSSMC and Kiali CRs stuck, requiring manual removal of the finalizer. Use the following command with `<custom_resource_type>` as `kiali` or `ossmconsole` to remove the finalizer, if needed:
+
+[source,terminal]
+----
+$ oc patch <custom_resource_type> <custom_resource_name> -n <custom_resource_namespace> -p '{"metadata":{"finalizers": []}}' --type=merge
+----
+
+include::modules/ossm-uninstall-console-plugin-ocp-web-console.adoc[leveloffset=+2]
+
+include::modules/ossm-uninstall-console-plugin-ocp-cli.adoc[leveloffset=+2]
+
+
+
+