Skip to content

Commit c3837f2

Browse files
xenolinuxxenolinux
authored
Merge pull request #92318 from shreyasiddhartha/OSSM-9337
OSSM-9337 Document Istio control plane update strategy: InPlace strategy
2 parents 831a527 + 3b454e3 commit c3837f2

12 files changed

+225
-110
lines changed

‎install/ossm-installing-openshift-service-mesh.adoc

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,8 @@ Before installing {SMProduct} 3, make sure you are not running {SMProduct} 3 and
1414
====
1515

1616
include::modules/ossm-about-deploying-istio-using-service-mesh-operator.adoc[leveloffset=+1]
17-
include::modules/ossm-about-deployment-and-update-strategies.adoc[leveloffset=+2]
17+
include::modules/ossm-about-istio-control-plane-update-strategies.adoc
18+
[leveloffset=+2]
1819
include::modules/ossm-installing-operator.adoc[leveloffset=+1]
1920

2021
[role="_additional-resources"]

‎modules/ossm-about-deployment-and-update-strategies.adoc

Lines changed: 0 additions & 16 deletions
This file was deleted.

‎modules/ossm-about-inplace-strategy.adoc

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,9 @@
44
:_mod-docs-content-type: Concept
55
[id="about-inplace-strategy_{context}"]
66
= About InPlace strategy
7-
:context: ossm-about-inplace-strategy
87

9-
The `InPlace` strategy runs only one revision of the control plane at all times. When you perform an `InPlace` update, all of the workloads immediately connect to the new version of the control plane. In order to ensure compatibility between the sidecars and the control plane you cannot upgrade by more than one minor version at a time.
8+
The `InPlace` update strategy runs only one revision of the control plane at a time. During an update, all the workloads immediately connect to the new control plane version. To maintain compatibility between the sidecars and the control plane, you can upgrade only one minor version at a time.
9+
10+
The `InPlace` strategy updates and restarts the existing {istio} control plane in place. During this process, only one instance of the control plane exists, eliminating the need to move workloads to a new control plane instance. To complete the update, restart the application workloads and gateways to refresh the Envoy proxies.
11+
12+
While the `InPlace` strategy offers simplicity and efficiency, there's a slight possibility of application traffic interruption if a workload pod updates, restarts, or scales while the control plane is restarting. You can mitigate this risk by running multiple replicas of the {istio} control plane (istiod).

‎modules/ossm-about-istio-control-plane-update-strategies.adoc

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
// Module included in the following assemblies:
2+
// update/ossm-updating-openshift-service-mesh.adoc
3+
4+
:_mod-docs-content-type: CONCEPT
5+
[id="ossm-about-istio-control-plane-update-strategies_{context}"]
6+
= About Istio control plane update strategies
7+
8+
The update strategy affects how the update process is performed. The `spec.updateStrategy` field in the `{istio}` resource configuration determines how the {SMProduct} Operator updates the {istio} control plane. When the Operator detects a change in the `spec.version` field or identifies a new minor release with a configured `vX.Y-latest` alias, it initiates an upgrade procedure. For each mesh, you select one of two strategies:
9+
10+
* `InPlace`
11+
* `RevisionBased`
12+
13+
`InPlace` is the default strategy for updating {SMProduct}.
14+

‎modules/ossm-about-istio-update-process.adoc

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
// Module included in the following assemblies:
2+
3+
// * update/ossm-updating-openshift-service-mesh.adoc
4+
5+
:_mod-docs-content-type: CONCEPT
6+
[id="ossm-about-istio-update-process_{context}"]
7+
= About Istio update process
8+
9+
After updating the {SMProduct} Operator, update the {istio} control plane to the latest supported version. The `{istio}` resource configuration determines how the control plane upgrade is performed, including which steps require manual action and which are handled automatically.
10+
11+
The `{istio}` resource configuration includes the following fields that are relevant to the upgrade process:
12+
13+
`spec.version`:: specifies the version of {istio} to install. Use the format `vX.Y.Z`, where `X.Y.Z` is the desired {istio} release. For example, set the field to `v1.24.4` to install {istio} `1.24.4`. Alternatively, set the value to an alias such as `vX.Y-latest` to automatically install the latest supported patch version for the specified minor release.
14+
15+
`spec.updateStrategy`:: defines the strategy for updating the {istio} control plane. The available update strategies are `InPlace` and `RevisionBased`.
16+
17+
[NOTE]
18+
====
19+
To enable automatic patch upgrades, set the approval strategy of the Operator to `Automatic`. When the Operator detects a new patch release and the `version` field uses the `vX.Y-latest` alias, the control plane is updated based on the configured `updateStrategy` type.
20+
====

‎modules/ossm-about-revisionbased-strategy.adoc

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,12 @@
11
// Module included in the following assemblies:
22
// update/ossm-updating-openshift-service-mesh.adoc
33

4-
:_mod-docs-content-type: Concept
4+
:_mod-docs-content-type: CONCEPT
55
[id="about-revisionbased-strategy_{context}"]
66
= About RevisionBased strategy
7-
:context: ossm-about-revisionbased-strategy
87

9-
An update that is performed using the `RevisionBased` strategy runs two revisions of a control plane. This capability allows you to gradually migrate workloads from the old control plane to the new control plane, making canary upgrades possible. The `RevisionBased` strategy also allows you to update by more than one minor version.
8+
The `RevisionBased` strategy runs two revisions of the control plane during an upgrade. This approach supports gradual workload migration from the old control plane to the new one, enabling canary upgrades. It also supports upgrades across more than one minor version.
9+
10+
The `RevisionBased` strategy creates a new {istio} control plane instance for each change to the `spec.version` field. The existing control plane remains active until all workloads transition to the new instance. You can move the workloads to the new control plane by updating the `istio.io/rev` labels or using the `IstioRevisionTag` resource, followed by a restart.
11+
12+
Although the `RevisionBased` strategy involves additional steps and requires multiple control plane instances to run concurrently during the upgrade, it allows for gradual migration of workloads. This approach enables validation of the updated control plane with a subset of workloads before migrating the rest, making it useful for large meshes with mission-critical workloads.

‎modules/ossm-attach-workloads-to-control-plane.adoc

Lines changed: 0 additions & 37 deletions
This file was deleted.

‎modules/ossm-performing-inplace-update.adoc

Lines changed: 0 additions & 43 deletions
This file was deleted.

‎modules/ossm-preparing-to-update-istio-control-plane-with-inplace.adoc

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
// Module included in the following assemblies:
2+
// update/ossm-updating-openshift-service-mesh.adoc
3+
4+
:_mod-docs-content-type: PROCEDURE
5+
[id="preparing-to-update-istio-control-plane-with-inplace_{context}"]
6+
= Preparing to update Istio control plane with InPlace strategy
7+
8+
You can configure the {istio} control plane and workloads for the `InPlace` update strategy. When using the `InPlace` strategy, the `IstioRevision` resource created by the {SMProduct} Operator always uses the same name as the `{istio}` resource.
9+
10+
.Procedure
11+
12+
. Attach the workloads to a control plane deployed using the `InPlace` strategy:
13+
14+
.. Label the namespace to automatically include all workloads by entering the following command:
15+
+
16+
[source,terminal]
17+
----
18+
$ oc label namespace <namespace_name> istio.io/rev=<revision_name>
19+
----
20+
21+
.. Apply the revision label to individual workloads by modifying the pod template in the `Deployment` resource. For example:
22+
+
23+
[source,yaml, subs="attributes,verbatim"]
24+
----
25+
apiVersion: apps/v1
26+
kind: Deployment
27+
spec:
28+
template:
29+
metadata:
30+
labels:
31+
istio.io/rev: <revision_name>
32+
----
33+
34+
. If the revision name is `default`, attach the workloads to the revision by running the following command. The following example labels the namespace with `istio-injection: enabled` label.
35+
+
36+
[source,terminal]
37+
----
38+
$ oc label namespace <namespace_name> istio-injection=enabled
39+
----
40+
41+
. Deploy the {istio} control plane using the `InPlace` update strategy. The following example configuration creates an `{istio}` resource named `default` in the `istio-system` namespace:
42+
+
43+
[source,yaml, subs="attributes,verbatim"]
44+
----
45+
apiVersion: sailoperator.io/v1
46+
kind: Istio
47+
metadata:
48+
name: default
49+
spec:
50+
namespace: istio-system
51+
version: v1.24.3
52+
updateStrategy:
53+
type: InPlace
54+
----
55+
56+
. Install the {istio} CNI plugin with the desired version. The following example configuration creates an `IstioCNI` resource named `default` in the `istio-cni` namespace:
57+
+
58+
[source,yaml, subs="attributes,verbatim"]
59+
----
60+
apiVersion: sailoperator.io/v1
61+
kind: IstioCNI
62+
metadata:
63+
name: default
64+
spec:
65+
version: v1.24.3
66+
namespace: istio-cni
67+
----
68+
69+
. Configure application workloads to run in the cluster. The following example deploys the `bookinfo` application in the `bookinfo` namespace.
70+
71+
.. Create the `bookinfo` namespace by running the following command:
72+
+
73+
[source,terminal]
74+
----
75+
$ oc create ns bookinfo
76+
----
77+
78+
.. Install the `bookinfo` pods in the `bookinfo` namespace by running the following command:
79+
+
80+
[source,terminal]
81+
----
82+
$ oc apply -f https://raw.githubusercontent.com/openshift-service-mesh/istio/release-1.24/samples/bookinfo/platform/kube/bookinfo.yaml -n bookinfo
83+
----
84+
85+
. Label the `bookinfo` namespace to enable sidecar injection by running the following command:
86+
+
87+
[source,terminal]
88+
----
89+
$ oc label namespace bookinfo istio-injection=enabled
90+
----

‎modules/ossm-select-inplace-strategy.adoc renamed to ‎modules/ossm-selecting-inplace-strategy.adoc

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,8 @@
22
// update/ossm-updating-openshift-service-mesh.adoc
33

44
:_mod-docs-content-type: Concept
5-
[id="select-inplace-strategy_{context}"]
6-
= Select InPlace strategy
7-
:context: ossm-select-inplace-strategy
5+
[id="selecting-inplace-strategy_{context}"]
6+
= Selecting InPlace strategy
87

98
To select the `InPlace` strategy, set the `spec.updateStrategy.type` value in the {istio} resource to `InPlace`.
109

@@ -17,4 +16,4 @@ spec:
1716
type: InPlace
1817
----
1918

20-
You can set this value when you first create the resource or you can edit the resource later. If you choose to edit the resource after it is created, make the change prior to updating the {istio} control plane.
19+
You can set this value while creating the resource or edit it later. If you edit the resource after creation, make the change before updating the {istio} control plane.

0 commit comments

Comments
 (0)