Pre-release v2.9.0-alpha2

Images with -rc

rancher/aks-operator v1.9.0-rc.1
rancher/backup-restore-operator v5.0.0-rc2
rancher/eks-operator v1.9.0-rc.1
rancher/fleet v0.10.0-rc.13
rancher/fleet-agent v0.10.0-rc.13
rancher/gke-operator v1.9.0-rc.1
rancher/pushprox-client v0.1.3-rc1-rancher2-client
rancher/pushprox-proxy v0.1.3-rc1-rancher2-proxy
rancher/rancher-csp-adapter v4.0.0-rc1
rancher/rancher-webhook v0.5.0-rc8
rancher/system-agent v0.3.6-rc2-suc

Components with -rc

CLI_VERSION v2.9.0-rc1
SYSTEM_AGENT_VERSION v0.3.6-rc2
AKS-OPERATOR v1.3.0-rc12
DYNAMICLISTENER v0.5.0-rc2
EKS-OPERATOR v1.4.0-rc9
GKE-OPERATOR v1.3.0-rc6
RKE v1.6.0-rc3

Min version components with -rc

RKE Kubernetes versions

v1.25.16-rancher2-3
v1.26.15-rancher1-1
v1.27.13-rancher1-1
v1.28.9-rancher1-1
v1.29.3-rancher1-1

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)

v2.8.4

Release v2.8.4

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

Rancher General

Behavior Changes

• The controller now cleans up instances of ClusterUserAttribute that have no corresponding UserAttribute. See #44985.

Cluster Provisioning

Behavior Changes

• 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 App (Global UI)

Known Issues

• When configuring permissions for a User on the Users & Authentication > Users page, the Global Permissions are listed out of order. See #11014.

Authentication

Major Bug Fixes

• When the Shibboleth is configured with OpenLDAP in versions prior to v2.8.4, the secret configuration is incorrect. Admins will be unable to search for users in the OpenLDAP server, and will see [WARNING] ldap search principals failed to get ldap config: error getting secret cattle-global-data:shibbolethconfig-serviceAccountPassword, the generated secret is cattle-global-data:shibbolethconfig-serviceaccountpassword, but this is incorrectly referenced in the shibboleth AuthConfig resource. This has been fixed and the correct name is now identified. However, if you have Shibboleth installed with OpenLDAP and this is not working, it will not be automatically fixed, you can disable and reenable Shibboleth, or alternatively, you can work around this by fixing the secret reference in the shibboleth AuthConfig, by changing .openLdapConfig.serviceAccountPassword to cattle-global-data:shibbolethconfig-serviceaccountpassword. See #44917.

Rancher Webhook

Known Issues

• The Rancher-Webhook version is not set in the settings and the environment variable is empty, allowing the webhook to be automatically upgraded to newer versions. Each Rancher version is designed to be compatible with a single version of the webhook. See #45418.

VM Management (Harvester)

Known Issues

• When provisioning a Harvester RKE1 cluster in Rancher, the vGPU field is not displayed under Cluster Management > Advanced Settings. However, the vGPU field is available when provisioning a Harvester RKE2 cluster. See #10909.
• When provisioning a multi-node Harvester RKE2 cluster in Rancher, you need to allocate one vGPU more than the number of nodes you have or provisioning will fail. See #11009.
• When you provision a Harvester RKE2 cluster in Rancher and add two vGPUs, Rancher gets stuck in a starting state and the VMs won't start. See #10947.

Extensions

Behavior Changes

• The Rancher dashboard fails to load an extension that utilizes backported Vue 3 features, displaying an error in the console object(...) is not a function. New extensions that utilize the defineComponent will not be backwards compatible with older versions of the dashboard. Existing extensions should continue to work moving forward. See #10568.

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

Tools

• CLI - v2.8.4
• RKE - v1.5.9

Kubernetes Versions for RKE

• v1.28.9 (Default)
• v1.27.13
• v1.26.15
• v1.25.16

Kubernetes Versions for RKE2/K3s

• v1.28.9 (Default)
• v1.27.13
• 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

Experimental Features

Dual-stack and IPv6-only support for RKE1 clusters using the Flannel CNI has been experimental since v1.23.x. See the upstream Kubernetes docs. Dual-stack is not currently supported on Windows. See #165.

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

Pre-release v2.8.4-rc5

Images with -rc

rancher/rancher v2.8.4-rc5
rancher/rancher-agent v2.8.4-rc5

Components with -rc

Min version components with -rc

RKE Kubernetes versions

v1.25.16-rancher2-3
v1.26.15-rancher1-1
v1.27.13-rancher1-1
v1.28.9-rancher1-1

Chart/KDM sources

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

Pre-release v2.8.3-debug-45509-1

Images with -rc

Components with -rc

Min version components with -rc

RKE Kubernetes versions

v1.25.16-rancher2-3
v1.26.15-rancher1-1
v1.27.13-rancher1-1
v1.28.9-rancher1-1

Chart/KDM sources

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

Pre-release v2.8.4-rc4

Images with -rc

rancher/rancher v2.8.4-rc4
rancher/rancher-agent v2.8.4-rc4

Components with -rc

Min version components with -rc

RKE Kubernetes versions

v1.25.16-rancher2-3
v1.26.15-rancher1-1
v1.27.13-rancher1-1
v1.28.9-rancher1-1

Chart/KDM sources

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

v2.7.13

Release v2.7.13

It is important to review the Install/Upgrade Notes below before upgrading to any Rancher version.

The v2.7.13 build is only available for Rancher Prime customers, through the Rancher Prime registry. To learn more about Rancher Prime, see our page on the Rancher Prime Platform.

Rancher App (Global UI)

Known Issues

• When configuring permissions for a User on the Users & Authentication > Users page, the Global Permissions are listed out of order. See #11010.

Cluster Provisioning

Behavior Changes

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

Known Issues

• When you attempt to register a new etcd/controlplane node in a CAPR-managed cluster after a failed etcd snapshot restoration, the node can become stuck in a perpetual paused state, displaying the error message [ERROR] 000 received while downloading Rancher connection information. Sleeping for 5 seconds and trying again. As a workaround, you can unpause the cluster by running kubectl edit clusters.cluster clustername -n fleet-default and set spec.unpaused to false. See #43735.
• If you upgrade a hosted cluster and go to Cluster Management > Clusters to view the details of the hosted cluster, you will see the Registration tab. See #8524.

Install/Upgrade Notes

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

Upgrade Requirements

• Creating backups: We strongly recommend creating a backup before upgrading Rancher. To roll back Rancher after an upgrade, you must back up and restore Rancher to the previous Rancher version. Because Rancher will be restored to its state when a backup was created, any changes post upgrade will not be included after the restore. For more information, see the documentation on backing up Rancher.
• Helm version: Rancher install or upgrade must occur with Helm 3.2.x+ due to the changes with the latest cert-manager release. See #29213.
• CNI requirements:
  • For Kubernetes v1.19 and newer, we recommend disabling firewalld as it's incompatible with various CNI plugins. See #28840.
  • If upgrading or installing a Linux distribution which 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 version v0.13.0, which supports nf_tables. See Flannel #1317.
• Requirements for air gapped environments:
  • When installing or upgrading Rancher in an air gapped environment, add the flag --no-hooks to the helm template command, to skip rendering files for Helm's hooks. See #3226.
  • If using a proxy in front of an air-gapped Rancher instance, you must pass additional parameters to NO_PROXY. See the documentation and related issue #2725.
• Requirements for Docker installs:
  • When starting the Rancher Docker container, you must use the privileged flag. See documentation.
  • When installing 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.
  • 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.

Reverting the Active Directory Migration Delivered in v2.7.5

The following information only applies if you are upgrading from Rancher v2.7.5. It does not apply if you are upgrading directly to the latest Rancher version from v2.7.4 or earlier, or if you are upgrading to the latest Rancher version from v2.7.6.

Rancher v2.7.6 and later contain a reverse migration utility that runs at startup. Data migration is only triggered if you have been on Rancher v2.7.5.

Users will be corrected from the v2.7.5 data migration, which updated personalIDs to use GUIDs instead of Distinguished Names (DNs). Rancher v2.7.6 and later fix several login-related bugs. See #41985 and #42120.

Important: If you disabled AD authentication while on v2.7.5, don't enable it after upgrading until after the utility is run. Doing so will cause the reverse migration to fail to clean up the remaining bad data.

We strongly recommend that you directly upgrade to the latest version of Rancher v2.7.x, especially if you're on a broken or partially downgraded Rancher setup after upgrading to v2.7.5. Allow the startup utility to revert the Active Directory changes to restore functionality to your setup.

Even if you're currently on Rancher v2.7.5 and your setup wasn't broken by the Active Directory changes, you should still upgrade to v2.7.6 or later and allow the startup utility to revert the migration.

The reverse migration startup utility saves all relevant changes to Rancher if it finds GUID-based users in Active Directory. The users' data (including the user object, all bindings, and tokens) return a Distinguished Name as the principalID. If the LDAP connection permanently fails during execution of the utility, Rancher automatically retries the utility several times with exponential backoff. Missing users are left behind and reported to the local admin for manual review.

If you need to clean up any missing users following an upgrade to the latest Rancher version, contact support.

Long-standing Rancher Behavior Changes

• Rancher no longer supports the Amazon Web Services (AWS) in-tree cloud provider for RKE clusters. This includes both RKE1 and RKE2. Upstream Kubernetes removed 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. This includes both RKE1 and RKE2. See the following issues:
  • RKE1 support: #44144.
  • RKE2 support: #44145.
• The cluster-api core provider controllers are now run in a pod in the cattle-provisioning-cattle-system namespace, within the local cluster. These controllers are installed with a Helm chart. Previously, Rancher ran cluster-api controllers in an embedded fashion. This change makes it easier to maintain cluster-api versioning. See #41094.
• Changed the token hashing algorithm to generate new tokens using SHA3. Existing tokens will not be re-hashed. This change affects ClusterAuthTokens (the downstream synced version of tokens for ACE) and Tokens (only when token hashing is enabled). SHA3 tokens should work with ACE and Token Hashing. Existing tokens which don't use SHA3 may not work when ACE and token hashing are used in combination. If, after upgrading to Rancher v2.7.7, you experience issues with ACE while Token Hashing is enabled, you should re-generate any applicable tokens. See #42062.
• If you use a version of backup restore older than v102.0.2+up3.1.2 to take a backup of Rancher v2.7.7, the migration will encounter a capi-webhook error. Make sure that the chart version used for backups is v102.0.2+up3.1.2, which has cluster.x-k8s.io/v1alpha4 resources removed from the resourceSet. If you can't use v102.0.2+up3.1.2 for backups, delete all cluster.x-k8s.io/v1alpha4 resources from the backup tar before using it. See #382.
• Rancher installs the same pinned version of the rancher-webhook chart not only in the local cluster but also in all downstream clusters. Note that restoring Rancher from v2.7.5 to an earlier version will result in downstream clusters' webhooks being at the version set by Rancher v2.7.5, which might cause incompatibility issues. Local and downstream webhook versions ideally need to be in sync. See #41730 and #41917.
• The mutating webhook configuration for secrets is no longer active in downstream clusters. See [#41613](#4...

Pre-release v2.7.13-rc5

bump CATTLE_UI_VERSION and CATTLE_DASHBOARD_UI_VERSION to 2.7.13 (#45…

…491)

Pre-release v2.7.11-patch-44760-1

Images with -rc

Components with -rc

Min version components with -rc

RKE Kubernetes versions

v1.23.16-rancher2-3
v1.24.17-rancher1-1
v1.25.16-rancher2-3
v1.26.15-rancher1-1
v1.27.13-rancher1-1

Chart/KDM sources

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

Pre-release v2.8.4-rc3

Images with -rc

rancher/rancher v2.8.4-rc3
rancher/rancher-agent v2.8.4-rc3
rancher/rancher-webhook v0.4.5-rc2

Components with -rc

DASHBOARD_UI_VERSION v2.8.4-rc1
UI_VERSION 2.8.4-rc1
RKE v1.5.9-rc2

Min version components with -rc

RKE Kubernetes versions

v1.25.16-rancher2-3
v1.26.15-rancher1-1
v1.27.13-rancher1-1
v1.28.9-rancher1-1

Chart/KDM sources

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

Pre-release v2.7.13-rc4

Merge pull request #45414 from MbolotSuse/webhook-bump-v0.3.9-rc1

Bump rancher-webhook to v0.3.9-rc1