Release v2.10.2

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

Rancher v2.10.2 is the latest patch release of Rancher. This is a Community and Prime version release that introduces maintenance updates and bug fixes.

For more information on new features in the general minor release see the v2.10.0 release notes.

Cluster Provisioning

Major Bug Fixes

• Fixed an issue where stale impersonation secrets were building up in the cattle-impersonation-system namespace. See #48313.
• Fixed an issue where the Rancher chart ingress path is set to "/" causing https://<rancher_url>/ to fail with "response 404 (backend NotFound), service rules for the path non-existent." The ingress path can now be configured as needed. See #48167.

RKE2 Provisioning

Major Bug Fixes

• Fixd an issue where clusters containing nodes with split etcd and control plane roles would fail to reconcile when upgrading Rancher. See #48389.

Rancher App (Global UI)

Major Bug Fixes

• Fixed an issue where users were able to create or edit clusters even when using an invalid Add-on YAML configuration. See #12466.

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, EOL for RKE is July 31st, 2025. Prime customers must replatform from RKE to RKE2 or K3s.

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

Images

• rancher/rancher:v2.10.2

Tools

• CLI - v2.10.1
• RKE - v1.7.2

Kubernetes Versions for RKE

• v1.31.4 (Default)
• v1.30.8
• v1.29.12
• v1.28.15

Kubernetes Versions for RKE2/K3s

• v1.31.4 (Default)
• v1.30.8
• v1.29.12
• v1.28.15

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.10.0:
  • Kubernetes v1.27 is no longer supported. Before you upgrade to Rancher v2.10.0, make sure that all clusters are running Kubernetes v1.28 or later. See #47591.
  • The new annotation field.cattle.io/creator-principal-name was introduced in addition to the existing field.cattle.io/creatorId that allows specifying the creator's principal name when creating a cluster or a project. If this annotation is used, the userPrincipalName field of the corresponding ClusterRoleTemplateBinding or ProjectRoleTemplateBinding will be set to the specified principal. The principal should belong to the creator's user, which is enforced by the webhook. See #46828.
  • When searching for group principals with a SAML authentication provider (with LDAP turned off), Rancher now returns a principal of correct type (group) with the name matching the search term. When searching principals with a SAML provider (with LDAP turned off) without specifying the desired type (as in Add cluster/project member), Rancher now returns both user and group principals with the name matching the search term. See #44441.
  • Rancher now captures the last used time for Tokens and stores it in the lastUsedAt field. If the Authorized Cluster Endpoint is enable...

Images with -rc

rancher/rancher v2.10.2-rc1
rancher/rancher-agent v2.10.2-rc1

Components with -rc

DASHBOARD_UI_VERSION v2.10.2-rc1
UI_VERSION 2.10.2-rc1

Min version components with -rc

Chart/KDM sources

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

Release v2.9.6

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

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

For more information on new features in the general minor release see the v2.9.0 release notes.

Cluster Provisioning

Major Bug Fixes

• Fixed an issue where stale impersonation secrets were building up in the cattle-impersonation-system namespace. See #48314.

RKE2 Provisioning

Major Bug Fixes

• Fixed an issue where clusters containing nodes with split etcd and control plane roles would fail to reconcile when upgrading Rancher. See #48390.

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 replatform from RKE to RKE2 or K3s.

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

Images

• rancher/rancher:v2.9.6

Tools

• CLI - v2.9.5
• RKE - v1.6.6

Kubernetes Versions for RKE

• v1.30.8 (Default)
• v1.29.12
• v1.28.15
• v1.27.16

Kubernetes Versions for RKE2/K3s

• v1.30.8 (Default)
• v1.29.12
• v1.28.15
• 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; however, enabling or disabling the feature won't have any effect. For more information, see CVE-2023-32196 and #45863.
  • Rancher now validates the Container Default Resource Limit on Projects. Validation mimics the upstream behavior of the Kubernetes API server when it validates LimitRanges. The container default resource configuration must have properly formatted quantities for all requests and limits. Limits for any resource must not be less than requests. See #39700.
• Rancher v2.8.4:
  • The controller now cleans up instances of ClusterUserAttribute that have no corresponding UserAttribute. See #44985.
• Rancher v2.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 v2.8.4:
  • Docker CLI 20.x is at end-of-life and no longer supported in...

Release v2.8.12

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

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

For more information on new features in the general minor release see the v2.8.0 release notes.

Changes Since v2.8.11

See the full list of issues addressed.

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

Tools

• CLI - v2.8.8
• RKE - v1.5.15

Kubernetes Versions for RKE

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

Kubernetes Versions for RKE2/K3s

• v1.28.15 (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.10:

  • 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 replatform from RKE to RKE2 or K3s.

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

• 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 for any Rancher-managed clusters running Kubernetes v1.27 or later. See #43175.
  • The Weave CNI plugin for RKE v1.27 and later is now deprecated. Weave will be removed in RKE v1.30. See #42730.

Previous Rancher Behavi...

Images with -rc

rancher/rancher-webhook v0.6.3-rc.3
rancher/wins v0.5.0-rc.2

Components with -rc

WINS_AGENT_VERSION v0.5.0-rc.2

Min version components with -rc

Chart/KDM sources

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

Images with -rc

rancher/rancher-webhook v0.6.3-rc.3
rancher/wins v0.5.0-rc.2

Components with -rc

WINS_AGENT_VERSION v0.5.0-rc.2

Min version components with -rc

Chart/KDM sources

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