Chapter 9. Serverless upgrades
OpenShift Serverless should be upgraded without skipping release versions. This section shows how to resolve problems with upgrading.
9.1. Serverless Operator maintenance release upgrades
9.1.1. 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
stablechannel. The maintenance release is available through its version-based channel, for example,
stable-1.29.NoteThe maintenance release is the release prior to the latest release. For example, if the
stablechannel includes version 1.30, then the maintenance release will be available in thestable-1.29channel.
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.
9.1.2. 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 | | | +--------+ | | | +--------------+
9.1.3. 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.
9.1.4. Upgrade examples
9.1.4.1. Scenario 1
In this scenario, the following circumstances are true:
-
The channel is
stable-1.28 -
You are switching to the
stablechannel - 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
stablechannel
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 | | | | | +--------+ | | | | | | | +--------------+ +--------------+
9.1.4.2. 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.29andstablechannels before1.30.0was released to thestablechannel
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 |<---------------------+ | | +--------+ | | | | | | | +--------------+ +--------------+
9.1.4.3. Scenario 3
In this scenario, the following circumstances are true:
-
The channel is
stable-1.29 -
You are switching to the
stable-1.30channel - The currently installed version is 1.29.1
-
1.29.1 is the head of the
stable-1.29channel
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 |-------+ | | | +--------+ | | | | | | | +--------------+ +--------------+
9.2. 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
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.MINORversion is1.5, which is covered in the release notes for OpenShift Serverless 1.26: OpenShift Serverless now uses Knative Serving 1.5.- Uninstall OpenShift Serverless Operator and all of its install plans.
Manually install the version of OpenShift Serverless Operator that you discovered in the first step. To install, first create a
serverless-subscription.yamlfile 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
Then, install the subscription by running the following command:
$ oc apply -f serverless-subscription.yaml
- Upgrade by manually approving the upgrade install plans as they appear.
