Skip to content

OSSM-12399 Perform CQA and make changes to migration guides assemblies in 3x #108757

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
shreyasiddhartha wants to merge 3 commits into
base: service-mesh-docs-main
Choose a base branch
from
Open

OSSM-12399 Perform CQA and make changes to migration guides assemblies in 3x #108757

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
caa50ae
OSSM-12399
shreyasiddhartha Mar 20, 2026
1768630
Update 2
shreyasiddhartha Mar 24, 2026
ec12e88
Fix 1
shreyasiddhartha Mar 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 3 additions & 51 deletions migrating/checklists/ossm-migrating-kiali-differences.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,3 @@
// This module is used in the following assemblies:

// * migrating/checklists/ossm-kiali-differences-assembly.adoc

:_mod-docs-content-type: ASSEMBLY
[id="ossm-migrating-kiali-differences"]
= Kiali differences for {SMProductName} 3
Expand All @@ -10,52 +6,8 @@ include::_attributes/common-attributes.adoc[]

toc::[]

{kialiproduct} with {SMProductName} 3 introduces the following changes:

* New topology graphs
* Deprecated configuration settings
* Renamed configuration settings

[id="new-topology-graphs_{context}"]
== New topology graphs

The **Traffic Page Graph** page has been reorganized and built using Patternfly topology with a new topology view showcasing the mesh infrastructure.

[id="deprecated-config-settings_{context}"]
== Deprecated configuration settings

To control which namespaces are accessible or visible to users in {smproduct} 3, Kiali relies on `discoverySelectors`.

By default, `deployment.cluster_wide_access=true` is enabled, granting Kiali cluster-wide access to all namespaces in the local cluster. If you are migrating a cluster-wide deployment with Kiali, you must remove the following deprecated and unavailable configuration settings from your Kiali custom resource (CR):

* `spec.deployment.accessible_namespaces`
* `api.namespaces.exclude`
* `api.namespaces.include`
* `api.namespaces.label_selector_exclude`
* `api.namespaces.label_selector_include`

If you are are using discovery selectors in Istio to restrict the namespaces that `Istiod` watches, then those must match the discovery selectors in your Kiali CR.

[id="renamed-config-settings_{context}"]
== Renamed configuration settings

The following configuration settings have been renamed:

[cols="1,1"]
|===
|Old configuration |New configuration

|`external_service.grafana.in_cluster_url`
|`external_service.grafana.internal_url`

|`external_service.grafana.url`
|`external_service.grafana.external_url`

|`external_service.tracing.in_cluster_url`
|`external_service.tracing.internal_url`
[role="_abstract"]

|`external_service.tracing.url`
|`external_service.tracing.external_url`
|===
Review the architectural and configuration changes in Kiali for {SMProductName} 3, including updated topology graphs, deprecated namespace settings, and renamed service URLs.

These changes reflect evolving capabilities and configuration standards of Kiali within {SMProduct} 3.
include::modules/ossm-migrating-about-kiali-differences.adoc[leveloffset=+1]
14 changes: 3 additions & 11 deletions migrating/checklists/ossm-migrating-network-policies.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,16 +6,8 @@ include::_attributes/common-attributes.adoc[]

toc::[]

In {SMProductName} 2, network policies are created by default when the `spec.security.manageNetworkPolicy` field is set to `true` in the `ServiceMeshControlPlane` resource. During the migration to {SMProduct} 3, these policies are removed.
[role="_abstract"]

It is recommended to re-create your network policies after you have migrated your deployment and workloads. However, if your security policies require you to keep your network policies, you must re-create them first, and then set the `spec.security.manageNetworkPolicy` field to `false` as outlined in the migration checklists.
{SMProduct} 3 changes how network security is managed by removing the automatic generation of network policies previously controlled by the `spec.security.manageNetworkPolicy` field in {SMProductName} 2.

include::modules/ossm-migrating-network-policies-setup-during-migration.adoc[leveloffset=+1]

.Next steps
* In {SMProduct} 2, set the `spec.security.manageNetworkPolicy` field to `false` in your `ServiceMeshControlPlane` resource, and continue with the migration checklists.

//exrefs handled by OSSM-8852


//Note to self: migrating-done-network-policies is file name in <done> dir for migrating network policies after completely deployment and workloads migration.
include::modules/ossm-migrating-network-policies-setup-during-migration.adoc[leveloffset=+1]
141 changes: 26 additions & 115 deletions migrating/checklists/ossm-migrating-premigration-checklists.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,145 +8,56 @@ toc::[]

[role="_abstract"]

.Before you begin
Complete these premigration checklists to prepare your {SMProduct} 2 environment for an upgrade by disabling traditional add-ons, migrating gateway configurations, and validating resource compatibility for {SMProduct} 3.

* You have read "Migrating from Service Mesh 2 to Service Mesh 3".
* You have read and understand the xref:../../migrating/checklists/ossm-migrating-read-me.adoc#ossm-2-and-3-differences_ossm-migrating-read-me[differences between OpenShift Service Mesh 2 and OpenShift Service Mesh 3].
* You have reviewed the xref:../../migrating/reference/ossm-migrating-references.adoc[Migrating references] material.
* You want to migrate from {SMProduct} 2 to {SMProduct} 3.
* You are running {SMProduct} {SMv2Version}.
* You have upgraded your `ServiceMeshControlPlane` resource to the latest version.
* If you are using the {KialiProduct}, you are running the latest version.
* You have installed the {SMProduct} Operator 3. To install the {SMProduct} 3 Operator, see: xref:../../install/ossm-installing-openshift-service-mesh.adoc[Installing OpenShift Service Mesh]
include::modules/ossm-migrating-premigration-before-you-begin.adoc[leveloffset=+1]

[IMPORTANT]
====
You must complete the following checklists before you can begin migrating your deployment and workloads.
====
include::modules/ossm-migrating-disable-add-ons-and-reconfigure-replacements.adoc[leveloffset=+1]

[id="disable-add-ons-and-reconfigure-replacements_{context}"]
== Disable add-ons and reconfigure replacements
include::modules/ossm-migrating-to-explicitly-managed-routes.adoc[leveloffset=+1]

* [ ] Disable Prometheus in your `ServiceMeshControlPlane` resource: `spec.addons.prometheus.enabled=false`
** [ ] Configure the `ServiceMeshControlPlane` with OpenShift Monitoring as the replacement. These instructions also include installing a standalone `Kiali` resource. Both can be done at the same time. link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.17/html/service_mesh/service-mesh-2-x#ossm-integrating-with-user-workload-monitoring_observability[Integration user-workload monitoring]
** [ ] If you are not using OpenShift monitoring, see: link:https://docs.redhat.com/en/documentation/red_hat_openshift_service_on_aws/4/html/service_mesh/service-mesh-2-x#integration-with-external-prometheus-installation[Integration with external Prometheus installation].
include::modules/ossm-migrating-to-gateway-injection.adoc[leveloffset=+1]

* [ ] Disable tracing in your `ServiceMeshControlPlane` resource: `spec.tracing.type=None`
** [ ] Configure the `ServiceMeshControlPlane` with OpenShift Distributed Tracing as the replacement: link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.17/html/service_mesh/service-mesh-2-x#ossm-configuring-distr-tracing-tempo_observability[Configuring {TempoName} and the Red{nbsp}Hat build of OpenTelemetry].
include::modules/ossm-migrating-disable-network-policy-management.adoc[leveloffset=+1]

* [ ] Disable Kiali in your `ServiceMeshControlPlane` resource: `spec.addons.kiali.enabled=false`
** [ ] If you did not create a standalone `Kiali` resource as part of Prometheus or tracing, see: "Using {KialiProduct}".
include::modules/ossm-migrating-disable-grafana-in-service-mesh-2.adoc[leveloffset=+1]

[WARNING]
====
{SMProductName} 3 fails to install if outdated `ServiceEntry` custom resources are present in the cluster. The upstream {istio} version 1.24 introduced schema changes that cause installation failures for `ServiceEntry` resources that miss port numbers or exceed 256 hostnames. You can check for affected resources by running the following commands:

* For `ServiceEntry` with hostnames over 256, run the following command:
+
[source,terminal]
----
$ oc get serviceentries -A -o json | jq -r '.items[] | select(.spec.hosts | length > 256) | "\(.metadata.namespace)/\(.metadata.name): \(.spec.hosts | length) hosts"'
----

* For `ServiceEntry` with missing port numbers, run the following command:
+
[source,terminal]
----
$ oc get serviceentries -A -o json | jq -r '.items[] | select(.spec.ports == null or (.spec.ports | length == 0)) | "\(.metadata.namespace)/\(.metadata.name)"'
----

To ensure a seamless migration to {SMProductName} 3, perform the following corrective actions before installing the OSSM 3 operator:

* Split `ServiceEntry` resources: You must split any `ServiceEntry` containing more than 256 hosts into multiple smaller resources.
* Validate port configurations: You must ensure that all the `ServiceEntry` definitions include the required port specifications.
====

[id="migrate-to-explicitly-managed-routes_{context}"]
== Migrate to explicitly managed routes

Automatic route creation, also known as Istio OpenShift Routing (IOR), is a deprecated feature that is disabled by default for any `ServiceMeshControlPlane` resource created using {SMProduct} 2.5 and later. To move from {SMProduct} 2 to {SMProduct} 3, you need to migrate from IOR to explicitly-managed routes.

If you already moved to explicitly-managed routes in {SMProduct} 2, then continue to gateway injection.

* [ ] Migrate from Istio OpenShift Routing (IOR) to to explicitly-managed routes: link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.17/html/service_mesh/service-mesh-2-x#ossm-route-migration[Service Mesh route migration].

[id="migrate-to-gateway-injection_{context}"]
== Migrate to gateway injection

Gateways were controlled by the `ServiceMeshControlPlane` (SMCP) resource in {SMProduct} 2. The {SMProduct} 3 control plane does not manage gateways so you must migrate from SMCP-Defined gateways to gateway injection.

* [ ] link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.17/html/service_mesh/service-mesh-2-x#ossm-gateway-migration[Service Mesh gateway migration].

[id="disable-network-policy-management_{context}"]
== Disable network policy management
include::modules/ossm-migrating-premigration-checklists-resource-files.adoc[leveloffset=+1]

If you do not want your network policies in place during your migration:
include::modules/ossm-migrating-find-your-deployment-model.adoc[leveloffset=+1]

* [ ] Disable network policy management in the {SMProduct} 2 `ServiceMeshControlPlane` resource: `spec.security.manageNetworkPolicy=false`.
* [ ] Complete the rest of the checklists.
* [ ] Migrate your deployment and workloads.
* [ ] Manually recreate your network policies after you have migrated your workloads.
include::modules/ossm-migrating-based-on-your-deployment-model.adoc[leveloffset=+1]

If you want your network policies in place during your migration:
include::modules/ossm-migrating-premigration-checklists-using-the-cert-manager-tool-with-your-deployment.adoc[leveloffset=+1]

* [ ] Manually xref:../../migrating/checklists/ossm-migrating-network-policies.adoc#ossm-migrating-network-policies-setup-during-migration_ossm-migrating-network-policies[set up network policies to use during migration].
* [ ] Disable network policy management in the {SMProduct} 2 `ServiceMeshControlPlane` resource: `spec.security.manageNetworkPolicy=false`.
* [ ] Complete the rest of the checklists.
* [ ] Migrate your deployment and workloads.
[role="_additional-resources"]
[id="additional-resources-checklists_{context}"]
== Additional resources

[id="disable-grafana-in-service-mesh-2_{context}"]
== Disable Grafana in {SMProduct} 2
* xref:../../migrating/checklists/ossm-migrating-read-me.adoc#ossm-2-and-3-differences_ossm-migrating-read-me[Differences between OpenShift Service Mesh 2 and OpenShift Service Mesh 3]

Grafana is not supported in {SMProduct} 3, and must be disabled in your {SMProduct} 2 `ServiceMeshControlPlane`.
* xref:../../migrating/reference/ossm-migrating-references.adoc#migrating-references[Migrating references]

* [ ] Disable Grafana in your {SMProduct} 2 `ServiceMeshControlPlane`: `spec.addons.grafana.enabled=false`.
* xref:../../install/ossm-installing-openshift-service-mesh.adoc#ossm-installing-openshift-service-mesh[Installing OpenShift Service Mesh]

include::modules/ossm-migrating-premigration-checklists-resource-files.adoc[leveloffset=+1]
* link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.17/html/service_mesh/service-mesh-2-x#ossm-integrating-with-user-workload-monitoring_observability[Integration with user-workload monitoring]

[id="find-your-deployment-model_{context}"]
== Find your deployment model
* link:https://docs.redhat.com/en/documentation/red_hat_openshift_service_on_aws/4/html/service_mesh/service-mesh-2-x#integration-with-external-prometheus-installation[Integration with external Prometheus installation]

Run the following command to find your deployment model:
* link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.17/html/service_mesh/service-mesh-2-x#ossm-configuring-distr-tracing-tempo_observability[Configuring {TempoName} and the Red{nbsp}Hat build of OpenTelemetry]

[source,terminal]
----
oc get smcp <smcp-name> -n <smcp-namespace> -o jsonpath='{.spec.mode}'
----
* link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.17/html/service_mesh/service-mesh-2-x#ossm-route-migration[Service Mesh route migration]

[NOTE]
====
If you did not set a value for the `.spec.mode` parameter in your `ServiceMeshControlPlane` resource, your deployment is multitenant.
====
* link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.17/html/service_mesh/service-mesh-2-x#ossm-gateway-migration[Service Mesh gateway migration]

[id="migrate-based-on-your-deployment-model_{context}"]
== Migrate based on your deployment model
* xref:../../migrating/checklists/ossm-migrating-network-policies.adoc#ossm-migrating-network-policies-setup-during-migration_ossm-migrating-network-policies[Migrating network policies from Service Mesh 2 to Service Mesh 3]

If you are not using the cert-manager tool with your deployment, you are ready to migrate your deployment.
* xref:../../observability/kiali/ossm-kiali.adoc#ossm-kiali[Using {kialiproduct}]

* xref:../../migrating/multitenant/ossm-migrating-multitenant.adoc#ossm-migrating-multitenant[Multitenant migration guide]
* xref:../../migrating/cluster-wide/ossm-migrating-cluster-wide.adoc#ossm-migrating-cluster-wide[Cluster-wide migration guide]

If you are unsure, you can check if you are using the cert-manager tool with your deployment.

include::modules/ossm-migrating-premigration-checklists-using-the-cert-manager-tool-with-your-deployment.adoc[leveloffset=+1]

.Next steps for migrating with the cert-manager tool

There are some configurations you must complete first before you can start migrating your deployments.
* xref:../../migrating/cluster-wide/ossm-migrating-cluster-wide.adoc#ossm-migrating-cluster-wide[Cluster-wide migration guide]

* xref:../../migrating/multitenant/ossm-migrating-multitenant.adoc#migrating-multitenant-with-cert-manager_ossm-migrating-multitenant[Migrating a multitenant deployment with the cert-manager tool]
* xref:../../migrating/cluster-wide/ossm-migrating-cluster-wide.adoc#ossm-cluster-wide-migration-methods_ossm-migrating-cluster-wide[Cluster-wide migration methods]

//Per engineering, uncomment Final check after GA
//move to module when uncommenting
//== Final check before migrating your deployment and workloads

//Once you have configured your `ServiceMeshControlPlane` according to the checklists, you can run the following script to detect any issues with your environment:

//* [ ] Run the [migration-checker script](migration-checker.sh) to detect any issues with your environment.

[role="_additional-resources"]
[id="additional-resources-checklists_{context}"]
== Additional resources

* xref:../../observability/kiali/ossm-kiali.adoc#ossm-kiali[Using {kialiproduct}]
* xref:../../migrating/cluster-wide/ossm-migrating-cluster-wide.adoc#ossm-cluster-wide-migration-methods_ossm-migrating-cluster-wide[Cluster-wide migration methods]
Loading