How to use a Rancher hotfix image

This document (000021247) is provided subject to the disclaimer at the end of this document.

Environment

SUSE Rancher 2.9.x

Situation

SUSE Rancher support and engineering might propose a hotfix image, which contains a potential fix for a specific issue, for troubleshooting purposes.
Hotfix images usually follow the naming convention: "v<X.Y.Z>-hotfix-<IDENTIFIER>"
The Rancher version should be respected (for Rancher v2.9.3, the debug image should be v2.9.3-hotfix-XYZ).

SUSE Support will give information about the content of a hotfix.

Disclaimers:

Please, use a hotfix build only when instructed by SUSE Support/Engineering personnel. Hotfix builds are meant to help troubleshoot specific problems and they are not supported for general use.

From an Engineering standpoint we are confident that hotfix builds will not introduce regressions, as changes target a small code region, pass reviews and a selection of automated tests as well. Nevertheless, hotfix builds do not go through full Rancher QA processes, so please be ready to revert to the original version in case unexpected behavior is noticed (instructions are provided below).

Important Upgrade Notice: This hotfix includes changes that may not be present in all subsequent Rancher releases. Therefore, to ensure a smooth upgrade process after applying this hotfix, please contact SUSE Support for guidance before upgrading to any later Rancher version. SUSE Support will indicate which versions are safe to upgrade to.

Resolution

Installation instructions

from a machine with access to the upstream cluster, edit the rancher deployment (to change the rancher image to the hotfix version):

export TAG=v2.9.3-hotfix-XXX
kubectl set image -n cattle-system deployment/rancher rancher=registry.rancher.com/rancher/rancher:$TAG

Note: rancher-agent images will be propagated downstream automatically, usually within minutes.

Note: customers using air-gap setups or not allowing images being pulled from external registries should transfer or whitelist the rancher and rancher-agent images appropriately for the procedure to work.

Uninstallation instructions (restoring the original Rancher version)

repeat instructions above, but setting the original version tag:

export TAG=v2.9.3
kubectl set image -n cattle-system deployment/rancher rancher=registry.rancher.com/rancher/rancher:$TAG

Follow-up instruction

Please report if changes help with symptoms.

Please contact SUSE again before upgrading to a newer Rancher version.

Disclaimer

This Support Knowledgebase provides a valuable tool for SUSE customers and parties interested in our products and solutions to acquire information, ideas and learn from one another. Materials are provided for informational, personal or non-commercial use within your organization and are presented "AS IS" WITHOUT WARRANTY OF ANY KIND.