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

Merge branch 'v2.12.0' into update-ssp

Browse Source
This commit is contained in:
Sunil Singh
2025-07-28 17:41:31 -07:00
committed by GitHub
parent 895e298b0b ce921bbd60
commit 3d66717aa0
150 changed files with 2748 additions and 2409 deletions
Download Patch File Download Diff File Expand all files Collapse all files
versioned_docs/version-2.12/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/install-kubernetes.md
+9 -1
View File
@@ -10,7 +10,15 @@ Once the infrastructure is ready, you can continue with setting up a Kubernetes
The steps to set up RKE, RKE2, or K3s are shown below.
For convenience, export the IP address and port of your proxy into an environment variable and set up the HTTP_PROXY variables for your current shell on every node:
For convenience, export the IP address and port of your proxy into an environment variable and set up the `HTTP_PROXY` variables for your current shell on every node:
:::caution
The `NO_PROXY` environment variable is not standardized, and the accepted format of the value can differ between applications. When configuring the `NO_PROXY` variable for Rancher, the value must adhere to the format expected by Golang.
Specifically, the value should be a comma-delimited string which only contains IP addresses, CIDR notation, domain names, or special DNS labels (e.g. `*`). For a full description of the expected value format, refer to the [**upstream Golang documentation**](https://pkg.go.dev/golang.org/x/net/http/httpproxy#Config)
:::
```
export proxy_host="10.0.0.5:8888"
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).