public/rancher-docs
1
0
Fork 0
mirror of https://github.com/rancher/rancher-docs.git synced 2026-09-25 20:48:11 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'main' into imperative-api-required

Browse Source
This commit is contained in:
Petr Kovar
2025-07-31 19:30:20 +02:00
committed by GitHub
parent 80dc50b560 8268557cfb
commit 30a5a05733
288 changed files with 16815 additions and 33505 deletions
Download Patch File Download Diff File Expand all files Collapse all files
versioned_docs/version-2.12/getting-started/installation-and-upgrade/installation-references/feature-flags.md
+39 -17
View File
@@ -26,32 +26,54 @@ The following is a list of feature flags available in Rancher. If you've upgrade
- `imperative-api-extension`: Enables Rancher's [extension API server](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/) to register new APIs to Kubernetes. This flag is enabled by default. See the [Extension API Server](../../../api/extension-apiserver.md) page for more information.
- `istio-virtual-service-ui`: Enables a [visual interface](../../../how-to-guides/advanced-user-guides/enable-experimental-features/istio-traffic-management-features.md) to create, read, update, and delete Istio virtual services and destination rules, which are Istio traffic management features.
- `legacy`: Enables a set of features from 2.5.x and earlier, that are slowly being phased out in favor of newer implementations. These are a mix of deprecated features as well as features that will eventually be available to newer versions. This flag is disabled by default on new Rancher installations. If you're upgrading from a previous version of Rancher, this flag is enabled.
- `managed-system-upgrade-controller`: Enables the installation of the system-upgrade-controller app in downstream RKE2/K3s clusters, currently limited to imported clusters and the local cluster, with plans to expand support to node-driver clusters.
- `managed-system-upgrade-controller`: Enables the installation of the system-upgrade-controller app in downstream imported RKE2/K3s clusters, as well as in the local cluster if it is an RKE2/K3s cluster.
:::note Important:
This `managed-system-upgrade-controller` flag is intended for **internal use only** and does not have an associated Feature CR. Use with caution.
To control whether Rancher should manage the Kubernetes version of imported RKE2/K3s clusters, it is recommended to use the [imported-cluster-version-management](../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/register-existing-clusters.md#configuring-version-management-for-rke2-and-k3s-clusters) feature that is available in Rancher v2.11.0 or newer.
:::
:::danger
If the `managed-system-upgrade-controller` flag was **disabled** in Rancher v2.10.x, and any imported RKE2/K3s clusters were upgraded **outside of Rancher**, follow the steps below to prevent the unexpected installation of the system-upgrade-controller app and to ensure the [imported-cluster-version-management](../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/register-existing-clusters.md#configuring-version-management-for-rke2-and-k3s-clusters) feature works correctly:
1. Upgrade Rancher to v2.11.0 or newer, making sure to **retain** the `managed-system-upgrade-controller=false` feature flag in Helm values if it was set during the v2.10.x installation.
1. After Rancher is fully up and running, disable the `imported-cluster-version-management` setting. You can do this either through the Rancher UI by clicking **☰ > Global Settings > Settings > imported-cluster-version-management**, or by editing the corresponding `Setting.management.cattle.io/v3` custom resource via kubectl.
1. Perform a second Helm upgrade, this time omitting the `managed-system-upgrade-controller=false` feature flag.
Now, the imported cluster version management is disabled by default, and Rancher no longer installs the system-upgrade-controller app on imported clusters automatically.
You can enable this feature on a per-cluster basis. For more information, please refer to the [documentation](../../../how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/register-existing-clusters.md#configuring-version-management-for-rke2-and-k3s-clusters).
:::
- `multi-cluster-management`: Allows multi-cluster provisioning and management of Kubernetes clusters. This flag can only be set at install time. It can't be enabled or disabled later.
- `rke1-custom-node-cleanup`: Enables cleanup of deleted RKE1 custom nodes. We recommend that you keep this flag enabled, to prevent removed nodes from attempting to rejoin the cluster.
- `rke2`: Enables provisioning RKE2 clusters. This flag is enabled by default.
- `token-hashing`: Enables token hashing. Once enabled, existing tokens will be hashed and all new tokens will be hashed automatically with the SHA256 algorithm. Once a token is hashed it can't be undone. This flag can't be disabled after its enabled. See [API Tokens](../../../api/api-tokens.md#token-hashing) for more information.
- `uiextension`: Enables UI extensions. This flag is enabled by default. Enabling or disabling the flag forces the Rancher pod to restart. The first time this flag is set to `true`, it creates a CRD and enables the controllers and endpoints necessary for the feature to work. If set to `false`, it disables the previously mentioned controllers and endpoints. Setting `uiextension` to `false` has no effect on the CRD -- it does not create a CRD if it does not yet exist, nor does it delete the CRD if it already exists.
- `uiextension`: Enables UI extensions. This flag is enabled by default. Enabling or disabling the flag forces the Rancher pod to restart. The first time this flag is set to `Active`, it creates a CRD and enables the controllers and endpoints necessary for the feature to work. If set to `Disabled`, it disables the previously mentioned controllers and endpoints. Setting `uiextension` to `Disabled` has no effect on the CRD -- it does not create a CRD if it does not yet exist, nor does it delete the CRD if it already exists.
- `unsupported-storage-drivers`: Enables types for storage providers and provisioners that aren't enabled by default. See [Allow Unsupported Storage Drivers](../../../how-to-guides/advanced-user-guides/enable-experimental-features/unsupported-storage-drivers.md) for more information.
- `ui-sql-cache`: Enables a SQLite-based cache for UI tables. See [UI Server-Side Pagination](../../../how-to-guides/advanced-user-guides/enable-experimental-features/ui-server-side-pagination.md) for more information.
- `ui-sql-cache`: Enables an SQLite-based cache for UI tables and Server-Side Pagination. See [UI Server-Side Pagination](../../../how-to-guides/advanced-user-guides/ui-server-side-pagination.md) for more information.
The following table shows the availability and default values for some feature flags in Rancher. Features marked "GA" are generally available:
| Feature Flag Name | Default Value | Status | Available As Of | Additional Information |
| ----------------------------- | ------------- | ------------ | --------------- | ---------------------- |
| `aggregated-roletemplates` | `false` | Highly experimentatl | v2.11.0 | This flag value is locked on install and can't be changed. |
| `clean-stale-secrets` | `true` | GA | v2.10.2 | |
| `continuous-delivery` | `true` | GA | v2.6.0 | |
| `external-rules` | v2.7.14: `false`, v2.8.5: `true` | Removed | v2.7.14, v2.8.5 | This flag affected [external `RoleTemplate` behavior](../../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#external-roletemplate-behavior). It is removed in Rancher v2.9.0 and later as the behavior is enabled by default. |
| `fleet` | `true` | Can no longer be disabled | v2.6.0 | |
| `fleet` | `true` | GA | v2.5.0 | |
| `harvester` | `true` | Experimental | v2.6.1 | |
| `imperative-api-extension` | `true` | GA | v2.11.0 | |
| `legacy` | `false` for new installs, `true` for upgrades | GA | v2.6.0 | |
| `managed-system-upgrade-controller` | `true` | GA | v2.10.0 | |
| `aggregated-roletemplates` | `Disabled` | Highly experimental | v2.11.0 | This flag value is locked on install and can't be changed. |
| `clean-stale-secrets` | `Active` | GA | v2.10.2 | |
| `continuous-delivery` | `Active` | GA | v2.6.0 | |
| `external-rules` | v2.7.14: `Disabled`, v2.8.5: `Active` | Removed | v2.7.14, v2.8.5 | This flag affected [external `RoleTemplate` behavior](../../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#external-roletemplate-behavior). It is removed in Rancher v2.9.0 and later as the behavior is enabled by default. |
| `fleet` | `Active` | Can no longer be disabled | v2.6.0 | |
| `fleet` | `Active` | GA | v2.5.0 | |
| `harvester` | `Active` | Experimental | v2.6.1 | |
| `imperative-api-extension` | `Active` | GA | v2.11.0 | |
| `legacy` | `Disabled` for new installs, `Active` for upgrades | GA | v2.6.0 | |
| `managed-system-upgrade-controller` | `Active` | GA | v2.10.0 | |
| `rke1-custom-node-cleanup`| `true` | GA | v2.6.0 | |
| `rke2` | `true` | Experimental | v2.6.0 | |
| `token-hashing` | `false` for new installs, `true` for upgrades | GA | v2.6.0 | |
| `uiextension` | `true` | GA | v2.9.0 | |
| `ui-sql-cache` | `false` | Highly experimental | v2.9.0 | |
| `token-hashing` | `Disabled` for new installs, `Active` for upgrades | GA | v2.6.0 | |
| `uiextension` | `Active` | GA | v2.9.0 | |
| `ui-sql-cache` | `Active` | GA | v2.9.0 | |
versioned_docs/version-2.12/getting-started/installation-and-upgrade/installation-references/helm-chart-options.md
+6 -1
View File
@@ -36,7 +36,8 @@ For information on enabling experimental features, refer to [this page.](../../.
| `antiAffinity` | "preferred" | `string` - AntiAffinity rule for Rancher pods - "preferred, required" |
| `auditLog.destination` | "sidecar" | `string` - Stream to sidecar container console or hostPath volume - "sidecar, hostPath" |
| `auditLog.hostPath` | "/var/log/rancher/audit" | `string` - log file destination on host (only applies when `auditLog.destination` is set to `hostPath`) |
| `auditLog.level` | 0 | `int` - set the [API Audit Log](../../../how-to-guides/advanced-user-guides/enable-api-audit-log.md) level. 0 is off. [0-3] |
| `auditLog.enabled` | false | `bool` - Enables / disables audit logging. |
| `auditLog.level` | 0 | `int` - Sets the [API Audit Log](../../../how-to-guides/advanced-user-guides/enable-api-audit-log.md) level [0-3]. |
| `auditLog.maxAge` | 1 | `int` - maximum number of days to retain old audit log files (only applies when `auditLog.destination` is set to `hostPath`) |
| `auditLog.maxBackup` | 1 | `int` - maximum number of audit log files to retain (only applies when `auditLog.destination` is set to `hostPath`) |
| `auditLog.maxSize` | 100 | `int` - maximum size in megabytes of the audit log file before it gets rotated (only applies when `auditLog.destination` is set to `hostPath`) |
@@ -63,6 +64,10 @@ For information on enabling experimental features, refer to [this page.](../../.
| `tls` | "ingress" | `string` - See [External TLS Termination](#external-tls-termination) for details. - "ingress, external" |
| `useBundledSystemChart` | `false` | `bool` - select to use the system-charts packaged with Rancher server. This option is used for air gapped installations. |
When using Rancher v2.12.0 and above, Rancher will use an audit logging controller that watches `AuditPolicy` CRs for configuring additional redactions, for more info see [API Audit Log](../../../how-to-guides/advanced-user-guides/enable-api-audit-log.md).
### Bootstrap Password
You can [set a specific bootstrap password](../resources/bootstrap-password.md) during Rancher installation. If you don't set a specific bootstrap password, Rancher randomly generates a password for the first admin account.
versioned_docs/version-2.12/getting-started/installation-and-upgrade/other-installation-methods/rancher-on-a-single-node-with-docker/upgrade-docker-installed-rancher.md
+43
View File
@@ -53,6 +53,10 @@ You can obtain `<RANCHER_CONTAINER_TAG>` and `<RANCHER_CONTAINER_NAME>` by loggi
## Upgrade
:::danger
Rancher upgrades to version 2.12.0 and later will be blocked if any RKE1-related resources are detected, as the Rancher Kubernetes Engine (RKE/RKE1) is end of life as of **July 31, 2025**. For detailed cleanup and recovery steps, refer to the [RKE1 Resource Validation and Upgrade Requirements in Rancher v2.12](#rke1-resource-validation-and-upgrade-requirements-in-rancher-v212).
:::
During upgrade, you create a copy of the data from your current Rancher container and a backup in case something goes wrong. Then you deploy the new version of Rancher in a new container using your existing data.
### 1. Create a copy of the data from your Rancher server container
@@ -388,6 +392,45 @@ See [Restoring Cluster Networking](https://github.com/rancher/rancher-docs/tree/
Remove the previous Rancher server container. If you only stop the previous Rancher server container (and don't remove it), the container may restart after the next server reboot.
## RKE1 Resource Validation and Upgrade Requirements in Rancher v2.12
Rancher v2.12.0 and later has removed support for the Rancher Kubernetes Engine (RKE/RKE1). During upgrade, Rancher validates the cluster resources and blocks the upgrade if any RKE1-related resources are detected.
This validation affects the following resource types:
- Clusters with `rkeConfig` (`clusters.management.cattle.io`)
- NodeTemplates (`nodetemplates.management.cattle.io`)
- ClusterTemplates (`clustertemplates.management.cattle.io`)
This is particularly relevant for single-node Docker installations, where Rancher is not running during the upgrade. In such cases, controllers are not available to automatically clean up deprecated resources, and the upgrade process will fail early with an error listing the blocking resources.
### 1. Pre-Upgrade (Recommended)
Before upgrading, while Rancher is still running:
- Run the `pre-upgrade-hook` cleanup script to delete all RKE1 clusters and templates. You can find the script in the Rancher GitHub repository: [pre-upgrade-hook.sh](https://github.com/rancher/rancher/blob/v2.12.0/chart/scripts/pre-upgrade-hook.sh).
- This allows Rancher to clean up associated resources and finalizers.
### 2. Post-Upgrade Failure Due to Residual RKE1 Resources
If the upgrade to Rancher v2.12.0 or later is attempted without prior cleanup of RKE1 resources:
- The upgrade will fail and display an error listing the resource names that are preventing the upgrade.
- This occurs because Rancher includes validation to detect and block upgrades when unsupported RKE1 resources are still present.
- To proceed, [rollback](#rolling-back) to the previous Rancher version, delete the identified resources, and then retry after [manual cleanup](#manual-cleanup-after-rollback).
:::note Helm-based Rancher
Helm-based Rancher installations are not affected by this issue, as Rancher remains available during the upgrade and can perform resource cleanup as needed.
:::
### Manual Cleanup After Rollback
Users should perform the following steps after rolling back to a previous Rancher version:
- **Manually delete** the resources listed in the upgrade error message (e.g., RKE1 clusters, NodeTemplates, ClusterTemplates).
- If deletion is blocked due to **finalizers**, edit the resources and remove the `metadata.finalizers` field.
- If a **validating webhook** prevents deletion (e.g., for the `system-project`), please refer to the [Bypassing the Webhook](../../../../reference-guides/rancher-webhook.md#bypassing-the-webhook) documentation.
## Rolling Back
If your upgrade does not complete successfully, you can roll back Rancher server and its data back to its last healthy state. For more information, see [Docker Rollback](roll-back-docker-installed-rancher.md).