OSSM-9383: Apply conditions to cluster-wide migration tasks

Author: rh-tokeefe

migrating/cluster-wide/ossm-migrating-cluster-wide.adoc

@@ -31,13 +31,14 @@ include::modules/ossm-control-plane-configuration-migration-requirements.adoc[le
 
 include::modules/ossm-cluster-wide-migration-methods.adoc[leveloffset=+1]
 
-// The following tasks are for migration using the Istio revision label
+// This sets the context to build the tasks for cluster-wide migration using the Istio revision label 
+:context: cw-revision
+
 include::modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-revision-label.adoc[leveloffset=+1]
 
 include::modules/ossm-migrating-workloads-using-the-istio-revision-label.adoc[leveloffset=+2]
 
-[id="next-steps-istio-revision_{context}"]
-== Next steps
+.Next steps
 
 If you are using gateways, you must migrate them before you complete the migration process.
 
@@ -47,13 +48,14 @@ If you are not using gateways, and have verified your cluster-wide migration, yo
 
 * xref:../../migrating/done/ossm-migrating-complete.adoc#ossm-migrating-complete[Completing the Migration]
 
-//The following tasks are for migrating using the Istio revision label with cert-manager
-include::modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-revision-label-with-cert-manager.adoc[leveloffset=+1]
+// This sets the context to build the tasks for cluster-wide migration using the Istio revision label with cert-manager tasks
+:context: cw-revision-cm
+
+include::modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-revision-label.adoc[leveloffset=+1]
 
-include::modules/ossm-migrating-workloads-using-the-istio-revision-label-with-cert-manager.adoc[leveloffset=+2]
+include::modules/ossm-migrating-workloads-using-the-istio-revision-label.adoc[leveloffset=+2]
 
-[id="next-steps-istio-revision-with-cert-manager_{context}"]
-== Next steps
+.Next steps
 
 If you are using gateways, you must migrate them before you complete the migration process.
 
@@ -63,14 +65,14 @@ If you are not using gateways, and have verified your cluster-wide migration, yo
 
 * xref:../../migrating/done/ossm-migrating-complete.adoc#ossm-migrating-complete[Completing the Migration]
 
-// The following tasks are for migrating using the Istio injection label
+// This sets the context to build the tasks for cluster-wide migration using the Istio injection label
+:context: cw-injection
 
 include::modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-injection-label.adoc[leveloffset=+1]
 
 include::modules/ossm-migrating-workloads-using-the-istio-injection-label.adoc[leveloffset=+2]
 
-[id="next-steps-istio-injection_{context}"]
-== Next steps
+.Next steps
 
 If you are using gateways, you must migrate them before you complete the migration process.
 
@@ -80,8 +82,7 @@ If you are not using gateways, and have verified your cluster-wide migration, cr
 
 include::modules/ossm-creating-a-default-revision-tag-and-relabeling-the-namespaces.adoc[leveloffset=+2]
 
-[id="next-steps-istio-injection-relabel_{context}"]
-== Next steps
+.Next steps
 
 You can proceed to complete the migration and remove {SMProduct} 2 resources.
 
@@ -92,14 +93,14 @@ You can proceed to complete the migration and remove {SMProduct} 2 resources.
 Before creating a default revision tag and relabelling the namespaces, you must migrate all remaining workload namespaces, including gateways.
 ====
 
-// The following tasks are for migration using the Istio injection label with cert-manager
+// This sets the context to build the tasks for cluster-wide migration using the Istio injection label with cert-manager
+:context: cw-injection-cm
 
-include::modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-injection-label-with-cert-manager.adoc[leveloffset=+1]
+include::modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-injection-label.adoc[leveloffset=+1]
 
-include::modules/ossm-migrating-workloads-using-the-istio-injection-label-with-cert-manager.adoc[leveloffset=+2]
+include::modules/ossm-migrating-workloads-using-the-istio-injection-label.adoc[leveloffset=+2]
 
-[id="next-steps-istio-injection-with-cert-manager_{context}"]
-== Next steps
+.Next steps
 
 If you are using gateways, you must migrate them before you complete the migration process.
 
@@ -114,12 +115,13 @@ Before creating a default revision tag and relabelling the namespaces, you must
 
 include::modules/ossm-creating-a-default-revision-tag-and-relabeling-the-namespaces-with-cert-manager.adoc[leveloffset=+2]
 
-//Te following tasks are for migration using the simple migration method
+:context: ossm-migrating-cluster-wide
+
+//The following tasks are for migration using the simple migration method
 include::modules/ossm-migrating-a-cluster-wide-deployment-using-the-simple-migration-method.adoc[leveloffset=+1]
 include::modules/ossm-migrating-workloads-using-the-simple-migration-method.adoc[leveloffset=+2]
 
-[id="next-steps-simple-migration_{context}"]
-== Next steps
+.Next steps
 
 If you are using gateways, you must migrate them before you complete the migration process.
 
@@ -133,4 +135,4 @@ If you are not using gateways, you can complete your migration.
 [id="additional-resources_{context}"]
 == Additional resources
 
-* xref:../../install/ossm-sidecar-injection.adoc#ossm-identifying-revision-name_ossm-sidecar-injection[Identifying the revision name]
+* xref:../../install/ossm-sidecar-injection.adoc#ossm-identifying-revision-name_ossm-sidecar-injection[Identifying the revision name]

modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-injection-label.adoc

@@ -2,9 +2,18 @@
 //
 // * service-mesh-docs-main/migrating/cluster-wide/ossm-migrating-cluster-wide.adoc
 
+ifeval::["{context}" == "cw-injection"]
+:ossm-cluster-wide-istio-injection:
+endif::[]
+ifeval::["{context}" == "cw-injection-cm"]
+:ossm-cert-manager-istio-injection:
+endif::[]
+
 :_mod-docs-content-type: PROCEDURE
 [id="ossm-migrating-a-cluster-wide-deployment-using-the-istio-injection-label_{context}"]
-= Migrating a cluster-wide deployment by using the istio injection label
+//= Migrating a cluster-wide deployment by using the Istio injection label
+ifdef::ossm-cluster-wide-istio-injection[= Migrating a cluster-wide deployment by using the Istio injection label]
+ifdef::ossm-cert-manager-istio-injection[= Migrating a cluster-wide deployment by using the Istio injection label with cert-manager]
 
 You can perform a canary upgrade with the gradual migration of data plane namespaces for a cluster-wide deployment by using the `istio-injection=enabled` label and the `default` revision tag.
 
@@ -21,11 +30,57 @@ The `bookinfo` application is used as an example for the `Istio` resource. For m
 * You have the {SMProduct} 3 Operator installed.
 * You have created an `IstioCNI` resource.
 * You have installed the `istioctl` tool.
+ifdef::ossm-cluster-wide-istio-injection[]
 * You are running a cluster-wide Service Mesh control plane resource.
+endif::[]
+ifdef::ossm-cert-manager-istio-injection[]
+* You are using the cert-manager and istio-csr tools in a cluster-wide deployment.
+* Your {SMProduct} {SMv2Version} `ServiceMeshControlPlane` resource is configured with the cert-manager tool
+endif::[]
 * You have installed the `bookinfo` application.
 
 .Procedure
 
+ifdef::ossm-cert-manager-istio-injection[]
+. Confirm that your {SMProduct} 2 `ServiceMeshControlPlane` resource 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,ossm-3-v1-24-3}" <1>
+----
++
+<1> The `app.istio.revisions` field must 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. 
+endif::[]
+
 . Identify the namespaces that contain a 2.6 control plane by running the following command:
 +
 [source,terminal]
@@ -98,4 +153,11 @@ $ oc logs deployments/istiod-ossm-3-v1-24-3 -n istio-system | grep 'Load signing
 [source,terminal]
 ----
 2024-12-18T08:13:53.788959Z	info	pkica	Load signing key and cert from existing secret istio-system/istio-ca-secret
-----
+----
+
+ifeval::["{context}" == "cw-injection"]
+:!ossm-cluster-wide-istio-injection:
+endif::[]
+ifeval::["{context}" == "cw-injection-cm"]
+:!ossm-cert-manager-istio-injection:
+endif::[]

modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-revision-label.adoc

@@ -2,9 +2,17 @@
 //
 // * service-mesh-docs-main/migrating/cluster-wide/ossm-migrating-cluster-wide.adoc
 
+ifeval::["{context}" == "cw-revision"]
+:ossm-cluster-wide-istio-revision:
+endif::[]
+ifeval::["{context}" == "cw-revision-cm"]
+:ossm-cert-manager-istio-revision:
+endif::[]
+
 :_mod-docs-content-type: PROCEDURE
 [id="ossm-migrating-a-cluster-wide-deployment-using-the-istio-revision-label_{context}"]
-= Migrating a cluster-wide deployment by using the Istio revision label
+ifdef::ossm-cluster-wide-istio-revision[= Migrating a cluster-wide deployment by using the Istio revision label]
+ifdef::ossm-cert-manager-istio-revision[= Migrating a cluster-wide deployment by using the Istio revision label with cert-manager]
 
 You can perform a canary upgrade with the gradual migration of data plane namespaces for a cluster-wide deployment by using the `istio.io/rev` label.
 
@@ -15,17 +23,63 @@ 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 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 cluster-wide Service Mesh control plane.
+* You have created an `IstioCNI` resource.
+* You have installed the `istioctl` tool.
+ifdef::ossm-cluster-wide-istio-revision[]
+* You are running a cluster-wide Service Mesh control plane resource.
+endif::[]
+ifdef::ossm-cert-manager-istio-revision[]
+* You are using the cert-manager and istio-csr tools in a cluster-wide deployment.
+* Your {SMProduct} {SMv2Version} `ServiceMeshControlPlane` resource is configured with the cert-manager tool.
+endif::[]
 * You have installed the `bookinfo` application.
 
 .Procedure
 
+ifdef::ossm-cert-manager-istio-revision[]
+. Confirm that your {SMProduct} 2 `ServiceMeshControlPlane` resource 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,ossm-3-v1-24-3}" <1>
+----
++
+<1> The `app.istio.revisions` field must 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. 
+endif::[]
+
 . Identify the namespaces that contain a 2.6 control plane by running the following command:
 +
 [source,terminal]
@@ -91,4 +145,11 @@ $ oc logs deployments/istiod-ossm-3-v1-24-3 -n istio-system | grep 'Load signing
 [source,terminal]
 ----
 2024-12-18T08:13:53.788959Z	info	pkica	Load signing key and cert from existing secret istio-system/istio-ca-secret
-----
+----
+
+ifeval::["{context}" == "cw-revision"]
+:!ossm-cluster-wide-istio-revision:
+endif::[]
+ifeval::["{context}" == "cw-revision-cm"]
+:!ossm-cert-manager-istio-revision:
+endif::[]

modules/ossm-migrating-workloads-using-the-istio-injection-label.adoc

@@ -2,9 +2,17 @@
 //
 // * service-mesh-docs-main/migrating/cluster-wide/ossm-migrating-cluster-wide.adoc
 
+ifeval::["{context}" == "cw-injection"]
+:ossm-cluster-wide-istio-injection:
+endif::[]
+ifeval::["{context}" == "cw-injection-cm"]
+:ossm-cert-manager-istio-injection:
+endif::[]
+
 :_mod-docs-content-type: PROCEDURE
 [id="ossm-migrating-workloads-using-the-istio-injection-label_{context}"]
-= Migrating workloads by using the istio injection label
+ifdef::ossm-cluster-wide-istio-injection[= Migrating workloads by using the Istio injection label]
+ifdef::ossm-cert-manager-istio-injection[= Migrating workloads by using the Istio injection label with cert-manager]
 
 Now you can migrate your workloads from the {SMProduct} 2.6 control plane to the {SMproduct} 3.0 control plane.
 
@@ -110,4 +118,11 @@ The output shows that the `productpage-v1` deployment is the only deployment tha
 [NOTE]
 ====
 Remove the `maistra.io/ignore-namespace="true"` label only after the 2.6 control plane has been uninstalled.
-====
+====
+
+ifeval::["{context}" == "cw-injection"]
+:!ossm-cluster-wide-istio-injection:
+endif::[]
+ifeval::["{context}" == "cw-injection-cm"]
+:!ossm-cert-manager-istio-injection:
+endif::[]

modules/ossm-migrating-workloads-using-the-istio-revision-label.adoc

@@ -2,9 +2,17 @@
 //
 // * service-mesh-docs-main/migrating/checklists/ossm-migrating-cluster-wide.adoc
 
+ifeval::["{context}" == "cw-revision"]
+:ossm-cluster-wide-istio-revision:
+endif::[]
+ifeval::["{context}" == "cw-revision-cm"]
+:ossm-cert-manager-istio-revision:
+endif::[]
+
 :_mod-docs-content-type: PROCEDURE
 [id="ossm-migrating-workloads-using-the-istio-revision-label_{context}"]
-= Migrating workloads by using the Istio revision label
+ifdef::ossm-cluster-wide-istio-revision[= Migrating workloads by using the Istio revision label]
+ifdef::ossm-cert-manager-istio-revision[= Migrating workloads by using the Istio revision label with cert-manager]
 
 Now you can migrate your workloads from the {SMProduct} 2.6 control plane to the {SMproduct} 3.0 control plane.
 
@@ -114,3 +122,10 @@ The previous output shows that the `productpage-v1` deployment is the only deplo
 ====
 Do not remove the `maistra.io/ignore-namespace="true"` label until the 2.6 control plane is uninstalled.
 ====
+
+ifeval::["{context}" == "cw-revision"] 
+:!ossm-cluster-wide-istio-revision:
+endif::[]
+ifeval::["{context}" == "cw-revision-cm"]
+:!ossm-cert-manager-istio-revision:
+endif::[]