Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 1. Updating OpenShift Service Mesh

The strategy you use to deploy a service mesh affects how you can update the mesh.

1.1. Understanding versioning
Copy link

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.2. Understanding Service Mesh and Istio versions
Copy link

The most current OpenShift Service Mesh Operator version is 3.1.1. This version supports the features listed in the "Service Mesh 3.1.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.3. Understanding Operator updates and channels
Copy link

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 corresponding Istio updates as soon as they are released. 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.1.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.3.1. About Operator update process
Copy link

The OpenShift Service Mesh Operator will upgrade automatically to the latest available version based on the selected channel when the approval strategy field is set to Automatic (default). If the approval strategy field is set to Manual, Operator Lifecycle Manager (OLM) will generate 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 the Istio resource version is set to an alias (for example, vX.Y-latest) and the updateStrategy is set 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.4. About Istio update process
Copy link

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

1.4.1. About Istio control plane update strategies
Copy link

The update strategy affects how the update process is performed. 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.

1.5. About InPlace strategy
Copy link

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.

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

1.5.1. Selecting InPlace strategy
Copy link

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

Example specification to select InPlace update strategy

kind: Istio
spec:
  updateStrategy:
    type: InPlace
Copy to Clipboard Toggle word wrap

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

1.5.2. Installing with InPlace update strategy
Copy link

You can install the Istio control plane, Istio CNI, and the Bookinfo demo application 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

  1. Create the istio-system namespace by running the following command: 

    $ oc create ns istio-system
    Copy to Clipboard Toggle word wrap

  2. 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>
      Copy to Clipboard Toggle word wrap

    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>
      Copy to Clipboard Toggle word wrap

  3. 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
    Copy to Clipboard Toggle word wrap

  4. 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
    Copy to Clipboard Toggle word wrap

  5. Install the Istio CNI plugin with the desired 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
    Copy to Clipboard Toggle word wrap

  6. 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
      Copy to Clipboard Toggle word wrap

    2. Label the bookinfo namespace to enable sidecar injection by running the following command: 

      $ oc label namespace bookinfo istio-injection=enabled
      Copy to Clipboard Toggle word wrap

    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
      Copy to Clipboard Toggle word wrap

  7. Review the Istio resource by running the following command: 

    $ oc get istio -n istio-system
    Copy to Clipboard Toggle word wrap

    Example output

    NAME      REVISIONS   READY   IN USE   ACTIVE REVISION   STATUS    VERSION   AGE
default   1           1       1        default           Healthy   v1.24.3   115s
    Copy to Clipboard Toggle word wrap

    The IN USE field shows 1 because both the namespace label and the injected proxies reference the IstioRevision resource.

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. Restarting workloads ensures compatibility between the sidecar and control plane versions. The update process is complete after restarting all workloads.

Prerequisites

  • You are 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 desired 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

  1. 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"}}'
    Copy to Clipboard Toggle word wrap

    Version update in Istio CR

    kind: Istio
spec:
  version: v1.24.4
  updateStrategy:
    type: InPlace
    Copy to Clipboard Toggle word wrap

    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.

  2. Confirm that the new version of the control plane is ready by running the following command: 

    $ oc get istio
    Copy to Clipboard Toggle word wrap

    Example output

    NAME      REVISIONS   READY   IN USE   ACTIVE REVISION   STATUS    VERSION   AGE
default   1           1       1        default           Healthy   v1.24.4   4m50s
    Copy to Clipboard Toggle word wrap

  3. 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
    Copy to Clipboard Toggle word wrap

Verification

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

    $ istioctl proxy-status
    Copy to Clipboard Toggle word wrap

    Example output

    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
    Copy to Clipboard Toggle word wrap

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

1.6. About RevisionBased strategy
Copy link

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

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.

1.6.1. Selecting RevisionBased strategy
Copy link

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

Example specification to select RevisionBased strategy

kind: Istio
spec:
  version: v1.24.4
  updateStrategy:
    type: RevisionBased
Copy to Clipboard Toggle word wrap

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

You can install the Istio control plane, Istio CNI, and the Bookinfo demo application 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

  1. Create the istio-system namespace by running the following command: 

    $ oc create ns istio-system
    Copy to Clipboard Toggle word wrap

  2. 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:

    Example configuration

    apiVersion: sailoperator.io/v1
kind: Istio
metadata:
  name: default
spec:
  namespace: istio-system
  version: v1.24.3
  updateStrategy:
    type: RevisionBased
    Copy to Clipboard Toggle word wrap

  3. Install the Istio CNI plugin with the desired version. The following example configuration creates an IstioCNI resource named default in the istio-cni namespace:

    Example configuration

    apiVersion: sailoperator.io/v1
kind: IstioCNI
metadata:
  name: default
spec:
  version: v1.24.3
  namespace: istio-cni
    Copy to Clipboard Toggle word wrap

  4. Get the IstioRevision name by running the following command: 

    $ oc get istiorevision -n istio-system
    Copy to Clipboard Toggle word wrap

    Example output

    NAME              TYPE    READY   STATUS    IN USE   VERSION   AGE
default-v1-24-3   Local   True    Healthy   False    v1.24.3   3m4s
    Copy to Clipboard Toggle word wrap

    The IstioRevision name is in the format <istio_resource_name>-<version>.

  5. 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
      Copy to Clipboard Toggle word wrap

    2. Label the bookinfo namespace to enable sidecar injection by running the following command: 

      $ oc label namespace bookinfo istio.io/rev=<revision_name>
      Copy to Clipboard Toggle word wrap

    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
      Copy to Clipboard Toggle word wrap

  6. Review the Istio resource by running the following command: 

    $ oc get istio -n istio-system
    Copy to Clipboard Toggle word wrap

    Example output

    NAME      REVISIONS   READY   IN USE   ACTIVE REVISION   STATUS    VERSION   AGE
default   1           1       1        default-v1-24-3   Healthy   v1.24.3   5m13s
    Copy to Clipboard Toggle word wrap

    The IN USE field shows 1 after you deploy the application.

  7. Confirm that the proxy version matches the control plane version by running the following command: 

    $ istioctl proxy-status
    Copy to Clipboard Toggle word wrap

    The VERSION column should match the control plane version.

    Example output

    NAME              TYPE    READY   STATUS    IN USE   VERSION   AGE
default-v1-24-3   Local   True    Healthy   True     v1.24.3   5m31s
    Copy to Clipboard Toggle word wrap

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 are 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 desired 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

  1. 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"}}'
    Copy to Clipboard Toggle word wrap

    Version Update in Istio CR

    kind: Istio
spec:
  version: v1.24.4
  updateStrategy:
    type: RevisionBased
    Copy to Clipboard Toggle word wrap

    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.

  2. 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
      Copy to Clipboard Toggle word wrap

      Example output

      NAME      REVISIONS   READY   IN USE   ACTIVE REVISION   STATUS    VERSION   AGE
default   2           2       1        default-v1-2-4   Healthy   v1.24.4   9m23s
      Copy to Clipboard Toggle word wrap

    2. Confirm that IstioRevision resource is ready by running the following command: 

      $ oc get istiorevision
      Copy to Clipboard Toggle word wrap

      Example output

      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
      Copy to Clipboard Toggle word wrap

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

    $ oc get pods -n istio-system
    Copy to Clipboard Toggle word wrap

    Example output

    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
    Copy to Clipboard Toggle word wrap

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

    $ istioctl proxy-status
    Copy to Clipboard Toggle word wrap

    Example output

    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
    Copy to Clipboard Toggle word wrap

    The VERSION column should match the old control plane version.

  5. 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
    Copy to Clipboard Toggle word wrap

  6. 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
    Copy to Clipboard Toggle word wrap

Verification

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

    $ istioctl proxy-status
    Copy to Clipboard Toggle word wrap

    The VERSION column should match the new control plane version.

  2. 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
      Copy to Clipboard Toggle word wrap

    2. Verify that the Istio resource has been deleted by running the following command: 

      $ oc get istio
      Copy to Clipboard Toggle word wrap

    3. Verify that the IstioRevision resource has been deleted by running the following command: 

      $ oc get istiorevision
      Copy to Clipboard Toggle word wrap

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 sufficient time to test the new control plane before removing the previous revision. Set a higher value during canary upgrades to ensure workload stability before fully transitioning.

You can install the Istio control plane, IstioRevisionTag resource, Istio CNI, and the Bookinfo demo application 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

  1. Create the istio-system namespace by running the following command: 

    $ oc create ns istio-system
    Copy to Clipboard Toggle word wrap

  2. 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:

    Example configuration

    apiVersion: sailoperator.io/v1
kind: Istio
metadata:
  name: default
spec:
  namespace: istio-system
  updateStrategy:
    type: RevisionBased
  version: v1.24.3
    Copy to Clipboard Toggle word wrap

  3. Create an IstioRevisionTag resource. The following example configuration creates an IstioRevisionTag resource named default:

    Example configuration

    apiVersion: sailoperator.io/v1
kind: IstioRevisionTag
metadata:
  name: default
spec:
  targetRef:
    kind: Istio
    name: default
    Copy to Clipboard Toggle word wrap

    Verify that the targetRef field points to the desired Istio resource. In the example above, the IstioRevisionTag references the Istio resource named default.

  4. Create the istio-cni namespace by running the following command: 

    $ oc create ns istion-cni
    Copy to Clipboard Toggle word wrap

  5. Install the Istio CNI plugin with the desired version. The following example configuration creates an IstioCNI resource named default in the istio-cni namespace:

    Example configuration

    apiVersion: sailoperator.io/v1
kind: IstioCNI
metadata:
  name: default
spec:
  version: v1.24.3
  namespace: istio-cni
    Copy to Clipboard Toggle word wrap

  6. 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
      Copy to Clipboard Toggle word wrap

    2. Label the bookinfo namespace to enable sidecar injection by running the following command: 

      $ oc label namespace bookinfo istio-injection=enabled
      Copy to Clipboard Toggle word wrap

    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
      Copy to Clipboard Toggle word wrap

  7. Review the IstioRevisionTag resource by running the following command: 

    $ oc get istiorevisiontag
    Copy to Clipboard Toggle word wrap

    Example output

    NAME      STATUS    IN USE   REVISION          AGE
default   Healthy   True     default-v1-24-3   2m46s
    Copy to Clipboard Toggle word wrap

    The IN USE field shows True because both active workloads and the bookinfo namespace now reference the tag.

  8. Confirm that the proxy version matches the control plane version by running the following command: 

    $ istioctl proxy-status
    Copy to Clipboard Toggle word wrap

    The VERSION column should match the control plane version.

    Example output

    NAME              TYPE    READY   STATUS    IN USE   VERSION   AGE
default-v1-24-3   Local   True    Healthy   True     v1.24.3   5m31s
    Copy to Clipboard Toggle word wrap

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 are 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 desired Istio resource.
  • You have installed the Istio CNI plugin with the desired 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 confirmed that the InUse field in the IstioRevisionTag resource is set to true.

Procedure

  1. 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"}}'
    Copy to Clipboard Toggle word wrap

    Version Update in Istio CR

    kind: Istio
spec:
  version: v1.24.4
  updateStrategy:
    type: RevisionBased
    Copy to Clipboard Toggle word wrap

    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.

  2. 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
      Copy to Clipboard Toggle word wrap

      Example output

      NAME      REVISIONS   READY   IN USE   ACTIVE REVISION   STATUS    VERSION   AGE
default   2           2       1        default-v1-24-3   Healthy   v1.24.3   9m23s
      Copy to Clipboard Toggle word wrap

    2. Confirm that IstioRevision resource is ready by running the following command: 

      $ oc get istiorevision
      Copy to Clipboard Toggle word wrap

      Example output

      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
      Copy to Clipboard Toggle word wrap

    3. Confirm that IstioRevisionTag resource is ready by running the following command: 

      $ oc get istiorevisiontag
      Copy to Clipboard Toggle word wrap

      Example output

      NAME      STATUS    IN USE   REVISION          AGE
default   Healthy   True     default-v1-24-4   10m44s
      Copy to Clipboard Toggle word wrap

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

    $ oc get pods -n istio-system
    Copy to Clipboard Toggle word wrap

    Example output

    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
    Copy to Clipboard Toggle word wrap

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

    $ istioctl proxy-status
    Copy to Clipboard Toggle word wrap

    Example output

    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
    Copy to Clipboard Toggle word wrap

    The VERSION column should match the old control plane version.

  5. 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
    Copy to Clipboard Toggle word wrap

Verification

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

    $ istioctl proxy-status
    Copy to Clipboard Toggle word wrap

    The VERSION column should match the new control plane version.

  2. 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
      Copy to Clipboard Toggle word wrap

    2. Verify that the Istio resource has been deleted by running the following command: 

      $ oc get istio
      Copy to Clipboard Toggle word wrap

    3. Verify that the IstioRevision resource has beend deleted by running the following command: 

      $ oc get istiorevision
      Copy to Clipboard Toggle word wrap

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 sufficient time to test the new control plane before removing the previous revision. Set a higher value during canary upgrades to ensure workload stability before fully transitioning.

1.7. About the Istio CNI update process
Copy link

The Istio Container Network Interface (CNI) update process uses in-place 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 desired version. For example, use v1.24.4 to install the CNI plugin version 1.24.4.

To update the CNI plugin, modify 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.

1.7.1. Updating the Istio CNI resource version
Copy link

You can update the Istio CNI resource version by changing the version in the resource. Then, the Service Mesh Operator deploys a new version of the CNI plugin that replaces the old version of the CNI plugin. The istio-cni-node pods automatically reconnect to the new CNI plugin.

Prerequisites

  • You are logged in to OpenShift Container Platform as a user with the cluster-admin role.
  • You installed the Red Hat OpenShift Service Mesh Operator and deployed Istio.
  • You installed the Istio CNI plugin with the desired version. In the following example, the IstioCNI resource named default is deployed in the istio-cni namespace.

Procedure

  1. 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 istiocni default -n istio-cni --type='merge' -p '{"spec":{"version":"v1.24.4"}}'
    Copy to Clipboard Toggle word wrap

  2. Confirm that the new version of the CNI plugin is ready by running the following command: 

    $ oc get istiocni default
    Copy to Clipboard Toggle word wrap

    Example Output

    NAME      READY   STATUS    VERSION   AGE
default   True    Healthy   v1.24.4   91m
    Copy to Clipboard Toggle word wrap

Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat