From 31cc76b6fa7ae92ade33598e80835041ca1eb18f Mon Sep 17 00:00:00 2001 From: Fernando Hoyos Date: Thu, 13 Feb 2025 14:33:25 +0100 Subject: [PATCH 1/4] Add compatibility version table for OSSMC plugin --- docs/ossm/ossmc-plugin/README.md | 23 +++++++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) diff --git a/docs/ossm/ossmc-plugin/README.md b/docs/ossm/ossmc-plugin/README.md index c1d3b725b..2eb778159 100644 --- a/docs/ossm/ossmc-plugin/README.md +++ b/docs/ossm/ossmc-plugin/README.md @@ -47,10 +47,25 @@ Under OpenShift **Networking** details page, the OSSMC plugin adds a **Service M ## Installing the OpenShift Service Mesh Console plugin -The OSSMC plugin can be installed in two ways: using the OpenShift web console or the OpenShift CLI. +The OSSMC plugin is installed through the Kiali Operator by creating a `OSSMConsole` resource with the corresponding plugin settings. + +### OSSM version compatibility + +The OSSMC plugin follows a different versioning scheme than OSSM, so it is necessary to determine the appropriate OSSMC plugin version to install based on the OSSM version: + +| 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.14 - 4.18 | +| 2.5 | v1.73 | v1.73 | 4.14 - 4.18 | [!NOTE] -The OSSMC plugin is only supported on OpenShift 4.15 and above. For OCP 4.14 users, only the standalone Kiali Console will be accessible. +The OSSMC plugin is only supported on OpenShift 4.15 and above for version v2.4. For OCP 4.14 users, only the standalone Kiali Console will be accessible. + +[!NOTE] +In most cases, it is recommended to install the latest version of the Kiali Operator, even when installing a previous OSSMC plugin version, as it includes the latest z-stream releases for all supported OSSMC plugin versions. + +The OSSMC plugin can be installed in two ways: using the OpenShift web console or the OpenShift CLI. ### Install via the OpenShift web console @@ -76,7 +91,7 @@ The following steps show how to install the OSSMC plugin via the OpenShift web c * **Name** and **Version** are required fields. [!NOTE] - The **Version** field must match the `spec.version` field in your Kiali CR. If the versions do not match, OSSMC will not work properly. In case the **Version** value is the string "default", the Kiali Operator will install OSSMC whose version is the same as the operator itself. + The **Version** field must match the `spec.version` field in your Kiali CR. If the versions do not match, OSSMC will not work properly. In case the **Version** value is the string "default", the Kiali Operator will install OSSMC whose version is the same as the operator itself. Otherwise, the `spec.version` field requires to have the a "v" prefix to the version number, and the version number must only include the major and minor version numbers (patch number must be omitted, for example "v1.73"). 5. Click **Create**. @@ -110,7 +125,7 @@ The following steps show how to install the OSSMC plugin via the OpenShift CLI. ``` [!NOTE] - If the `spec.version` field is not specified (or if set explicitly to the string “default”), then the Kiali Operator will install OSSMC whose version is the same as the operator itself. It is very important that the version of OSSMC be the same version as the Kiali Server that is installed. If the versions do not match, OSSMC will not work properly. + It is very important that the version of OSSMC be the same version as the Kiali Server that is installed. If the versions do not match, OSSMC will not work properly. If the `spec.version` field is not specified (or if set explicitly to the string “default”), then the Kiali Operator will install OSSMC whose version is the same as the operator itself. Otherwise, the `spec.version` field requires to have the a "v" prefix to the version number, and the version number must only include the major and minor version numbers (patch number must be omitted, for example "v1.73"). The plugin resources are deployed in the same namespace where the `OSSMConsole` CR is created. From 6092f967477f3e58b8e28071f3594eeef39a0016 Mon Sep 17 00:00:00 2001 From: Fernando Hoyos Date: Thu, 13 Feb 2025 15:54:00 +0100 Subject: [PATCH 2/4] Fix typo --- docs/ossm/ossmc-plugin/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/ossm/ossmc-plugin/README.md b/docs/ossm/ossmc-plugin/README.md index 2eb778159..f5e844043 100644 --- a/docs/ossm/ossmc-plugin/README.md +++ b/docs/ossm/ossmc-plugin/README.md @@ -91,7 +91,7 @@ The following steps show how to install the OSSMC plugin via the OpenShift web c * **Name** and **Version** are required fields. [!NOTE] - The **Version** field must match the `spec.version` field in your Kiali CR. If the versions do not match, OSSMC will not work properly. In case the **Version** value is the string "default", the Kiali Operator will install OSSMC whose version is the same as the operator itself. Otherwise, the `spec.version` field requires to have the a "v" prefix to the version number, and the version number must only include the major and minor version numbers (patch number must be omitted, for example "v1.73"). + The **Version** field must match the `spec.version` field in your Kiali CR. If the versions do not match, OSSMC will not work properly. In case the **Version** value is the string "default", the Kiali Operator will install OSSMC whose version is the same as the operator itself. Otherwise, the `spec.version` field requires the "v" prefix to the version number, and the version number must only include the major and minor version numbers (patch number must be omitted); for example: `v1.73`. 5. Click **Create**. @@ -125,7 +125,7 @@ The following steps show how to install the OSSMC plugin via the OpenShift CLI. ``` [!NOTE] - It is very important that the version of OSSMC be the same version as the Kiali Server that is installed. If the versions do not match, OSSMC will not work properly. If the `spec.version` field is not specified (or if set explicitly to the string “default”), then the Kiali Operator will install OSSMC whose version is the same as the operator itself. Otherwise, the `spec.version` field requires to have the a "v" prefix to the version number, and the version number must only include the major and minor version numbers (patch number must be omitted, for example "v1.73"). + It is very important that the version of OSSMC be the same version as the Kiali Server that is installed. If the versions do not match, OSSMC will not work properly. If the `spec.version` field is not specified (or if set explicitly to the string “default”), then the Kiali Operator will install OSSMC whose version is the same as the operator itself. Otherwise, the `spec.version` field requires the "v" prefix to the version number, and the version number must only include the major and minor version numbers (patch number must be omitted); for example: `v1.73`. The plugin resources are deployed in the same namespace where the `OSSMConsole` CR is created. From 1f0576ef1cb8156077278f570fa094314f43d4c7 Mon Sep 17 00:00:00 2001 From: Fernando Hoyos Date: Tue, 18 Feb 2025 17:37:40 +0100 Subject: [PATCH 3/4] Remove certificate warning section --- docs/ossm/ossmc-plugin/README.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/ossm/ossmc-plugin/README.md b/docs/ossm/ossmc-plugin/README.md index f5e844043..277f76ec8 100644 --- a/docs/ossm/ossmc-plugin/README.md +++ b/docs/ossm/ossmc-plugin/README.md @@ -4,9 +4,6 @@ The OpenShift Service Mesh Console (OSSMC) plugin is an extension to the OpenShi The features of the OSSMC plugin are the same as those of the standalone Kiali Console, but the pages are organized differently to better integrate with the OpenShift console. The OSSMC plugin does not replace the Kiali Console, and after installing the OSSMC plugin, you can still access the standalone Kiali Console. -[!IMPORTANT] -If you are using a certificate that your browser does not initially trust, you must tell your browser to trust the certificate first before you are able to access the OSSMC plugin. To do this, go to the Kiali standalone user interface (UI) and tell the browser to accept its certificate. - ## About the OpenShift Service Mesh Console plugin The OpenShift Service Mesh Console (OSSMC) plugin is an extension to the OpenShift web console that provides visibility into your Service Mesh. From 450b3ef987e061808dff518030aeafa3808ed994 Mon Sep 17 00:00:00 2001 From: Fernando Hoyos Date: Wed, 5 Mar 2025 12:34:31 +0100 Subject: [PATCH 4/4] Align with official red hat docs --- docs/ossm/ossmc-plugin/README.md | 143 ++++++++++++++++--------------- 1 file changed, 72 insertions(+), 71 deletions(-) diff --git a/docs/ossm/ossmc-plugin/README.md b/docs/ossm/ossmc-plugin/README.md index 277f76ec8..715484857 100644 --- a/docs/ossm/ossmc-plugin/README.md +++ b/docs/ossm/ossmc-plugin/README.md @@ -1,55 +1,48 @@ -# OpenShift Service Mesh Console plugin +# Using OpenShift Service Mesh Console plugin -The OpenShift Service Mesh Console (OSSMC) plugin is an extension to the OpenShift web console that provides visibility into your Service Mesh. With the OSSMC plugin installed, a new **Service Mesh** menu category is available in the navigation menu on the left side of the web console, as well as new **Service Mesh** tabs that enhance the existing **Workloads** and **Services** OpenShift console detail pages. - -The features of the OSSMC plugin are the same as those of the standalone Kiali Console, but the pages are organized differently to better integrate with the OpenShift console. The OSSMC plugin does not replace the Kiali Console, and after installing the OSSMC plugin, you can still access the standalone Kiali Console. +The OpenShift Service Mesh Console (OSSMC) plugin extends the OpenShift web console with a **Service Mesh** menu and enhanced tabs for workloads and services. ## About the OpenShift Service Mesh Console plugin The OpenShift Service Mesh Console (OSSMC) plugin is an extension to the OpenShift web console that provides visibility into your Service Mesh. [!WARNING] -The OSSMC plugin only supports a single Kiali instance. Whether that Kiali instance is configured to access only a subset of OpenShift projects or has access cluster-wide to all projects does not matter. However, only a single Kiali instance can be accessed. +The OSSMC plugin supports only one Kiali instance, regardless of its project access scope. + +The OSSMC plugin provides a new category, **Service Mesh**, in the main OpenShift web console navigation with the following menu options: -The OSSMC plugin provides a new category, **Service Mesh**, in the main OpenShift web console navigation. +* **Overview:** Provides a summary of your mesh, displayed as cards that represent the namespaces in the mesh. -The following menu options are available under **Service Mesh** category: +* **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. -* **Overview** for a summary of your mesh, displayed as cards that represent the namespaces in the mesh. -* **Traffic Graph** for a full topology view of your mesh, represented by nodes and edges, each node representing a component of the mesh and each edge representing traffic flowing through the mesh between components. -* **Istio config** for 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** for 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. +* **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. -Under the OpenShift **Workloads** details page, the OSSMC plugin adds a **Service Mesh** tab that contains the following subtabs: +* **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. -* **Overview** subtab provides a summary of the selected workload, including a localized topology graph showing the workload with all inbound and outbound edges and nodes. -* **Traffic** subtab displays information about all inbound and outbound traffic to the workload. -* **Logs** subtab shows the logs for the workload's containers. +In the web console **Workloads** details page, the OSSMC plugin adds a **Service Mesh** tab that has the following subtabs: - * You can view container logs individually or in a unified fashion, ordered by log time. This is especially helpful to see how the Envoy sidecar proxy logs relate to your workload's application logs. - * You can enable the tracing span integration which then allows you to see which logs correspond to trace spans. +* **Overview:** Shows a summary of the selected workload, including a localized topology graph showing the workload with all inbound and outbound edges and nodes. -* **Metrics** subtab shows both inbound and outbound metric graphs in the corresponding subtabs. All the workload metrics can be displayed here, providing you with a detail view of the performance of your workload. +* **Traffic:** Shows information about all inbound and outbound traffic to the workload. - * You can enable the tracing span integration which allows you to see which spans occurred at the same time as the metrics. Click a span marker in the graph to view the specific spans associated with that timeframe. +* **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. -* **Traces** provides a chart showing the trace spans collected over the given timeframe. +* **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. - * Click a bubble to drill down into those trace spans; the trace spans can provide you the most low-level detail within your workload application, down to the individual request level. The trace details view gives further details, including heatmaps that provide you with a comparison of one span in relation to other requests and spans in the same timeframe. - * If you hover over a cell in a heatmap, a tooltip gives some details on the cell data. +* **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** subtab provides information about the Envoy sidecar configuration. This is useful when you need to dig down deep into the sidecar configuration when debugging things such as connectivity issues. +* **Envoy:** Shows information about the Envoy sidecar configuration. -Under OpenShift **Networking** details page, the OSSMC plugin adds a **Service Mesh** tab to Services and contains the **Overview**, **Traffic**, **Inbound Metrics**, and **Traces** subtabs that are similar to the same subtabs found in **Workloads**. +In the web console **Networking** details page, the OSSMC plugin adds a **Service Mesh** tab similar to the **Workloads** details page. + +In the web console **Projects** details page, the OSSMC plugin adds a **Service Mesh** 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. ## Installing the OpenShift Service Mesh Console plugin -The OSSMC plugin is installed through the Kiali Operator by creating a `OSSMConsole` resource with the corresponding plugin settings. +You can install the OSSMC plugin 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 OSSMC plugin version, as it includes the latest z-stream release. ### OSSM version compatibility -The OSSMC plugin follows a different versioning scheme than OSSM, so it is necessary to determine the appropriate OSSMC plugin version to install based on the OSSM version: - | OSSM Version | Kiali Server Version | OSSMC Plugin Version | OCP Version | | --------------- | -------------------- | -------------------- | ----------- | | 3.0 | v2.4 | v2.4 | 4.15+ | @@ -57,57 +50,56 @@ The OSSMC plugin follows a different versioning scheme than OSSM, so it is neces | 2.5 | v1.73 | v1.73 | 4.14 - 4.18 | [!NOTE] -The OSSMC plugin is only supported on OpenShift 4.15 and above for version v2.4. For OCP 4.14 users, only the standalone Kiali Console will be accessible. +The OSSMC plugin is only supported on OpenShift 4.15 and above. For OCP 4.14 users, only the standalone Kiali console is accessible. -[!NOTE] -In most cases, it is recommended to install the latest version of the Kiali Operator, even when installing a previous OSSMC plugin version, as it includes the latest z-stream releases for all supported OSSMC plugin versions. - -The OSSMC plugin can be installed in two ways: using the OpenShift web console or the OpenShift CLI. +You can install the OSSMC plugin by using the OpenShift web console or the OpenShift CLI (`oc`). -### Install via the OpenShift web console +### Installing the OSSMC plugin by using the OpenShift web console -The following steps show how to install the OSSMC plugin via the OpenShift web console. +You can install the OSSMC plugin by using the OpenShift web console. **Prerequisites** -* Access to the OpenShift web console with administrator access. -* Red Hat OpenShift Service Mesh (OSSM) is installed. -* `Istio` control plane from OSSM 3.0 is installed. -* Kiali Server 2.4 is installed. +* You have the administrator access to the OpenShift web console. +* You have installed the Red Hat OpenShift Service Mesh (OSSM). +* You have installed the `Istio` control plane from OSSM 3.0. +* You have installed the Kiali Server 2.4. **Procedure** 1. Navigate to **Installed Operators**. -2. Click the **Kiali Operator** item to access to the operator details page. - -3. Click **Create instance** on the **Red Hat OpenShift Service Mesh Console** tile. Another way is to click **Create OSSMConsole** button under the **OpenShift Service Mesh Console** tab. +2. Click **Kiali Operator**. -4. Use the **Create OSSMConsole** form to create an instance of the `OSSMConsole` custom resource (CR). +3. Click **Create instance** on the **Red Hat OpenShift Service Mesh Console** tile. You can also click **Create OSSMConsole** button under the **OpenShift Service Mesh Console** tab. - * **Name** and **Version** are required fields. +4. 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 the `spec.version` field in your Kiali CR. If the versions do not match, OSSMC will not work properly. In case the **Version** value is the string "default", the Kiali Operator will install OSSMC whose version is the same as the operator itself. Otherwise, the `spec.version` field requires the "v" prefix to the version number, and the version number must only include the major and minor version numbers (patch number must be omitted); for example: `v1.73`. + 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 the OSSMC plugin 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`. 5. Click **Create**. -6. Once the OpenShift Console UI detects the availability of the OSSM Console plugin, a message will appear in the OpenShift Console asking you to refresh it. You can use OSSMC once you refresh the OpenShift Console UI. +**Verification** -### Install via the OpenShift CLI +1. Wait until the web console notifies you that the OSSMC plugin is installed and prompts you to refresh. -The following steps show how to install the OSSMC plugin via the OpenShift CLI. +2. Verify that the **Service Mesh** category is added in the main OpenShift web console navigation. + +### Installing the OSSMC plugin by using the CLI + +You can install the OSSMC plugin by using the OpenShift CLI (`oc`). **Prerequisites** -* Access to the OpenShift cluster via CLI with administrator privileges. -* Red Hat OpenShift Service Mesh (OSSM) is installed. -* `Istio` control plane from OSSM 3.0 is installed. -* Kiali Server 2.4 is installed. +* You have access to the OpenShift CLI on the cluster as an administrator. +* You have installed the Red Hat OpenShift Service Mesh (OSSM). +* You have installed the `Istio` control plane from OSSM 3.0. +* You have installed the Kiali Server 2.4. **Procedure** -1. Create a small `OSSMConsole` custom resource (CR) to instruct the operator to install the plugin: +1. Create a `OSSMConsole` custom resource (CR) to install the plugin by running the following command: ```yaml cat < -n -p '{"metadata":{"finalizers": []}}' --type=merge`, where CR type is `kialis` or `ossmconsoles`. +You must uninstall the OSSMC plugin 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 `` as `kiali` or `ossmconsole` to remove the finalizer, if needed: + +```console +$ oc patch -n -p '{"metadata":{"finalizers": []}}' --type=merge +``` -### Uninstall via the OpenShift web console +### Uninstalling the OSSMC plugin by using the web console -The following steps show how to uninstall the OSSMC plugin via the OpenShift web console. +You can uninstall the OSSMC plugin by using the OpenShift web console. **Procedure** 1. Navigate to **Installed Operators**. -2. Click the **Kiali Operator** item to access to the operator details page. +2. Click **Kiali Operator**. 3. Select the **OpenShift Service Mesh Console** tab. -4. Click **Delete OSSMConsole** option from the ossmconsole entry menu. +4. Click **Delete OSSMConsole** option from the entry menu. -5. Confirm the delete in the modal confirmation message. +5. Confirm that you want to delete the plugin. -### Uninstall via the OpenShift CLI +### Uninstalling the OSSMC plugin by using the CLI -The following steps show how to uninstall the OSSMC plugin via the OpenShift CLI. +You can uninstall the OSSMC plugin by using the OpenShift CLI (`oc`). **Procedure** -1. Remove the `OSSMC` custom resource (CR) by running the following command: +1. Remove the OSSMC custom resource (CR) by running the following command: ```console - oc delete ossmconsoles -n + $ oc delete ossmconsoles -n ``` -2. Verify all CRs are deleted from all namespaces by running the following command: +**Verification** + +1. Verify all the CRs are deleted from all namespaces by running the following command: ```console - 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 + $ 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 ```