From 55dc721d3b24e2326e2ef76d0c28a235dcd8b728 Mon Sep 17 00:00:00 2001 From: Gwynne Monahan Date: Fri, 8 Nov 2024 09:25:11 -0600 Subject: [PATCH] OSSM-4835 [Doc] Capture Differences between OSSM 2.x and OSSM 3.0 --- _topic_maps/_topic_map.yml | 7 ++ migrating/_attributes | 1 + migrating/docinfo.xml | 12 +++ migrating/images | 1 + migrating/modules | 1 + .../ossm-migrating-read-me-assembly.adoc | 96 +++++++++++++++++++ migrating/snippets | 1 + .../ossm-migrating-2-and-3-differences.adoc | 28 ++++++ ...me-explicitly-create-openshift-routes.adoc | 16 ++++ ...ead-me-independently-managed-gateways.adoc | 27 ++++++ ...ng-read-me-introducing-canary-updates.adoc | 20 ++++ ...-kubernetes-network-policy-management.adoc | 17 ++++ .../ossm-migrating-read-me-new-operator.adoc | 33 +++++++ .../ossm-migrating-read-me-new-resources.adoc | 40 ++++++++ ...ng-read-me-observability-integrations.adoc | 24 +++++ ...g-read-me-scoping-discovery-selectors.adoc | 14 +++ ...d-me-sidecar-injection-considerations.adoc | 39 ++++++++ ...igrating-read-me-support-for-istioctl.adoc | 34 +++++++ ...e-support-for-multiple-control-planes.adoc | 16 ++++ ...me-supported-multi-cluster-topologies.adoc | 24 +++++ ...ting-read-me-tls-configuration-change.adoc | 23 +++++ 21 files changed, 474 insertions(+) create mode 120000 migrating/_attributes create mode 100644 migrating/docinfo.xml create mode 120000 migrating/images create mode 120000 migrating/modules create mode 100644 migrating/ossm-migrating-read-me-assembly.adoc create mode 120000 migrating/snippets create mode 100644 modules/ossm-migrating-2-and-3-differences.adoc create mode 100644 modules/ossm-migrating-read-me-explicitly-create-openshift-routes.adoc create mode 100644 modules/ossm-migrating-read-me-independently-managed-gateways.adoc create mode 100644 modules/ossm-migrating-read-me-introducing-canary-updates.adoc create mode 100644 modules/ossm-migrating-read-me-kubernetes-network-policy-management.adoc create mode 100644 modules/ossm-migrating-read-me-new-operator.adoc create mode 100644 modules/ossm-migrating-read-me-new-resources.adoc create mode 100644 modules/ossm-migrating-read-me-observability-integrations.adoc create mode 100644 modules/ossm-migrating-read-me-scoping-discovery-selectors.adoc create mode 100644 modules/ossm-migrating-read-me-sidecar-injection-considerations.adoc create mode 100644 modules/ossm-migrating-read-me-support-for-istioctl.adoc create mode 100644 modules/ossm-migrating-read-me-support-for-multiple-control-planes.adoc create mode 100644 modules/ossm-migrating-read-me-supported-multi-cluster-topologies.adoc create mode 100644 modules/ossm-migrating-read-me-tls-configuration-change.adoc diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index 65d887bd53c8..208d08371c9d 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -6,6 +6,13 @@ Topics: - Name: Service Mesh 3.x release notes File: ossm-release-notes-assembly --- +Name: Migrating from OpenShift Service Mesh 2.6 +Dir: migrating +Distros: openshift-service-mesh +Topics: +- Name: Important information to know before migrating + File: ossm-migrating-read-me-assembly +--- Name: About Dir: about Distros: openshift-service-mesh diff --git a/migrating/_attributes b/migrating/_attributes new file mode 120000 index 000000000000..93957f02273f --- /dev/null +++ b/migrating/_attributes @@ -0,0 +1 @@ +../_attributes \ No newline at end of file diff --git a/migrating/docinfo.xml b/migrating/docinfo.xml new file mode 100644 index 000000000000..06f4b4241eae --- /dev/null +++ b/migrating/docinfo.xml @@ -0,0 +1,12 @@ +Migrating +{product-title} +{product-version} +Migrating from OpenShift Service Mesh 2.6 to 3 + + This document provides important information on difference between {product-title} 2.6 and {product-title} 3, including a new operator, new resources, and changes to integrations like OpenShift Observability and Kiali. It also provides information on migrating from OpenShift Serivce Mesh 2.6 to OpenShift Service Mesh 3. + + + + Red Hat OpenShift Documentation Team + + \ No newline at end of file diff --git a/migrating/images b/migrating/images new file mode 120000 index 000000000000..5e67573196d8 --- /dev/null +++ b/migrating/images @@ -0,0 +1 @@ +../images \ No newline at end of file diff --git a/migrating/modules b/migrating/modules new file mode 120000 index 000000000000..464b823aca16 --- /dev/null +++ b/migrating/modules @@ -0,0 +1 @@ +../modules \ No newline at end of file diff --git a/migrating/ossm-migrating-read-me-assembly.adoc b/migrating/ossm-migrating-read-me-assembly.adoc new file mode 100644 index 000000000000..f8265d0ab477 --- /dev/null +++ b/migrating/ossm-migrating-read-me-assembly.adoc @@ -0,0 +1,96 @@ +:_mod-docs-content-type: ASSEMBLY +[id=ossm-migrating-read-me-assembly] += Important information to know if you are migrating from OpenShift Service Mesh 2.6 +include::_attributes/common-attributes.adoc[] +:context: ossm-migrating-read-me-assembly + +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. + +include::modules/ossm-migrating-2-and-3-differences.adoc[leveloffset=+1] +include::modules/ossm-migrating-read-me-new-operator.adoc[leveloffset=+1] + +.Next steps +You can install the {SMProduct} 3 Operator, or you can run {SMProduct} 2.6 and {SMProduct} 3 in the same cluster using either the multi-tenant deployment model, or the cluster-wide model. + +* xref:../install/ossm-installing-openshift-service-mesh.adoc#ossm-installing-operator_ossm-about-deployment-and-update-strategies[Installing the Service Mesh Operator] +* xref:../install/ossm-running-v2-same-cluster-as-v3-assembly.adoc#ossm-running-v2-v3-multitenant-deployment-model_ossm-running-v2-same-cluster-as-v3-assembly[Running OpenShift Service Mesh 2.6 and OpenShift Service Mesh 3 using multi-tenant model] +* xref:../install/ossm-running-v2-same-cluster-as-v3-assembly.adoc#ossm-running-v2-v3-cluster-wide-deployment-model_ossm-running-v2-same-cluster-as-v3-assembly[Running OpenShift Service Mesh 2.6 and OpenShift Service Mesh 3 using cluster-wide deployment model] + +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-about-discoveryselectors_ossm-scoping-service-mesh-with-discoveryselectors[Scoping Service Mesh with discoverySelectors] + +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. + +* 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-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-assembly.adoc#updating-istio-csr-revision-based-only_ossm-cert-manager-assembly[Updating istio-csr agents with revision-based update strategies] + +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] +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] + +//comments will be removed for OSSM 3.0 GA. For future reference only as Gwynne will likely be living in this file for Q1 2025. +//Migrating dir will be similar to Observability dir structure. Something like: +//Dir: migrating +//Distros: openshift-service-mesh +//Topics: +//-Name: Migration Guides +// File: ossm-file-name +//- Name: Migrating Metrics +// Dir: mig dir name1 +// Topics: +// - Name: Migrating metrics guide +// File: ossm-file-name2 +//- Name: Migratiing Traces +// Dir: mig dir name2 +// Topics: +// - Name: Migrating traces +// File: ossm-file-name3 +//- Name: Migrating from Kiali to Kiali 2 +// Dir: kiali +// Topics: +// - Name: Something about Kiali +// File: ossm-file-name4 +//Will be dependent on both the number of and type of migrations that need to take place to move from 2.6 to 3. +//migrating-read-me is the only content we have as of 11/19/2024. +//Possible file names will change once doc work can start on migration guides. As of 11/19/2024 it is unclear what migration guides will need to be created as engineering work is incomplete, and it is unknown how migration will happen. Will the operator have to go first? Do the integrations have to go in a particular order? Will there be differences if customers choose RevisionBased instead of the default InPlace update strategy? There are more questions than answers, so setting it up as best I can with the knowledge I have at this time. +//Possible each module will have Next Steps that will link out to respective migration guide. + +[role="_additional-resources"] +[id="addition-resource_{context}"] +== 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) + +//influx. Will be part of larger content strategy/IA effort to bridge 2.x users on their way to moving to 3.x +//Start of an overall Migrating section. +//Section is most likely to be reworked/restructured with OSSM 2 to OSSM 3 migration guides for GA. Unknown how many migration guides there are at this time (11/11/2024). It would be beneficial to be able to link from differences to the relevent migration guide so that users A) understand the change, esp significant changes like new operator, installing tracing and Kiali separately, gateways, etc. +//Migration likely to resemble https://docs.openshift.com/container-platform/4.17/migrating_from_ocp_3_to_4/about-migrating-from-3-to-4.html#about-migrating-from-3-to-4 when done for OSSM 3.0 GA. diff --git a/migrating/snippets b/migrating/snippets new file mode 120000 index 000000000000..9f5bc7e4dde0 --- /dev/null +++ b/migrating/snippets @@ -0,0 +1 @@ +../snippets \ No newline at end of file diff --git a/modules/ossm-migrating-2-and-3-differences.adoc b/modules/ossm-migrating-2-and-3-differences.adoc new file mode 100644 index 000000000000..cd0c9ebde8aa --- /dev/null +++ b/modules/ossm-migrating-2-and-3-differences.adoc @@ -0,0 +1,28 @@ +// Module included in the following assemblies: +// +// * service-mesh-docs-main/about/ossm-migrating-assembly.adoc + +//Start of an overall Migrating section. +//Section is most likely to be reworked/restructured with OSSM 2 to OSSM 3 migration guides for GA. Unknown how many migration guides there are at this time (11/11/2024). It would be beneficial to be able to link from differences to the relevent migration guide so that users A) understand the change, esp significant changes like new operator, installing tracing and Kiali separately, gateways, etc. + +:_mod-docs-content-type: CONCEPT +[id="ossm-2-and-3-differences_{context}"] += Differences between OpenShift Service Mesh 2 and OpenShift Service Mesh 3 + +If you are a current {SMProductName} user, there are a number of important differences you need to understand between {SMProduct} 2 and {SMProduct} 3 before you migrate, including the following: + +* A new Operator +* Integrations like Observability and Kiali are installed separately +* New resources: `Istio` and `IstioCNI` +* Scoping of a mesh with `discoverySelectors` and labels +* New considerations for sidecar injection +* Support for multiple control planes +* Independently managed gateways +* Explicit Istio OpenShift route creation +* Canary upgrades +* Support for Istio multi-cluster topologies +* Support for Istioctl +* Change to Kubernetes network policy management +* Transport layer security (TLS) configuration change + +You must be using {SMProduct} 2.6 to migrate to {SMProduct} 3. \ No newline at end of file diff --git a/modules/ossm-migrating-read-me-explicitly-create-openshift-routes.adoc b/modules/ossm-migrating-read-me-explicitly-create-openshift-routes.adoc new file mode 100644 index 000000000000..fcb047002f7b --- /dev/null +++ b/modules/ossm-migrating-read-me-explicitly-create-openshift-routes.adoc @@ -0,0 +1,16 @@ +// Module included in the following assemblies: +// +// * service-mesh-docs-main/about/ossm-migrating-assembly.adoc + +//Start of an overall Migrating section. +//Section is most likely to be reworked/restructured with OSSM 2 to OSSM 3 migration guides for GA. Unknown how many migration guides there are at this time (11/11/2024). It would be beneficial to be able to link from differences to the relevent migration guide so that users A) understand the change, esp significant changes like new operator, installing tracing and Kiali separately, gateways, etc. + +:_mod-docs-content-type: CONCEPT +[id="explicitly-create-openshift-routes_{context}"] += Explicitly create OpenShift Routes +//In the ocp-docs repo, there is no attribute for OpenShift Container Platform Ingress Operator so followed https://docs.openshift.com/container-platform/4.17/networking/ingress-operator.html +An OpenShift `Route` resource allows an application to be exposed with a public URL using {ocp-product-title} Ingress Operator for managing HAProxy based Ingress controllers. + +{SMProductName} 2 used Istio OpenShift Routing (IOR) that automatically created and managed OpenShift routes for Istio gateways. While this was convenient, as the Operator managed these routes for you, it also caused confusion around ownership as many `Route` resources are managed by administrators. Istio OpenShift Routing also lacked the ability to configure an independent `Route` resource, created unnecessary routes, and exhibited unpredictable behavior during updates. + +Thus, in {SMProduct} 3, when a `Route` is desired to expose an Istio gateway, you must create and manage it manually. You can also expose an Istio gateway through a Kubernetes service of type `LoadBalancer` if a route is not desired. \ 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 new file mode 100644 index 000000000000..6bb673f0f2b1 --- /dev/null +++ b/modules/ossm-migrating-read-me-independently-managed-gateways.adoc @@ -0,0 +1,27 @@ +// Module included in the following assemblies: +// +// * service-mesh-docs-main/about/ossm-migrating-assembly.adoc + +//Start of an overall Migrating section. +//Section is most likely to be reworked/restructured with OSSM 2 to OSSM 3 migration guides for GA. Unknown how many migration guides there are at this time (11/11/2024). It would be beneficial to be able to link from differences to the relevent migration guide so that users A) understand the change, esp significant changes like new operator, installing tracing and Kiali separately, gateways, etc. + +:_mod-docs-content-type: CONCEPT +[id="ossm-migrating-read-me-independently-managed-istio-gateways_{context}"] += Independently managed Istio gateways + +In Istio, gateways are used to manage traffic entering (ingress) and exiting (egress) the mesh. {SMProductName} 2 deployed and managed an ingress gateway and an egress gateway with the Service Mesh control plane. Both an ingress gateway and an egress gateway were configured using the `ServiceMeshControlPlane` resource. + +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. + +//Note to add GitOps attributes to common-attributes file. Adding attributes is being handled by a different Jira issue, and is outside the scope of this PR. + +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. + +//Note to check if OpenShift Container Platform Infrastructure Nodes (or maybe OpenShift Infrastructure Nodes) has an attribute, and if it does, add it to service-mesh-docs-main _attributes file, which is being handled by a separate Jira and running spreadsheet. \ 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 new file mode 100644 index 000000000000..99574e7d8876 --- /dev/null +++ b/modules/ossm-migrating-read-me-introducing-canary-updates.adoc @@ -0,0 +1,20 @@ +// Module included in the following assemblies: +// +// * service-mesh-docs-main/about/ossm-migrating-assembly.adoc + +//Start of an overall Migrating section. +//Section is most likely to be reworked/restructured with OSSM 2 to OSSM 3 migration guides for GA. Unknown how many migration guides there are at this time (11/11/2024). It would be beneficial to be able to link from differences to the relevent migration guide so that users A) understand the change, esp significant changes like new operator, installing tracing and Kiali separately, gateways, etc. + +:_mod-docs-content-type: CONCEPT +[id="ossm-migrating-read-me-introducing-canary-updatess_{context}"] += Introducing canary updates + +{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. + +{SMProduct} 3 retains support for simple in-place style updates, and adds support for canary-style updatess of the Istio control plane 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`. + +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`. + +Setting your `updateStrategy` to `RevisionBased` also has implications for integrations, such as the cert-manager tool, and gateways. \ No newline at end of file diff --git a/modules/ossm-migrating-read-me-kubernetes-network-policy-management.adoc b/modules/ossm-migrating-read-me-kubernetes-network-policy-management.adoc new file mode 100644 index 000000000000..123ed2c48798 --- /dev/null +++ b/modules/ossm-migrating-read-me-kubernetes-network-policy-management.adoc @@ -0,0 +1,17 @@ +// Module included in the following assemblies: +// +// * service-mesh-docs-main/about/ossm-migrating-assembly.adoc + +//Start of an overall Migrating section. +//Section is most likely to be reworked/restructured with OSSM 2 to OSSM 3 migration guides for GA. Unknown how many migration guides there are at this time (11/11/2024). It would be beneficial to be able to link from differences to the relevent migration guide so that users A) understand the change, esp significant changes like new operator, installing tracing and Kiali separately, gateways, etc. + +:_mod-docs-content-type: CONCEPT +[id="ossm-migrating-read-me-kubernetes-network-policy-management_{context}"] += Kubernetes network policy management + +By default, {SMProductName} 2 created Kubernetes `NetworkPolicy` resources with the following behavior: + +* Ensured network applications and the control plane could communicate with each other. +* Restricted ingress for mesh applications to only member projects. + +{SMProduct} 3 does not create these policies. Instead, you must configure the level of isolation required for your environment. Istio provides fine grained access control of service mesh workloads through Authorization Policies. For more information, see "Authorization Policies". \ No newline at end of file diff --git a/modules/ossm-migrating-read-me-new-operator.adoc b/modules/ossm-migrating-read-me-new-operator.adoc new file mode 100644 index 000000000000..432810a1ba2a --- /dev/null +++ b/modules/ossm-migrating-read-me-new-operator.adoc @@ -0,0 +1,33 @@ +// Module included in the following assemblies: +// +// * service-mesh-docs-main/about/ossm-migrating-read-me-assembly.adoc + +//Start of an overall Migrating section. +//Section is most likely to be reworked/restructured with OSSM 2 to OSSM 3 migration guides for GA. Unknown how many migration guides there are at this time (11/11/2024). It would be beneficial to be able to link from differences to the relevent migration guide so that users A) understand the change, esp significant changes like new operator, installing tracing and Kiali separately, gateways, etc. + +:_mod-docs-content-type: CONCEPT +[id="ossm-migrating-read-me-new-operator_{context}"] += New Operator: The {SMProductName} 3 Operator + +{SMProductName} 3 is a major update with a feature set closer to the link:https://istio.io/[Istio project]. Whereas {SMProduct} 2 was based on the midstream Maistra project, {SMProduct} 3 is based directly on Istio. This means {SMProduct} 3 is managed using a different, simplified Operator and provides greater support for the latest stable features of Istio. + +This alignment with the Istio project along with lessons learned in the first two major releases of {SMProduct} have resulted in the following changes: + +[id="ossm-maistra-to-istio_{context}"] +== From Maistra to Istio + +{SMProduct} 1 and 2 were based on Istio, and included additional functionality that was maintained as part of the midstream Maistra project, but not part of the upstream Istio project. While this provided extra features to {SMProduct} users, the effort to maintain Maistra meant that {SMProduct} 2 was usually several releases behind Istio, and did not support major features like multi-cluster deployment. Since the release of {SMProduct} 1 and 2, Istio has matured to cover most of the use cases addressed by Maistra. + +Basing {SMProduct} 3 directly on Istio ensures that {SMProduct} 3 supports users on the latest stable Istio features while Red{nbsp}Hat contributes directly to the Istio community on behalf of its customers. + +[id="ossm-service-mesh-3-operator_{context}"] +== {SMProduct} 3 Operator + +{SMProduct} 3 uses an Operator that is maintained upstream as the Sail Operator in the *istio-ecosystem* organization on GitHub. The {SMProduct} 3 Operator is smaller in scope and includes significant changes from the Operator used in {SMProduct} 2: + +* The `Istio` resource replaces the `ServiceMeshControlPlane` resource. +* The `IstioCNI` resource manages the Istio Container Network Interface (CNI). +* Red{nbsp}Hat OpenShift Observability components are installed and configured separately. + +//Note for later: update "Red{nbsp}Hate OpenShift Observability" with appropriate attribute when that attribute has been added to the Service Mesh stand alone _attributes file. +//Note that as of 11/18/2024, no attributes in OCP main _attributes file use Red{nbsp}Hat. OCP main _attributes are not in line with current style. \ No newline at end of file diff --git a/modules/ossm-migrating-read-me-new-resources.adoc b/modules/ossm-migrating-read-me-new-resources.adoc new file mode 100644 index 000000000000..30f0e0b64288 --- /dev/null +++ b/modules/ossm-migrating-read-me-new-resources.adoc @@ -0,0 +1,40 @@ +// Module included in the following assemblies: +// +// * service-mesh-docs-main/about/ossm-migrating-assembly.adoc + +//Start of an overall Migrating section. +//Section is most likely to be reworked/restructured with OSSM 2 to OSSM 3 migration guides for GA. Unknown how many migration guides there are at this time (11/11/2024). It would be beneficial to be able to link from differences to the relevent migration guide so that users A) understand the change, esp significant changes like new operator, installing tracing and Kiali separately, gateways, etc. + +:_mod-docs-content-type: CONCEPT +[id="ossm-migrating-read-me-new-resources_{context}"] += New resources in {SMProduct} 3 + +{SMProductName} 3 uses two new resources: + +* `Istio` resource +* `IstioCNI` resource + +[id="ossm-istio-resource-replaces-smcp_{context}"] +== The Istio resource replaces the ServiceMeshControlPlane resource + +{SMProduct} 2 uses a resource called `ServiceMeshControlPlane` to configure Istio. In {SMProduct} 3, the `ServiceMeshControlPlane` resource is replaced with a resource called `Istio`. + +The `Istio` resource contains a `spec.values` field that derives its schema from Istio's Helm chart values. This means that configuration examples from the community Istio documentation can often be applied directly to the {SMProduct} 3 `Istio` resource. + +The `Istio` resource provides an additional validation schema enabling the ability to explore the resource running the following the {ocp-short-name} command line interface (CLI) command: + +[source,terminal] +---- +$ oc explain istios.spec.values +---- + +//Note that there might be an attribute for OpenShift CLI. Check main _attributes file, and if there is an attribute for it, add it to list for service-mesh-docs-main _attributes file. + +[id="ossm-new-resource-istiocni_{context}"] +== New resource: IstioCNI + +The Istio Container Network Interface (CNI) node agent is used to configure traffic redirection for pods in the mesh. It runs as a daemon set, on every node, with elevated privileges. + +In {SMProduct} 2, the Operator deployed an Istio CNI instance for each minor version of Istio present in the cluster, and pods were automatically annotated during sidecar injection so they picked up the correct Istio CNI. While this meant that the management of Istio CNI was mostly hidden from you, it obscured the fact that the Istio CNI agent has an independent lifecycle from the Istio control plane and, in some cases, the Istio CNI agent must be be upgraded separately. + +For these reasons, the {SMProduct} 3 Operator manages the Istio CNI node agent with a separate resource called `IstioCNI`. A single instance of this resource is shared by all Istio control planes, which are managed by `Istio` resources. diff --git a/modules/ossm-migrating-read-me-observability-integrations.adoc b/modules/ossm-migrating-read-me-observability-integrations.adoc new file mode 100644 index 000000000000..b3ee8f7a2c4f --- /dev/null +++ b/modules/ossm-migrating-read-me-observability-integrations.adoc @@ -0,0 +1,24 @@ +// Module included in the following assemblies: +// +// * service-mesh-docs-main/about/ossm-migrating-assembly.adoc + +//Start of an overall Migrating section. +//Section is most likely to be reworked/restructured with OSSM 2 to OSSM 3 migration guides for GA. Unknown how many migration guides there are at this time (11/11/2024). It would be beneficial to be able to link from differences to the relevent migration guide so that users A) understand the change, esp significant changes like new operator, installing tracing and Kiali separately, gateways, etc. + +:_mod-docs-content-type: CONCEPT +[id="ossm-migrating-read-me-observability-integrations_{context}"] += Independent Red{nbsp}Hat OpenShift Observability component integrations and configurations + +A significant change in {SMProductName} 3 is that the Operator no longer installs and manages observability components such as Prometheus and Grafana with the Istio control plane. It also no longer installs and manages {DTProductName} components such as {TempoShortName} and {OTELName} (previously Jaeger and Elasticsearch), or Kiali. + +The {SMProduct} 3 Operator limits its scope to Istio-related resources, with observability components supported and managed by the independent Operators that make up Red{nbsp}Hat OpenShift Observability, such as the following: + +//Note to add Observability attributes. Adding attributes is being handled by a different Jira issue, and is outside the scope of this PR. + +* Logging +* User workload monitoring +* {DTProductName} + +Kiali and the {SMPlugin} are still supported with the {KialiProduct}. + +This simplification greatly reduces the footprint and complexity of {SMProduct} 3, while providing better, production-grade support for observability through Red{nbsp}Hat OpenShift Observability components. \ No newline at end of file diff --git a/modules/ossm-migrating-read-me-scoping-discovery-selectors.adoc b/modules/ossm-migrating-read-me-scoping-discovery-selectors.adoc new file mode 100644 index 000000000000..490ad0b91cc1 --- /dev/null +++ b/modules/ossm-migrating-read-me-scoping-discovery-selectors.adoc @@ -0,0 +1,14 @@ +// Module included in the following assemblies: +// +// * service-mesh-docs-main/about/ossm-migrating-assembly.adoc + +//Start of an overall Migrating section. +//Section is most likely to be reworked/restructured with OSSM 2 to OSSM 3 migration guides for GA. Unknown how many migration guides there are at this time (11/11/2024). It would be beneficial to be able to link from differences to the relevent migration guide so that users A) understand the change, esp significant changes like new operator, installing tracing and Kiali separately, gateways, etc. + +:_mod-docs-content-type: CONCEPT +[id="ossm-migrating-read-me-scoping-discovery-selectors_{context}"] += Scoping of the mesh with discoverySelectors and labels + +In {SMProduct} 2.4, a _cluster-wide_ mode was introduced to allow a mesh to be cluster-scoped, with the option to limit the mesh using an Istio feature called `discoverySelectors`. Using `discoverySelectors` limits the Istio control plane's visibility to a set of namespaces defined with a label selector. This aligned with how community Istio worked, and allowed Istio to manage cluster-level resources. For more information, see "Labels and Selectors". + +{SMProduct} 3 makes all meshes cluster-wide by default. This change means that Istio control planes are all cluster-scoped resources and the resources `ServiceMeshMemberRoll` and `ServiceMeshMember` are no longer present, with control planes watching, or _discovering_, the entire cluster by default. The control plane's discovery of namespaces can be limited using the `discoverySelectors` feature. diff --git a/modules/ossm-migrating-read-me-sidecar-injection-considerations.adoc b/modules/ossm-migrating-read-me-sidecar-injection-considerations.adoc new file mode 100644 index 000000000000..90bd2d948b18 --- /dev/null +++ b/modules/ossm-migrating-read-me-sidecar-injection-considerations.adoc @@ -0,0 +1,39 @@ +// Module included in the following assemblies: +// +// * service-mesh-docs-main/about/ossm-migrating-assembly.adoc + +//Start of an overall Migrating section. +//Section is most likely to be reworked/restructured with OSSM 2 to OSSM 3 migration guides for GA. Unknown how many migration guides there are at this time (11/11/2024). It would be beneficial to be able to link from differences to the relevent migration guide so that users A) understand the change, esp significant changes like new operator, installing tracing and Kiali separately, gateways, etc. + +:_mod-docs-content-type: CONCEPT +[id="ossm-migrating-read-me-sidecar-injection-considerations_{context}"] += New considerations for sidecar injection + +{SMProductName} 2 supported using pod annotations and labels to configure sidecar injection and there was no need to indicate which control plane a workload belonged to. + +With {SMProduct} 3, even though the Istio control plane discovers a namespace, the workloads present in that namespace still require sidecar proxies to be included as workloads in the service mesh, and to be able to use Istio's many features. + +In {SMProduct} 3, sidecar injection works the same way as it does for Istio, with pod or namespace labels used to trigger sidecar injection. However, it might be necessary to include a label that indicates which control plane the workload belongs to. + +[NOTE] +==== +The Istio Project has deprecated pod annotations in favor of labels for sidecar injection. +==== + +When an `Istio` resource has the name `default` and `InPlace` upgrades are used, there is a single `IstioRevision` with the name `default` and the label `istio-injection=enabled` for sidecar injection. + +However, an `IstioRevision` resource is required to have a different name in the following cases: + +* Multiple control plane instances are present. +* A `RevisionBased`, canary-style control plane upgrade is in progress. + +If there are running multiple control plane instances, or you chose the `RevisionBased` update strategy during your {SMProduct} 3 installation, then an `IstioRevision` resource is required to have a different name than `default`. When that happens, it is necessary to use a label that indicates which control plane revision the workloads belong to by specifying `istio.io/rev=`. + +These labels can be applied at the workload or namespace level. + +You can inspect available revisions by running the following command: + +[source,terminal] +---- +$ oc get istiorevision +---- \ No newline at end of file diff --git a/modules/ossm-migrating-read-me-support-for-istioctl.adoc b/modules/ossm-migrating-read-me-support-for-istioctl.adoc new file mode 100644 index 000000000000..5d975dd99268 --- /dev/null +++ b/modules/ossm-migrating-read-me-support-for-istioctl.adoc @@ -0,0 +1,34 @@ +// Module included in the following assemblies: +// +// * service-mesh-docs-main/about/ossm-migrating-assembly.adoc + +//Start of an overall Migrating section. +//Section is most likely to be reworked/restructured with OSSM 2 to OSSM 3 migration guides for GA. Unknown how many migration guides there are at this time (11/11/2024). It would be beneficial to be able to link from differences to the relevent migration guide so that users A) understand the change, esp significant changes like new operator, installing tracing and Kiali separately, gateways, etc. + +:_mod-docs-content-type: CONCEPT +[id="ossm-migrating-read-me-support-for-istioctl_{context}"] += Support for Istioctl + +{SMProductName} 1 and 2 did not include support for Istioctl, the command line utility for the Istio project that includes many diagnostic and debugging utilities. {SMProduct} 3 introduces support for Istioctl for select commands. + +.Supported Istioctl commands +[cols="1,1"] +|=== +|Command |Description + +|`admin` | Manage control plane (`istiod`) configuration +|`analyze` | Analyze Istio configuration and print validation messages +|`bug-report` | Cluster information and log capture support tool +|`completion` | Generate the autocompletion script for the specified shell +|`create-remote-secret` | Create a secret with credentials to allow Istio to access remote Kubernetes `apiservers` +|`help` | Help about any command +|`manifest` | Commands related to Istio manifests +|`proxy-config` | Retrieve information about proxy configuration from Envoy (Kubernetes only) +|`proxy-status` | Retrieves the synchronization status of each Envoy in the mesh +|`remote-clusters` | Lists the remote clusters each `istiod` instance is connected to +|`version` | Prints out build version information +|=== + +//table for supported commands may need to be included in prod doc instructions for Istioctl, if Istioctl procedure content is to be included in prod docs. As of 11/11/2024, there is no additional prod doc content for Istioctl. It is upstream https://github.com/openshift-service-mesh/sail-operator/blob/55e26da369c897583a578b6a622b70c9ff67beb9/docs/ossm/istioctl/README.md#supported-commands but that may change for GA. + +Installation and management of Istio is only supported by the {SMProduct} 3 Operator. \ No newline at end of file diff --git a/modules/ossm-migrating-read-me-support-for-multiple-control-planes.adoc b/modules/ossm-migrating-read-me-support-for-multiple-control-planes.adoc new file mode 100644 index 000000000000..914742eb9e81 --- /dev/null +++ b/modules/ossm-migrating-read-me-support-for-multiple-control-planes.adoc @@ -0,0 +1,16 @@ +// Module included in the following assemblies: +// +// * service-mesh-docs-main/about/ossm-migrating-assembly.adoc + +//Start of an overall Migrating section. +//Section is most likely to be reworked/restructured with OSSM 2 to OSSM 3 migration guides for GA. Unknown how many migration guides there are at this time (11/11/2024). It would be beneficial to be able to link from differences to the relevent migration guide so that users A) understand the change, esp significant changes like new operator, installing tracing and Kiali separately, gateways, etc. + +:_mod-docs-content-type: CONCEPT +[id="ossm-migrating-read-me-support-multiple-control-planes_{context}"] += Support for multiple control planes + +{SMProductName} 3 supports multiple service meshes in the same cluster, but in a different manner than in {SMProduct} 2. A cluster administrator must create multiple `Istio` instances and then configure `discoverySelectors` appropriately to ensure that there is no overlap between mesh namespaces. + +As `Istio` resources are cluster-scoped, they must have unique names to represent unique meshes within the same cluster. The {SMProduct} 3 Operator uses this unique name to create a resource called `IstioRevision` with a name in the format of `{Istio name}` or `{Istio name}-{Istio version}`. + +Each instance of `IstioRevision` is responsible for managing a single control plane. Workloads are assigned to a specific control plane using Istio's revision labels of the format `istio.io/rev={IstioRevision name}`. The name with the version identifier becomes important to support canary-style control plane upgrades. \ No newline at end of file diff --git a/modules/ossm-migrating-read-me-supported-multi-cluster-topologies.adoc b/modules/ossm-migrating-read-me-supported-multi-cluster-topologies.adoc new file mode 100644 index 000000000000..fb9887de8505 --- /dev/null +++ b/modules/ossm-migrating-read-me-supported-multi-cluster-topologies.adoc @@ -0,0 +1,24 @@ +// Module included in the following assemblies: +// +// * service-mesh-docs-main/about/ossm-migrating-assembly.adoc + +//Start of an overall Migrating section. +//Section is most likely to be reworked/restructured with OSSM 2 to OSSM 3 migration guides for GA. Unknown how many migration guides there are at this time (11/11/2024). It would be beneficial to be able to link from differences to the relevent migration guide so that users A) understand the change, esp significant changes like new operator, installing tracing and Kiali separately, gateways, etc. + +:_mod-docs-content-type: CONCEPT +[id="ossm-migrating-read-me-supported-multi-cluster-topologies_{context}"] += Supported multi-cluster topologies + +{SMProductName} 2 supported one form of multi-cluster, _federation_, which was introduced in {SMProduct} 2.1. Each cluster maintained its own independent control plane in this topology, with services only shared between those meshes on an as-needed basis. + +Communication between federated meshes is through Istio gateways, so there was no need for Service Mesh control planes to watch remote Kubernetes control planes, as is the case with Istio's multi-cluster service mesh topologies. Federation is ideal where service meshes are loosely coupled, such as those managed by different administrative teams. + +{SMProduct} 3 introduces support for the following Istio multi-cluster topologies as well: + +* Multi-Primary +* Primary-Remote +* External control planes + +These topologies effectively stretch a single, unified service mesh across multiple clusters, which is ideal when all clusters involved are managed by the same administrative team. Istio's multi-cluster topologies are also ideal for implementing high-availability or failover use cases across a commonly managed set of applications. + +//Note that this section may need to be updated when federation is supported in OSSM 3. As of 11/12/2024: federation topology is not supported in OSSM 3. \ No newline at end of file diff --git a/modules/ossm-migrating-read-me-tls-configuration-change.adoc b/modules/ossm-migrating-read-me-tls-configuration-change.adoc new file mode 100644 index 000000000000..4ae3ab3778c7 --- /dev/null +++ b/modules/ossm-migrating-read-me-tls-configuration-change.adoc @@ -0,0 +1,23 @@ + +// Module included in the following assemblies: +// +// * service-mesh-docs-main/about/ossm-migrating-assembly.adoc + +//Start of an overall Migrating section. +//Section is most likely to be reworked/restructured with OSSM 2 to OSSM 3 migration guides for GA. Unknown how many migration guides there are at this time (11/11/2024). It would be beneficial to be able to link from differences to the relevent migration guide so that users A) understand the change, esp significant changes like new operator, installing tracing and Kiali separately, gateways, etc. + +:_mod-docs-content-type: CONCEPT +[id="ossm-migrating-read-me-transport-layer-security-configuration-change_{context}"] += Transport layer security (TLS) configuration change + +In {SMProductName} 2, you created the `ServiceMeshControlPlane` resource, and enabled mTLS strict mode by setting `spec.security.dataPlane.mtls` to `true`. + +You were able to set the minimum and maximum TLS protocol versions by setting the `spec.security.controlPlane.tls.minProtocolVersion` or `spec.security.controlPlane.tls.maxProtocolVersion` in your `ServiceMeshControlPlane` resource. + +In {SMProduct} 3, the `Istio` resource replaces the `ServiceMeshControlPlane` resource and does not include these settings. + +To enable enable mTLS strict mode in {SMProduct} 3, you must apply the corresponding `PeerAuthentication` and `DestinationRule` resources. + +In {SMProduct} 3, you can enable the minimum TLS protocol by setting `spec.meshConfig.tlsDefaults.minProtocolVersion` in your `Istio` resource. For more information, see "Istio Workload Minimum TLS Version Configuration". + +In {SMProduct} 2 and {SMProduct} 3, `auto mTLS` remains enabled by default. \ No newline at end of file