Skip to content

Commit 9bcda74

Browse files
JSticklerJStickler
authored
Merge pull request #48055 from JStickler/OSSMDOC-428
OSSMDOC-428: Break upgrade into modules.
2 parents e9bbeb2 + 25ee136 commit 9bcda74

File tree

5 files changed

+117
-50
lines changed

5 files changed

+117
-50
lines changed

‎modules/ossm-upgrade-20-21-changes.adoc

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
// Module included in the following assemblies:
2+
// * service_mesh/v2x/upgrading-ossm.adoc
3+
4+
:_content-type: CONCEPT
5+
[id="ossm-upgrade-20-21-changes_{context}"]
6+
= Upgrade changes from version 2.0 to version 2.1
7+
8+
Upgrading the control plane from version 2.0 to 2.1 introduces the following architectural and behavioral changes.
9+
10+
.Architecture changes
11+
12+
Mixer has been completely removed in {SMProductName} 2.1. Upgrading from a {SMProductName} 2.0.x release to 2.1 will be blocked if Mixer is enabled.
13+
14+
[id="ossm-upgrading-differences-behavior_{context}"]
15+
.Behavioral changes
16+
17+
* `AuthorizationPolicy` updates:
18+
** With the PROXY protocol, if you're using `ipBlocks` and `notIpBlocks` to specify remote IP addresses, update the configuration to use `remoteIpBlocks` and `notRemoteIpBlocks` instead.
19+
** Added support for nested JSON Web Token (JWT) claims.
20+
* `EnvoyFilter` breaking changes>
21+
** Must use `typed_config`
22+
** xDS v2 is no longer supported
23+
** Deprecated filter names
24+
* Older versions of proxies may report 503 status codes when receiving 1xx or 204 status codes from newer proxies.
25+
26+
[NOTE]
27+
====
28+
Red Hat is unable to support `EnvoyFilter` configuration except where explicitly documented. This is due to tight coupling with the underlying Envoy APIs, meaning that backward compatibility cannot be maintained.
29+
====

‎modules/ossm-upgrade-apps-workloads.adoc

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
// Module included in the following assemblies:
2+
// * service_mesh/v2x/upgrading-ossm.adoc
3+
4+
:_content-type: CONCEPT
5+
[id="ossm-upgrading-apps-workloads_{context}"]
6+
= Updating your applications and workloads
7+
8+
To complete the migration, restart all of the application pods in the mesh to upgrade the Envoy sidecar proxies and their configuration.
9+
10+
To perform a rolling update of a deployment use the following command:
11+
12+
[source,terminal]
13+
----
14+
$ oc rollout restart <deployment>
15+
----
16+
17+
You must perform a rolling update for all applications that make up the mesh.

‎modules/ossm-upgrading-to-21.adoc renamed to ‎modules/ossm-upgrading-from-20-to-21.adoc

Lines changed: 6 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -2,20 +2,15 @@
22
// * service_mesh/v2x/upgrading-ossm.adoc
33

44
:_content-type: PROCEDURE
5-
[id="ossm-upgrading-to-21_{context}"]
6-
= Upgrading {SMProductName} from version 2.0 to version 2.1
7-
8-
Upgrading from version 2.0 to 2.1 requires manual steps that migrate your workloads and application to a new instance of {SMProductName} running the new version.
9-
10-
[id="ossm-upgrading-upgrade-2-1_{context}"]
11-
== Upgrading to {SMProductName} 2.1
5+
[id="ossm-upgrading-from-20-21_{context}"]
6+
= Upgrading to {SMProductName} 2.1
127

138
To upgrade {SMProductName}, you must update the version field of the {SMProductName} `ServiceMeshControlPlane` v2 resource. Then, once it's configured and applied, restart the application pods to update each sidecar proxy and its configuration.
149

1510
.Prerequisites
1611

1712
* You are running {product-title} 4.6 or later.
18-
* You have the {SMProductName} version 2.1.0 operator. If the *automatic* upgrade path is enabled, the operator automatically downloads the latest information. However, there are steps you must take to use the features in {SMProductName} version 2.1.
13+
* You have the {SMProductName} version 2.1.x operator. If the *automatic* upgrade path is enabled, the operator automatically downloads the latest information. However, there are steps you must take to use the features in {SMProductName} version 2.1.
1914
* You must upgrade from {SMProductName} 2.0 to 2.1. You cannot upgrade `ServiceMeshControlPlane` from 1.1 to 2.1 directly.
2015
2116
.Procedure
@@ -27,7 +22,7 @@ To upgrade {SMProductName}, you must update the version field of the {SMProductN
2722
$ oc project istio-system
2823
----
2924

30-
. Check your v2 `ServiceMeshControlPlane` resource configuration to make sure it is valid.
25+
. Check your v2 `ServiceMeshControlPlane` resource configuration to verify it is valid.
3126
+
3227
.. Run the following command to view your `ServiceMeshControlPlane` resource as a v2 resource.
3328
+
@@ -55,6 +50,8 @@ For example:
5550
+
5651
[source,terminal]
5752
----
53+
apiVersion: maistra.io/v2
54+
kind: ServiceMeshControlPlane
5855
spec:
5956
policy:
6057
type: Istiod
@@ -69,43 +66,3 @@ Alternatively, instead of using the command line, you can use the web console to
6966
.. Find your `ServiceMeshControlPlane` instance.
7067
.. Select *YAML view* and update text of the YAML file, as shown in the previous example.
7168
.. Click *Save*.
72-
73-
[id="ossm-upgrading-differences-arch_{context}"]
74-
== Changes from prior release
75-
76-
This upgrade introduces the following architectural and behavioral changes.
77-
78-
.Architecture changes
79-
80-
Mixer has been completely removed in {SMProductName} 2.1. Upgrading from a {SMProductName} 2.0.x release to 2.1 will be blocked if Mixer is enabled.
81-
82-
[id="ossm-upgrading-differences-behavior_{context}"]
83-
.Behavioral changes
84-
85-
* `AuthorizationPolicy` updates
86-
** With the PROXY protocol, if you're using `ipBlocks` and `notIpBlocks` to specify remote IP addresses, update the configuration to use `remoteIpBlocks` and `notRemoteIpBlocks` instead.
87-
** Added support for nested JSON Web Token (JWT) claims
88-
* `EnvoyFilter` breaking changes
89-
** Must use `typed_config`
90-
** xDS v2 is no longer supported
91-
** Deprecated filter names
92-
* Older versions of proxies may report 503 status codes when receiving 1xx or 204 status codes from newer proxies.
93-
94-
[NOTE]
95-
====
96-
Red Hat is unable to support `EnvoyFilter` configuration except where explicitly documented. This is due to tight coupling with the underlying Envoy APIs, meaning that backward compatibility cannot be maintained.
97-
====
98-
99-
[id="ossm-upgrading-mig-apps_{context}"]
100-
== Next steps for migrating your applications and workloads
101-
102-
To complete the migration, restart all of the application pods in the mesh to upgrade the Envoy sidecar proxies and their configuration.
103-
104-
To perform a rolling update of a deployment use the following command:
105-
106-
[source,terminal]
107-
----
108-
$ oc rollout restart <deployment>
109-
----
110-
111-
You must perform a rolling update for all applications that make up the mesh.

‎modules/ossm-upgrading-from-21-to-22.adoc

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
// Module included in the following assemblies:
2+
// * service_mesh/v2x/upgrading-ossm.adoc
3+
4+
:_content-type: PROCEDURE
5+
[id="ossm-upgrading-from-21-22_{context}"]
6+
= Upgrading to {SMProductName} 2.2
7+
8+
To upgrade {SMProductName}, you must update the version field of the {SMProductName} `ServiceMeshControlPlane` v2 resource. Then, once it's configured and applied, restart the application pods to update each sidecar proxy and its configuration.
9+
10+
.Prerequisites
11+
12+
* You are running {product-title} 4.9 or later.
13+
* You have the {SMProductName} version 2.2.x operator.
14+
* You cannot upgrade your `ServiceMeshControlPlane` from 1.1 to 2.2 directly. Because of possibly breaking changes at each stage, you must migrate from 1.1 to 2.0, then upgrade from 2.0 to 2.1, then upgrade 2.1 to 2.2.
15+
16+
.Procedure
17+
18+
. Switch to the project that contains your `ServiceMeshControlPlane` resource. In this example, `istio-system` is the name of the control plane project.
19+
+
20+
[source,terminal]
21+
----
22+
$ oc project istio-system
23+
----
24+
25+
. Check your v2 `ServiceMeshControlPlane` resource configuration to make sure it is valid.
26+
+
27+
.. Run the following command to view your `ServiceMeshControlPlane` resource as a v2 resource.
28+
+
29+
[source,terminal]
30+
----
31+
$ oc get smcp -o yaml
32+
----
33+
+
34+
[TIP]
35+
====
36+
Back up your control plane configuration.
37+
====
38+
39+
. Update the `.spec.version` field from v2.1 to v2.2, and apply the configuration.
40+
+
41+
For example:
42+
+
43+
[source,terminal]
44+
----
45+
apiVersion: maistra.io/v2
46+
kind: ServiceMeshControlPlane
47+
metadata:
48+
name: basic
49+
spec:
50+
version: v2.2
51+
----
52+
+
53+
Alternatively, instead of using the command line, you can use the web console to edit the control plane. In the {product-title} web console, click *Project* and select the project name you just entered.
54+
+
55+
.. Click *Operators* -> *Installed Operators*.
56+
.. Find your `ServiceMeshControlPlane` instance.
57+
.. Select *YAML view* and update text of the YAML file, as shown in the previous example.
58+
.. Click *Save*.

‎service_mesh/v2x/upgrading-ossm.adoc

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,12 @@ include::modules/ossm-upgrading-operator.adoc[leveloffset=+1]
1919

2020
For more information about upgrading Operators, refer to the xref:../../operators/admin/olm-upgrading-operators.adoc[Operator Lifecycle Manager] documentation.
2121

22-
include::modules/ossm-upgrading-to-21.adoc[leveloffset=+1]
22+
include::modules/ossm-upgrading-from-21-to-22.adoc[leveloffset=+2]
23+
24+
include::modules/ossm-upgrade-20-21-changes.adoc[leveloffset=+2]
25+
26+
include::modules/ossm-upgrading-from-20-to-21.adoc[leveloffset=+2]
27+
28+
include::modules/ossm-upgrade-apps-workloads.adoc[leveloffset=+1]
2329

2430
include::modules/ossm-migrating-to-20.adoc[leveloffset=+1]

0 commit comments

Comments
 (0)