Release v2.9.2

Important: Review the Install/Upgrade Notes before upgrading to any Rancher version.

Rancher v2.9.2 is the latest minor release of Rancher. This is a Community and Prime version release that introduces new features, enhancements, and various updates. To learn more about Rancher Prime, see our page on the Rancher Prime Platform.

RKE2 Provisioning

Major Bug Fixes

• Fixed an issue where, when upgrading from Rancher v2.7.4 or earlier to a more recent Rancher version with provisioned RKE2/K3s clusters in an unhealthy state, you may have encountered the error message, implausible joined server for entry. This required manually marking the nodes in the cluster with a joined server. A workaround was available. See #42856.

Windows Cluster Provisioning Fixes

Major Bug Fixes

• The following fix only applies to newly provisioned Windows nodes, and existing Windows nodes running the August 2024 patch releases of RKE2 (v1.30.4, v1.29.8, v1.28.13, and v1.27.16): The STRICT_VERIFY environment variable is now successfully passed to Windows nodes. There is a workaround for existing nodes that do not have the August patches. See #46396.

Rancher App (Global UI)

Known Issues

• Although system mode node pools must have at least one node, the Rancher UI allows a minimum node count of zero. Inputting a zero minimum node count through the UI can cause cluster creation to fail due to an invalid parameter error. To prevent this error from occuring, enter a minimum node count at least equal to the node count. See #11922.
• Node drivers that rely on machine configs that contain fields of the type array string render a form requesting a single string instead. See #11936.
• Some node drivers incorrectly stipulate that no credentials are required, resulting in the UI skipping the requirement to supply credentials when provisioning a cluster of that type. See #11974.

Role-Based Access Control (RBAC) Framework

Known Issues

• Multiple, stale secrets may be erroneously created for users on downstream clusters. The stale secrets don't get reconciled even if the referenced secret is deleted in the user account. This can cause problems with memory usage and UI slowdown. See #46894.

Install/Upgrade Notes

• If you're installing Rancher for the first time, your environment must fulfill the installation requirements.

Upgrade Requirements

• Creating backups: Create a backup before you upgrade Rancher. To roll back Rancher after an upgrade, you must first back up and restore Rancher to the previous Rancher version. Because Rancher will be restored to the same state as when the backup was created, any changes post-upgrade will not be included after the restore.
• CNI requirements:
  • For Kubernetes v1.19 and later, disable firewalld as it's incompatible with various CNI plugins. See #28840.
  • When upgrading or installing a Linux distribution that uses nf_tables as the backend packet filter, such as SLES 15, RHEL 8, Ubuntu 20.10, Debian 10, or later, upgrade to RKE v1.19.2 or later to get Flannel v0.13.0. Flannel v0.13.0 supports nf_tables. See Flannel #1317.
• Requirements for air gapped environments:
  • When using a proxy in front of an air-gapped Rancher instance, you must pass additional parameters to NO_PROXY. See the documentation and issue #2725.
  • When installing Rancher with Docker in an air-gapped environment, you must supply a custom registries.yaml file to the docker run command, as shown in the K3s documentation. If the registry has certificates, then you'll also need to supply those. See #28969.
• Requirements for general Docker installs:
  • When starting the Rancher Docker container, you must use the privileged flag. See documentation.
  • When upgrading a Docker installation, a panic may occur in the container, which causes it to restart. After restarting, the container will come up and work as expected. See #33685.

Versions

Please refer to the README for the latest and stable Rancher versions.

Please review our version documentation for more details on versioning and tagging conventions.

Important: With the release of Rancher Kubernetes Engine (RKE) v1.6.0, we are informing customers that RKE is now deprecated. RKE will be maintained for two more versions, following our deprecation policy.

Please note, End-of-Life (EOL) for RKE is July 31st, 2025. Prime customers must re-platform from RKE to RKE2 or k3s.

RKE2 and K3s provide stronger security, and move away from upstream-deprecated Docker machine. Learn more about re-platforming here.

Images

• rancher/rancher:v2.9.2

Tools

• CLI - v2.9.0
• RKE - v1.6.2

Kubernetes Versions for RKE

• v1.30.4 (Default)
• v1.29.8
• v1.28.13
• v1.27.16

Kubernetes Versions for RKE2/K3s

• v1.30.4 (Default)
• v1.29.7
• v1.28.13
• v1.27.16

Rancher Helm Chart Versions

In Rancher v2.6.0 and later, in the Apps & Marketplace UI, many Rancher Helm charts are named with a major version that starts with 100. This avoids simultaneous upstream changes and Rancher changes from causing conflicting version increments. This also complies with semantic versioning (SemVer), which is a requirement for Helm. You can see the upstream version number of a chart in the build metadata, for example: 100.0.0+up2.1.0. See #32294.

Other Notes

Experimental Features

Rancher now supports the ability to use an OCI Helm chart registry for Apps & Marketplace. View documentation on using OCI based Helm chart repositories and note this feature is in an experimental stage. See #29105 and #45062

Deprecated Upstream Projects

In June 2023, Microsoft deprecated the Azure AD Graph API that Rancher had been using for authentication via Azure AD. When updating Rancher, update the configuration to make sure that users can still use Rancher with Azure AD. See the documentation and issue #29306 for details.

Removed Legacy Features

Apps functionality in the cluster manager has been deprecated as of the Rancher v2.7 line. This functionality has been replaced by the Apps & Marketplace section of the Rancher UI.

Also, rancher-external-dns and rancher-global-dns have been deprecated as of the Rancher v2.7 line.

The following legacy features have been removed as of Rancher v2.7.0. The deprecation and removal of these features was announced in previous releases. See #6864.

UI and Backend

• CIS Scans v1 (Cluster)
• Pipelines (Project)
• Istio v1 (Project)
• Logging v1 (Project)
• RancherD

UI

• Multiclusterapps (Global): Apps within the Multicluster Apps section of the Rancher UI.

Previous Rancher Behavior Changes

Previous Rancher Behavior Changes - Rancher General

• Rancher v2.9.0:
  • Kubernetes v1.25 and v1.26 are no longer supported. Before you upgrade to Rancher v2.9.0, make sure that all clusters are running Kubernetes v1.27 or later. See #45882.
  • The external-rules feature flag functionality is removed in Rancher v2.9.0 as the behavior is enabled by default. The feature flag is still present when upgrading from v2.8.5;...

Images with -rc

rancher/rancher v2.9.2-rc1
rancher/rancher-agent v2.9.2-rc1

Components with -rc

DASHBOARD_UI_VERSION v2.9.2-rc1
UI_VERSION 2.9.2-rc1

Min version components with -rc

Chart/KDM sources

• SYSTEM_CHART_DEFAULT_BRANCH: release-v2.9 (scripts/package-env)
• CHART_DEFAULT_BRANCH: release-v2.9 (scripts/package-env)
• SYSTEM_CHART_DEFAULT_BRANCH: release-v2.9 (package/Dockerfile)
• CHART_DEFAULT_BRANCH: release-v2.9 (package/Dockerfile)
• CATTLE_KDM_BRANCH: release-v2.9 (package/Dockerfile)
• CATTLE_KDM_BRANCH: release-v2.9 (Dockerfile.dapper)
• KDMBranch: release-v2.9 (pkg/settings/setting.go)
• ChartDefaultBranch: release-v2.9 (pkg/settings/setting.go)

Release v2.8.8

Important: Review the Install/Upgrade Notes before upgrading to any Rancher version.

Rancher v2.8.8 is the latest patch release of Rancher. This is a Prime version release that introduces bug fixes. To learn more about Rancher Prime, see our page on the Rancher Prime Platform.

RKE2 Provisioning

Major Bug Fixes

• Fixed an issue where, when upgrading from Rancher v2.7.4 or earlier to a more recent Rancher version with provisioned RKE2/K3s clusters in an unhealthy state, you may have encountered the error message, implausible joined server for entry. This required manually marking the nodes in the cluster with a joined server. See #46441.

Windows Cluster Provisioning Fixes

Major Bug Fixes

• The following fix only applies to newly provisioned Windows nodes, and existing Windows nodes running the August 2024 patch releases of RKE2 (v1.30.4, v1.29.8, v1.28.13, and v1.27.16): The STRICT_VERIFY environment variable is now successfully passed to Windows nodes. There is a workaround for existing nodes that do not have the August patches. See #46773.

Role-Based Access Control (RBAC) Framework

Known Issues

• Multiple, stale secrets may be erroneously created for users on downstream clusters. The stale secrets don't get reconciled even if the referenced secret is deleted in the user account. This can cause problems with memory usage and UI slowdown. See #46537.

Install/Upgrade Notes

• If you're installing Rancher for the first time, your environment must fulfill the installation requirements.

Upgrade Requirements

• Creating backups: Create a backup before you upgrade Rancher. To roll back Rancher after an upgrade, you must first back up and restore Rancher to the previous Rancher version. Because Rancher will be restored to the same state as when the backup was created, any changes post-upgrade will not be included after the restore.
• CNI requirements:
  • For Kubernetes v1.19 and later, disable firewalld as it's incompatible with various CNI plugins. See #28840.
  • When upgrading or installing a Linux distribution that uses nf_tables as the backend packet filter, such as SLES 15, RHEL 8, Ubuntu 20.10, Debian 10, or later, upgrade to RKE v1.19.2 or later to get Flannel v0.13.0. Flannel v0.13.0 supports nf_tables. See Flannel #1317.
• Requirements for air gapped environments:
  • When using a proxy in front of an air-gapped Rancher instance, you must pass additional parameters to NO_PROXY. See the documentation and issue #2725.
  • When installing Rancher with Docker in an air-gapped environment, you must supply a custom registries.yaml file to the docker run command, as shown in the K3s documentation. If the registry has certificates, then you'll also need to supply those. See #28969.
• Requirements for general Docker installs:
  • When starting the Rancher Docker container, you must use the privileged flag. See documentation.
  • When upgrading a Docker installation, a panic may occur in the container, which causes it to restart. After restarting, the container will come up and work as expected. See #33685.

Versions

Please refer to the README for the latest and stable Rancher versions.

Please review our version documentation for more details on versioning and tagging conventions.

Images

• rancher/rancher:v2.8.8

Tools

• CLI - v2.8.6
• RKE - v1.5.13

Kubernetes Versions for RKE

• v1.28.13 (Default)
• v1.27.16
• v1.26.15
• v1.25.16

Kubernetes Versions for RKE2/K3s

• v1.28.13 (Default)
• v1.27.16
• v1.26.15
• v1.25.16

Rancher Helm Chart Versions

In Rancher v2.6.0 and later, in the Apps & Marketplace UI, many Rancher Helm charts are named with a major version that starts with 100. This avoids simultaneous upstream changes and Rancher changes from causing conflicting version increments. This also complies with semantic versioning (SemVer), which is a requirement for Helm. You can see the upstream version number of a chart in the build metadata, for example: 100.0.0+up2.1.0. See #32294.

Other Notes

Deprecated Upstream Projects

In June 2023, Microsoft deprecated the Azure AD Graph API that Rancher had been using for authentication via Azure AD. When updating Rancher, update the configuration to make sure that users can still use Rancher with Azure AD. See the documentation and issue #29306 for details.

Removed Legacy Features

Apps functionality in the cluster manager has been deprecated as of the Rancher v2.7 line. This functionality has been replaced by the Apps & Marketplace section of the Rancher UI.

Also, rancher-external-dns and rancher-global-dns have been deprecated as of the Rancher v2.7 line.

The following legacy features have been removed as of Rancher v2.7.0. The deprecation and removal of these features was announced in previous releases. See #6864.

UI and Backend

• CIS Scans v1 (Cluster)
• Pipelines (Project)
• Istio v1 (Project)
• Logging v1 (Project)
• RancherD

UI

• Multiclusterapps (Global): Apps within the Multicluster Apps section of the Rancher UI.

Previous Rancher Behavior Changes

Previous Rancher Behavior Changes - Rancher General

• Rancher 2.8.4:
  • The controller now cleans up instances of ClusterUserAttribute that have no corresponding UserAttribute. See #44985.
• Rancher 2.8.3:
  • When Rancher starts, it now identifies all deprecated and unrecognized setting resources and adds a cattle.io/unknown label. You can list these settings with the command kubectl get settings -l 'cattle.io/unknown==true'. In Rancher v2.9 and later, these settings will be removed instead. See #43992.
• Rancher v2.8.0:
  • Rancher Compose is no longer supported, and all parts of it are being removed in the v2.8 release line. See #43341.
  • Kubernetes v1.23 and v1.24 are no longer supported. Before you upgrade to Rancher v2.8.0, make sure that all clusters are running Kubernetes v1.25 or later. See #42828.

Previous Rancher Behavior Changes - Cluster Provisioning

• Rancher 2.8.4:
  • Docker CLI 20.x is at end-of-life and no longer supported in Rancher. Please update your local Docker CLI versions to 23.0.x or later. Earlier versions may not recognize OCI compliant Rancher image manifests. See #45424.
• Rancher v2.8.0:
  • Kontainer Engine v1 (KEv1) provisioning and the respective cluster drivers are now deprecated. KEv1 provided plug-ins for different targets using cluster drivers. The Rancher-maintained cluster drivers for EKS, GKE and AKS have been replaced by the hosted provider drivers, EKS-Operator, GKE-Operator and AKS-Operator. Node drivers are now available for self-managed Kubernetes.
• Rancher v2.7.2:
  • When you provision a downstream cluster, the cluster's name must conform to RFC-1123. Previously, characters that did not follow the specification, such as ., were permitted and would result in clusters being provisioned without the necessary Fleet components. See #39248.
  • Privilege escalation is disabled by default when creating deployments from the Rancher API. See #7165.

Previous Rancher Behavior Changes - RKE Provisioning

• Rancher v2.8.0:
  • Rancher no longer supports the Amazon Web Services (AWS) in-tree cloud provider for RKE clusters. This is in response to upstream Kubernetes removing the in-tree AWS provider in Kubernetes v1.27. You should instead [use the out-of-tree AWS cloud provider](https://ranchermanager...

Images with -rc

rancher/rancher-webhook v0.5.2-rc.3
rancher/system-agent v0.3.9-rc.4-suc

Components with -rc

SYSTEM_AGENT_VERSION v0.3.9-rc.4
RKE v1.6.2-rc.3

Min version components with -rc

Chart/KDM sources

• SYSTEM_CHART_DEFAULT_BRANCH: dev-v2.9 (scripts/package-env)
• CHART_DEFAULT_BRANCH: dev-v2.9 (scripts/package-env)
• SYSTEM_CHART_DEFAULT_BRANCH: dev-v2.9 (package/Dockerfile)
• CHART_DEFAULT_BRANCH: dev-v2.9 (package/Dockerfile)
• CATTLE_KDM_BRANCH: dev-v2.9 (package/Dockerfile)
• CATTLE_KDM_BRANCH: dev-v2.9 (Dockerfile.dapper)
• KDMBranch: dev-v2.9 (pkg/settings/setting.go)
• ChartDefaultBranch: dev-v2.9 (pkg/settings/setting.go)