Add docs for multi-tenant ossm migration (openshift-service-mesh#168)

nrfox · web-flow · commit ca2f1b0a1b12 · 2024-12-05T14:16:17.000-05:00
Signed-off-by: Nick Fox &lt;nfox@redhat.com&gt;
diff --git a/docs/ossm/README.md b/docs/ossm/README.md
@@ -13,4 +13,4 @@ This documentation is specific to the OpenShift Service Mesh product and may dif
 - [Installing the Sidecar](./injection/README.md)
 - [Multiple Istio Control Planes in a Single Cluster](./multi-control-planes/README.md)
 - [Security Mutual TLS Configuration](./security/security-mTLS-configuration.md)
-
+- [2.X to 3.0 migration guide](./ossm2-migration/README.md)
diff --git a/docs/ossm/ossm2-migration/README.md b/docs/ossm/ossm2-migration/README.md
@@ -0,0 +1,29 @@
+# OpenShift Service Mesh 2.6 migration to 3.0
+
+This document details how to migrate from 2.6 to OpenShift Service Mesh 3.0.
+
+## Pre-migration Checklist
+
+Before you begin to migrate your controlplane from OpenShift Service Mesh 2.6 to 3.0, ensure you have done the following:
+
+- Upgrade your 2.6 OpenShift Service Mesh Operator to the latest release.
+- Upgrade your `ServiceMeshControlPlane` version to the latest OpenShift Service Mesh release.
+- Disable the following features on your `ServiceMeshControlPlane`. These fields are unsupported in 3.0 and must be disabled prior to migration.
+    <!-- TODO: create a separate page for each of these bullet points describing how to migrate off the SMCP managed version. -->
+    <!-- TODO: revisit this list when: https://issues.redhat.com/browse/OSSM-8299 is completed. -->
+  - Network Policy management: `spec.security.manageNetworkPolicy=false`. If you wish to keep the Network Policies created by the 2.6 `ServiceMeshControlPlane`, you will need to recreate and manage these manually.
+  - Disabled addons:
+    - Prometheus: `spec.addons.prometheus.enabled=false`
+    - Kiali: `spec.addons.kiali.enabled=false`
+    - Grafana: `spec.addons.grafana.enabled=false`
+    - Tracing: `spec.tracing.type=None`
+  - IOR is disabled.
+  - Default ingress/egress gateways are disabled.
+
+Now you are ready to migrate. Check the `spec.mode` field on your `ServiceMeshControlPlane` resource to determine if you are running a `MultiTenant` or a `ClusterWide` mesh.
+
+```sh
+oc get smcp <smcp-name> -n <smcp-namespace> -o jsonpath='{.spec.mode}'
+```
+
+For `MultiTenant` meshes, follow [these instructions](./multi-tenancy/README.md). For `ClusterWide` meshes, follow [these instructions](#TODO).
diff --git a/docs/ossm/ossm2-migration/multi-tenancy/README.md b/docs/ossm/ossm2-migration/multi-tenancy/README.md
@@ -0,0 +1,294 @@
+# OpenShift Service Mesh 2 --> 3 Multi-tenancy Migration guide
+
+This guide is for users who are currently running `MultiTenant` OpenShift Service Mesh 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.
+
+## Migrating OpenShift Service Mesh 2 Multi-Tenant 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
+   ```
+
+1. Add bookinfo to the SMMR
+
+   ```yaml
+   apiVersion: maistra.io/v1
+   kind: ServiceMeshMemberRoll
+   metadata:
+     name: default
+     namespace: istio-system-tenant-a
+   spec:
+     members:
+       - bookinfo
+   ```
+
+1. Deploy bookinfo
+
+   ```sh
+   oc apply -n bookinfo -f https://raw.githubusercontent.com/Maistra/istio/maistra-2.6/samples/bookinfo/platform/kube/bookinfo.yaml
+   ```
+
+1. 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:
+
+   1. 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.
+   2. 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
+   ```
+
+1. `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
+   ```
+
+1. 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
+   ```
+
+1. 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>
+   ...
+   ```
