Skip to content

Commit 98c5d9b

Browse files
xenolinuxxenolinux
authored
Merge pull request #90044 from openshift-cherrypick-robot/cherry-pick-89396-to-service-mesh-docs-3.0
[service-mesh-docs-3.0] OSSM-8509: Cluster-wide migration using the Istio revision label with cert manager
2 parents c6e98f2 + 0651a22 commit 98c5d9b

3 files changed

+286
-12
lines changed

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

Lines changed: 38 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * service-mesh-docs-main/migrating/cluster-wide/ossm-migrating-cluster-wide-assembly.adoc
4+
15
:_mod-docs-content-type: ASSEMBLY
26
[id=ossm-migrating-cluster-wide-assembly]
37
= Cluster-wide migration guide
@@ -17,31 +21,41 @@ include::modules/ossm-control-plane-configuration-migration-requirements.adoc[le
1721

1822
include::modules/ossm-cluster-wide-migration-methods.adoc[leveloffset=+1]
1923

24+
2025
// The following tasks are for migration using the Istio revision label
26+
2127
include::modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-revision-label.adoc[leveloffset=+1]
2228

23-
[role="_additional-resources"]
24-
.Additional resources
29+
include::modules/ossm-migrating-workloads-using-the-istio-revision-label.adoc[leveloffset=+2]
2530

26-
* xref:../../install/ossm-sidecar-injection-assembly.adoc#ossm-identifying-revision-name_ossm-sidecar-injection-assembly[Identifying the revision name]
31+
.Next steps
2732

28-
include::modules/ossm-migrating-workloads-using-the-istio-revision-label.adoc[leveloffset=+2]
33+
If you are using gateways, you must migrate them before you complete the migration process.
2934

30-
include::modules/ossm-creating-a-default-revision-tag-and-relabeling-the-namespaces.adoc[leveloffset=+1]
35+
* xref:../../migrating/migrating-gateways/ossm-migrating-gateways-assembly.adoc[Migrating gateways from Service Mesh 2 to Service Mesh 3]
36+
37+
If you are not using gateways, and have verified your cluster-wide migration, you can proceed to complete the migration and remove {SMProduct} 2 resources.
38+
39+
* xref:../../migrating/done/ossm-migrating-complete-assembly.adoc[Completing the Migration]
40+
41+
//The following tasks are for the Istio revision label with cert-manager
42+
include::modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-revision-label-with-cert-manager.adoc[leveloffset=+1]
43+
44+
include::modules/ossm-migrating-workloads-using-the-istio-revision-label-with-cert-manager.adoc[leveloffset=+2]
3145

3246
.Next steps
3347

34-
You can proceed to complete the migration and remove {SMProduct} 2 resources.
48+
If you are using gateways, you must migrate them before you complete the migration process.
3549

36-
* xref:../../migrating/done/ossm-migrating-complete-assembly.adoc[Completing the Migration]
50+
* xref:../../migrating/migrating-gateways/ossm-migrating-gateways-assembly.adoc[Migrating gateways from Service Mesh 2 to Service Mesh 3]
3751
38-
// The following tasks are for migration using the Istio injection label
39-
include::modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-injection-label.adoc[leveloffset=+1]
52+
If you are not using gateways, and have verified your cluster-wide migration, you can proceed to complete the migration and remove {SMProduct} 2 resources.
4053

41-
[role="_additional-resources"]
42-
.Additional resources
54+
* xref:../../migrating/done/ossm-migrating-complete-assembly.adoc[Completing the Migration]
4355
44-
* xref:../../install/ossm-sidecar-injection-assembly.adoc#ossm-identifying-revision-name_ossm-sidecar-injection-assembly[Identifying the revision name]
56+
// The following tasks are for the Istio injection label
57+
58+
include::modules/ossm-migrating-a-cluster-wide-deployment-using-the-istio-injection-label.adoc[leveloffset=+1]
4559

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

@@ -53,6 +67,14 @@ If you are using gateways, you must migrate them before you complete the migrati
5367
5468
If you are not using gateways, and have verified your cluster-wide migration, create a default revision tag and re-label namespaces.
5569

70+
include::modules/ossm-creating-a-default-revision-tag-and-relabeling-the-namespaces.adoc[leveloffset=+2]
71+
72+
.Next steps
73+
74+
You can proceed to complete the migration and remove {SMProduct} 2 resources.
75+
76+
* xref:../../migrating/done/ossm-migrating-complete-assembly.adoc[Completing the Migration]
77+
5678
[IMPORTANT]
5779
====
5880
Before creating a default revision tag and relabelling the namespaces, you must migrate all remaining workload namespaces, including gateways.
@@ -61,3 +83,7 @@ Before creating a default revision tag and relabelling the namespaces, you must
6183
// insert xref to "Creating the default revision tag and relabeling the namespaces" after PR OSSM-9000 is merged
6284

6385
* Creating the default revision tag and relabeling the namespaces
86+
[role="_additional-resources"]
87+
.Additional resources
88+
89+
* 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-istio-revision-label-with-cert-manager.adoc

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
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-istio-revision-label-with-cert-manager_{context}"]
7+
= Migrating a cluster-wide deployment by using the Istio revision label with cert-manager
8+
9+
You can perform a canary upgrade with the gradual migration of data plane namespaces for a cluster-wide deployment by using the `istio.io/rev` label with cert-manager.
10+
11+
The `bookinfo` application is used as an example for the `Istio` resource. For more information on configuration differences between the {SMProduct} 2 `ServiceMeshControlPlane` resource and the {SMProduct} 3 `Istio` resource, see "Configuration fields mapping between Service Mesh 2 and Service Mesh 3."
12+
13+
You can follow these same steps with your own workloads.
14+
15+
.Prerequisites
16+
17+
* You have deployed {ocp-product-title} 4.14 or later.
18+
* You are logged in to the {ocp-product-title} web console as a user with the `cluster-admin` role.
19+
* You have completed the premigration checklists.
20+
* You have installed the {SMProduct} {SMv2Version} Operator.
21+
* You have installed the {SMProduct} 3 Operator.
22+
* You have created an `IstioCNI` resource.
23+
* You have installed the `istioctl` tool.
24+
* You are using the cert-manager and istio-csr tools in a cluster-wide deployment.
25+
* Your {SMProduct} 2 `ServiceMeshControlPlane` resource is configured with the cert-manager tool.
26+
27+
.Procedure
28+
29+
. Check that your {SMProduct} 2 `ServiceMeshControlPlane` resource is configured with the cert-manager tool.
30+
+
31+
.Example `ServiceMeshControlPlane` cert-manager configuration
32+
[source,yaml]
33+
----
34+
apiVersion: maistra.io/v2
35+
kind: ServiceMeshControlPlane
36+
metadata:
37+
name: basic
38+
namespace: istio-system
39+
spec:
40+
...
41+
security:
42+
certificateAuthority:
43+
cert-manager:
44+
address: cert-manager-istio-csr.istio-system.svc:443
45+
type: cert-manager
46+
dataPlane:
47+
mtls: true
48+
identity:
49+
type: ThirdParty
50+
manageNetworkPolicy: false
51+
----
52+
53+
. Update the `istio-csr` deployment to include your {SMProduct} 3 control plane by running the following command:
54+
+
55+
[source,terminal]
56+
----
57+
helm upgrade cert-manager-istio-csr jetstack/cert-manager-istio-csr \
58+
--install \
59+
--reuse-values \
60+
--namespace istio-system \
61+
--wait \
62+
--set "app.istio.revisions={basic,ossm-3-v1-24-3}" <1>
63+
----
64+
+
65+
<1> The `app.istio.revisions` field must include your {SMProduct} 3.0 control plane revision _before_ you create your `Istio` resource so that proxies can properly communicate with the {SMProduct} 3.0 control plane.
66+
67+
. Identify the namespaces that contain a 2.6 control plane by running the following command:
68+
+
69+
[source,terminal]
70+
----
71+
$ oc get smcp -A
72+
----
73+
+
74+
.Example output:
75+
[source,terminal]
76+
----
77+
NAMESPACE NAME READY STATUS PROFILES VERSION AGE
78+
istio-system install-istio-system 6/6 ComponentsReady ["default"] 2.6.6 115m
79+
----
80+
81+
. 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:
82+
+
83+
.Example `Istio` resource
84+
[source,yaml,subs="attributes,verbatim"]
85+
----
86+
apiVersion: sailoperator.io/v1
87+
kind: Istio
88+
metadata:
89+
name: ossm-3 # <1>
90+
spec:
91+
updateStrategy:
92+
type: RevisionBased
93+
namespace: istio-system # <2>
94+
version: v1.24.3
95+
values:
96+
meshConfig:
97+
extensionProviders: # <3>
98+
- name: prometheus
99+
prometheus: {}
100+
- name: otel
101+
opentelemetry:
102+
port: 4317
103+
service: otel-collector.opentelemetrycollector-3.svc.cluster.local
104+
global:
105+
caAddress: cert-manager-istio-csr.istio-system.svc:443
106+
pilot:
107+
env:
108+
ENABLE_CA_SERVER: "false"
109+
----
110+
<1> The `name`, `updateStrategy`, and `version` fields specify how the `IstioRevision` resource name is created. For more information, see "Identifying the revision name."
111+
<2> The 3.0 and 2.6 control planes must run in the same namespace.
112+
<3> If you are migrating metrics and tracing, update the `extensionProviders` fields according to your tracing and metrics configurations.
113+
114+
. Apply the YAML file by running the following command:
115+
+
116+
[source,terminal]
117+
----
118+
$ oc apply -f ossm-3.yaml
119+
----
120+
121+
. Verify that the new `istiod` resource uses the existing root certificate by running the following command:
122+
+
123+
[source,terminal]
124+
----
125+
$ oc logs deployments/istiod-ossm-3-v1-24-3 -n istio-system | grep 'Load signing key and cert from existing secret'
126+
----
127+
+
128+
.Example output:
129+
[source,terminal]
130+
----
131+
2024-12-18T08:13:53.788959Z info pkica Load signing key and cert from existing secret istio-system/istio-ca-secret
132+
----

‎modules/ossm-migrating-workloads-using-the-istio-revision-label-with-cert-manager.adoc

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
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-istio-revision-label-with-cert-manager_{context}"]
7+
= Migrating workloads by using the Istio revision label with cert-manager
8+
9+
After migrating a cluster-wide deployment, you can migrate your workloads workloads from the {SMProduct} 2.6 control plane to the {SMproduct} 3.0 control plane.
10+
11+
To maintain simplicity, revision tags are not used in this example. When migrating large meshes, you can use revision tags to avoid re-labeling all namespaces during future 3.y.z upgrades.
12+
13+
[NOTE]
14+
====
15+
You can migrate workloads and gateways separately, and in any order. For more information, see "Migrating gateways."
16+
====
17+
18+
.Procedure
19+
20+
. Find the current `IstioRevision` resource for your {SMProduct} 3.0 control plane by running the following command:
21+
+
22+
[source,terminal]
23+
----
24+
$ oc get istios
25+
----
26+
+
27+
.Example output
28+
+
29+
[source,terminal]
30+
----
31+
NAME REVISIONS READY IN USE ACTIVE REVISION STATUS VERSION AGE
32+
ossm-3 1 1 0 ossm-3-v1-24-3 Healthy v1.24.3 30s
33+
----
34+
35+
. Copy the value in the `ACTIVE REVISION` column to use as your `istio.io/rev` label in the next step.
36+
+
37+
[NOTE]
38+
====
39+
The naming format of your revisions depends on which upgrade strategy you choose for your `Istio` instance.
40+
====
41+
42+
. Update the injection labels on the `dataplane` namespace by running the following command:
43+
+
44+
[source,terminal]
45+
----
46+
$ oc label ns bookinfo istio.io/rev=ossm-3-v1-24-3 maistra.io/ignore-namespace="true" istio-injection- --overwrite=true
47+
----
48+
+
49+
Running the `oc label` command performs the following actions:
50+
51+
.. Removes the `istio-injection` label: This label prevents the 3.0 control plane from injecting the proxy. The `istio-injection` label takes precedence over `istio.io/rev` label.
52+
53+
.. Adds the `istio.io/rev=ossm-3-v1-24-3` label: This label ensures that any newly created or restarted pods in the namespace connect to the {SMProduct} 3.0 proxy.
54+
55+
.. Adds the `maistra.io/ignore-namespace: "true"` label: This 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 will have both the {SMProduct} 2.6 and the {SMProduct} 3.0 Container Network Interface(CNI) annotations.
56+
57+
+
58+
[NOTE]
59+
====
60+
Once you apply the `maistra.io/ignore-namespace` label, any new pod created 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.
61+
====
62+
63+
. Restart the workloads by using one of the following options:
64+
+
65+
.. To restart all the workloads at once so that the new pods are injected with the {SMProduct} 3.0 proxy, run the following command:
66+
+
67+
.Example command for `bookinfo` application
68+
[source,terminal]
69+
----
70+
$ oc rollout restart deployments -n bookinfo
71+
----
72+
73+
.. To restart each workload individually, run the following command for each workload:
74+
+
75+
.Example command for `bookinfo` application
76+
[source,terminal]
77+
----
78+
$ oc rollout restart deployments productpage-v1 -n bookinfo
79+
----
80+
81+
. Wait for the `productpage` application to restart by running the following command:
82+
+
83+
[source,terminal]
84+
----
85+
$ oc rollout status deployment productpage-v1 -n bookinfo
86+
----
87+
88+
.Verification
89+
90+
. Verify that the expected workloads are managed by the new control plane by running the following command:
91+
+
92+
[source,terminal]
93+
----
94+
$ istioctl ps -n bookinfo
95+
----
96+
+
97+
.Example output:
98+
[source,terminal]
99+
----
100+
NAME CLUSTER CDS LDS EDS RDS ECDS ISTIOD VERSION
101+
details-v1-7f46897b-d497c.bookinfo Kubernetes SYNCED SYNCED SYNCED SYNCED NOT SENT istiod-install-istio-system-866b57d668-6lpcr 1.20.8
102+
productpage-v1-74bfbd4d65-vsxqm.bookinfo Kubernetes SYNCED (4s) SYNCED (4s) SYNCED (3s) SYNCED (4s) IGNORED istiod-ossm-3-v1-24-1-797bb4d78f-xpchx 1.24.3
103+
ratings-v1-559b64556-c5ppg.bookinfo Kubernetes SYNCED SYNCED SYNCED SYNCED NOT SENT istiod-install-istio-system-866b57d668-6lpcr 1.20.8
104+
reviews-v1-847fb7c54d-qxt5d.bookinfo Kubernetes SYNCED SYNCED SYNCED SYNCED NOT SENT istiod-install-istio-system-866b57d668-6lpcr 1.20.8
105+
reviews-v2-5c7ff5b77b-8jbhd.bookinfo Kubernetes SYNCED SYNCED SYNCED SYNCED NOT SENT istiod-install-istio-system-866b57d668-6lpcr 1.20.8
106+
reviews-v3-5c5d764c9b-rrx8w.bookinfo Kubernetes SYNCED SYNCED SYNCED SYNCED NOT SENT istiod-install-istio-system-866b57d668-6lpcr 1.20.8
107+
----
108+
+
109+
The output shows that the `productpage-v1` deployment is the only deployment that restarted and was injected with the 3.0 proxy. Even if there are different versions of the proxies, communication between services still works.
110+
111+
. If the 2.6 installation contains additional data plane namespaces, migrate the next namespace now.
112+
+
113+
[NOTE]
114+
====
115+
Remove the `maistra.io/ignore-namespace="true"` label only after the 2.6 control plane has been uninstalled.
116+
====

0 commit comments

Comments
 (0)