Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

OSSM-8507 Migration guide for multitenant 2.6 #86917

Open
wants to merge 3 commits into
base: service-mesh-docs-main
Choose a base branch
from
Open

OSSM-8507 Migration guide for multitenant 2.6 #86917

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
32ec645
OSSM-8507 Migration guide for multitenant 2.6
gwynnemonahan Jan 10, 2025
4dc4a0d
update to topic map
gwynnemonahan Jan 10, 2025
35e779c
Squash me
gwynnemonahan Jan 14, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions _topic_maps/_topic_map.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,8 @@ Distros: openshift-service-mesh
Topics:
- Name: Important information to know before migrating
File: ossm-migrating-read-me-assembly
- Name: Migration guides
File: ossm-migrating-migration-guides-assembly
---
Name: About
Dir: about
Expand Down
22 changes: 22 additions & 0 deletions migrating/ossm-migrating-migration-guides-assembly.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
:_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 to {SMProductName} 3 migration guides.

If you have not done so already, please read "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.

//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.
299 changes: 299 additions & 0 deletions modules/ossm-migrating-multitenant-migration-guide.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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` 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.

.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>
...
```