Skip to content

Commit e432b74

Browse files
gabriel-rhgabriel-rh
authored
Merge pull request #90109 from openshift-cherrypick-robot/cherry-pick-89842-to-service-mesh-docs-3.0
[service-mesh-docs-3.0] OSSM-8959: Cluster-wide migration using simple migration method
2 parents 1afe60e + a62673c commit e432b74

3 files changed

+224
-8
lines changed

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

Lines changed: 28 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,8 @@ include::modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-revisi
3535

3636
include::modules/ossm-migrating-workloads-using-the-istio-revision-label.adoc[leveloffset=+2]
3737

38-
.Next steps
38+
[id="next-steps-istio-revision_{context}"]
39+
== Next steps
3940

4041
If you are using gateways, you must migrate them before you complete the migration process.
4142

@@ -50,7 +51,8 @@ include::modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-revisi
5051

5152
include::modules/ossm-migrating-workloads-using-the-istio-revision-label-with-cert-manager.adoc[leveloffset=+2]
5253

53-
.Next steps
54+
[id="next-steps-istio-revision-with-cert-manager_{context}"]
55+
== Next steps
5456

5557
If you are using gateways, you must migrate them before you complete the migration process.
5658

@@ -66,7 +68,8 @@ include::modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-inject
6668

6769
include::modules/ossm-migrating-workloads-using-the-istio-injection-label.adoc[leveloffset=+2]
6870

69-
.Next steps
71+
[id="next-steps-istio-injection_{context}"]
72+
== Next steps
7073

7174
If you are using gateways, you must migrate them before you complete the migration process.
7275

@@ -77,7 +80,8 @@ If you are not using gateways, and have verified your cluster-wide migration, cr
7780

7881
include::modules/ossm-creating-a-default-revision-tag-and-relabeling-the-namespaces.adoc[leveloffset=+2]
7982

80-
.Next steps
83+
[id="next-steps-istio-injection-relabel_{context}"]
84+
== Next steps
8185

8286
You can proceed to complete the migration and remove {SMProduct} 2 resources.
8387

@@ -94,7 +98,8 @@ include::modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-inject
9498

9599
include::modules/ossm-migrating-workloads-using-the-istio-injection-label-with-cert-manager.adoc[leveloffset=+2]
96100

97-
.Next steps
101+
[id="next-steps-istio-injection-with-cert-manager_{context}"]
102+
== Next steps
98103

99104
If you are using gateways, you must migrate them before you complete the migration process.
100105

@@ -110,7 +115,22 @@ Before creating a default revision tag and relabelling the namespaces, you must
110115

111116
include::modules/ossm-creating-a-default-revision-tag-and-relabeling-the-namespaces-with-cert-manager.adoc[leveloffset=+2]
112117

113-
[role="_additional-resources"]
114-
.Additional resources
118+
//Te following tasks are for migration using the simple migration method
119+
include::modules/ossm-migrating-a-cluster-wide-deployment-using-the-simple-migration-method.adoc[leveloffset=+1]
120+
include::modules/ossm-migrating-workloads-using-the-simple-migration-method.adoc[leveloffset=+2]
121+
122+
[id="next-steps-simple-migration_{context}"]
123+
== Next steps
124+
125+
If you are using gateways, you must migrate them before you complete the migration process.
126+
127+
* xref:../../migrating/migrating-gateways/ossm-migrating-gateways-assembly.adoc[Migrating gateways from Service Mesh 2 to Service Mesh 3]
128+
129+
If you are using gateways, you can complete your migration.
130+
131+
* xref:../../migrating/done/ossm-migrating-complete-assembly.adoc[Completing the Migration]
132+
133+
[id="additional-resources_{context}"]
134+
== Additional resources
115135

116-
* xref:../../install/ossm-sidecar-injection-assembly.adoc#ossm-identifying-revision-name_ossm-sidecar-injection-assembly[Identifying the revision name]
136+
* xref:../../install/ossm-sidecar-injection-assembly.adoc#ossm-identifying-revision-name_ossm-sidecar-injection-assembly[Identifying the revision name]

‎modules/ossm-migrating-a-cluster-wide-deployment-using-the-simple-migration-method.adoc

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * service-mesh-docs-main/migrating/cluster-wide/ossm-migrating-cluster-wide-assembly.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="ossm-migrating-a-cluster-wide-deployment-using-the-simple-migration-method_{context}"]
7+
= Migrating a cluster-wide deployment by using the simple migration method
8+
9+
You can perform a canary upgrade with the gradual migration of data plane namespaces for a cluster-wide deployment by using the simple migration method. In an {SMProduct} {SMv2Version} installation, if the `istio-injection=enabled` label is already applied to the data plane namespaces, the simple migration method is the easiest way to migrate from the {SMProduct} 2 installation to the {SMProduct} 3 installation.
10+
11+
The simple migration method should not be used in production environments.
12+
13+
[NOTE]
14+
====
15+
Using the simple migration method to migrate from {SMProduct} 2 to {SMProduct} 3 might result in traffic disruption to the services running on a mesh. There are two methods to perform the cluster-wide migration without disrupting traffic. See "Migrating a cluster-wide deployment by using the istio injection label" or "Migrating a cluster-wide deployment by using the Istio revision label" for more information.
16+
====
17+
18+
The `bookinfo` application is used as an example for the `Istio` resource. For more information about configuration differences between the {SMProduct} 2 `ServiceMeshControlPlane` resource and the {SMProduct} 3 `Istio` resource, see "ServiceMeshControlPlane resource to Istio resource fields mapping."
19+
20+
.Prerequisites
21+
22+
* You have deployed {ocp-product-title} 4.14 or later.
23+
* You are logged in to the {ocp-product-title} web console as a user with the `cluster-admin` role.
24+
* You have completed the premigration checklists.
25+
* You have the {SMProduct} {SMv2Version} Operator installed.
26+
* You have the {SMProduct} 3 Operator installed.
27+
* You have created an `IstioCNI` resource.
28+
* You have installed the `istioctl` tool.
29+
* You are running a cluster-wide Service Mesh control plane resource.
30+
* You have installed the `bookinfo` application.
31+
32+
.Procedure
33+
34+
. Identify the namespaces that contain a 2.6 control plane by running the following command:
35+
+
36+
[source,terminal]
37+
----
38+
$ oc get smcp -A
39+
----
40+
+
41+
.Example output
42+
[source,terminal]
43+
----
44+
NAMESPACE NAME READY STATUS PROFILES VERSION AGE
45+
istio-system install-istio-system 6/6 ComponentsReady ["default"] 2.6.6 115m
46+
----
47+
48+
. Create a YAML file named `ossm-3.yaml`. This procedure creates the {istio} resource for the 3.0 installation in the same namespace as the `ServiceMeshControlPlane` resource for the 2.6 installation.
49+
+
50+
[NOTE]
51+
====
52+
In the following example configuration, the {istio} control plane has access to all namespaces on the cluster. If you want to limit the namespaces the control plane has access to, you must define discovery selectors. You must match all the data plane namespaces that you plan to migrate from version 2.6.
53+
====
54+
+
55+
.Example `Istio` resource
56+
[source,yaml,subs="attributes,verbatim"]
57+
----
58+
apiVersion: sailoperator.io/v1
59+
kind: Istio
60+
metadata:
61+
name: default # <1>
62+
spec:
63+
updateStrategy:
64+
type: InPlace
65+
namespace: istio-system # <2>
66+
version: v1.24.3
67+
values:
68+
meshConfig:
69+
extensionProviders: # <3>
70+
- name: prometheus
71+
prometheus: {}
72+
- name: otel
73+
opentelemetry:
74+
port: 4317
75+
service: otel-collector.opentelemetrycollector-3.svc.cluster.local
76+
----
77+
<1> The `name`, `updateStrategy` and `version` fields specify how the `IstioRevision` resource name is created. For more information, see "Identifying the revision name."
78+
<2> The 3.0 and 2.6 control planes must run in the same namespace.
79+
<3> If you are migrating metrics and tracing, update the `extensionProviders` fields according to your tracing and metrics configurations.
80+
+
81+
[NOTE]
82+
====
83+
If the {istio} resource is named `default`, and the installation uses the `InPlace` update strategy, you can use the `istio-injection=enabled` label without creating the `IstioRevisionTag` tag. If you use a different name for the {istio} resource or you use the `RevisionBased` update strategy, you must configure the default `IstioRevisionTag` tag. For more information, see "Creating the default revision tag and relabeling the namespaces."
84+
====
85+
86+
. Apply the YAML file by running the following command:
87+
+
88+
[source,terminal]
89+
----
90+
$ oc apply -f ossm-3.yaml
91+
----
92+
+
93+
[NOTE]
94+
====
95+
After you apply the YAML file, any time the workloads are restarted, both the {SMProduct} 2.6 and the {SMProduct} 3.0 control planes will try to inject side cars to all pods in namespaces that have the `istio-injection=enabled` label applied and to all pods that have the `sidecar.istio.io/inject="true"` label applied. This causes a traffic disruption. To prevent traffic disruption, restart the workloads only after the `maistra.io/ignore-namespace: "true"` label is added.
96+
====
97+
98+
.Verification
99+
100+
. Verify that the new `istiod` resource uses the existing root certificate by running the following command:
101+
+
102+
[source,terminal]
103+
----
104+
$ oc logs deployments/istiod -n istio-system | grep 'Load signing key and cert from existing secret'
105+
----
106+
+
107+
.Example output
108+
[source,terminal]
109+
----
110+
2024-12-18T08:13:53.788959Z info pkica Load signing key and cert from existing secret istio-system/istio-ca-secret
111+
----

‎modules/ossm-migrating-workloads-using-the-simple-migration-method.adoc

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * service-mesh-docs-main/migrating/cluster-wide/ossm-migrating-cluster-wide-assembly.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="ossm-migrating-workloads-using-the-simple-migration-method_{context}"]
7+
= Migrating workloads by using the simple migration method
8+
9+
After migrating a cluster-wide deployment, you can migrate your workloads from the {SMProduct} 2.6 control plane to the {SMproduct} 3.0 control plane.
10+
11+
[NOTE]
12+
====
13+
You can migrate workloads and gateways separately, and in any order. For more information, see "Migrating gateways."
14+
====
15+
16+
.Procedure
17+
18+
. Add the `maistra.io/ignore-namespace: "true"` label to the data plane namespace by running the following command:
19+
+
20+
[source,terminal]
21+
----
22+
$ oc label ns bookinfo maistra.io/ignore-namespace="true"
23+
----
24+
+
25+
The `maistra.io/ignore-namespace: "true"` label disables sidecar injection for {SMProduct} 2.6 proxies in the namespace. With the label applied, {SMProduct} 2.6 stops injecting proxies in this namespace, and any new proxies are injected by {SMProduct} 3.0. Without this label, the {SMProduct} 2.6 injection webhook tries to inject the pod and the injected sidecar proxy refuses to start since it has both the {SMProduct} 2.6 and the {SMProduct} 3.0 Container Network Interface(CNI) annotations.
26+
+
27+
[NOTE]
28+
====
29+
After you apply the `maistra.io/ignore-namespace` label, any new pod that gets created or restarted in the namespace connects to the {SMProduct} 3.0 proxy. Workloads can still communicate with each other regardless of which control plane they are connected to.
30+
====
31+
32+
. Restart the workloads by using one of the following options:
33+
+
34+
.. To restart all the workloads at the same time so that the new pods are injected with the {SMProduct} 3.0 proxy, run the following command:
35+
+
36+
.Example command for `bookinfo` application
37+
[source,terminal]
38+
----
39+
$ oc rollout restart deployments -n bookinfo
40+
----
41+
42+
.. To restart each workload individually, run the following command for each workload:
43+
+
44+
.Example command for `bookinfo` application
45+
[source,terminal]
46+
----
47+
$ oc rollout restart deployments productpage-v1 -n bookinfo
48+
----
49+
50+
. Wait for the `productpage` application to restart by running the following command:
51+
+
52+
[source,terminal]
53+
----
54+
$ oc rollout status deployment productpage-v1 -n bookinfo
55+
----
56+
57+
.Verification
58+
59+
. Verify that the the new control plane manages the expected workloads by running the following command:
60+
+
61+
[source,terminal]
62+
----
63+
$ istioctl ps -n bookinfo
64+
----
65+
+
66+
.Example output:
67+
[source,terminal]
68+
----
69+
NAME CLUSTER CDS LDS EDS RDS ECDS ISTIOD VERSION
70+
details-v1-7f46897b-d497c.bookinfo Kubernetes SYNCED SYNCED SYNCED SYNCED NOT SENT istiod-install-istio-system-866b57d668-6lpcr 1.20.8
71+
productpage-v1-74bfbd4d65-vsxqm.bookinfo Kubernetes SYNCED (4s) SYNCED (4s) SYNCED (3s) SYNCED (4s) IGNORED istiod-797bb4d78f-xpchx 1.24.3
72+
ratings-v1-559b64556-c5ppg.bookinfo Kubernetes SYNCED SYNCED SYNCED SYNCED NOT SENT istiod-install-istio-system-866b57d668-6lpcr 1.20.8
73+
reviews-v1-847fb7c54d-qxt5d.bookinfo Kubernetes SYNCED SYNCED SYNCED SYNCED NOT SENT istiod-install-istio-system-866b57d668-6lpcr 1.20.8
74+
reviews-v2-5c7ff5b77b-8jbhd.bookinfo Kubernetes SYNCED SYNCED SYNCED SYNCED NOT SENT istiod-install-istio-system-866b57d668-6lpcr 1.20.8
75+
reviews-v3-5c5d764c9b-rrx8w.bookinfo Kubernetes SYNCED SYNCED SYNCED SYNCED NOT SENT istiod-install-istio-system-866b57d668-6lpcr 1.20.8
76+
----
77+
+
78+
The output shows that the `productpage-v1` deployment is the only deployment that has been restarted and was injected with the 3.0 proxy. Even if there are different versions of the proxies, communication between the services still works.
79+
80+
. If the 2.6 installation contains additional namespaces, migrate the next namespace now.
81+
+
82+
[NOTE]
83+
====
84+
Remove the `maistra.io/ignore-namespace="true"` label only after the 2.6 control plane has been uninstalled.
85+
====

0 commit comments

Comments
 (0)