Updating

Red Hat OpenShift Service Mesh 3.3

Updating OpenShift Service Mesh

Red Hat OpenShift Documentation Team

Abstract

This documentation provides information about how to update OpenShift Service Mesh.

Chapter 1. About updating OpenShift Service Mesh

Red Hat OpenShift Service Mesh upgrade lifecycle involves aligning product and Istio versions through specific Operator channels and orchestrated workflows for the control plane and data plane.

1.1. Understanding versioning

Red Hat OpenShift Service Mesh follows Semantic Versioning for all product releases. Semantic Versioning uses a three-part version number in the format X.Y.Z to communicate the nature of changes in each release.

X (Major version): Indicates significant updates that might include breaking changes, such as architectural shifts, API changes, or schema modifications.
Y (Minor version): Introduces new features and enhancements while maintaining backward compatibility.
Z (Patch version or z-stream release): Delivers critical bug fixes and security updates, such as Common Vulnerabilities and Exposures (CVEs) resolutions. Patch versions do not include new features.

1.1.1. Understanding Service Mesh and Istio versions

The most current OpenShift Service Mesh Operator version is 3.3.1. This version supports the features listed in the "Service Mesh 3.3.1 feature support tables".

The OpenShift Service Mesh Operator includes additional Istio releases for upgrades but supports only the latest Istio version available for each Operator version. See the "Service Mesh version support tables" to identify the supported Istio version for each Operator release.

1.2. Understanding Operator updates and channels

The Operator Lifecycle Manager (OLM) manages Operators and their associated services by using channels to organize and distribute updates. Channels are a way to group related updates.

To ensure that your OpenShift Service Mesh stays current with the latest security patches, bug fixes, and software updates, keep the OpenShift Service Mesh Operator up to date. The upgrade process depends on the configured channel and approval strategy.

OLM provides the following channels for the OpenShift Service Mesh Operator:

Stable channel: tracks the most recent version of the OpenShift Service Mesh 3 Operator and the latest supported version of Istio. This channel enables upgrades to new operator versions and Istio updates immediately following their release. Use the stable channel to stay current with the latest features, bug fixes, and security updates.
Versioned channel: restricts updates to patch-level releases within a specific minor version. For example, stable-3.0 provides access to the latest 3.3.1 patch version. When a new patch release becomes available, you can upgrade the Operator to the newer patch version. To move to a newer minor release, you must manually switch to a different channel. You can use a versioned channel to maintain a consistent minor version while applying only patch updates.

Note

You can find the update strategy field in the Install Operator section and under the sub-section update approval. The default value for the update strategy is Automatic.

1.2.1. About Operator update process

Manage the lifecycle of the OpenShift Service Mesh Operator and the Istio control plane by configuring OLM approval strategies and resource update settings for automated or manual upgrades.

The OpenShift Service Mesh Operator upgrades automatically to the latest available version based on the selected channel when you set the approval strategy field to Automatic (default). If you set the approval strategy field to Manual, Operator Lifecycle Manager (OLM) generates an update request, which a cluster administrator must approve to update the Operator to the latest version.

The Operator update process does not automatically update the Istio control plane unless you set the Istio resource version to an alias (for example, vX.Y-latest) and the updateStrategy to InPlace. This triggers a control plane update when a new version is available in the Operator. By default, the Operator will not update the Istio control plane unless the Istio resource is updated with a new version.

1.2.2. About Istio update process

After updating the OpenShift Service Mesh 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.

The Istio resource configuration includes the following fields that are relevant to the upgrade process:

spec.version: specifies the version of Istio to install. Use the format vX.Y.Z, where X.Y.Z is the required Istio release. For example, set the field to v1.24.4 to install Istio 1.24.4. Or, set the value to an alias such as vX.Y-latest to automatically install the latest supported patch version for the specified minor release.
spec.updateStrategy: defines the strategy for updating the Istio control plane. The available update strategies are InPlace and RevisionBased.

Note

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, it updates the control plane based on the configured updateStrategy type.

1.3. Additional resources

Chapter 2. Updating OpenShift Service Mesh

Compare the available strategies for updating the Istio control plane in Red Hat OpenShift Service Mesh. Identify when to use the InPlace or RevisionBased strategy and learn how to apply each during an upgrade.

2.1. About Istio control plane update strategies

The update strategy affects how the Operator performs the update. The spec.updateStrategy field in the Istio resource configuration determines how the OpenShift Service Mesh 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:

InPlace
RevisionBased

InPlace is the default strategy for updating OpenShift Service Mesh. Both the update strategies apply to sidecar and ambient modes.

If you use ambient mode, you must update the Istio Container Network Interface (CNI) and ZTunnel components in addition to the standard control plane update procedures.

Important

Service Mesh recommends the InPlace update strategy for ambient mode. Using RevisionBased updates with ambient mode has limitations and requires manual intervention.

2.2. About InPlace strategy

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 support compatibility between the sidecars and the control plane, you can upgrade only one minor version at a time.

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.

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 many replicas of the Istio control plane (istiod).

2.2.1. Selecting InPlace strategy

To select the InPlace strategy, set the spec.updateStrategy.type value in the Istio resource to InPlace.

You can see the following example configuration for reference:

kind: Istio
spec:
  updateStrategy:
    type: InPlace

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.

Running the Istio resource in High Availability mode to minimize traffic disruptions requires additional property settings. For more information, see "About Istio High Availability".

2.2.2. Installing with InPlace update strategy

You can install the Istio control plane, Istio CNI, and the Bookinfo demo application by using the Inplace update strategy.

Note

You can skip this installation procedure if the cluster already includes an Istio deployment.

When using the InPlace strategy, the IstioRevision resource created by the OpenShift Service Mesh Operator always uses the same name as the Istio resource.

Procedure

Create the istio-system namespace by running the following command:
```
$ oc create ns istio-system
```
Attach the workloads to a control plane deployed using the InPlace strategy:
1. Label the namespace to automatically include all workloads by entering the following command:
```
$ oc label namespace <namespace_name> istio.io/rev=<revision_name>
```
2. Apply the revision label to individual workloads by modifying the pod template in the Deployment resource. For example:
```
apiVersion: apps/v1
kind: Deployment
spec:
  template:
    metadata:
      labels:
        istio.io/rev: <revision_name>
```
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.
```
$ oc label namespace <namespace_name> istio-injection=enabled
```
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:
```
apiVersion: sailoperator.io/v1
kind: Istio
metadata:
  name: default
spec:
  namespace: istio-system
  version: v1.24.3
  updateStrategy:
    type: InPlace
```
Install the Istio CNI plugin with the required version. The following example configuration creates an IstioCNI resource named default in the istio-cni namespace:
```
apiVersion: sailoperator.io/v1
kind: IstioCNI
metadata:
  name: default
spec:
  version: v1.24.3
  namespace: istio-cni
```
Configure application workloads to run in the cluster. The following example deploys the bookinfo application in the bookinfo namespace.
1. Create the bookinfo namespace by running the following command:
```
$ oc create ns bookinfo
```
2. Label the bookinfo namespace to enable sidecar injection by running the following command:
```
$ oc label namespace bookinfo istio-injection=enabled
```
3. Install the bookinfo pods in the bookinfo namespace by running the following command:
```
$ oc apply -f https://raw.githubusercontent.com/openshift-service-mesh/istio/release-1.24/samples/bookinfo/platform/kube/bookinfo.yaml -n bookinfo
```
Review the Istio resource by running the following command:
```
$ oc get istio -n istio-system
```
Example output:
```
NAME      REVISIONS   READY   IN USE   ACTIVE REVISION   STATUS    VERSION   AGE
default   1           1       1        default           Healthy   v1.24.3   115s
```
The IN USE field shows 1 because both the namespace label and the injected proxies reference the IstioRevision resource.

2.2.3. Updating Istio control plane with InPlace strategy

When updating Istio using the InPlace strategy, you can increment the version by only one minor release at a time. To update by more than one minor version, you must increment the version and restart the workloads after each update.

Note

Restarting workloads ensures compatibility between the sidecar and control plane versions. The update process is complete after restarting all workloads.

Prerequisites

You have logged in to OpenShift Container Platform as a user with the cluster-admin role.
You have installed the Red Hat OpenShift Service Mesh Operator, and deployed Istio.
You have installed istioctl on your local machine.
You have configured the Istio control plane to use the InPlace update strategy. In this example, the Istio resource named default is deployed in the istio-system namespace.
You have installed the Istio CNI plugin with the required version. In this example, the IstioCNI resource named default is deployed in the istio-cni namespace.
You have labeled the bookinfo namespace to enable sidecar injection.
You have application workloads running in the cluster. In this example, the bookinfo application is deployed in the bookinfo namespace.

Procedure

Change the version in the Istio resource. For example, to update to Istio 1.24.4, set the spec.version field to v1.24.4 by running the following command:
```
$ oc patch istio default --type='merge' -p '{"spec":{"version":"v1.24.4"}}'
```
You can see the following example configuration for reference:
```
kind: Istio
spec:
  version: v1.24.4
  updateStrategy:
    type: InPlace
```
The Service Mesh Operator deploys a new version of the control plane that replaces the old version of the control plane. The sidecars automatically reconnect to the new control plane.
Confirm that the new version of the control plane is ready by running the following command:
```
$ oc get istio
```
You should see output similar to the following example:
```
NAME      REVISIONS   READY   IN USE   ACTIVE REVISION   STATUS    VERSION   AGE
default   1           1       1        default           Healthy   v1.24.4   4m50s
```
Restart the application workloads so that the new version of the sidecar gets injected by running the following command:
```
$ oc rollout restart deployment -n bookinfo
```

Verification

Verify that the new version of the sidecar is running by entering the following command:

$ istioctl proxy-status

You should see output similar to the following example:

NAME                                                    CLUSTER        CDS                LDS                EDS                RDS                ECDS        ISTIOD                                     VERSION
details-v1-7d775cb4f6-5t9zm.bookinfo                    Kubernetes     SYNCED (2m25s)     SYNCED (2m25s)     SYNCED (2m17s)     SYNCED (2m25s)     IGNORED     istiod-default-v1-24-4-c98fd9675-r7bfw     1.24.4
productpage-v1-7c4b6b857-mxrw6.bookinfo                 Kubernetes     SYNCED (2m35s)     SYNCED (2m35s)     SYNCED (2m17s)     SYNCED (2m35s)     IGNORED     istiod-default-v1-24-4-c98fd9675-r7bfw     1.24.4
ratings-v1-5b896f8544-r552l.bookinfo                    Kubernetes     SYNCED (2m21s)     SYNCED (2m21s)     SYNCED (2m17s)     SYNCED (2m21s)     IGNORED     istiod-default-v1-24-4-c98fd9675-r7bfw     1.24.4
reviews-v1-746f96c9d4-9pw8k.bookinfo                    Kubernetes     SYNCED (2m17s)     SYNCED (2m17s)     SYNCED (2m17s)     SYNCED (2m17s)     IGNORED     istiod-default-v1-24-4-c98fd9675-r7bfw     1.24.4
reviews-v2-97bdf5876-4mzx5.bookinfo                     Kubernetes     SYNCED (2m35s)     SYNCED (2m35s)     SYNCED (2m17s)     SYNCED (2m35s)     IGNORED     istiod-default-v1-24-4-c98fd9675-r7bfw     1.24.4
reviews-v3-77d9db6844-djgjk.bookinfo                    Kubernetes     SYNCED (2m19s)     SYNCED (2m19s)     SYNCED (2m17s)     SYNCED (2m19s)     IGNORED     istiod-default-v1-24-4-c98fd9675-r7bfw     1.24.4

The column VERSION should match with the new control plane version.

2.3. About RevisionBased strategy

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.

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

Although the RevisionBased strategy involves additional steps and requires many 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.

2.3.1. Selecting RevisionBased strategy

To deploy Istio with the RevisionBased strategy, create the Istio resource with the following spec.updateStrategy value:

You can see the following example configuration for reference:

kind: Istio
spec:
  version: v1.24.4
  updateStrategy:
    type: RevisionBased

After you select the strategy for the Istio resource, the Operator creates a new IstioRevision resource with the name <istio_resource_name>-<version>.

2.3.2. Installing Istio with RevisionBased strategy

You can install the Istio control plane, Istio CNI, and the Bookinfo demo application by using the RevisionBased update strategy.

Note

You can use the following section to understand the update process. You can skip this installation if the cluster already includes an Istio deployment.

Procedure

Create the istio-system namespace by running the following command:
```
$ oc create ns istio-system
```
Deploy the Istio control plane using the RevisionBased update strategy. The following example configuration creates an Istio resource named default in the istio-system namespace:
You can see the following example configuration for reference:
```
apiVersion: sailoperator.io/v1
kind: Istio
metadata:
  name: default
spec:
  namespace: istio-system
  version: v1.24.3
  updateStrategy:
    type: RevisionBased
```
Install the Istio CNI plugin with the required version. The following example configuration creates an IstioCNI resource named default in the istio-cni namespace:
You can see the following example configuration for reference:
```
apiVersion: sailoperator.io/v1
kind: IstioCNI
metadata:
  name: default
spec:
  version: v1.24.3
  namespace: istio-cni
```
Get the IstioRevision name by running the following command:
```
$ oc get istiorevision -n istio-system
```
You should see output similar to the following example:
```
NAME              TYPE    READY   STATUS    IN USE   VERSION   AGE
default-v1-24-3   Local   True    Healthy   False    v1.24.3   3m4s
```
The IstioRevision name is in the format <istio_resource_name>-<version>.
Configure application workloads to run in the cluster. The following example deploys the bookinfo application in the bookinfo namespace:
1. Create the bookinfo namespace by running the following command:
```
$ oc create ns bookinfo
```
2. Label the bookinfo namespace to enable sidecar injection by running the following command:
```
$ oc label namespace bookinfo istio.io/rev=<revision_name>
```
3. Install the bookinfo pods in the bookinfo namespace by running the following command:
```
$ oc apply -f https://raw.githubusercontent.com/openshift-service-mesh/istio/release-1.24/samples/bookinfo/platform/kube/bookinfo.yaml -n bookinfo
```
Review the Istio resource by running the following command:
```
$ oc get istio -n istio-system
```
You should see output similar to the following example:
```
NAME      REVISIONS   READY   IN USE   ACTIVE REVISION   STATUS    VERSION   AGE
default   1           1       1        default-v1-24-3   Healthy   v1.24.3   5m13s
```
The IN USE field shows 1 after you deploy the application.
Confirm that the proxy version matches the control plane version by running the following command:
```
$ istioctl proxy-status
```
The VERSION column should match the control plane version.
You should see output similar to the following example:
```
NAME              TYPE    READY   STATUS    IN USE   VERSION   AGE
default-v1-24-3   Local   True    Healthy   True     v1.24.3   5m31s
```

2.3.3. Updating Istio control plane with RevisionBased strategy

When updating Istio using the RevisionBased strategy, you can upgrade by more than one minor version at a time. The Red Hat OpenShift Service Mesh Operator creates a new IstioRevision resource for each change to the .spec.version field and deploys a corresponding control plane instance. To migrate workloads to the new control plane, set the istio.io/rev label on the namespace to match the name of the IstioRevision resource, and then restart the workloads.

Prerequisites

You have logged in to OpenShift Container Platform as a user with the cluster-admin role.
You have installed the Red Hat OpenShift Service Mesh Operator 3, and deployed Istio with the RevisionBased strategy. In this example, the Istio resource named default is deployed in the istio-system namespace.
You have installed the Istio CNI plugin with the required version. In this example, the IstioCNI resource named default is deployed in the istio-cni namespace.
You have labeled the bookinfo namespace to enable sidecar injection.
You have application workloads running in the cluster. In this example, the bookinfo application is deployed in the bookinfo namespace.
You have installed istioctl on your local machine.

Procedure

Change the version in the Istio resource. For example, to update to Istio 1.24.4, set the spec.version field to v1.24.4 by running the following command:
```
$ oc patch istio default --type='merge' -p '{"spec":{"version":"v1.24.4"}}'
```
Version Update in Istio CR:
```
kind: Istio
spec:
  version: v1.24.4
  updateStrategy:
    type: RevisionBased
```
The Service Mesh Operator deploys a new version of the control plane alongside the old version of the control plane. The sidecars remain connected to the old control plane.
Confirm that both Istio and IstioRevision resources are ready with the new revision.
1. Confirm that Istio resource is ready by running the following command:
```
$ oc get istio
```
  You should see output similar to the following example:
```
NAME      REVISIONS   READY   IN USE   ACTIVE REVISION   STATUS    VERSION   AGE
default   2           2       1        default-v1-2-4   Healthy   v1.24.4   9m23s
```
2. Confirm that IstioRevision resource is ready by running the following command:
```
$ oc get istiorevision
```
  You should see output similar to the following example:
```
NAME              TYPE    READY   STATUS    IN USE   VERSION   AGE
default-v1-24-3   Local   True    Healthy   True     v1.24.3   10m
default-v1-24-4   Local   True    Healthy   False    v1.24.4   66s
```

Confirm that there are two control plane pods running, one for each revision by running the following command:

$ oc get pods -n istio-system

You should see output similar to the following example:

NAME                                      READY   STATUS    RESTARTS   AGE
istiod-default-v1-24-3-c98fd9675-r7bfw    1/1     Running   0          10m
istiod-default-v1-24-4-7495cdc7bf-v8t4g   1/1     Running   0          113s

Confirm that the workload sidecars are still connected to the earlier control plane by running the following command:

$ istioctl proxy-status

You should see output similar to the following example:

NAME                                                    CLUSTER        CDS                LDS                EDS                RDS                ECDS        ISTIOD                                     VERSION
details-v1-7d775cb4f6-5t9zm.bookinfo                    Kubernetes     SYNCED (2m25s)     SYNCED (2m25s)     SYNCED (2m17s)     SYNCED (2m25s)     IGNORED     istiod-default-v1-24-3-c98fd9675-r7bfw     1.24.3
productpage-v1-7c4b6b857-mxrw6.bookinfo                 Kubernetes     SYNCED (2m35s)     SYNCED (2m35s)     SYNCED (2m17s)     SYNCED (2m35s)     IGNORED     istiod-default-v1-24-3-c98fd9675-r7bfw     1.24.3
ratings-v1-5b896f8544-r552l.bookinfo                    Kubernetes     SYNCED (2m21s)     SYNCED (2m21s)     SYNCED (2m17s)     SYNCED (2m21s)     IGNORED     istiod-default-v1-24-3-c98fd9675-r7bfw     1.24.3
reviews-v1-746f96c9d4-9pw8k.bookinfo                    Kubernetes     SYNCED (2m17s)     SYNCED (2m17s)     SYNCED (2m17s)     SYNCED (2m17s)     IGNORED     istiod-default-v1-24-3-c98fd9675-r7bfw     1.24.3
reviews-v2-97bdf5876-4mzx5.bookinfo                     Kubernetes     SYNCED (2m35s)     SYNCED (2m35s)     SYNCED (2m17s)     SYNCED (2m35s)     IGNORED     istiod-default-v1-24-3-c98fd9675-r7bfw     1.24.3
reviews-v3-77d9db6844-djgjk.bookinfo                    Kubernetes     SYNCED (2m19s)     SYNCED (2m19s)     SYNCED (2m17s)     SYNCED (2m19s)     IGNORED     istiod-default-v1-24-3-c98fd9675-r7bfw     1.24.3

The VERSION column should match the old control plane version.

Move the workloads to the new control plane by updating the istio.io/rev label on the application namespace or pods to the revision name. For example, update the label for the entire namespace by running the following command:
```
$ oc label namespace bookinfo istio.io/rev=<new_revision_name> --overwrite
```
Restart the application workloads so that the new version of the sidecar gets injected by running the following command:
```
$ oc rollout restart deployment -n bookinfo
```

Verification

Verify that the new version of the sidecar is running by entering the following command:
```
$ istioctl proxy-status
```
The VERSION column should match the new control plane version.
Verify that the old control plane, Istio, and IstioRevision resources has been deleted.
1. Verify that the old control plane has beend deleted by running the following command:
```
$ oc get pods -n istio-system
```
2. Verify that the Istio resource has been deleted by running the following command:
```
$ oc get istio
```
3. Verify that the IstioRevision resource has been deleted by running the following command:
```
$ oc get istiorevision
```

The OpenShift Service Mesh Operator deletes the old IstioRevision resource and the associated control plane after the grace period defined in the spec.updateStrategy.inactiveRevisionDeletionGracePeriodSeconds field expires. The default grace period is 30 seconds.

You can increase the grace period to allow enough time to test the new control plane before removing the earlier revision. Set a higher value during canary upgrades to ensure workload stability before fully transitioning.

2.3.4. Installing Istio with RevisionBased strategy and IstioRevisionTag

You can install the Istio control plane, IstioRevisionTag resource, Istio CNI, and the Bookinfo demo application by using the RevisionBased update strategy.

Note

You can use the following section to understand the update process. You can skip this installation if the cluster already includes an Istio deployment.

Procedure

Create the istio-system namespace by running the following command:
```
$ oc create ns istio-system
```
Deploy the Istio control plane using the RevisionBased update strategy. The following example configuration creates an Istio resource named default in the istio-system namespace:
You can see the following example configuration for reference:
```
apiVersion: sailoperator.io/v1
kind: Istio
metadata:
  name: default
spec:
  namespace: istio-system
  updateStrategy:
    type: RevisionBased
  version: v1.24.3
```
Create an IstioRevisionTag resource. The following example configuration creates an IstioRevisionTag resource named default:
You can see the following example configuration for reference:
```
apiVersion: sailoperator.io/v1
kind: IstioRevisionTag
metadata:
  name: default
spec:
  targetRef:
    kind: Istio
    name: default
```
Verify that the targetRef field points to the required Istio resource. In the example above, the IstioRevisionTag references the Istio resource named default.
Create the istio-cni namespace by running the following command:
```
$ oc create ns istion-cni
```
Install the Istio CNI plugin with the required version. The following example configuration creates an IstioCNI resource named default in the istio-cni namespace:
You can see the following example configuration for reference:
```
apiVersion: sailoperator.io/v1
kind: IstioCNI
metadata:
  name: default
spec:
  version: v1.24.3
  namespace: istio-cni
```
Configure application workloads to run in the cluster. The following example deploys the bookinfo application in the bookinfo namespace.
1. Create the bookinfo namespace by running the following command:
```
$ oc create ns bookinfo
```
2. Label the bookinfo namespace to enable sidecar injection by running the following command:
```
$ oc label namespace bookinfo istio-injection=enabled
```
3. Install the bookinfo pods in the bookinfo namespace by running the following command:
```
$ oc apply -f https://raw.githubusercontent.com/openshift-service-mesh/istio/release-1.24/samples/bookinfo/platform/kube/bookinfo.yaml -n bookinfo
```
Review the IstioRevisionTag resource by running the following command:
```
$ oc get istiorevisiontag
```
You should see output similar to the following example:
```
NAME      STATUS    IN USE   REVISION          AGE
default   Healthy   True     default-v1-24-3   2m46s
```
The IN USE field shows True because both active workloads and the bookinfo namespace now reference the tag.
Confirm that the proxy version matches the control plane version by running the following command:
```
$ istioctl proxy-status
```
The VERSION column should match the control plane version.
You should see output similar to the following example:
```
NAME              TYPE    READY   STATUS    IN USE   VERSION   AGE
default-v1-24-3   Local   True    Healthy   True     v1.24.3   5m31s
```

2.3.5. Updating Istio control plane with RevisionBased strategy and IstioRevisionTag

When updating Istio using the RevisionBased strategy, you can create an IstioRevisionTag resource to tag a specific IstioRevision resource. You can use the IstioRevisionTag resource to attach workloads to a specific IstioRevision resource without modifying the istio.io/rev label on namespaces or pods.

Prerequisites

You have logged in to OpenShift Container Platform as a user with the cluster-admin role.
You have installed the Red Hat OpenShift Service Mesh Operator 3, and deployed Istio with the RevisionBased strategy. In this example, the Istio resource named default is deployed in the istio-system namespace.
You have created an IstioRevisionTag resource and the targetRef field is referencing the required Istio resource.
You have installed the Istio CNI plugin with the required version.
You have labeled the bookinfo namespace to enable sidecar injection.
You have application workloads running in the cluster. In this example, the bookinfo application is deployed in the bookinfo namespace.
You have installed istioctl on your local machine.
You have set the InUse field in the IstioRevisionTag resource to true.

Procedure

Change the version in the Istio resource. For example, to update to Istio 1.24.4, set the spec.version field to v1.24.4 by running the following command:
```
$ oc patch istio default --type='merge' -p '{"spec":{"version":"v1.24.4"}}'
```
You can see the following example configuration for reference:
```
kind: Istio
spec:
  version: v1.24.4
  updateStrategy:
    type: RevisionBased
```
The Service Mesh Operator deploys a new version of the control plane alongside the old version of the control plane. The sidecars remain connected to the old control plane.
Confirm that the Istio, IstioRevision and IstioRevisionTag resources are ready with the new revision.
1. Confirm that Istio resource is ready by running the following command:
```
$ oc get istio
```
  You should see output similar to the following example:
```
NAME      REVISIONS   READY   IN USE   ACTIVE REVISION   STATUS    VERSION   AGE
default   2           2       1        default-v1-24-3   Healthy   v1.24.3   9m23s
```
2. Confirm that IstioRevision resource is ready by running the following command:
```
$ oc get istiorevision
```
  You should see output similar to the following example:
```
NAME              TYPE    READY   STATUS    IN USE   VERSION   AGE
default-v1-24-3   Local   True    Healthy   True     v1.24.3   10m
default-v1-24-4   Local   True    Healthy   True     v1.24.4   66s
```
3. Confirm that IstioRevisionTag resource is ready by running the following command:
```
$ oc get istiorevisiontag
```
  You should see output similar to the following example:
```
NAME      STATUS    IN USE   REVISION          AGE
default   Healthy   True     default-v1-24-4   10m44s
```

Confirm that there are two control plane pods ready for each revision by running the following command:

$ oc get pods -n istio-system

You should see output similar to the following example:

NAME                                      READY   STATUS    RESTARTS   AGE
istiod-default-v1-24-3-c98fd9675-r7bfw    1/1     Running   0          10m
istiod-default-v1-24-4-7495cdc7bf-v8t4g   1/1     Running   0          113s

Confirm that the proxy sidecar version is the same by running the following command:

$ istioctl proxy-status

You should see output similar to the following example:

NAME                                                    CLUSTER        CDS                LDS                EDS                RDS                ECDS        ISTIOD                                     VERSION
details-v1-7d775cb4f6-5t9zm.bookinfo                    Kubernetes     SYNCED (2m25s)     SYNCED (2m25s)     SYNCED (2m17s)     SYNCED (2m25s)     IGNORED     istiod-default-v1-24-3-c98fd9675-r7bfw     1.24.3
productpage-v1-7c4b6b857-mxrw6.bookinfo                 Kubernetes     SYNCED (2m35s)     SYNCED (2m35s)     SYNCED (2m17s)     SYNCED (2m35s)     IGNORED     istiod-default-v1-24-3-c98fd9675-r7bfw     1.24.3
ratings-v1-5b896f8544-r552l.bookinfo                    Kubernetes     SYNCED (2m21s)     SYNCED (2m21s)     SYNCED (2m17s)     SYNCED (2m21s)     IGNORED     istiod-default-v1-24-3-c98fd9675-r7bfw     1.24.3
reviews-v1-746f96c9d4-9pw8k.bookinfo                    Kubernetes     SYNCED (2m17s)     SYNCED (2m17s)     SYNCED (2m17s)     SYNCED (2m17s)     IGNORED     istiod-default-v1-24-3-c98fd9675-r7bfw     1.24.3
reviews-v2-97bdf5876-4mzx5.bookinfo                     Kubernetes     SYNCED (2m35s)     SYNCED (2m35s)     SYNCED (2m17s)     SYNCED (2m35s)     IGNORED     istiod-default-v1-24-3-c98fd9675-r7bfw     1.24.3
reviews-v3-77d9db6844-djgjk.bookinfo                    Kubernetes     SYNCED (2m19s)     SYNCED (2m19s)     SYNCED (2m17s)     SYNCED (2m19s)     IGNORED     istiod-default-v1-24-3-c98fd9675-r7bfw     1.24.3

The VERSION column should match the old control plane version.

Restart the application workloads so that the new version of the sidecar gets injected by running the following command:
```
$ oc rollout restart deployment -n bookinfo
```

Verification

Verify that the new version of the sidecar is running by entering the following command:
```
$ istioctl proxy-status
```
The VERSION column should match the new control plane version.
Verify that the old control plane, Istio, and IstioRevision resources has been deleted.
1. Verify that the old control plane has been deleted by running the following command:
```
$ oc get pods -n istio-system
```
2. Verify that the Istio resource has been deleted by running the following command:
```
$ oc get istio
```
3. Verify that the IstioRevision resource has beend deleted by running the following command:
```
$ oc get istiorevision
```

2.4. Additional resources

Updating waypoint proxies with InPlace strategy in ambient mode
Updating waypoint proxies with RevisionBased strategy in ambient mode

Chapter 3. Updating OpenShift Service Mesh in ambient mode

Update Red Hat OpenShift Service Mesh in ambient mode by transitioning the control plane and waypoint proxies to new revisions while maintaining Layer 7 (L7) functionality and resource compatibility.

3.1. About the update strategies in ambient mode

In ambient mode, components update directly through InPlace updates. In ambient mode, you can move application pods to an upgraded ztunnel proxy without restarting or rescheduling them, unlike sidecar mode.

Update sequence

To update in ambient mode, use the following sequence:

Istio control plane: Update the patch version in the Istio resource.
Istio CNI: Update to the same patch version as the control plane.
ZTunnel: Update to the same patch version as the control plane.

3.2. Updating waypoint proxies with InPlace strategy in ambient mode

Maintain application uptime during InPlace updates by independently upgrading waypoint proxies through the Kubernetes Gateway API without restarting associated workloads.

Prerequisites

You have updated the Istio control plane with InPlace update strategy.

Procedure

Confirm that you updated the waypoint proxy to the latest proxy version by running the following command:
```
$ istioctl proxy-status | grep waypoint
```
You should see an output similar to the following example:
```
waypoint-5d9c8b7f9-abc12.bookinfo     SYNCED     SYNCED     SYNCED     SYNCED     istiod-6cf8d4f9cb-wm7x6.istio-system     1.28.5
```
You can run the command to query the Istio control plane and verify that the waypoint proxy connects and synchronizes. The output lists the waypoint proxy name and namespace, the synchronization status for each configuration type, the connected istiod pod, and the Istio version of the running proxy. Columns showing SYNCED confirm that the waypoint proxy is successfully receiving configuration from the control plane.

3.3. Updating waypoint proxies with RevisionBased strategy in ambient mode

In ambient mode, you can update waypoint proxies by using the RevisionBased update strategy. During the migration period, the proxies remain compatible with many control plane versions and automatically connect to the active control plane revision.

Note

Keep waypoint proxies within one minor version of the control plane (same version or n-1). This recommendation aligns with the support policy of Istio, which states that data plane components must not run ahead of the control plane version. Apply the same versioning guidance to Istio Container Network Interface (CNI) and Ztunnel components. For more details, see the "Istio Supported Releases" documentation.

Prerequisites

You have updated the Istio control plane with RevisionBased update strategy.

Procedure

After the new Istio control plane revision is ready, verify waypoint proxy pods are running by entering the following command:
```
$ oc get pods -n bookinfo -l gateway.networking.k8s.io/gateway-name=waypoint
```
You should see an output similar to the following example:
```
NAME                       READY   STATUS    RESTARTS   AGE
waypoint-5d9c8b7f9-abc12   1/1     Running   0          5m
```
Confirm that you updated the waypoint proxy to the latest version by running the following command:
```
$ istioctl proxy-status | grep waypoint
```
You should see an output similar to the following example:
```
waypoint-5d9c8b7f9-abc12.bookinfo     SYNCED     SYNCED     SYNCED     SYNCED     istiod-1-27-3-7b9f8c5d6-xyz78.istio-system     1.28.5
```
You can run the command to query the Istio control plane and verify that the waypoint proxy connects to the new revision. The output lists the revision-specific istiod pod (for example, istiod-1-27-3) and shows that the waypoint proxy is running the updated version, 1.28.5. The revision-specific name in the ISTIOD column confirms that the waypoint proxy has successfully migrated to the new control plane revision.

3.4. Verifying Layer 7 (L7) features with traffic routing

After updating the waypoint proxies, verify that Layer 7 (L7) features function as expected. If you use traffic routing rules such as HTTPRoute, confirm that they continue to enforce the intended behavior.

Prerequisites

You have updated the waypoint proxies.
You have deployed the bookinfo application.
You have created an HTTPRoute resource.

Procedure

Optional: Create the HTTPRoute resource if it does not already exist by running the following command:

$ oc apply -f - <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: reviews
  namespace: bookinfo
spec:
  parentRefs:
  - group: ""
    kind: Service
    name: reviews
    port: 9080
  rules:
  - backendRefs:
    - name: reviews-v1
      port: 9080
      weight: 90
    - name: reviews-v2
      port: 9080
      weight: 10
EOF

Verify that the HTTPRoute rules distribute traffic correctly by running the following command:
```
for i in {1..10}; do
  kubectl exec "$(
    kubectl get pod \
      -l app=productpage \
      -n bookinfo \
      -o jsonpath='{.items[0].metadata.name}'
  )" \
  -c istio-proxy \
  -n bookinfo -- \
  curl -s http://reviews:9080/reviews/0 | grep -o "reviews-v[0-9]"
done
```
The output should reflect the traffic distribution defined in your HTTPRoute. For example, with a 90/10 weight split between reviews-v1 and reviews-v2, you should observe about nine requests routed to reviews-v1 and one request routed to reviews-v2. The exact ratio can vary slightly due to load balancing behavior, but should closely match the configured weights over many test runs.

3.5. Verifying Layer 7 (L7) features with authorization policies

After updating the waypoint proxies, verify that the Layer 7 (L7) authorization policies enforce correctly. In this example, the AuthorizationPolicy resource named productpage-waypoint allows only requests from the default/sa/curl service account to send GET requests to the productpage service.

Prerequisites

You have updated the waypoint proxies.
You have created an application pod using the described service account in the AuthorizationPolicy resource.
You have created an AuthorizationPolicy resource.

Procedure

Optional: Create the AuthorizationPolicy resource if it does not already exist by running the following command:

$ oc apply -f - <<EOF
apiVersion: security.istio.io/v1
kind: AuthorizationPolicy
metadata:
  name: productpage-waypoint
  namespace: bookinfo
spec:
  targetRefs:
  - kind: Service
    group: ""
    name: productpage
  action: ALLOW
  rules:
  - from:
    - source:
        principals:
        - cluster.local/ns/default/sa/curl
    to:
    - operation:
        methods: ["GET"]
EOF

Verify that services not included in the allow list, such as the ratings service, are denied access by running the following command:
```
$ oc exec "$(
  kubectl get pod \
    -l app=ratings \
    -n bookinfo \
    -o jsonpath='{.items[0].metadata.name}'
)" \
-c ratings \
-n bookinfo -- \
curl -sS productpage:9080/productpage
```
The request will be denied because the ratings service is not included in the authorization policy’s allow list. Only the curl pod by using the default/curl service account can access productpage service.
Verify that the curl service can access the productpage service with GET requests by running the following command:
```
oc exec "$(
  kubectl get pod \
    -l app=curl \
    -n default \
    -o jsonpath='{.items[0].metadata.name}'
)" \
-c curl \
-n default -- \
curl -sS http://productpage.bookinfo:9080/productpage | grep -o "<title>.*</title>"
```
The request will succeed because the curl service meets the authorization policy rules. It uses the cluster.local/ns/default/sa/curl principal and performs a GET operation, both allowed by the policy. The successful response containing the page title confirms that the waypoint proxy correctly enforces L7 authorization rules and allows valid traffic.

3.6. Updating cross-namespace waypoint

If you are using cross-namespace waypoints, verify that the istio.io/use-waypoint-namespace and istio.io/use-waypoint labels are correctly applied to the relevant namespaces before updating.

Procedure

Verify the namespace with any of the waypoint labels by running the following command:
```
$ oc get ns bookinfo --show-labels | grep waypoint
```
If there is no namespace with the label or if the label is wrong, re-apply the labels:
1. Apply the istio.io/use-waypoint-namespace by running the following command:
```
$ oc label ns bookinfo istio.io/use-waypoint-namespace=foo --overwrite
```
2. Apply the istio.io/use-waypoint by running the following command:
```
$ oc label ns bookinfo istio.io/use-waypoint=waypoint-foo --overwrite
```

3.7. About Ztunnel update lifecycle

Understand the Ztunnel rolling update process, and how the process affects connection persistence during a proxy restart.

Ztunnel operates at Layer 4 (L4) of the Open Systems Interconnection (OSI) model and proxies TCP traffic. Ztunnel cannot transfer connection states to another process. Upgrading the Ztunnel DaemonSet affects all traffic on at least one node at a time. By default, the Ztunnel DaemonSet uses a RollingUpdate strategy. During a restart, each node goes through the following phases:

Startup: A new Ztunnel pod starts on the node while the old pod continues running.
Readiness: The new Ztunnel establishes listeners in each pod on the node and marks itself as ready. For a brief period, both instances run simultaneously, and either one might handle new connections.
Draining: Kubernetes sends a SIGTERM to the old Ztunnel, which begins the draining process. The old instance closes its listeners so that only the new Ztunnel accepts new connections. At all times, at least one Ztunnel remains available to handle incoming connections.
Connection processing: The old Ztunnel continues processing existing connections until the terminationGracePeriodSeconds expires.
Termination: Once the terminationGracePeriodSeconds expires, the old Ztunnel forcefully terminates any remaining connections.

3.7.1. Configuring the Ztunnel termination grace period

Configure a high termination grace period in the ZTunnel custom resource (CR) for the application pods to ensure that active connections close gracefully during a rolling update.

Procedure

Update the terminationGracePeriodSeconds value in the ZTunnel CR to a higher value similar to the following example:

apiVersion: sailoperator.io/v1
kind: ZTunnel
metadata:
  name: default
spec:
  version: 1.28.5
  namespace: ztunnel
  values:
    ztunnel:
      terminationGracePeriodSeconds: 300

3.7.2. Updating Ztunnel using node draining

Drain nodes to force long-lived TCP connections to reconnect through a new Ztunnel instance, without risking traffic loss because the node is empty during the proxy swap.

Procedure

Configure the OnDelete update strategy in the ZTunnel custom resource (CR) to need manual pod deletion before the update to the new version starts, similar to the following example:
```
apiVersion: sailoperator.io/v1
kind: ZTunnel
metadata:
  name: default
spec:
  version: 1.28.5
  namespace: ztunnel
  values:
    ztunnel:
      updateStrategy:
        type: OnDelete
```
Update the version field in the ZTunnel CR to the target version.
Drain a node to force all applications to move to other nodes, allowing their long-lived connections to close gracefully based on their terminationGracePeriodSeconds.
Delete the old Ztunnel pod on the empty node and wait for the new pod to start.
Mark the node as schedulable. Applications that return to the node will automatically use the new Ztunnel.
Repeat steps 3 through 5 for all remaining nodes in the cluster.

3.8. Additional resources

Chapter 4. Updating the Istio CNI

Review the update procedure for the Istio Container Network Interface (CNI). Ensure the CNI plugin remains compatible with the OpenShift Service Mesh control plane during an upgrade.

4.1. About the Istio CNI update process

The Istio Container Network Interface (CNI) update process uses Inplace updates. When the IstioCNI resource changes, the daemonset automatically replaces the existing istio-cni-node pods with the specified version of the CNI plugin.

You can use the following field to manage version updates:

spec.version: defines the CNI plugin version to install. Specify the value in the format vX.Y.Z, where X.Y.Z represents the required version. For example, use v1.28.5 to install the CNI plugin version 1.28.5.

To update the CNI plugin, change the spec.version field with the target version. The IstioCNI resource also includes a values field that exposes configuration options from the istio-cni chart.

In ambient mode, the Istio CNI component manages traffic redirection. During RevisionBased upgrades, the component remains compatible with the control plane’s old version and continues to manage traffic redirection for both the old and the new control planes throughout the migration.

Note

The Istio CNI is compatible with a control plane running the same minor version or one minor version higher.

After you update the Istio control plane, update the Istio CNI component. The OpenShift Service Mesh Operator deploys a new version of the CNI plugin, replacing the existing one. The istio-cni-node DaemonSet pods update using a rolling update strategy, ensuring that traffic redirection rules remain active during the entire update process.

4.1.1. Updating the Istio CNI resource version

Update the Istio CNI plugin by modifying the version in the resource, triggering the Service Mesh Operator to deploy new plugin versions and automatically reconnect the node pods.

Prerequisites

You have logged in to OpenShift Container Platform as a user with the cluster-admin role.
You have installed the Red Hat OpenShift Service Mesh Operator and deployed Istio.
You have installed the Istio CNI plugin with the required version. In the following example, the deployment of the IstioCNI resource named default is in the istio-cni namespace.
You have either updated the Istio control plane to the required version (for Inplace strategy) or created a new control plane revision (for RevisionBased strategy).

Procedure

Change the version in the Istio resource. For example, to update to Istio 1.28.5, set the spec.version field to 1.28.5 by running the following command:
```
$ oc patch istiocni default -n istio-cni --type='merge' -p '{"spec":{"version":"v1.28.5"}}'
```
Wait for the IstioCNI DaemonSet to reach the Ready status after the update by running the following command:
```
$ oc wait --for=condition=Ready istiocnis/default --timeout=5m
```
Confirm that the new version of the CNI plugin is ready by running the following command:
```
$ oc get istiocni default
```
You should see an output similar to the following example:
```
NAME      READY   STATUS    VERSION   AGE
default   True    Healthy   v{istio-latest}   7d1h
```
Check the status of the pods by running the following command:
```
$ oc get pods -n istio-cni
```
You should see an output similar to the following example:
```
NAME                   READY   STATUS    RESTARTS   AGE
istio-cni-node-abc12   1/1     Running   0          3m
istio-cni-node-def34   1/1     Running   0          3m
istio-cni-node-ghi56   1/1     Running   0          3m
```
Note
When you use the RevisionBased strategy, the Istio CNI component remains compatible with many control plane versions. It continues to manage traffic redirection for both the old and the new control planes throughout the migration. The Istio CNI is compatible with a control plane running the same minor version or one minor version higher.

Legal Notice

Except as otherwise noted below, the text of and illustrations in this documentation are licensed by Red Hat under the Creative Commons Attribution–Share Alike 3.0 Unported license . If you distribute this document or an adaptation of it, you must provide the URL for the original version.

Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.

Red Hat, the Red Hat logo, JBoss, Hibernate, and RHCE are trademarks or registered trademarks of Red Hat, LLC. or its subsidiaries in the United States and other countries.

Linux® is the registered trademark of Linus Torvalds in the United States and other countries.

XFS is a trademark or registered trademark of Hewlett Packard Enterprise Development LP or its subsidiaries in the United States and other countries.

The OpenStack® Word Mark and OpenStack logo are trademarks or registered trademarks of the Linux Foundation, used under license.

All other trademarks are the property of their respective owners.