OSSM-8507 Migration guide for multitenant 2.6

_topic_maps/_topic_map.yml

@@ -22,8 +22,6 @@ Topics:
     File: ossm-migrating-premigration-checklists-assembly
   - Name: Migrating network policies for security purposes
     File: ossm-migrating-network-policies-security-assembly
-  - Name: Migrating with cert-manager
-    File: ossm-migrating-cert-manager-assembly
   - Name: Kiali differences for Service Mesh 3
     File: ossm-migrating-kiali-differences-assembly
     #Kiali PR https://github.com/openshift/openshift-docs/pull/88193

migrating/docinfo.xml

@@ -10,4 +10,3 @@
     <orgname>Red Hat OpenShift Documentation Team</orgname>
 </authorgroup>
 <xi:include href="Common_Content/Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
-

migrating/done/ossm-migrating-complete-assembly.adoc

@@ -2,6 +2,15 @@
 [id=ossm-migrating-complete-assembly.adoc]
 = Completing the Migration
 include::_attributes/common-attributes.adoc[]
-:context: ossm-migrating-deleting-2-6-assembly
+:context: ossm-migrating-complete-assembly
 
 toc::[]
+
+include::modules/ossm-migrating-complete-multitant-cert-manager.adoc[leveloffset=+1]
+
+.Next steps
+
+* Remove {Smproduct} 2
+
+//exrefs handled by OSSM-8852
+//may not be necessary; will depend on all the other migrating complete content in other PRs

migrating/multitenant/docinfo.xml

@@ -1,12 +1,12 @@
 <title>Multitenant migration guide</title>
 <productname>{product-title}</productname>
 <productnumber>{product-version}</productnumber>
-<subtitle>Migrating a multitenant deployment</subtitle>
+<subtitle>Multitenant migration guide</subtitle>
 <abstract>
-    <para>This document provides important information and step-by-step procedures for migrating a multitenant deployment from OpenShift Service Mesh 2 to OpenShift Service Mesh 3.
+    <para>This document provides important information for migrating a multitenant deployment, and a multitenant deployment with the cert-manager tool.
     </para>
 </abstract>
 <authorgroup>
     <orgname>Red Hat OpenShift Documentation Team</orgname>
 </authorgroup>
-<xi:include href="Common_Content/Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+<xi:include href="Common_Content/Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />

migrating/multitenant/ossm-migrating-multitenant-assembly.adoc

@@ -6,3 +6,48 @@ include::_attributes/common-attributes.adoc[]
 
 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.
+
+* Migrate gateways
+//<insert exref to gateway migration content>
+//xrefs across Migration Guides will be handled by OSSM-8852
+
+If you are not using gateways, and have verified your mulitenant migration, you can proceed to complete the migration and remove {SMProduct} 2 resources.
+
+* Cleanup {SMProduct} 2
+//<insert exref to done dir>
+//xrefs across Migration Guides will be handled by OSSM-8852
+
+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
+
+If you are using gateways, you must migrate them before you can complete the migration process for your deployment and workloads.
+
+* Migrate gateways
+//<insert exref to gateway migration content>
+//xrefs across Migration Guides are handled by OSSM-8852
+
+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.
+
+* Complete your migration with cert-manager
+//<insert exreft to complete-cert-manager>
+//xrefs across Migration Guides will be handled by OSSM-8852
+
+
+//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.

modules/ossm-migrating-a-multitenant-deployment.adoc

@@ -0,0 +1,68 @@
+// Module included in the following assemblies:
+//
+// * service-mesh-docs-main/migrating/checklists/ossm-migrating-multitenant-assembly.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="migrating-a-multitenant-deployment_{context}""]
+= Migrating a multitenant deployment
+
+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".
+
+You can follow these same steps with your own workloads.
+
+.Prerequisites
+
+* You have deployed {ocp-product-title} 4.14 or later.
+* You are logged in to the {ocp-product-title} web console as a user with the cluster-admin role.
+* You have completed the premigration checklists.
+* You have the {SMProduct} {SMv2Version} Operator installed.
+* You have the {SMProduct} 3 Operator installed.
+* You created an `IstioCNI` resource.
+* You have the `istioctl` tool installed.
+* You are running a `MultiTenant` `ServiceMeshControlPlane`.
+* You have installed the `bookinfo` application.
+
+.Procedure
+
+. Create your `Istio` resource.
++
+.Example `Istio` resource
++
+[source,yaml]
+----
+apiVersion: sailoperator.io/v1
+kind: Istio
+metadata:
+  name: istio-tenant-a
+  spec:
+    namespace: istio-system-tenant-a <1>
+    version: v1.24.3
+    values:
+      meshConfig:
+        discoverySelectors: <2>
+          - matchLabels:
+              tenant: tenant-a
+    extensionProviders:  <3>
+      - name: prometheus
+        prometheus: {}
+      - name: otel
+        opentelemetry:
+          port: 4317
+          service: otel-collector.opentelemetrycollector-3.svc.cluster.local
+----
++
+<1> The `spec.namespace` field in your `Istio` resource must be the same namespace as your `ServiceMeshControlPlane` resource. If you set the `spec.namespace` field in your `Istio` resource to a different namespace than your `ServiceMeshControlPlane` resource, the migration does not complete successfully.
+<2> By default, control planes watch the entire cluster. When managing multiple control planes on a single cluster, you must narrow the scope of each control plane by setting `discoverySelectors` fields. In this example, the label `tenant` is used, but you can use any label or combination of labels.
+<3> Optional: If you are migrating metrics and tracing, update the `extensionProviders` fields according to your tracing and metrics configurations.
+
+. Add your `tenant` label to each one of your dataplane namespaces by running the following command for each dataplane namespace:
++
+[source,terminal]
+----
+$ oc label ns bookinfo tenant=tenant-a
+----
++
+[NOTE]
+====
+With {SMProduct} 2.6, namespaces were enrolled into the mesh by adding them to the `ServiceMeshMemberRoll` resource. In {SMProduct} 3, you must label each one of your dataplane namespaces to match your `discoverySelectors` fields.
+====

modules/ossm-migrating-complete-multitant-cert-manager.adoc

@@ -0,0 +1,28 @@
+
+// Module included in the following assemblies:
+//
+// * service-mesh-docs-main/multitenant/ossm-migrating-multitenant-assembly.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="migrating-complete-multitant-cert-manager_{context}""]
+= Completing a multitenant deployment with cert-manager
+
+.Prerequisites
+
+* You have migrated a multitenant deployment with the cert-manager and istio-csr tools.
+
+.Procedure
+
+. Verify that your new injection label is present in all workload namespaces.
+
+. Update the `app.controller.configmapNamespaceSelector` field by running the following command:
++
+[source,terminal]
+----
+helm upgrade cert-manager-istio-csr jetstack/cert-manager-istio-csr \
+   --install \
+   --reuse-values \
+   --namespace istio-system \
+   --wait \
+   --set "app.controller.configmapNamespaceSelector=tenant=tenant-a"
+----

modules/ossm-migrating-multitenant-with-cert-manager.adoc

@@ -0,0 +1,113 @@
+
+// Module included in the following assemblies:
+//
+// * service-mesh-docs-main/multitenant/ossm-migrating-multitenant-assembly.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="migrating-multitenant-with-cert-manager_{context}""]
+= Migrating a multitenant deployment with cert-manager
+
+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".
+
+You can follow these same steps with your own workloads.
+
+.Prerequisites
+
+* You have deployed {ocp-product-title} 4.14 or later.
+* You are logged in to the {ocp-product-title} web console as a user with the cluster-admin role.
+* You have completed the premigration checklists.
+* You have the {SMProduct} {SMv2Version} Operator installed.
+* You have the {SMProduct} 3 Operator installed.
+* You created an `IstioCNI` resource.
+* You have the `istioctl` tool installed.
+* You are using the cert-manager and istio-csr tools in a multitenant deployment.
+//change to "You are using the cert-manager and istio-csr tools in a cluster-wide deployment" for the cluster-wide procedure
+* Your {SMProduct} 2 `ServiceMeshControlPlane` is configured with the cert-manager tool.
+
+.Procedure
+
+. Check that your {SMProduct} 2 `ServiceMeshControlPlane` is configured with the cert-manager-tool:
++
+.Example `ServiceMeshControlPlane` cert-manager configuration
+[source,yaml]
+----
+apiVersion: maistra.io/v2
+kind: ServiceMeshControlPlane
+metadata:
+  name: basic
+  namespace: istio-system
+spec:
+  ...
+  security:
+    certificateAuthority:
+      cert-manager:
+        address: cert-manager-istio-csr.istio-system.svc:443
+      type: cert-manager
+    dataPlane:
+      mtls: true
+    identity:
+      type: ThirdParty
+    manageNetworkPolicy: false
+----
+
+. Update the `istio-csr` deployment to include your {SMProduct} 3 control plane by running the following command:
++
+[source,terminal]
+----
+  helm upgrade cert-manager-istio-csr jetstack/cert-manager-istio-csr \
+      --install \
+      --reuse-values \
+      --namespace istio-system \
+      --wait \
+      --set "app.istio.revisions={basic,istio-tenant-a}" <1>
+----
++
+<1> The `app.istio.revisions` field needs to include your {SMProduct} 3.0 control plane revision _before_ you create your `Istio` resource so that proxies can properly communicate with the {SMProduct} 3.0 control plane.
+
+. Create your `Istio` resource.
++
+.Example `Istio` resource with cert-manager
++
+[source,yaml]
+----
+apiVersion: sailoperator.io/v1
+kind: Istio
+metadata:
+  name: istio-tenant-a
+spec:
+  namespace: istio-system-tenant-a <1>
+  version: v1.24.3
+  values:
+    meshConfig:
+      discoverySelectors:
+        - matchLabels:
+            tenant: tenant-a <2>
+      extensionProviders:  <3>
+        - name: prometheus
+          prometheus: {}
+        - name: otel
+          opentelemetry:
+           port: 4317
+          service: otel-collector.opentelemetrycollector-3.svc.cluster.local
+  global:
+    caAddress: cert-manager-istio-csr.istio-system.svc:443
+    pilot:
+      env:
+        ENABLE_CA_SERVER: "false"
+----
++
+<1> The `spec.namespace` field in your `Istio` resource must be the _same_ namespace as your `ServiceMeshControlPlane` resource. If you set the `spec.namespace` field in your `Istio` resource to a different namespace than your `ServiceMeshControlPlane` resource, the migration will not work properly.
+<2> By default, control planes watch the entire cluster. When managing multiple control planes on a single cluster, you must narrow the scope of each control plane by setting `discoverySelectors` fields. In this example, the label `tenant` is used, but you can use any label or combination of labels.
+<3> Optional: If you are migrating metrics and tracing, update the `extensionProviders` fields according to your tracing and metrics configurations.
+
+. Add your `tenant` label to each one of your dataplane namespaces by running the following command for each dataplane namespace:
++
+[source,terminal]
+----
+$ oc label ns bookinfo tenant=tenant-a
+----
++
+[NOTE]
+====
+With {SMProduct} 2.6, namespaces were enrolled into the mesh by adding them to the `ServiceMeshMemberRoll` resource. In {SMProduct} 3, you must label each one of your dataplane namespaces to match your `discoverySelectors` fields.
+====