From ca2f1b0a1b120c131d1b1edb85b250c8b746204a Mon Sep 17 00:00:00 2001 From: Nick Fox <6226732+nrfox@users.noreply.github.com> Date: Thu, 5 Dec 2024 14:16:17 -0500 Subject: [PATCH] Add docs for multi-tenant ossm migration (#168) Signed-off-by: Nick Fox --- docs/ossm/README.md | 2 +- docs/ossm/ossm2-migration/README.md | 29 ++ .../ossm2-migration/multi-tenancy/README.md | 294 ++++++++++++++++++ 3 files changed, 324 insertions(+), 1 deletion(-) create mode 100644 docs/ossm/ossm2-migration/README.md create mode 100644 docs/ossm/ossm2-migration/multi-tenancy/README.md diff --git a/docs/ossm/README.md b/docs/ossm/README.md index 47aa53d68..007ff75bc 100644 --- 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 new file mode 100644 index 000000000..e83292553 --- /dev/null +++ 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. + + + - 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 -n -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 new file mode 100644 index 000000000..9d10951c0 --- /dev/null +++ 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). + + + +#### 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 + ... +

Absolutely fun and entertaining. The play lacks thematic depth when compared to other plays by Shakespeare.

+ Reviewer2 + + + + + + + + + + + + + + + + + + + + + + +
+
Reviews served by:
+ reviews-v2-6dd458b5db-frrlb + +
+ ... + ``` + +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 + ... +

Absolutely fun and entertaining. The play lacks thematic depth when compared to other plays by Shakespeare.

+ Reviewer2 + + + + + + + + + + + + + + + + + + + + + + +
+
Reviews served by:
+ reviews-v2-6dd458b5db-frrlb + +
+ ... + ```