Release v2.12.0

Important: If you are using Active Directory Federation Service (AD FS), upgrading to Rancher v2.10.1 or later may cause issues with authentication, requiring manual intervention. These issues are due to the AD FS Relying Party Trust not being able to pick up a signature verification certificate from the metadata. They can be corrected by either of two methods:

• Updating the Relying Party Trust information from federation metadata (Relying Party Trust -> Update from Federation Metadata...)
• Directly adding the certificate (Relying Party Trust -> Properties -> Signature tab -> Add -> Select the certificate).

For more information see #48655.

Important: Rancher-Istio is now deprecated in Rancher v2.12.0; turn to the SUSE Application Collection build of Istio for enhanced security (included in SUSE Rancher Prime subscriptions). Detailed information can be found in this announcement.

Install/Upgrade Notes

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

Important: Rancher now requires the cluster it runs on to have the Kubernetes API Aggregation Layer enabled. This is because Rancher extends Kubernetes with additional APIs by registering its own extension API server. Refer to the Extension API Server documentation and #50400 for more information.

Important: Rancher Kubernetes Engine (RKE/RKE1) has reached end of life as of July 31, 2025. Rancher versions 2.12.0 and later no longer support provisioning or managing downstream RKE1 clusters. We recommend replatforming RKE1 clusters to RKE2 to ensure continued support and security updates. Learn more about the transition here.

Rancher now has a pre-upgrade validation check for RKE1 resources which fails and lists the RKE1 resources if present. Refer to the RKE1 Resource Validation and Upgrade Requirements documentation and #50286 for more information.

Important: It is crucial that you review the available disk space on your nodes and plan accordingly before upgrading to Rancher v2.12.0 to avoid potential disk pressure and pod eviction issues. For additional information refer to the UI Server Side Pagination - Disk Space documentation.

Changes in Image Artifacts

Image artifact digests are renamed in Rancher v2.12.0, v2.11.4 and v2.10.8. Up until this change, separate image digests files for each operating system and architecture have been maintained for compatibility reasons. With this change, only one file for each operating system is to be provided:

• The rancher-images-digests-linux-amd64.txt and rancher-images-digests-linux-arm64.txt files are to be renamed to rancher-images-digests-linux.txt.
• The rancher-images-digests-windows-ltsc2019.txt and rancher-images-digests-windows-ltsc2022.txt files are to be renamed to rancher-images-digests-windows.txt.

Rancher v2.12.0 is the latest minor release of Rancher. This is a Community version release that introduces new features, enhancements, and various updates.

Rancher General

Features and Enhancements

• Rancher now supports Kubernetes v1.33. See #48796 for information on Rancher support for Kubernetes v1.33. You can view the upstream Kubernetes changelogs for v1.33 for a complete list of changes.

Behavior Changes

• Kubernetes v1.30 is no longer supported. Before upgrading to Rancher v2.12.0, ensure all clusters are running Kubernetes v1.31 or later. See #49679.
• The feature flag ui-sql-cache (Server-Side Pagination) is now enabled by default in Rancher. Please refer to the UI Server-Side Pagination document for more information.

Beginning with Rancher v2.12.0, UI Server-Side Pagination is enabled by default to provide significant performance improvements across the Rancher UI. This feature relies on a caching mechanism that introduces a new requirement for ephemeral disk space on your cluster nodes.

This cache, an internal SQLite database, is stored within the container's filesystem. This affects the nodes running the Rancher server pods (rancher in the cattle-system namespace on the local cluster) and the nodes running the Rancher agent pods (cattle-cluster-agent in the cattle-system namespace on all downstream clusters).

The amount of disk space required is dynamic and depends on the quantity and size of Kubernetes resources visualized in the UI. As a guideline, the cache may consume approximately twice the size of the raw Kubernetes objects it stores. For instance, internal tests showed that caching 5000 ConfigMaps, totaling 50 MB, consumed 81 MB of disk space. For a conservative, high-level estimate, you can plan for the available disk space on each relevant node to be at least twice the size of your etcd snapshot. For most production environments, ensuring a few extra gigabytes of storage are available on the relevant nodes is a safe starting point.

It is crucial that you review the available disk space on your nodes and plan accordingly before upgrading to this version to avoid potential disk pressure and pod eviction issues.

This update has introduced limitations which are outlined in the UI Server Side Pagination documentation. See #48691 and #12975 for more information.

Rancher App (Global UI)

Features and Enhancements

• The Legacy section has been removed from the explorer UI and Project Scoped Secrets have been moved to the Storage > Secrets page. See #14542 and #13245.
• The About page has been updated to indicate Rancher Prime installations when installed. See #14269.
• The Rancher Dashboard adds support for a Notification Center that is clickable in the top-right of the UI. See #14007.
• Improved initial UI load time by avoiding fetching all upstream Helm apps. See #10434.
• The Rancher UI now allows users to assign a default OCI Storage to Fleet workspaces from the Continuous Delivery Advanced > Workspaces view. When creating/editing GitRepos, users can assign one of {None, Default, custom-secret} from a list of OCI storage secrets in the Continuous Delivery Git Repos view. See #13270.
• A new HTML field is supported for banner configurations which allows for an HTML block to be configured. This is only used if the existing text field is empty and the banner settings pages have been updated with a toggle to switch between the existing text options or HTML. See #13080.
• The Apps Charts page has been improved with a new design. See #14198.
• The header section of all Resource Detail pages has been improved with Header, System Messages and Metadata components. See #14561.

Major Bug Fixes

• Fixed an issue when adding the provisioning.cattle.io/allow-dynamic-schema-drop annotation through the cluster config UI, the annotation would disappear before adding the value field. When viewing the YAML, the respective value field is not updated and is displayed as an empty string. See #13655 and #11229.
• Fixed an issue when modifying the Kubernetes version when upgrading would incorrectly change the K8s Distro directory path configuration in the Cluster Configuration > Advanced page. See #14287.
• Fixed an issue where two projects with the same name incorrectly group their respective created namespaces. See #13843.
• Fixed an issue when attempting to remove an environment variable using the Rancher UI during deployment, the last environment variable in the list is removed regardless of which variable is selected for deletion. See #14071.
• Fixed an issue with deleting/scaling down nodes for GKE, AKS, and EKS from the Cluster Management > (cluster-name) > Machine Pools view. See #11624.

Authentication

Features and Enhancements

• Rancher now functions as a standard OpenID Connect (OIDC) provider, allowing applications to use Rancher for authentication and enabling SSO integration with SUSE Observability. The OIDC provider can be enabled with the added oidc-provider feature flag. Refer to the Rancher OIDC documentation. See #48317.
• Rancher now supports Amazon Cognito as an authentication provider. This allows users to authenticate to Rancher using Amazon Cognito user pools. Refer to the documentation for configuration steps. See #48512.
• The updatepsa for project level features allows administrators to enable permissions for unprivileged users to create/modify the PSA labels on their project's namespaces through the application of a RoleTemplate. To do so, you can use the following RoleTemplate to be applied to the cluster:

yaml apiVersion: management.cattle.io/v3 builtin: false context: project description: '' displayName: Manage PSA Labels external: false hidden: false kind: RoleTemplate metadata: name: namespaces-psa rules: - apiGroups: - management.cattle.io resources: - projects verbs: - updatepsa

When creating a new project (from the Members tab), click Add to add the user and select Custom > Create Namespaces (to allow the user to create namespaces). Then click Add again and select UpdatePSA project role template from the list of Project Permissions. See #48721.

Role-Based Access Control (RBAC)

Features and Enhancements

• Project-scoped secrets have been moved out from behind the "Legacy" feature flag and are now available in the UI under Storage > Project Secrets. Project-scoped secrets allow for a secret to be available in all namespaces in the project. Refer to the Secrets documentation for more information. See #48568.

Rancher Kubernetes API (RK-API)

Features and Enhancements

• Rancher now has a new imperative resource tokens.ext.cattle.io that allows for generating tokens for authenticating with Rancher. The new resource is part of the Rancher Kubernetes API and is accessible via tools like kubectl and K8s clients. This feature is enabled by default but can be disabled using the ext-tokens feature flag as seen in the example below:

sh kubectl patch feature ext-tokens -p '{"spec":{"value":false}}'

Refer to the Tokens Public API documentation for more configuration and maintenance options. See #49015. - The Kubeconfigs Public API is now available and enabled by default. The new resource is part of the Rancher Kubernetes API and is accessible via tools like kubectl and K8s clients. It can be disabled by setting the ext-kubeconfigs feature flag to false:

sh kubectl patch feature ext-kubeconfigs -p '{"spec":{"value":false}}'

Refer to the Kubeconfigs Public API documentation for more configuration and maintenance options. See #50683.

Known Issues

• When the Rancher API Audit Log is enabled, Rancher does not validate new AWS Cloud Credentials to make sure they are valid. See #51079.

Cluster Provisioning

Features and Enhancements

• Rancher now supports Google Compute Engine (GCE) Node Driver provisioning of RKE2 and K3s clusters. See #49681 and #14011.

Behavior Changes

• Rancher's system-upgrade-controller app is now managed by the systemchart handler in downstream provisioned RKE2/K3s clusters. For additional information refer to this comment and see #47737.
• Rancher v2.12.0 introduces changes in Custom Resource Definition (CRD) validations for dynamicschemas.management.cattle.io and dynamically generated CRDs:

DynamicSchema dynamicschemas.management.cattle.io

This CRD had a generic schema that allowed any field to be set. It has been updated to only allow the expected fields.

This is not a user-facing CRD and is used internally by rancher.

InfrastructureMachine CRDs These are the CAPI InfrastructureMachine CRDs defined for the Rancher Cluster API (CAPI) infrastructure provider. They are dynamically generated and are named <name>machines.rke-machine.cattle.io, where <name> is derived from the node driver used to provision machines with a given infrastructure provider. Each active node driver has an associated InfrastructureMachine CRD.

InfrastructureMachine objects are generated automatically by Rancher from other configuration objects.

The following validations were changed in this CRD schema:

• spec.common.cloudCredentialSecretName
  • Value must be 317 characters long or less (<namespace>:<secretname>).
• spec.common.labels
  • Label values are no longer allowed to take a null value.
• spec.common.taints, in each taint object:
  • Fields effect and key are now required.
  • Field timeAdded is now required to be in the date-time format.
  • All fields are no longer allowed to take a null value.
• status.addresses, in each address object:
  • Fields address and type are now required and are no longer allowed to take a null value.
  • Field type must take one of the following values: Hostname, ExternalIP, InternalIP, ExternalDNS or InternalDNS.
  • Field address must be between 1 and 256 characters long.
• status.conditions, in each condition object:
  • Fields status and type are now required.
  • No fields are allowed to take a null value anymore.
• status
  • No fields are allowed to take a null value anymore.

InfrastructureMachineTemplate CRDs These are the CAPI InfrastructureMachineTemplate CRDs defined for the Rancher CAPI infrastructure provider. They are dynamically generated and are named <name>machinetemplates.rke-machine.cattle.io, where <name> is derived from the node driver used to provision machines with a given infrastructure provider. Each active node driver has an associated InfrastructureMachineTemplate CRD.

InfrastructureMachineTemplate objects are generated automatically by Rancher from other configuration objects.

• spec.template.spec.common.cloudCredentialSecretName
  • Value must be 317 characters long or less (<namespace>:<secretname>).
• spec.template.spec.common.labels
  • Label values are no longer allowed to take a null value.
• spec.template.spec.common.taints, in each taint object:
  • Fields effect and key are now required.
  • Field timeAdded is now required to be in the date-time format.
  • No fields are allowed to take a null value anymore.

See #49402 for more information.

Major Bug Fixes

• Fixed an issue where deleting a control plane node may result in worker nodes reconciling. See #39021.

Known Issues

• After upgrading Rancher from v2.11.x to v2.12.0, all imported clusters created by directly instantiating cluster.provisioning.cattle.io object fail to reconnect to Rancher. For a solution regarding affected imported clusters, please refer to this comment. Note that since v2.11.0 imported clusters are created via cluster.management.cattle.io instead, see release noted #13151. Additionally, creating custom resources directly is not an officially supported method of creating imported clusters. See #51066.

Rancher CLI

Features and Enhancements

• Rancher now produces Linux ARM64 binaries for the Rancher CLI. See #447.

Rancher Compliance App

Features and Enhancements

• A new Rancher Compliance App is introduced and replaces the former Rancher CIS Benchmarks. The new App expands its scope, enabling checks across a broader range of security benchmarks. This update also replaces the CIS Operator with the new Compliance Operator. The Custom Resource Definitions which were previously available in the cis.cattle.io/v1, have now moved to the compliance.cattle.io/v1 API Group. See #50797.

Continuous Delivery (Fleet)

Features and Enhancements

• HelmOps is no longer experimental and now enabled by default, with semantic versioning and polling support. This comes with a new UI in Rancher, splitting workloads between GitOps and HelmOps. See #13449 and Fleet v0.13.0 release notes for more details on what this means and how to use it.
• Various UX improvements for GitRepo create and maintenance actions. See 13171.
• Continuous Delivery Dashboard updates regarding improved error handling, performance issue fixes, and improved resource display. See #13172.
• Fleet settings can be modified now in the Global Settings > Fleet view. After saving changes, the corresponding value in the rancher-config ConfigMap is updated and the Fleet agent and controller are re-deployed. If updating the replica count, the relevant deployment in the cattle-fleet-system namespace is automatically reconciled to match the new replica count. See #13765.

Behavior Changes

• A migration patching service account is removed, meaning the image rancher/kubectl is no longer needed. See fleet#3601.

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

Tools

• CLI - v2.12.0

Kubernetes Versions for RKE2/K3s

• v1.33.2 (Default)
• v1.32.6
• v1.31.10

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.

Long-standing Known Issues

Long-standing Known Issues - Cluster Provisioning

• Not all cluster tools can be installed on a hardened cluster.

• Rancher v2.8.1:

• 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.
• Rancher v2.7.2:
• If you upgrade or update any hosted cluster, and go to Cluster Management > Clusters while the cluster is still provisioning, the Registration tab is visible. Registering a cluster that is already registered with Rancher can cause data corruption. See #8524.

Long-standing Known Issues - RKE2 Provisioning

• Rancher v2.7.7:
• Due to the backoff logic in various components, downstream provisioned K3s and RKE2 clusters may take longer to re-achieve Active status after a migration. If you see that a downstream cluster is still updating or in an error state immediately after a migration, please let it attempt to resolve itself. This might take up to an hour to complete. See #34518 and #42834.
• Rancher v2.7.6:
• Provisioning RKE2/K3s clusters with added (not built-in) custom node drivers causes provisioning to fail. As a workaround, fix the added node drivers after activating. See #37074.

Long-standing Known Issues - K3s Provisioning

• Rancher v2.7.6:
• Provisioning RKE2/K3s clusters with added (not built-in) custom node drivers causes provisioning to fail. As a workaround, fix the added node drivers after activating. See #37074.
• Rancher v2.7.2:
• Clusters remain in an Updating state even when they contain nodes in an Error state. See #39164.

Long-standing Known Issues - Rancher App (Global UI)

• Rancher v2.10.0:
• After deleting a Namespace or Project in the Rancher UI, the Namespace or Project remains visible. As a workaround, refresh the page. See #12220.
• Rancher v2.9.2:
• 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 occurring, enter a minimum node count at least equal to the node count. See #11922.
• Rancher v2.7.7:
• When creating a cluster in the Rancher UI it does not allow the use of an underscore _ in the Cluster Name field. See #9416.

Long-standing Known Issues - Hosted Rancher

• Rancher v2.7.5:
• The Cluster page shows the Registration tab when updating or upgrading a hosted cluster. See #8524.

Long-standing Known Issues - EKS

• Rancher v2.7.0:
• EKS clusters on Kubernetes v1.21 or below on Rancher v2.7 cannot be upgraded. See #39392.

Long-standing Known Issues - Authentication

• Rancher v2.9.0:
• There are some known issues with the OpenID Connect provider support:
  • When the generic OIDC auth provider is enabled, and you attempt to add auth provider users to a cluster or project, users are not populated in the dropdown search bar. This is expected behavior as the OIDC auth provider alone is not searchable. See #46104.
  • When the generic OIDC auth provider is enabled, auth provider users that are added to a cluster/project by their username are not able to access resources upon logging in. A user will only have access to resources upon login if the user is added by their userID. See #46105.
  • When the generic OIDC auth provider is enabled and an auth provider user in a nested group is logged into Rancher, the user will see the following error when they attempt to create a Project: [projectroletemplatebindings.management.cattle.io](http://projectroletemplatebindings.management.cattle.io/) is forbidden: User "u-gcxatwsnku" cannot create resource "projectroletemplatebindings" in API group "[management.cattle.io](http://management.cattle.io/)" in the namespace "p-9t5pg". However, the project is still created. See #46106.

Long-standing Known Issues - Rancher Webhook

• Rancher v2.7.2:
• A webhook is installed in all downstream clusters. There are several issues that users may encounter with this functionality:
  • If you rollback from a version of Rancher v2.7.2 or later, to a Rancher version earlier than v2.7.2, the webhooks will remain in downstream clusters. Since the webhook is designed to be 1:1 compatible with specific versions of Rancher, this can cause unexpected behaviors to occur downstream. The Rancher team has developed a script which should be used after rollback is complete (meaning after a Rancher version earlier than v2.7.2 is running). This removes the webhook from affected downstream clusters. See #40816.

Long-standing Known Issues - Virtualization Management (Harvester)

• Rancher v2.7.2:
• If you're using Rancher v2.7.2 with Harvester v1.1.1 clusters, you won't be able to select the Harvester cloud provider when deploying or updating guest clusters. The Harvester release notes contain instructions on how to resolve this. See #3750.

Long-standing Known Issues - Backup/Restore

• When migrating to a cluster with the Rancher Backup feature, the server-url cannot be changed to a different location. It must continue to use the same URL.

• Rancher v2.7.7:

• Due to the backoff logic in various components, downstream provisioned K3s and RKE2 clusters may take longer to re-achieve Active status after a migration. If you see that a downstream cluster is still updating or in an error state immediately after a migration, please let it attempt to resolve itself. This might take up to an hour to complete. See #34518 and #42834.