×

Serverless Operator maintenance release upgrades

Latest and maintenance releases

Beginning with OpenShift Serverless 1.29, the different product versions are available as follows:

  • The latest release is available through the stable channel.

  • The maintenance release is available through its version-based channel, for example, stable-1.29.

    The maintenance release is the release prior to the latest release. For example, if the stable channel includes version 1.30, then the maintenance release will be available in the stable-1.29 channel.

Using a version-based channel allows you to stay within a specific x.y stream. Additionally, it prevents an upgrade to the latest version of the product, which might contain breaking changes.

To switch to the maintenance release, update the channel parameter in the subscription object YAML file from stable to the corresponding version-based channel, such as stable-1.29.

Patches and hotfixes for maintenance releases

As with the stable release, the maintenance release is subject to patches and hotfixes, which help to keep your deployment up to date with critical bug and security fixes.

  • Patches are updates that are distributed as z-releases, for example, OpenShift Serverless 1.29.1 is the patch that provides updates made since version 1.29.0.

  • Hotfixes are fixes that require zero downtime and are used directly in production. They are different from the usual updates in that they upgrade the customer’s deployed version, and not the latest released version.

    Hotfixes might not be available to all customers immediately. However, changes introduced by hotfixes often become available to all customers as part of a future release.

    When a hotfix pertaining to your deployment is available, you will be given the hotfix CatalogSource to update your subscription and obtain the hotfix.

    After a new operator release is available, deployed operators with hotfixes can also be upgraded. To use the latest GA version, modify the subscription to use the public CatalogSource instead of the hotfix one.

The following diagram illustrates how patches and hotfixes work:

     stable                                       stable-1.28
+--------------+                 +--------------------------------------------+
|              |                 |                                            |
|  +--------+  | corresponds to  |   +--------+    +--------+    +--------+   |
|  | 1.28.0 |----------------------> | 1.28.0 |    | 1.28.1 |    | 1.28.2 |   |
|  +--------+  |                 |   +--------+    +--------+    +--------+   |
|              |                 |     |                   ^            |     |
|              |                 +-----|-------------------|------------|-----+
|  +--------+  |                created|                   |upgrades    |
|  | 1.28.1 |  |                from   |     hotfix_xyz    |to          |
|  +--------+  |                       |   +------------+  |            |
|              |                       +-->|            |--+            |
|              |                           |            |               |
|  +--------+  | upgrades to               +------------+               |
|  | 1.29.0 |<----------------------------------------------------------+
|  +--------+  |
|              |
|              |
|  +--------+  |
|  | 1.30.0 |  |
|  +--------+  |
|              |
+--------------+

Upgrade path for maintenance releases

If you use a version-based channel, you can always upgrade to the latest version in the channel, or head. For example, you can upgrade from 1.29.0 to 1.29.2 in the stable-1.29 channel.

Additionally, from the head of the channel, you can upgrade to the next x.y release. For example, if 1.29.2 is the head in the stable-1.29 channel, you can upgrade from 1.29.2 to 1.30. Such cross-channel updates are not done automatically, and the administrator needs to switch the channel manually by updating the subscription.

Upgrade examples

Scenario 1

In this scenario, the following circumstances are true:

  • The channel is stable-1.28

  • You are switching to the stable channel

  • The currently installed version is 1.28.0

  • 1.29.0 was released before 1.28.1

  • 1.30.0 is the head of the stable channel

The upgrade path from 1.28.0 on stable-1.28 to 1.29.0 on stable in this scenario is 1.28.0 to 1.28.1 to 1.29.0.

     stable                    stable-1.28
+--------------+            +--------------+
|              |            |              |
|  +--------+  |            |  +--------+  |
|  | 1.28.0 |  |            |  | 1.28.0 |  |
|  +--------+  |            |  +--------+  |
|              |            |       |      |
|              |            |       |      |
|  +--------+  |            |       |      |
|  | 1.29.0 |<--------      |       v      |
|  +--------+  |     |      |  +--------+  |
|              |     +---------| 1.28.1 |  |
|              |            |  +--------+  |
|  +--------+  |            |              |
|  | 1.30.0 |  |            |              |
|  +--------+  |            |              |
|              |            |              |
+--------------+            +--------------+

Scenario 2

In this scenario, the following circumstances are true:

  • The channel is stable-1.29

  • The currently installed version is 1.29.0

  • 1.29.1 was released to both the stable-1.29 and stable channels before 1.30.0 was released to the stable channel

The upgrade path from 1.29.0 on stable-1.29 to 1.30.0 on stable in this scenario is 1.29.0 to 1.29.1 to 1.30.0.

     stable                   stable-1.29
+--------------+           +--------------+
|              |           |              |
|  +--------+  |           |  +--------+  |
|  | 1.29.0 |  |           |  | 1.29.0 |  |
|  +--------+  |           |  +--------+  |
|              |           |       |      |
|              |           |       v      |
|  +--------+  |           |  +--------+  |
|  | 1.29.1 |  |           |  | 1.29.1 |  |
|  +--------+  |           |  +--------+  |
|              |           |       |      |
|              |           |       |      |
|  +--------+  |           |       |      |
|  | 1.30.0 |<---------------------+      |
|  +--------+  |           |              |
|              |           |              |
+--------------+           +--------------+

Scenario 3

In this scenario, the following circumstances are true:

  • The channel is stable-1.29

  • You are switching to the stable-1.30 channel

  • The currently installed version is 1.29.1

  • 1.29.1 is the head of the stable-1.29 channel

The upgrade path from 1.29.1 on stable-1.29 to 1.30.0 on stable-1.30 in this scenario is 1.29.1 to 1.30.0.

   stable-1.29              stable-1.30
+--------------+         +--------------+
|              |         |              |
|  +--------+  |         |  +--------+  |
|  | 1.29.0 |  |    ------> | 1.30.0 |  |
|  +--------+  |    |    |  +--------+  |
|              |    |    |              |
|              |    |    |              |
|  +--------+  |    |    |              |
|  | 1.29.1 |-------+    |              |
|  +--------+  |         |              |
|              |         |              |
+--------------+         +--------------+

Resolving an OpenShift Serverless Operator upgrade failure

You might encounter an error when upgrading OpenShift Serverless Operator, for example, when performing manual uninstalls and reinstalls. If you encounter an error, you must manually reinstall OpenShift Serverless Operator.

Procedure
  1. Identify the version of OpenShift Serverless Operator that was installed originally by searching in the OpenShift Serverless Release Notes.

    For example, the error message during attempted upgrade might contain the following string:

    The installed KnativeServing version is v1.5.0.

    In this example, the KnativeServing MAJOR.MINOR version is 1.5, which is covered in the release notes for OpenShift Serverless 1.26: OpenShift Serverless now uses Knative Serving 1.5.

  2. Uninstall OpenShift Serverless Operator and all of its install plans.

  3. Manually install the version of OpenShift Serverless Operator that you discovered in the first step. To install, first create a serverless-subscription.yaml file as shown in the following example:

    apiVersion: operators.coreos.com/v1alpha1
    kind: Subscription
    metadata:
      name: serverless-operator
      namespace: openshift-serverless
    spec:
      channel: stable
      name: serverless-operator
      source: redhat-operators
      sourceNamespace: openshift-marketplace
      installPlanApproval: Manual
      startingCSV: serverless-operator.v1.26.0
  4. Then, install the subscription by running the following command:

    $ oc apply -f serverless-subscription.yaml
  5. Upgrade by manually approving the upgrade install plans as they appear.