diff --git a/migrating/checklists/ossm-migrating-kiali-differences.adoc b/migrating/checklists/ossm-migrating-kiali-differences.adoc index 6cd25c73a211..ef851338a308 100644 --- a/migrating/checklists/ossm-migrating-kiali-differences.adoc +++ b/migrating/checklists/ossm-migrating-kiali-differences.adoc @@ -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 @@ -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] \ No newline at end of file diff --git a/migrating/checklists/ossm-migrating-network-policies.adoc b/migrating/checklists/ossm-migrating-network-policies.adoc index f8abfb537ef8..da6b95269616 100644 --- a/migrating/checklists/ossm-migrating-network-policies.adoc +++ b/migrating/checklists/ossm-migrating-network-policies.adoc @@ -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 dir for migrating network policies after completely deployment and workloads migration. +include::modules/ossm-migrating-network-policies-setup-during-migration.adoc[leveloffset=+1] \ No newline at end of file diff --git a/migrating/checklists/ossm-migrating-premigration-checklists.adoc b/migrating/checklists/ossm-migrating-premigration-checklists.adoc index 0b77dd070fc7..618834ceefd8 100644 --- a/migrating/checklists/ossm-migrating-premigration-checklists.adoc +++ b/migrating/checklists/ossm-migrating-premigration-checklists.adoc @@ -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 -n -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] diff --git a/migrating/checklists/ossm-migrating-read-me.adoc b/migrating/checklists/ossm-migrating-read-me.adoc index cf5b59d3ff14..8d8056fdfd2a 100644 --- a/migrating/checklists/ossm-migrating-read-me.adoc +++ b/migrating/checklists/ossm-migrating-read-me.adoc @@ -6,55 +6,63 @@ include::_attributes/common-attributes.adoc[] toc::[] -If you are moving from {SMProductName} 2.6 to {SMProductName} 3, read the content in this section first as it contains important information and explanations on the differences between the versions. These differences have a direct impact on your installation and configuration of {SMProduct} 3. +[role="_abstract"] + +Identify the architectural and functional differences between {SMProductName} 2.6 and {SMProductName} 3 to prepare for the specific installation and configuration changes required for a successful migration. include::modules/ossm-migrating-2-and-3-differences.adoc[leveloffset=+1] + include::modules/ossm-migrating-read-me-new-operator.adoc[leveloffset=+1] + include::modules/ossm-migrating-read-me-new-resources.adoc[leveloffset=+1] + include::modules/ossm-migrating-read-me-observability-integrations.adoc[leveloffset=+1] -include::modules/ossm-migrating-read-me-scoping-discovery-selectors.adoc[leveloffset=+1] -.Next steps -* xref:../../install/ossm-installing-openshift-service-mesh.adoc#ossm-scoping-service-mesh-with-discoveryselectors_ossm-installing-openshift-service-mesh[Scoping Service Mesh with discoverySelectors] +include::modules/ossm-migrating-read-me-scoping-discovery-selectors.adoc[leveloffset=+1] include::modules/ossm-migrating-read-me-sidecar-injection-considerations.adoc[leveloffset=+1] -include::modules/ossm-migrating-read-me-support-for-multiple-control-planes.adoc[leveloffset=+1] -include::modules/ossm-migrating-read-me-independently-managed-gateways.adoc[leveloffset=+1] -.Next steps -If you are using {SMProduct} 2.6, and have not migrated from `ServiceMeshControlPlane` defined gateways to gateway injection, then you must follow the {SMProduct} 2.x gateway migration procedure before you can move to {SMProduct} 3. +include::modules/ossm-migrating-read-me-support-for-multiple-control-planes.adoc[leveloffset=+1] -* link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.17/html/service_mesh/service-mesh-2-x#ossm-about-gateway-migration_gateway-migration[Gateway migration] +include::modules/ossm-migrating-read-me-independently-managed-gateways.adoc[leveloffset=+1] include::modules/ossm-migrating-read-me-explicitly-create-openshift-routes.adoc[leveloffset=+1] -include::modules/ossm-migrating-read-me-introducing-canary-updates.adoc[leveloffset=+1] -.Next steps -You can set `updateStrategy` to `RevisionBased` to use canary updates. - -* xref:../../update/ossm-updating-openshift-service-mesh.adoc#about-revisionbased-strategy_ossm-performing-inplace-update[About RevisionBased strategy] - -Be aware that setting the `updateStrategy` to `RevisionBased` also has implications for some integrations with {SMProduct}, such as the cert-manager tool integration. - -* xref:../../install/ossm-cert-manager.adoc#updating-istio-csr-revision-based-only_ossm-cert-manager[Updating istio-csr agents with revision-based update strategies] +include::modules/ossm-migrating-read-me-introducing-canary-updates.adoc[leveloffset=+1] include::modules/ossm-migrating-read-me-supported-multi-cluster-topologies.adoc[leveloffset=+1] -include::modules/ossm-migrating-read-me-support-for-istioctl.adoc[leveloffset=+1] -.Next steps -* You can install the xref:../../install/ossm-istioctl-tool.adoc#ossm-installing-the-istioctl-tool_ossm-istioctl-tool[Istioctl tool]. +include::modules/ossm-migrating-read-me-support-for-istioctl.adoc[leveloffset=+1] include::modules/ossm-migrating-read-me-kubernetes-network-policy-management.adoc[leveloffset=+1] + include::modules/ossm-migrating-read-me-tls-configuration-change.adoc[leveloffset=+1] [role="_additional-resources"] [id="additional-resource_{context}"] -== Additional Resources +== Additional resources * link:https://docs.redhat.com/en/documentation/openshift_container_platform/#Observability[Red Hat OpenShift Observability] + * link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.17/html/logging/index[Logging] + * link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.17/html/monitoring/index[User workload monitoring] + * link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.17/html/distributed_tracing/index[{DTProductName}] -* link:https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/[Labels and Selectors] (Kubernetes documentation) -* link:https://istio.io/latest/docs/tasks/security/tls-configuration/workload-min-tls-version/[Istio Workload Minimum TLS Version Configuration] (Istio documentation) -* link:https://istio.io/latest/docs/reference/config/security/authorization-policy/[Authorization Policies] (Istio documentation) + +* link:https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/[Labels and Selectors (Kubernetes documentation)] + +* link:https://istio.io/latest/docs/tasks/security/tls-configuration/workload-min-tls-version/[Istio Workload Minimum TLS Version Configuration (Istio documentation)] + +* link:https://istio.io/latest/docs/reference/config/security/authorization-policy/[Authorization Policies (Istio documentation)] + +* xref:../../install/ossm-installing-openshift-service-mesh.adoc#ossm-scoping-service-mesh-with-discoveryselectors_ossm-installing-openshift-service-mesh[Scoping Service Mesh with discoverySelectors] + +* xref:../../update/ossm-updating-openshift-service-mesh.adoc#about-revisionbased-strategy_ossm-performing-inplace-update[About RevisionBased strategy] + +* xref:../../install/ossm-cert-manager.adoc#updating-istio-csr-revision-based-only_ossm-cert-manager[Updating istio-csr agents with revision-based update strategies] + +* xref:../../install/ossm-istioctl-tool.adoc#ossm-installing-the-istioctl-tool_ossm-istioctl-tool[Istioctl tool] + +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.17/html/service_mesh/service-mesh-2-x#ossm-about-gateway-migration_gateway-migration[Gateway migration] + diff --git a/migrating/cluster-wide/ossm-migrating-cluster-wide.adoc b/migrating/cluster-wide/ossm-migrating-cluster-wide.adoc index 46c5772d186a..84e966bb2cf4 100644 --- a/migrating/cluster-wide/ossm-migrating-cluster-wide.adoc +++ b/migrating/cluster-wide/ossm-migrating-cluster-wide.adoc @@ -1,7 +1,3 @@ -// Module included in the following assemblies: -// -// * service-mesh-docs-main/migrating/cluster-wide/ossm-migrating-cluster-wide-assembly.adoc - :_mod-docs-content-type: ASSEMBLY [id="ossm-migrating-cluster-wide"] = Cluster-wide migration guide @@ -10,6 +6,8 @@ include::_attributes/common-attributes.adoc[] toc::[] +[role="_abstract"] + This guide is for users who are running a cluster-wide deployment of {SMProductName} {SMv2Version} and are migrating to {SMProduct} 3.0. [IMPORTANT] @@ -19,16 +17,6 @@ You must complete the premigration checklists before you start migrating your de include::modules/ossm-control-plane-configuration-migration-requirements.adoc[leveloffset=+1] -[role="_additional-resources"] -[id="additional-resources-cluster-wide_{context}"] -.Additional resources - -* xref:../../install/ossm-sidecar-injection.adoc#ossm-about-sidecar-injection_ossm-sidecar-injection[About sidecar injection] - -* 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] - -* xref:../../install/ossm-installing-openshift-service-mesh.adoc#ossm-scoping-service-mesh-with-discoveryselectors_ossm-installing-openshift-service-mesh[Scoping the mesh with discoverySelectors] - include::modules/ossm-cluster-wide-migration-methods.adoc[leveloffset=+1] // This sets the context to build the tasks for cluster-wide migration using the Istio revision label @@ -135,4 +123,10 @@ If you are not using gateways, you can complete your migration. [id="additional-resources_{context}"] == Additional resources +* xref:../../install/ossm-sidecar-injection.adoc#ossm-about-sidecar-injection_ossm-sidecar-injection[About sidecar injection] + +* 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] + +* xref:../../install/ossm-installing-openshift-service-mesh.adoc#ossm-scoping-service-mesh-with-discoveryselectors_ossm-installing-openshift-service-mesh[Scoping the mesh with discoverySelectors] + * xref:../../install/ossm-sidecar-injection.adoc#ossm-identifying-revision-name_ossm-sidecar-injection[Identifying the revision name] diff --git a/migrating/done/ossm-migrating-complete.adoc b/migrating/done/ossm-migrating-complete.adoc index 4ccb75dd33d9..ebedd3aaa56c 100644 --- a/migrating/done/ossm-migrating-complete.adoc +++ b/migrating/done/ossm-migrating-complete.adoc @@ -6,26 +6,20 @@ include::_attributes/common-attributes.adoc[] toc::[] -At this stage, you have completed the migration process. It is safe to remove {SMProduct} {smv2version}. - -//need to add cleanup/delete 2.6 content - -Optionally, if you already have Kiali installed, before you delete {SMProduct} {SMv2Version}, you can verify that all data plane namespaces have been migrated by checking the Kiali **Mesh** page. To learn more about the Kiali **Mesh** page, see "Istio infrastructure status (Kiali.io)". +Once the migration is complete, you can uninstall {SMProduct} {smv2version} and optionally verify the migration status of data plane namespaces by using the Kiali *Mesh* page. include::modules/ossm-migrating-done-network-policies.adoc[leveloffset=+1] -include::modules/ossm-migrating-complete-multitenant-cert-manager.adoc[leveloffset=+1] - -.Next steps -* Remove {Smproduct} 2 +include::modules/ossm-migrating-complete-multitenant-cert-manager.adoc[leveloffset=+1] include::modules/ossm-migrating-complete-remove-2-6-control-plane.adoc[leveloffset=+1] + include::modules/ossm-migrating-complete-remove-2-6-operator-crds.adoc[leveloffset=+1] -include::modules/ossm-migrating-complete-remove-maistra-labels.adoc[leveloffset=+1] +include::modules/ossm-migrating-complete-remove-maistra-labels.adoc[leveloffset=+1] [role="_additional-resources"] [id="additional-resources-complete_{context}"] -== Additional Resources +== Additional resources * link:https://kiali.io/docs/features/istio-component-status/#control-plane-namespace[Istio infrastructure status] (Kiali.io documentation) diff --git a/migrating/migrating-gateways/ossm-migrating-gateways.adoc b/migrating/migrating-gateways/ossm-migrating-gateways.adoc index 9b04aae67909..f6d5e30ac2fc 100644 --- a/migrating/migrating-gateways/ossm-migrating-gateways.adoc +++ b/migrating/migrating-gateways/ossm-migrating-gateways.adoc @@ -6,31 +6,18 @@ include::_attributes/common-attributes.adoc[] toc::[] -If you are using gateways with {SMProductName} {SMv2Version} and migrating them to {smproduct} 3.0, you can migrate gateways from {SMProduct} 2 to {SMProduct} 3 just like regular workloads. - -Use one of the following two methods for migrating gateways from {SMProductName} 2 to {SMProduct} 3: - -* Gateway canary migration -* Gateway in place migration +Migrate {SMProductName} gateways from version 2 to version 3 by using either a canary or an in-place migration strategy to ensure continuous traffic management. include::modules/ossm-migrating-gateways-canary.adoc[leveloffset=+1] -.Next steps - -* xref:../../migrating/done/ossm-migrating-complete.adoc#ossm-migrating-complete[Completing your migration] - include::modules/ossm-migrating-gateways-in-place.adoc[leveloffset=+1] -.Next steps - -* xref:../../migrating/done/ossm-migrating-complete.adoc#ossm-migrating-complete[Completing your migration] - [role="_additional-resources"] [id="additional-resources-gateways_{context}"] == Additional resources +* xref:../../migrating/done/ossm-migrating-complete.adoc#ossm-migrating-complete[Completing your migration] + * 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] -//there is already a Gateways dir that contains 3.0 concept and procedure content for configuring and using gateways in 3.0. -//named this dir migrating-gateways for clarity \ No newline at end of file +* xref:../../migrating/cluster-wide/ossm-migrating-cluster-wide.adoc#ossm-migrating-cluster-wide[Cluster-wide migration guide] \ No newline at end of file diff --git a/migrating/multitenant/ossm-migrating-multitenant.adoc b/migrating/multitenant/ossm-migrating-multitenant.adoc index 1d2ecdb39edd..b1d42214fffe 100644 --- a/migrating/multitenant/ossm-migrating-multitenant.adoc +++ b/migrating/multitenant/ossm-migrating-multitenant.adoc @@ -8,35 +8,18 @@ toc::[] This guide is for users who are currently running a multitenant deployment of {SMProductName} {SMv2Version}, and are migrating to {SMProduct} 3.0. -[IMPORTANT] -==== -If you have not completed the premigration checklists, you must complete them first before you can start migrating your deployment. -==== - include::modules/ossm-migrating-a-multitenant-deployment.adoc[leveloffset=+1] -include::modules/ossm-migrating-multitenant-workloads.adoc[leveloffset=+1] - -.Next steps - -If you are using gateways, you must migrate them before you complete the migration process for your deployment and workloads. - -* xref:../migrating-gateways/ossm-migrating-gateways.adoc#ossm-migrating-gateways[Migrating gateways] -If you are not using gateways, and have verified your mulitenant migration, you can proceed to complete the migration and remove {SMProduct} 2 resources. - -* xref:../done/ossm-migrating-complete.adoc[Completing the Migration] +include::modules/ossm-migrating-multitenant-workloads.adoc[leveloffset=+1] include::modules/ossm-migrating-multitenant-with-cert-manager.adoc[leveloffset=+1] -include::modules/ossm-migrating-multitenant-workloads-with-cert-manager.adoc[leveloffset=+1] -.Next steps +include::modules/ossm-migrating-multitenant-workloads-with-cert-manager.adoc[leveloffset=+1] -If you are using gateways, you must migrate them before you can complete the migration process for your deployment and workloads. +[role="_additional-resources"] +[id="additional-resources-migrating-multitenant_{context}"] +== Additional resources * xref:../migrating-gateways/ossm-migrating-gateways.adoc#ossm-migrating-gateways[Migrating gateways] -After you have migrated your gateways, you must update the `app.controller.configmapNamespaceSelector` field in your `istio-csr` deployment. - -If you are not using gateways, you can complete your migration with cert-manager. - -* xref:../../migrating/done/ossm-migrating-complete.adoc#ossm-migrating-complete[Completing the Migration] \ No newline at end of file +* xref:../done/ossm-migrating-complete.adoc[Completing the Migration] \ No newline at end of file diff --git a/migrating/reference/ossm-migrating-references.adoc b/migrating/reference/ossm-migrating-references.adoc index 83da9f20ae98..04c789d85013 100644 --- a/migrating/reference/ossm-migrating-references.adoc +++ b/migrating/reference/ossm-migrating-references.adoc @@ -5,17 +5,14 @@ include::_attributes/common-attributes.adoc[] :context: ossm-migrating-references toc::[] -Many configuration options in the {SMProduct} 2 `ServiceMeshControlPlane` resource have changed location in the {SMProduct} 3 `Istio` resource. The following tables provide guidance for creating a new `Istio` resource in {SMProduct} 3 based on your existing {SMProduct} 2 `ServiceMeshControlPlane` resource. +Many configuration options in the {SMProduct} 2 `ServiceMeshControlPlane` resource have changed location in the {SMProduct} 3 `{istio}` resource. The following tables offer guidance for creating a new `{istio}` resource in {SMProduct} 3 based on your existing {SMProduct} 2 `ServiceMeshControlPlane` resource. include::modules/ossm-migrating-reference-smcp-configurations.adoc[leveloffset=+1] + include::modules/ossm-migrating-reference-unsupported-configurations.adoc[leveloffset=+1] [role="_additional-resources"] [id="additional-resources-reference_{context}"] == Additional Resources -* xref:../../observability/ossm-observability-service-mesh.adoc#ossm-observability-service-mesh[Observability and Service Mesh] - -//* add exref to "Deploying multiple service meshes on a single cluster" -//exrefs handled by OSSM-8852 -//titles handled by OSM-8852 \ No newline at end of file +* xref:../../observability/ossm-observability-service-mesh.adoc#ossm-observability-service-mesh[Observability and Service Mesh] \ No newline at end of file diff --git a/modules/ossm-migrating-a-multitenant-deployment.adoc b/modules/ossm-migrating-a-multitenant-deployment.adoc index ac06180551cd..95fb0d2c9ec0 100644 --- a/modules/ossm-migrating-a-multitenant-deployment.adoc +++ b/modules/ossm-migrating-a-multitenant-deployment.adoc @@ -10,6 +10,11 @@ The `bookinfo` example application is being used for demonstration purposes with a minimal example for the `Istio` resource. For more information on configuration differences between the {SMProduct} 2 `ServiceMeshControlPlane` resource and the {SMProduct} 3 `Istio` resource, see "ServiceMeshControlPlane resource to Istio resource fields mapping". +[IMPORTANT] +==== +If you have not completed the premigration checklists, you must complete them first before you can start migrating your deployment. +==== + You can follow these same steps with your own workloads. .Prerequisites diff --git a/modules/ossm-migrating-about-kiali-differences.adoc b/modules/ossm-migrating-about-kiali-differences.adoc new file mode 100644 index 000000000000..a00d280b11af --- /dev/null +++ b/modules/ossm-migrating-about-kiali-differences.adoc @@ -0,0 +1,52 @@ +// Module included in the following assemblies: +// +// * service-mesh-docs-main/migrating/checklists/ossm-migrating-kiali-differences.adoc + +:_mod-docs-content-type: CONCEPT +[id="ossm-migrating-about-kiali-differences_{context}"] += About migrating Kiali differences + +[role="_abstract"] + +{kialiproduct} with {SMProductName} 3 introduces the following changes: + +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. + +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. + +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` + +|`external_service.tracing.url` +|`external_service.tracing.external_url` +|=== + +These changes reflect evolving capabilities and configuration standards of Kiali within {SMProduct} 3. \ No newline at end of file diff --git a/modules/ossm-migrating-based-on-your-deployment-model.adoc b/modules/ossm-migrating-based-on-your-deployment-model.adoc new file mode 100644 index 000000000000..238998e01acb --- /dev/null +++ b/modules/ossm-migrating-based-on-your-deployment-model.adoc @@ -0,0 +1,17 @@ +// Module included in the following assemblies: +// +// * service-mesh-docs-main/migrating/checklists/ossm-migrating-premigration-checklists.adoc + +:_mod-docs-content-type: REFERENCE +[id="ossm-migrating-based-on-your-deployment-model_{context}"] += Find your deployment model + +[role="_abstract"] + +If you are not using the cert-manager tool with your deployment, you are ready to migrate your deployment. Refer to the following migration guides based on your deployment model: + +* "Multitenant migration guide" + +* "Cluster-wide migration guide" + +If you are unsure, you can check if you are using the cert-manager tool with your deployment. \ No newline at end of file diff --git a/modules/ossm-migrating-disable-add-ons-and-reconfigure-replacements.adoc b/modules/ossm-migrating-disable-add-ons-and-reconfigure-replacements.adoc new file mode 100644 index 000000000000..2035e09ce737 --- /dev/null +++ b/modules/ossm-migrating-disable-add-ons-and-reconfigure-replacements.adoc @@ -0,0 +1,49 @@ +// Module included in the following assemblies: +// +// * service-mesh-docs-main/migrating/checklists/ossm-migrating-premigration-checklists.adoc + +:_mod-docs-content-type: REFERENCE +[id="ossm-migrating-disable-add-ons-and-reconfigure-replacements_{context}"] += Disable add-ons and reconfigure replacements + +[role="_abstract"] + +To prepare for your migration to {SMProduct} 3, you must disable legacy add-ons in your {SMProduct} 2 `ServiceMeshControlPlane` resource and reconfigure replacements for the features that those add-ons provided. + +* [ ] 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. For more information, see "Integration with user-workload monitoring". + +** [ ] If you are not using OpenShift monitoring, see: "Integration with external Prometheus installation". + +* [ ] Disable tracing in your `ServiceMeshControlPlane` resource: `spec.tracing.type=None` + +** [ ] Configure the `ServiceMeshControlPlane` with OpenShift Distributed Tracing as the replacement. For more information, see "Configuring {TempoName} and the Red{nbsp}Hat build of OpenTelemetry". + +* [ ] 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}". + +[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. +==== \ No newline at end of file diff --git a/modules/ossm-migrating-disable-grafana-in-service-mesh-2.adoc b/modules/ossm-migrating-disable-grafana-in-service-mesh-2.adoc new file mode 100644 index 000000000000..0925c588bd0d --- /dev/null +++ b/modules/ossm-migrating-disable-grafana-in-service-mesh-2.adoc @@ -0,0 +1,14 @@ + +// Module included in the following assemblies: +// +// * service-mesh-docs-main/migrating/checklists/ossm-migrating-premigration-checklists.adoc + +:_mod-docs-content-type: REFERENCE +[id="ossm-migrating-disable-grafana-in-service-mesh-2_{context}"] += Disable Grafana in {SMProduct} 2 + +[role="_abstract"] + +Grafana is not supported in {SMProduct} 3, and must be disabled in your {SMProduct} 2 `ServiceMeshControlPlane`. + + * [ ] Disable Grafana in your {SMProduct} 2 `ServiceMeshControlPlane`: `spec.addons.grafana.enabled=false`. \ No newline at end of file diff --git a/modules/ossm-migrating-disable-network-policy-management.adoc b/modules/ossm-migrating-disable-network-policy-management.adoc new file mode 100644 index 000000000000..ba1e5c90c152 --- /dev/null +++ b/modules/ossm-migrating-disable-network-policy-management.adoc @@ -0,0 +1,29 @@ +// Module included in the following assemblies: +// +// * service-mesh-docs-main/migrating/checklists/ossm-migrating-premigration-checklists.adoc + +:_mod-docs-content-type: REFERENCE +[id="ossm-migrating-disable-network-policy-management_{context}"] += Disable network policy management + +[role="_abstract"] + +If you do not want your network policies in place during your 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. + +* [ ] Manually recreate your network policies after you have migrated your workloads. + +If you want your network policies in place during your migration: + +* [ ] Manually set up network policies to use during migration. For more information, see "Migrating network policies from Service Mesh 2 to Service Mesh 3". + +* [ ] 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. \ No newline at end of file diff --git a/modules/ossm-migrating-find-your-deployment-model.adoc b/modules/ossm-migrating-find-your-deployment-model.adoc new file mode 100644 index 000000000000..254ba63e7248 --- /dev/null +++ b/modules/ossm-migrating-find-your-deployment-model.adoc @@ -0,0 +1,21 @@ +// Module included in the following assemblies: +// +// * service-mesh-docs-main/migrating/checklists/ossm-migrating-premigration-checklists.adoc + +:_mod-docs-content-type: REFERENCE +[id="ossm-migrating-find-your-deployment-model_{context}"] += Find your deployment model + +[role="_abstract"] + +Run the following command to find your deployment model: + +[source,terminal] +---- +oc get smcp -n -o jsonpath='{.spec.mode}' +---- + +[NOTE] +==== +If you did not set a value for the `.spec.mode` parameter in your `ServiceMeshControlPlane` resource, your deployment is multitenant. +==== \ No newline at end of file diff --git a/modules/ossm-migrating-multitenant-workloads-with-cert-manager.adoc b/modules/ossm-migrating-multitenant-workloads-with-cert-manager.adoc index 6e15787191ce..cf5a6adc2f6a 100644 --- a/modules/ossm-migrating-multitenant-workloads-with-cert-manager.adoc +++ b/modules/ossm-migrating-multitenant-workloads-with-cert-manager.adoc @@ -127,4 +127,9 @@ productpage-v1-7745c5cc94-wpvth.bookinfo Kubernetes SYNCED SYNCED [source,terminal] ---- $ oc exec -it -n bookinfo deployments/productpage-v1 -c istio-proxy -- curl localhost:9080/productpage ----- \ No newline at end of file +---- + +[NOTE] +==== +If you are using gateways, you must migrate them before you complete the migration process for your deployment and workloads. After you have migrated your gateways, you must update the `app.controller.configmapNamespaceSelector` field in your `istio-csr` deployment. If you are not using gateways, you can complete your migration with cert-manager. +==== \ No newline at end of file diff --git a/modules/ossm-migrating-multitenant-workloads.adoc b/modules/ossm-migrating-multitenant-workloads.adoc index 2d45d42cc3d4..d952b6f76627 100644 --- a/modules/ossm-migrating-multitenant-workloads.adoc +++ b/modules/ossm-migrating-multitenant-workloads.adoc @@ -127,4 +127,9 @@ productpage-v1-7745c5cc94-wpvth.bookinfo Kubernetes SYNCED SYNCED [source,terminal] ---- $ oc exec -it -n bookinfo deployments/productpage-v1 -c istio-proxy -- curl localhost:9080/productpage ----- \ No newline at end of file +---- + +[NOTE] +==== +If you are using gateways, you must migrate them before you complete the migration process for your deployment and workloads. If you are not using gateways, and have verified your mulitenant migration, you can proceed to complete the migration and remove {SMProduct} 2 resources. +==== \ No newline at end of file diff --git a/modules/ossm-migrating-network-policies-setup-during-migration.adoc b/modules/ossm-migrating-network-policies-setup-during-migration.adoc index 122377afa269..0f8a1ed04759 100644 --- a/modules/ossm-migrating-network-policies-setup-during-migration.adoc +++ b/modules/ossm-migrating-network-policies-setup-during-migration.adoc @@ -10,6 +10,11 @@ You can set up network policies to use during your migration. +[NOTE] +==== +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. +==== + [IMPORTANT] ==== * During the recreation of network policies from {SMProduct} 2 to {SMProduct} 3, both control planes must have access to all workloads and all workloads must have access to control planes. @@ -227,4 +232,6 @@ spec: ---- <1> Must match your current active revision name. +.Next steps +* In {SMProduct} 2, set the `spec.security.manageNetworkPolicy` field to `false` in your `ServiceMeshControlPlane` resource, and continue with the migration checklists. \ No newline at end of file diff --git a/modules/ossm-migrating-premigration-before-you-begin.adoc b/modules/ossm-migrating-premigration-before-you-begin.adoc new file mode 100644 index 000000000000..06f316bb24db --- /dev/null +++ b/modules/ossm-migrating-premigration-before-you-begin.adoc @@ -0,0 +1,32 @@ +// Module included in the following assemblies: +// +// * service-mesh-docs-main/migrating/checklists/ossm-migrating-premigration-checklists.adoc + +:_mod-docs-content-type: REFERENCE +[id="ossm-migrating-premigration-before-you-begin_{context}"] += Before you begin + +[role="_abstract"] + +Verify that your environment meets the following requirements, version dependencies, and operator installations necessary to begin the migration from {SMProduct} 2 to {SMProduct} 3. + +* You have read "Migrating from Service Mesh 2 to Service Mesh 3". + +* You have read and understand the "Differences between OpenShift Service Mesh 2 and OpenShift Service Mesh 3" section. + +* You have reviewed the "Migrating references" section. + +* 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 "Installing OpenShift Service Mesh". + +[IMPORTANT] +==== +You must complete the following checklists before you can begin migrating your deployment and workloads. +==== \ No newline at end of file diff --git a/modules/ossm-migrating-premigration-checklists-using-the-cert-manager-tool-with-your-deployment.adoc b/modules/ossm-migrating-premigration-checklists-using-the-cert-manager-tool-with-your-deployment.adoc index 4c8c4977d3a6..fb60e204a6a6 100644 --- a/modules/ossm-migrating-premigration-checklists-using-the-cert-manager-tool-with-your-deployment.adoc +++ b/modules/ossm-migrating-premigration-checklists-using-the-cert-manager-tool-with-your-deployment.adoc @@ -49,4 +49,12 @@ oc get smcp -n -o jsonpath='{.spec.security.certifi [source,yaml] ---- cert-manager ----- \ No newline at end of file +---- + +Next steps for migrating with the cert-manager tool:: + +There are some configurations you must complete first before you can start migrating your deployments: + +* "Migrating a multitenant deployment with the cert-manager tool" + +* "Cluster-wide migration methods" \ No newline at end of file diff --git a/modules/ossm-migrating-read-me-independently-managed-gateways.adoc b/modules/ossm-migrating-read-me-independently-managed-gateways.adoc index 96ffa05be8c9..0b21bc9a09be 100644 --- a/modules/ossm-migrating-read-me-independently-managed-gateways.adoc +++ b/modules/ossm-migrating-read-me-independently-managed-gateways.adoc @@ -12,11 +12,16 @@ In Istio, gateways are used to manage traffic entering (ingress) and exiting (eg The {SMProduct} 3 Operator does not create or manage gateways. -Instead, gateways in {SMProduct} 3 are created and managed independent of the Operator and control plane using gateway injection or the Kubernetes Gateway API. This provides greater flexibility and ensures that gateways can be fully customized and managed as part of a Red Hat OpenShift GitOps pipeline. This allows the gateways to be deployed and managed alongside their applications with the same lifecycle. +Instead, gateways in {SMProduct} 3 are created and managed independent of the Operator and control plane by using gateway injection or the Kubernetes Gateway API. This provides greater flexibility and ensures that gateways can be fully customized and managed as part of a {gitops-title} pipeline. This allows the gateways to be deployed and managed alongside their applications with the same lifecycle. This change was made for two reasons: * To start with a gateway configuration that can expand over time to meet the more robust needs of a production environment. * Gateways are better managed together with their corresponding workloads. -Gateways may continue to be deployed onto nodes or namespaces independent of applications. For example, a centralized gateway node. Istio gateways also remain eligible to be deployed on {ocp-product-title} infrastructure nodes. \ No newline at end of file +Gateways might continue to be deployed onto nodes or namespaces independent of applications. For example, a centralized gateway node. Istio gateways also remain eligible to be deployed on {ocp-product-title} infrastructure nodes. + +[NOTE] +==== +If you are using {SMProduct} 2.6, and have not migrated from `ServiceMeshControlPlane` defined gateways to gateway injection, then you must follow the {SMProduct} 2.x gateway migration procedure before you can move to {SMProduct} 3. +==== \ No newline at end of file diff --git a/modules/ossm-migrating-read-me-introducing-canary-updates.adoc b/modules/ossm-migrating-read-me-introducing-canary-updates.adoc index 1b6b79753952..2570f637b1be 100644 --- a/modules/ossm-migrating-read-me-introducing-canary-updates.adoc +++ b/modules/ossm-migrating-read-me-introducing-canary-updates.adoc @@ -8,12 +8,17 @@ [role="_abstract"] -{SMProductName} 2 supported only in-place style updates, which created risk for large meshes where, after the control plane was updated, all workloads must update to the new control plane version without a simple way to roll back if something goes wrong. +{SMProductName} 3 addresses the risks of traditional in-place updates by providing revision-based update strategies that allow for incremental workload transitions and simplified rollbacks. -{SMProduct} 3 retains support for simple in-place style updates, and adds support for canary-style updates of the Istio control plane using Istio's revision feature. +{SMProduct} 3 retains support for simple in-place style updates, and adds support for canary-style updates of the Istio control plane by using Istio's revision feature. -The `Istio` resource manages Istio revision labels using the `IstioRevision` resource. When the `Istio` resource's `updateStrategy` type is set to `RevisionBased`, it creates Istio revision labels using the `Istio` resource's name combined with the Istio version, for example `mymesh-v1-21-2`. +The `Istio` resource manages Istio revision labels by using the `IstioRevision` resource. When the `Istio` resource's `updateStrategy` type is set to `RevisionBased`, it creates Istio revision labels using the `Istio` resource's name combined with the Istio version, for example `mymesh-v1-21-2`. -During an updates, a new `IstioRevision` deploys the new Istio control plane with an updated revision label, for example `mymesh-v1-22-0`. Workloads can then be migrated between control planes using the revision label on namespaces or workloads, for example `istio.io/rev=mymesh-v1-22-0`. +During an updates, a new `IstioRevision` deploys the new Istio control plane with an updated revision label, for example `mymesh-v1-22-0`. Workloads can then be migrated between control planes by using the revision label on namespaces or workloads, for example `istio.io/rev=mymesh-v1-22-0`. -Setting your `updateStrategy` to `RevisionBased` also has implications for integrations, such as the cert-manager tool, and gateways. \ No newline at end of file +Setting your `updateStrategy` to `RevisionBased` also has implications for integrations, such as the cert-manager tool, and gateways. + +[NOTE] +==== +You can set `updateStrategy` to `RevisionBased` to use canary updates. Be aware that setting the `updateStrategy` to `RevisionBased` also has implications for some integrations with {SMProduct}, such as the cert-manager tool integration. +==== \ No newline at end of file diff --git a/modules/ossm-migrating-to-explicitly-managed-routes.adoc b/modules/ossm-migrating-to-explicitly-managed-routes.adoc new file mode 100644 index 000000000000..c9a7b9502ebe --- /dev/null +++ b/modules/ossm-migrating-to-explicitly-managed-routes.adoc @@ -0,0 +1,17 @@ +// Module included in the following assemblies: +// +// * service-mesh-docs-main/migrating/checklists/ossm-migrating-premigration-checklists.adoc + +:_mod-docs-content-type: REFERENCE +[id="ossm-migrating-to-explicitly-managed-routes_{context}"] += Migrate to explicitly managed routes + +[role="_abstract"] + +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. For more information, see "Service Mesh route migration". \ No newline at end of file diff --git a/modules/ossm-migrating-to-gateway-injection.adoc b/modules/ossm-migrating-to-gateway-injection.adoc new file mode 100644 index 000000000000..19a6b954aecc --- /dev/null +++ b/modules/ossm-migrating-to-gateway-injection.adoc @@ -0,0 +1,13 @@ +// Module included in the following assemblies: +// +// * service-mesh-docs-main/migrating/checklists/ossm-migrating-premigration-checklists.adoc + +:_mod-docs-content-type: REFERENCE +[id="ossm-migrating-to-gateway-injection_{context}"] += Migrate to gateway injection + +[role="_abstract"] + +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. + +* [ ] Migrate to gateway injection. For more information, see "Service Mesh gateway migration". \ No newline at end of file