PR being used to structure all of the migration content in one spot t…

…o see the whole picture
openshift · Jan 14, 2025 · 4b7c29a · 4b7c29a
1 parent 29bf00e
commit 4b7c29a
Show file tree

Hide file tree

Showing 14 changed files with 369 additions and 1 deletion.
diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml
@@ -13,7 +13,15 @@ Topics:
 - Name: Important information to know before migrating
   File: ossm-migrating-read-me-assembly
 - Name: Premigration checklist
-  File: ossm-migrating-premigration-checklist-assembly
+  Dir: checklist
+  Topics:
+   - Name: Service Mesh 2.6.z to 3.0 premigration checklist
+   - File: ossm-migrating-premigration-checklist-assembly
+- Name: Migration guides
+  Dir: guides
+  Topics:
+   - Name: ossm-migrating-migration-guides-assembly
+
 ---
 Name: About
 Dir: about

diff --git a/migrating/checklist/_attributes b/migrating/checklist/_attributes
@@ -0,0 +1 @@
+../_attributes
diff --git a/migrating/checklist/docinfo.xml b/migrating/checklist/docinfo.xml
@@ -0,0 +1,13 @@
+<title>Service Mesh 2.6.z to 3.0 premigration checklist</title>
+<productname>Red Hat OpenShift Service Mesh</productname>
+<productnumber>3.0.0tp1</productnumber>
+<subtitle>Premigration checklist</subtitle>
+<abstract>
+    <para>This documentation provides a premigration checklist that must be completed before migrating
+    from OpenShift Service Mesh 2.6.z to 3.0.
+    </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" />
diff --git a/migrating/checklist/images b/migrating/checklist/images
@@ -0,0 +1 @@
+../images
diff --git a/migrating/checklist/modules b/migrating/checklist/modules
@@ -0,0 +1 @@
+../modules
diff --git a/...ting-premigration-checklist-assembly.adoc → ...ting-premigration-checklist-assembly.adoc b/...ting-premigration-checklist-assembly.adoc → ...ting-premigration-checklist-assembly.adoc
diff --git a/migrating/checklist/snippets b/migrating/checklist/snippets
@@ -0,0 +1 @@
+../snippets
diff --git a/migrating/guides/_attributes b/migrating/guides/_attributes
@@ -0,0 +1 @@
+../_attributes
diff --git a/migrating/guides/docinfo.xml b/migrating/guides/docinfo.xml
@@ -0,0 +1,12 @@
+<title>Service Mesh 2.6.z to 3.0 migration guides</title>
+<productname>Red Hat OpenShift Service Mesh</productname>
+<productnumber>3.0.0tp1</productnumber>
+<subtitle>Migration guides</subtitle>
+<abstract>
+    <para>This documentation provides information about migrating multitenant and cluster-wide installations of OpenShift Service Mesh.
+    </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" />
diff --git a/migrating/guides/images b/migrating/guides/images
@@ -0,0 +1 @@
+../images
diff --git a/migrating/guides/modules b/migrating/guides/modules
@@ -0,0 +1 @@
+../modules
diff --git a/migrating/guides/ossm-migrating-migration-guides-assembly.adoc b/migrating/guides/ossm-migrating-migration-guides-assembly.adoc
@@ -0,0 +1,28 @@
+:_mod-docs-content-type: ASSEMBLY
+[id=ossm-migrating-migration-guides-assembly]
+= OpenShift 2.6 to OpenShift 3.0 migration guides
+include::_attributes/common-attributes.adoc[]
+:context: ossm-migrating-migration-guides-assembly
+
+toc::[]
+
+This section provides a set of {SMProductName} 2.6.z to {SMProductName} 3.0 migration guides.
+
+If you have not done so already, please read the following documents:
+
+//01/14/2025: will likely link to respective sections; using this as a test to put all the pieces together before ironing out the details such as style things and linking to appropriate sections/references.
+//possible content will be split out into multiple PRs to correspond with respective section Jiras in the epic OSSM-6706
+
+* "Important information to know if you are migrating from OpenShift Service Mesh 2.6" before you start. 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.
+* Premigration Checklist
+
+//includes will likely be modules for multitenant, cluster-wide, uninstalling 2.6, unsupported fields
+
+include::modules/ossm-migrating-multitenant-migration-guide.adoc[]
+
+//NEEDS TO BE PART OF DIFFERENT PR NOW
+
+//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/guides/snippets b/migrating/guides/snippets
@@ -0,0 +1 @@
+../snippets
diff --git a/modules/ossm-migrating-multitenant-migration-guide.adoc b/modules/ossm-migrating-multitenant-migration-guide.adoc
@@ -0,0 +1,299 @@
+
+// Module included in the following assemblies:
+//
+// * service-mesh-docs-main/about/ossm-migrating-migration-guides-assembly.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="migrating-multitenant-migration-guide_{context}""]
+== Migrating OpenShift Service Mesh 2 Multi-Tenant to OpenShift Service Mesh 3
+
+This guide is for users who are currently running `MultiTenant` {SMProductName} 2.6 migrating to OpenShift Service Mesh 3.0. You should first read [this document comparing OpenShift Service Mesh 2 vs. OpenShift Service Mesh 3](../../ossm2-vs-ossm3.md) to familiarize yourself with the concepts between the two versions and the differences in manging `MultiTenant` workloads. Specifically the [Scoping the Mesh section](../../ossm2-vs-ossm3.md#scoping-of-the-mesh-discovery-selectors-and-labels-replace-servicemeshmemberroll-and-servicemeshmember) is important for migrating from OpenShift Service Mesh 2 to OpenShift Service Mesh 3.
+
+.Prerequisites
+
+- OSSM2 operator is installed
+- OSSM3 operator is installed
+- `IstioCNI` is installed
+- `istioctl` is installed
+- MultiTenant `ServiceMeshControlPlane`
+
+.Procedure
+
+In this example, we'll be using the [bookinfo demo](https://raw.githubusercontent.com/Maistra/istio/maistra-2.6/samples/bookinfo/platform/kube/bookinfo.yaml) but you can follow these same steps with your own workloads.
+
+Before you begin, please ensure that you have completed all the steps in the [pre-migration checklist](../README.md#pre-migration-checklist).
+
+<!-- Developer instructions for testing with a fresh 2.6 install.
+
+1. Create SMCP namespace
+
+```sh
+oc create ns istio-system-tenant-a
+```
+
+1. Create SMCP
+
+   ```yaml
+   apiVersion: maistra.io/v2
+   kind: ServiceMeshControlPlane
+   metadata:
+     name: basic
+     namespace: istio-system-tenant-a
+   spec:
+     security:
+       manageNetworkPolicy: false
+       dataPlane:
+         mtls: true
+     addons:
+       grafana:
+         enabled: false
+       kiali:
+         enabled: false
+       prometheus:
+         enabled: false
+     gateways:
+       openshiftRoute:
+         enabled: false
+     mode: MultiTenant
+     policy:
+       type: Istiod
+     profiles:
+       - default
+     telemetry:
+       type: Istiod
+     tracing:
+       type: None
+     version: v2.6
+   ```
+
+*1.* Create bookinfo namespace
+
+   ```sh
+   oc create ns bookinfo
+   ```
+
+*2.* Add bookinfo to the SMMR
+
+   ```yaml
+   apiVersion: maistra.io/v1
+   kind: ServiceMeshMemberRoll
+   metadata:
+     name: default
+     namespace: istio-system-tenant-a
+   spec:
+     members:
+       - bookinfo
+   ```
+
+*3.* Deploy bookinfo
+
+   ```sh
+   oc apply -n bookinfo -f https://raw.githubusercontent.com/Maistra/istio/maistra-2.6/samples/bookinfo/platform/kube/bookinfo.yaml
+   ```
+
+*4.* Ensure pods are all healthy and you see `2/2` pods indicating a sidecar was injected.
+
+   ```sh
+   oc get pods -n bookinfo
+   ```
+
+   Example output
+
+   ```sh
+   NAME                             READY   STATUS    RESTARTS   AGE
+   details-v1-75cb5b97b4-5c6nm      2/2     Running   0          6h13m
+   productpage-v1-899d756d8-ch424   2/2     Running   0          6h10m
+   ratings-v1-58757c649b-8bdg4      2/2     Running   0          6h13m
+   reviews-v1-6878c868b6-42kw7      2/2     Running   0          6h13m
+   reviews-v2-6c8bd45654-jpt76      2/2     Running   0          6h13m
+   reviews-v3-57997d6ccd-j6pmh      2/2     Running   0          6h13m
+   ``` -->
+
+== Install OpenShift Service Mesh 3.0
+
+1. Create your `Istio` resource.
+
+   Here we are setting `discoverySelectors` on our `Istio` resource. In 3.0, controlplanes by default watch the entire cluster and when managing multiple controlplanes on a single cluster, you must narrow the scope of each controlplane by setting `discoverySelectors`. In this example, we use the label `tenant` but you can use any label or combination of labels that you choose.
+
+   ```yaml
+   apiVersion: sailoperator.io/v1alpha1
+   kind: Istio
+   metadata:
+     name: istio-tenant-a
+   spec:
+     namespace: istio-system-tenant-a
+     values:
+       meshConfig:
+         discoverySelectors:
+           - matchLabels:
+               tenant: tenant-a
+     version: v1.23.0
+   ```
+
+> [!WARNING]
+> It is important your `Istio` resource's `spec.namespace` field is the **same** namespace as your `ServiceMeshControlPlane`. If you set your `Istio` resource's `spec.namespace` field to a different namespace than your `ServiceMeshControlPlane`, the migration will not work properly. In this example, we assume that your `ServiceMeshControlPlane` is found in the `istio-system-tenant-a` namespace.
+
+*2.* Add your `tenant` label to each one of your dataplane namespaces.
+
+   With 2.6, we enrolled namespaces into the mesh by adding them to the Service Mesh Member Roll resource. In 3.0, you must label each one of your dataplane namespaces with this label. For every namespace in your Service Mesh Member Roll, add your tenant label to the namespace.
+
+   ```sh
+   oc label ns bookinfo tenant=tenant-a
+   ```
+
+   Now we are ready to migrate our workloads from our 2.6 controlplane to our 3.0 controlplane.
+
+=== Migrate Workloads
+
+1. Update injection labels on the dataplane namespace.
+
+   Here we're adding two labels to the namespace:
+
+   * The `istio.io/rev: istio-tenant-a` label which ensures that any new pods that get created in that namespace will connect to the 3.0 proxy.
+   * The `maistra.io/ignore-namespace: "true"` label which will disable sidecar injection for 2.6 proxies in the namespace. This ensures that 2.6 will stop injecting proxies in this namespace and any new proxies will be injected by the 3.0 controlplane. Without this, the 2.6 injection webhook will try to inject the pod and it will connect to the 2.6 proxy as well as refuse to start since it will have the 2.6 cni annotation.
+
+   **Note:** that once you apply the `maistra.io/ignore-namespace` label, any new pod that gets created in the namespace will be connected to the 3.0 proxy. Workloads will still be able to communicate with each other though regardless of which controlplane they are connected to.
+
+   ```sh
+   oc label ns bookinfo istio.io/rev=istio-tenant-a maistra.io/ignore-namespace="true" --overwrite=true
+   ```
+
+*2*. `curl` the productpage pod in `bookinfo` to ensure proxies can still communicate with one another.
+
+   ```sh
+   oc exec -it -n bookinfo deployments/productpage-v1 -c istio-proxy -- curl localhost:9080/productpage
+   ```
+
+   You should see
+
+   ```html
+   ...
+           <p>Absolutely fun and entertaining. The play lacks thematic depth when compared to other plays by Shakespeare.</p>
+           <small>Reviewer2</small>
+
+
+           <font color="black">
+             <!-- full stars: -->
+
+             <span class="glyphicon glyphicon-star"></span>
+
+             <span class="glyphicon glyphicon-star"></span>
+
+             <span class="glyphicon glyphicon-star"></span>
+
+             <span class="glyphicon glyphicon-star"></span>
+
+             <!-- empty stars: -->
+
+             <span class="glyphicon glyphicon-star-empty"></span>
+
+           </font>
+
+
+         </blockquote>
+
+         <dl>
+           <dt>Reviews served by:</dt>
+           <u>reviews-v2-6dd458b5db-frrlb</u>
+
+         </dl>
+   ...
+   ```
+
+1. Migrate workloads.
+
+   You can now restart the workloads so that the new pod will be injected with the 3.0 proxy.
+
+   This can be done all at once:
+
+   ```sh
+   oc rollout restart deployments -n bookinfo
+   ```
+
+   or individually:
+
+   ```sh
+   oc rollout restart deployments productpage-v1 -n bookinfo
+   ```
+
+*2*. Wait for the productpage app to restart.
+
+   ```sh
+   oc rollout status deployment productpage-v1 -n bookinfo
+   ```
+
+=== Validate Workload Migration
+
+1. Ensure the productpage app is connected to the new controlplane
+
+   You can see which proxies are still connected to the 2.6 controlplane with `istioctl`. Here `basic` should be the name of your `ServiceMeshControlPlane`:
+
+   ```sh
+   istioctl ps --istioNamespace istio-system-tenant-a --revision basic
+   ```
+
+   Example response:
+
+   ```sh
+   NAME                                              CLUSTER        CDS        LDS        EDS        RDS          ECDS         ISTIOD                            VERSION
+   details-v1-7b49464bc-zr7nr.bookinfo               Kubernetes     SYNCED     SYNCED     SYNCED     SYNCED       NOT SENT     istiod-basic-6c9f8d9894-sh6lx     1.20.8
+   ratings-v1-d6f449f59-9rds2.bookinfo               Kubernetes     SYNCED     SYNCED     SYNCED     SYNCED       NOT SENT     istiod-basic-6c9f8d9894-sh6lx     1.20.8
+   reviews-v1-686cd989df-9x59z.bookinfo              Kubernetes     SYNCED     SYNCED     SYNCED     SYNCED       NOT SENT     istiod-basic-6c9f8d9894-sh6lx     1.20.8
+   reviews-v2-785b8b48fc-l7xkj.bookinfo              Kubernetes     SYNCED     SYNCED     SYNCED     SYNCED       NOT SENT     istiod-basic-6c9f8d9894-sh6lx     1.20.8
+   reviews-v3-67889ffd49-7bhxn.bookinfo              Kubernetes     SYNCED     SYNCED     SYNCED     SYNCED       NOT SENT     istiod-basic-6c9f8d9894-sh6lx     1.20.8
+   ```
+
+   And which proxies have been migrated to the new 3.0 controlplane:
+
+   ```sh
+   istioctl ps --istioNamespace istio-system-tenant-a --revision istio-tenant-a
+   ```
+
+   Example response:
+
+   ```sh
+   NAME                                         CLUSTER        CDS        LDS        EDS        RDS        ECDS     ISTIOD                      VERSION
+   productpage-v1-7745c5cc94-wpvth.bookinfo     Kubernetes     SYNCED     SYNCED     SYNCED     SYNCED              istiod-5bbf98dccf-n8566     1.23.0
+   ```
+
+*2*. Ensure the `bookinfo` application is still working correctly.
+
+   ```sh
+   oc exec -it -n bookinfo deployments/productpage-v1 -c istio-proxy -- curl localhost:9080/productpage
+   ```
+
+   Example response:
+
+   ```html
+   ...
+           <p>Absolutely fun and entertaining. The play lacks thematic depth when compared to other plays by Shakespeare.</p>
+           <small>Reviewer2</small>
+
+
+           <font color="black">
+             <!-- full stars: -->
+
+             <span class="glyphicon glyphicon-star"></span>
+
+             <span class="glyphicon glyphicon-star"></span>
+
+             <span class="glyphicon glyphicon-star"></span>
+
+             <span class="glyphicon glyphicon-star"></span>
+
+             <!-- empty stars: -->
+
+             <span class="glyphicon glyphicon-star-empty"></span>
+
+           </font>
+
+
+         </blockquote>
+
+         <dl>
+           <dt>Reviews served by:</dt>
+           <u>reviews-v2-6dd458b5db-frrlb</u>
+
+         </dl>
+   ...
+   ```