* Add draft of Guide to Ingress NGINX Retirement
* Revise Guide to Ingress NGINX Retirement page for community
* Add note about version availability for Dual Mode migration option
Co-authored-by: Billy Tat <btat@suse.com>
* Update note on Rancher version availability
* Remove note in Downstream RKE2 clusters (provisioned by Rancher) section
---------
Co-authored-by: Billy Tat <btat@suse.com>
* Update the deprecated features table
* Update the CSP adapter compatibility matrix
* Update the Rancher:webhook version mapping table
* Update the versions table
* Update Resource Quota Type Reference page for support of all upstream Kubernetes ResourceQuota types
* Apply changes to v2.14 / zh files
* Apply suggestions from code review
Co-authored-by: Billy Tat <btat@suse.com>
* Apply feedback to other versions/zh, reword/reorder intro
* Add back zh content
---------
Co-authored-by: Billy Tat <btat@suse.com>
* Add v3 API token deprecation warning shared file / Add warning to applicable pages
* Update Deprecation of v3 API tokens warning
* Update shared-files/_v3-api-tokens-deprecation-warning.md
Co-authored-by: Billy Tat <btat@suse.com>
* Update src/theme/MDXComponents.js
Co-authored-by: Billy Tat <btat@suse.com>
* Fix/update typo in shared file name (v3APITokensDeprecationWarning)
* Fix wording in Deprecation of v3 API tokens warning
---------
Co-authored-by: Billy Tat <btat@suse.com>
* Add shared fle for OIDC Support for PKCE Extension
* Update OIDC pages
* Update shared-files/_oidc-pkce-support.md
Co-authored-by: Billy Tat <btat@suse.com>
* Reword OIDC PKCE support text
---------
Co-authored-by: Billy Tat <btat@suse.com>
- Updates `troubleshooting-etcd-nodes.md` to replace Docker-based commands with `crictl` and `etcdctl` for RKE2 and K3s.
- Replaces `curl` connectivity checks with `openssl s_client` to support etcd 3.5+ gRPC requirements and isolate transport layer testing.
- Adds prerequisites section with necessary environment exports.
- Updates all `etcdctl` commands to use explicit inline certificate paths for RKE2 and K3s.
- Replaces shell-dependent container commands with host-side processing to support distroless images.
- Updates log level configuration instructions for RKE2/K3s config files.
* Update the deprecated features table
* Update the CSP adapter compatibility matrix
* Update the Rancher:webhook version mapping table
* Update the versions table
* Update the CNI popularity table
* Update the deprecated features table
* Update the CSP adapter compatibility matrix
* Update the Rancher:webhook version mapping table
* Update the versions table
* Update the deprecated features table
* Update the CSP adapter compatibility matrix
* Update the Rancher:webhook version mapping table
* Update the versions table
* Update the deprecated features table
* Update the CSP adapter compatibility matrix
* Update the Rancher:webhook version mapping table
* Update the versions table
* Update src/pages/versions.md
Co-authored-by: Billy Tat <btat@suse.com>
---------
Co-authored-by: Billy Tat <btat@suse.com>
* Add Notification Banner page
* Remove notifications banner page
* Rename Notificaitons Center page to Notifications / Update Notifications page
* Undo change to canonical link
* Undo change to canonical link
* Update docs/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/notification-center.md
Co-authored-by: Billy Tat <btat@suse.com>
* Fix typo on v2.13/v2.14 page
---------
Co-authored-by: Billy Tat <btat@suse.com>
* tweak: paragraph describing how to go beyond the fixed builtin resources
* chore: formatting fixes (alignments)
tweak: added ref and explanations for `extended`
* fix: namespace limit of a namespace is nonsense. switched to cpu limits.
* tweak: added editing of extended via `edit yaml`
* add unit ref for memory/storage
* address comments
* updated to match the dashboard's new `custom` resource type.
* Update docs/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/manage-project-resource-quotas.md
Co-authored-by: Jonathan Crowther <jonathan.crowther@suse.com>
* Apply to v2.14 folder: 'Document the extended project resource quotas'
---------
Co-authored-by: Jonathan Crowther <jonathan.crowther@suse.com>
Co-authored-by: Billy Tat <btat@suse.com>
* Add SamlOpenLDAPGroupPermissions shared file
* Add SamlOpenLDAPGroupPermissions shared file to Configure Keycloak (SAML) page
* Add SamlOpenLDAPGroupPermissions shared file to Configure Okta (SAML) page
* Add SamlOpenLDAPGroupPermissions shared file to Configure PingIdentity (SAML) page
* Add SamlOpenLDAPGroupPermissions shared file to Configuring Rancher for Microsoft AD FS page
* Add SamlOpenLDAPGroupPermissions shared file to Group Permissions with Shibboleth and OpenLDAP page
* Add SamlOpenLDAPGroupPermissions shared file to other versions of Configure Keycloak (SAML) page
* Add SamlOpenLDAPGroupPermissions shared file to other versions of Configure Okta (SAML) page
* Add SamlOpenLDAPGroupPermissions shared file to other versions Configure PingIdentity (SAML) page
* Add SamlOpenLDAPGroupPermissions shared file to other versions of Configuring Rancher for Microsoft AD FS page
* Add SamlOpenLDAPGroupPermissions shared file to other versions of Group Permissions with Shibboleth and OpenLDAP page
> Hello, our team is currently in the process of consolidating our Rancher documentation repositories. With this change, the contents of this repository was moved to [rancher/rancher-product-docs](https://github.com/rancher/rancher-product-docs).
>
> We understand this is a significant change and disruption to the standard process and wish to note the Rancher documentation team is here to assist in any way it can to make the transition process straight forward. Going forward, we kindly ask that any new issue reports or contributions be made to the `rancher-product-docs` repository instead. If you wish to make contributions, please refer to our updated [README](https://github.com/rancher/rancher-product-docs/blob/main/README.md) for guidance.
>
> Please note as part of this change, the Chinese portion of the site was dropped. No URLs for the Community documentation site changed.
This issue is to track tasks that need to be done every release regardless of whether the release has new feature content or not.
This issue is to track tasks that need to be done every release regardless of whether the release has new feature content or not.
- [ ] Create a new branch for the release. Release-specific updates should use this branch as its base
- [ ] Create a new branch for the release. Release-specific updates should use this branch as its base
about:For requesting new feature(s) to be added to the docs.
about:For requesting new feature(s) to be added to the docs.
---
---
> [!IMPORTANT]
> Hello, our team is currently in the process of consolidating our Rancher documentation repositories. With this change, the contents of this repository was moved to [rancher/rancher-product-docs](https://github.com/rancher/rancher-product-docs).
>
> We understand this is a significant change and disruption to the standard process and wish to note the Rancher documentation team is here to assist in any way it can to make the transition process straight forward. Going forward, we kindly ask that any new issue reports or contributions be made to the `rancher-product-docs` repository instead. If you wish to make contributions, please refer to our updated [README](https://github.com/rancher/rancher-product-docs/blob/main/README.md) for guidance.
>
> Please note as part of this change, the Chinese portion of the site was dropped. No URLs for the Community documentation site changed.
> Hello, our team is currently in the process of consolidating our Rancher documentation repositories. With this change, the contents of this repository was moved to [rancher/rancher-product-docs](https://github.com/rancher/rancher-product-docs).
>
> We understand this is a significant change and disruption to the standard process and wish to note the Rancher documentation team is here to assist in any way it can to make the transition process straight forward. Going forward, we kindly ask that any new issue reports or contributions be made to the `rancher-product-docs` repository instead. If you wish to make contributions, please refer to our updated [README](https://github.com/rancher/rancher-product-docs/blob/main/README.md) for guidance.
>
> Please note as part of this change, the Chinese portion of the site was dropped. No URLs for the Community documentation site changed.
## Related Issues
## Related Issues
<!--
<!--
List any issues or tickets on other platforms that are associated with the request. For example, include a link to the issue tracking that feature in the Rancher repo, or list the Jira ticket number for the request.
List any issues or tickets on other platforms that are associated with the request. For example, include a link to the issue tracking that feature in the Rancher repo, or list the Jira ticket number for the request.
Check the Rancher docs issues to see if there is an existing issue for this pull request. If there is, enter the issue number below.
Check the Rancher docs issues to see if there is an existing issue for this pull request. If there is, enter the issue number below.
-->
-->
> [!IMPORTANT]
> Hello, our team is currently in the process of consolidating our Rancher documentation repositories. With this change, the contents of this repository was moved to [rancher/rancher-product-docs](https://github.com/rancher/rancher-product-docs).
>
> We understand this is a significant change and disruption to the standard process and wish to note the Rancher documentation team is here to assist in any way it can to make the transition process straight forward. Going forward, we kindly ask that any new issue reports or contributions be made to the `rancher-product-docs` repository instead. If you wish to make contributions, please refer to our updated [README](https://github.com/rancher/rancher-product-docs/blob/main/README.md) for guidance.
>
> Please note as part of this change, the Chinese portion of the site was dropped. No URLs for the Community documentation site changed.
> The contents of this repository was moved to [rancher/rancher-product-docs](https://github.com/rancher/rancher-product-docs).
>
> We understand this is a significant change and disruption to the standard process and wish to note the Rancher documentation team is here to assist in any way it can to make the transition process straight forward. Going forward, we kindly ask that any new issue reports or contributions be made to the `rancher-product-docs` repository instead. If you wish to make contributions, please refer to our updated [README](https://github.com/rancher/rancher-product-docs/blob/main/README.md) for guidance.
>
> Please note as part of this change, the Chinese portion of the site was dropped. No URLs for the Community documentation site changed.
Welcome to the [Rancher docs](https://ranchermanager.docs.rancher.com/) repository. See the [Rancher software](https://github.com/rancher/rancher) repository if you have questions or requests for the Rancher platform.
Welcome to the [Rancher docs](https://ranchermanager.docs.rancher.com/) repository. See the [Rancher software](https://github.com/rancher/rancher) repository if you have questions or requests for the Rancher platform.
@@ -65,7 +65,7 @@ Kubernetes workers should open UDP port `8472` (VXLAN) and TCP port `9099` (heal


For more information, see the [Canal GitHub Page.](https://github.com/projectcalico/canal)
For more information, refer to the [Rancher maintained Canal source](https://github.com/rancher/rke2-charts/tree/main-source/packages/rke2-canal) and the [Canal GitHub Page](https://github.com/projectcalico/canal).
The community version of Rancher follows the same deprecation policy as Rancher Prime. The official deprecation policy is documented in the [Rancher Prime Deprecation Policy](https://www.suse.com/support/rancher-prime/#Rancher-Prime-Deprecation-Policy).
## Where can I find out which features have been deprecated in Rancher?
## Where can I find out which features have been deprecated in Rancher?
Rancher will publish deprecated features as part of the [release notes](https://github.com/rancher/rancher/releases) for Rancher found on GitHub. Please consult the following patch releases for deprecated features:
Rancher will publish deprecated features as part of the [release notes](https://github.com/rancher/rancher/releases) for Rancher found on GitHub. Please consult the following patch releases for deprecated features:
| Patch Version | Release Date |
| Patch Version | Release Date |
|---------------|---------------|
|---------------|---------------|
| [2.10.12](https://github.com/rancher/rancher/releases/tag/v2.10.12) | May 27, 2026 |
| [2.10.11](https://github.com/rancher/rancher/releases/tag/v2.10.11) | January 29, 2026 |
| [2.10.11](https://github.com/rancher/rancher/releases/tag/v2.10.11) | January 29, 2026 |
| [2.10.10](https://github.com/rancher/rancher/releases/tag/v2.10.10) | September 25, 2025 |
| [2.10.10](https://github.com/rancher/rancher/releases/tag/v2.10.10) | September 25, 2025 |
| [2.10.9](https://github.com/rancher/rancher/releases/tag/v2.10.9) | August 27, 2025 |
| [2.10.9](https://github.com/rancher/rancher/releases/tag/v2.10.9) | August 27, 2025 |
@@ -52,12 +52,6 @@ az group create --name rancher-rg --location eastus
To create an AKS cluster, run the following command. Use a VM size that applies to your use case. Refer to [this article](https://docs.microsoft.com/en-us/azure/virtual-machines/sizes) for available sizes and options. When choosing a Kubernetes version, be sure to first consult the [support matrix](https://rancher.com/support-matrix/) to find the highest version of Kubernetes that has been validated for your Rancher version.
To create an AKS cluster, run the following command. Use a VM size that applies to your use case. Refer to [this article](https://docs.microsoft.com/en-us/azure/virtual-machines/sizes) for available sizes and options. When choosing a Kubernetes version, be sure to first consult the [support matrix](https://rancher.com/support-matrix/) to find the highest version of Kubernetes that has been validated for your Rancher version.
:::note
If you're updating from an older version of Kubernetes, to Kubernetes v1.22 or above, you also need to [update](https://kubernetes.github.io/ingress-nginx/user-guide/k8s-122-migration/) ingress-nginx.
:::
```
```
az aks create \
az aks create \
--resource-group rancher-rg \
--resource-group rancher-rg \
@@ -81,48 +75,46 @@ This command merges your cluster's credentials into the existing kubeconfig and
## 5. Install an Ingress
## 5. Install an Ingress
The cluster needs an Ingress so that Rancher can be accessed from outside the cluster. Installing an Ingress requires allocating a public IP address. Ensure you have sufficient quota, otherwise it will fail to assign the IP address. Limits for public IP addresses are applicable at a regional level per subscription.
The cluster needs an Ingress so that Rancher can be accessed from outside the cluster. Installing an Ingress requires allocating a public IP address. Ensure you have sufficient quota, otherwise it will fail to assign the IP address. Limits for public IP addresses are applicable at a regional level per subscription. You can use a managed ingress controller provided by Azure or a third-party ingress controller like Traefik.
To make sure that you choose the correct Ingress-NGINX Helm chart, first find an `Ingress-NGINX version` that's compatible with your Kubernetes version in the [Kubernetes/ingress-nginx support table](https://github.com/kubernetes/ingress-nginx#supported-versions-table).
:::warning
It is not recommended to install a third-party ingress controller, like Traefik, if a managed ingress controller is already being used.
:::
Then, list the Helm charts available to you by running the following command:
:::warning
**Ingress-NGINX EOL:** The community `ingress-nginx` controller reaches End-of-Life (EOL) in March 2026. This page uses Traefik, which is the recommended migration path for Rancher environments.
:::
```
Traefik includes a native Ingress NGINX provider. This allows you to migrate from NGINX without rewriting your existing Ingress objects, as Traefik will automatically interpret `nginx.ingress.kubernetes.io` annotations. If you are upgrading a cluster that is already using `ingress-nginx`, follow this [guide](https://doc.traefik.io/traefik/migrate/nginx-to-traefik/) for more information.
The `helm search` command's output contains an `APP VERSION` column. The versions under this column are equivalent to the `Ingress-NGINX version` you chose earlier. Using the app version, select a chart version that bundles an app compatible with your Kubernetes install. For example, if you have Kubernetes v1.24, you can select the v4.6.0 Helm chart, since Ingress-NGINX v1.7.0 comes bundled with that chart, and v1.7.0 is compatible with Kubernetes v1.24. When in doubt, select the most recent compatible version.
Now that you know which Helm chart `version` you need, run the following command. It installs an `nginx-ingress-controller` with a Kubernetes load balancer service:
@@ -145,7 +137,7 @@ Use that DNS name from the previous step as the Rancher server URL when you inst
When installing Rancher on top of this setup, you will also need to pass the value below into the Rancher Helm install command in order to set the name of the ingress controller to be used with Rancher's ingress resource:
When installing Rancher on top of this setup, you will also need to pass the value below into the Rancher Helm install command in order to set the name of the ingress controller to be used with Rancher's ingress resource:
```
```
--set ingress.ingressClassName=nginx
--set ingress.ingressClassName=traefik
```
```
Refer [here for the Helm install command](install-upgrade-on-a-kubernetes-cluster.md#5-install-rancher-with-helm-and-your-chosen-certificate-option) for your chosen certificate option.
Refer [here for the Helm install command](install-upgrade-on-a-kubernetes-cluster.md#5-install-rancher-with-helm-and-your-chosen-certificate-option) for your chosen certificate option.
@@ -52,8 +52,6 @@ Then enter the following values:
To create an EKS cluster, run the following command. Use the AWS region that applies to your use case. When choosing a Kubernetes version, be sure to first consult the [support matrix](https://rancher.com/support-matrix/) to find the highest version of Kubernetes that has been validated for your Rancher version.
To create an EKS cluster, run the following command. Use the AWS region that applies to your use case. When choosing a Kubernetes version, be sure to first consult the [support matrix](https://rancher.com/support-matrix/) to find the highest version of Kubernetes that has been validated for your Rancher version.
**Note:** If you're updating from an older version of Kubernetes, to Kubernetes v1.22 or above, you also need to [update](https://kubernetes.github.io/ingress-nginx/user-guide/k8s-122-migration/) ingress-nginx.
The cluster needs an Ingress so that Rancher can be accessed from outside the cluster.
The cluster needs an Ingress so that Rancher can be accessed from outside the cluster. Installing an Ingress requires allocating a public IP address. Ensure you have sufficient quota, otherwise it will fail to assign the IP address. Limits for public IP addresses are applicable at a regional level per subscription. You can use a managed ingress controller provided by AWS (ALB) or a third-party ingress controller like Traefik.
To make sure that you choose the correct Ingress-NGINX Helm chart, first find an `Ingress-NGINX version` that's compatible with your Kubernetes version in the [Kubernetes/ingress-nginx support table](https://github.com/kubernetes/ingress-nginx#supported-versions-table).
:::warning
It is not recommended to install a third-party ingress controller, like Traefik, if a managed ingress controller (ALB) is already being used.
:::
Then, list the Helm charts available to you by running the following command:
**Ingress-NGINX EOL:** The community `ingress-nginx` controller reaches End-of-Life (EOL) in March 2026. This page uses Traefik, which is the recommended migration path for Rancher environments.
:::
Traefik includes a native Ingress NGINX provider. This allows you to migrate from NGINX without rewriting your existing Ingress objects, as Traefik will automatically interpret `nginx.ingress.kubernetes.io` annotations. If you are upgrading a cluster that is already using `ingress-nginx`, follow this [guide](https://doc.traefik.io/traefik/migrate/nginx-to-traefik/) for more information.
To install Traefik (chart version 39.0.0) on a fresh cluster, run the following `helm` commands:
The `helm search` command's output contains an `APP VERSION` column. The versions under this column are equivalent to the `Ingress-NGINX version` you chose earlier. Using the app version, select a chart version that bundles an app compatible with your Kubernetes install. For example, if you have Kubernetes v1.23, you can select the v4.6.0 Helm chart, since Ingress-NGINX v1.7.0 comes bundled with that chart, and v1.7.0 is compatible with Kubernetes v1.23. When in doubt, select the most recent compatible version.
Now that you know which Helm chart `version` you need, run the following command. It installs an `nginx-ingress-controller` with a Kubernetes load balancer service:
```
helm upgrade --install \
helm upgrade --install \
ingress-nginx ingress-nginx/ingress-nginx \
traefik traefik/traefik \
--namespace ingress-nginx \
--namespace traefik \
--set controller.service.type=LoadBalancer \
--version 39.0.0 \
--version 4.6.0 \
--create-namespace \
--create-namespace
--set service.type=LoadBalancer \
--set ping.enabled=true \
```
```
### 6. Get Load Balancer IP
### 6. Get Load Balancer IP
To get the address of the load balancer, run:
To get the address of the load balancer, run:
```
```bash
kubectl get service ingress-nginx-controller --namespace=ingress-nginx
@@ -149,7 +149,7 @@ Use that DNS name from the previous step as the Rancher server URL when you inst
When installing Rancher on top of this setup, you will also need to pass the value below into the Rancher Helm install command in order to set the name of the ingress controller to be used with Rancher's ingress resource:
When installing Rancher on top of this setup, you will also need to pass the value below into the Rancher Helm install command in order to set the name of the ingress controller to be used with Rancher's ingress resource:
```
```
--set ingress.ingressClassName=nginx
--set ingress.ingressClassName=traefik
```
```
Refer [here for the Helm install command](install-upgrade-on-a-kubernetes-cluster.md#5-install-rancher-with-helm-and-your-chosen-certificate-option) for your chosen certificate option.
Refer [here for the Helm install command](install-upgrade-on-a-kubernetes-cluster.md#5-install-rancher-with-helm-and-your-chosen-certificate-option) for your chosen certificate option.
@@ -124,7 +124,6 @@ When choosing a Kubernetes version, be sure to first consult the [support matrix
To successfully create a GKE cluster with Rancher, your GKE must be in Standard mode. GKE has two modes of operation when creating a Kubernetes cluster, Autopilot and Standard mode. The cluster configuration for Autopilot mode has restrictions on editing the kube-system namespace. However, Rancher needs to create resources in the kube-system namespace during installation. As a result, you will not be able to install Rancher on a GKE cluster created in Autopilot mode. For more information about the difference between GKE Autopilot mode and Standard mode, visit [Compare GKE Autopilot and Standard.](https://cloud.google.com/kubernetes-engine/docs/resources/autopilot-standard-feature-comparison)
To successfully create a GKE cluster with Rancher, your GKE must be in Standard mode. GKE has two modes of operation when creating a Kubernetes cluster, Autopilot and Standard mode. The cluster configuration for Autopilot mode has restrictions on editing the kube-system namespace. However, Rancher needs to create resources in the kube-system namespace during installation. As a result, you will not be able to install Rancher on a GKE cluster created in Autopilot mode. For more information about the difference between GKE Autopilot mode and Standard mode, visit [Compare GKE Autopilot and Standard.](https://cloud.google.com/kubernetes-engine/docs/resources/autopilot-standard-feature-comparison)
**Note:** If you're updating from an older version of Kubernetes, to Kubernetes v1.22 or above, you also need to [update](https://kubernetes.github.io/ingress-nginx/user-guide/k8s-122-migration/) ingress-nginx.
This command configures `kubectl` to use the cluster you created.
This command configures `kubectl` to use the cluster you created.
## 7. Install an Ingress
## 7. Install an Ingress
The cluster needs an Ingress so that Rancher can be accessed from outside the cluster.
The cluster needs an Ingress so that Rancher can be accessed from outside the cluster. Installing an Ingress requires allocating a public IP address. Ensure you have sufficient quota, otherwise it will fail to assign the IP address. Limits for public IP addresses are applicable at a regional level per subscription. You can use a managed ingress controller provided by GCP or a third-party ingress controller like Traefik.
The following command installs an `nginx-ingress-controller` with a LoadBalancer service:
:::warning
It is not recommended to install a third-party ingress controller, like Traefik, if a managed ingress controller is already being used.
**Ingress-NGINX EOL:** The community `ingress-nginx` controller reaches End-of-Life (EOL) in March 2026. This page uses Traefik, which is the recommended migration path for Rancher environments.
:::
Traefik includes a native Ingress NGINX provider. This allows you to migrate from NGINX without rewriting your existing Ingress objects, as Traefik will automatically interpret `nginx.ingress.kubernetes.io` annotations. If you are upgrading a cluster that is already using `ingress-nginx`, follow this [guide](https://doc.traefik.io/traefik/migrate/nginx-to-traefik/) for more information.
To install Traefik (chart version 39.0.0) on a fresh cluster, run the following `helm` commands:
@@ -191,7 +202,7 @@ Use the DNS name from the previous step as the Rancher server URL when you insta
When installing Rancher on top of this setup, you will also need to set the name of the ingress controller to be used with Rancher's ingress resource:
When installing Rancher on top of this setup, you will also need to set the name of the ingress controller to be used with Rancher's ingress resource:
```
```
--set ingress.ingressClassName=nginx
--set ingress.ingressClassName=traefik
```
```
Refer [here for the Helm install command](install-upgrade-on-a-kubernetes-cluster.md#5-install-rancher-with-helm-and-your-chosen-certificate-option) for your chosen certificate option.
Refer [here for the Helm install command](install-upgrade-on-a-kubernetes-cluster.md#5-install-rancher-with-helm-and-your-chosen-certificate-option) for your chosen certificate option.
If its ready and the SSL is still not working you may have a malformed cert or secret.
If its ready and the SSL is still not working you may have a malformed cert or secret.
Check the nginx-ingress-controller logs. Because the nginx-ingress-controller has multiple containers in its pod you will need to specify the name of the container.
W0705 23:04:58.240571 7 backend_ssl.go:49] error obtaining PEM from secret cattle-system/tls-rancher-ingress: error retrieving secret cattle-system/tls-rancher-ingress: secret cattle-system/tls-rancher-ingress was not found
W0705 23:04:58.240571 7 backend_ssl.go:49] error obtaining PEM from secret cattle-system/tls-rancher-ingress: error retrieving secret cattle-system/tls-rancher-ingress: secret cattle-system/tls-rancher-ingress was not found
```
```
@@ -148,11 +148,6 @@ The most common cause of this issue is port 8472/UDP is not open between the nod
Once the network issue is resolved, the `canal` pods should timeout and restart to establish their connections.
Once the network issue is resolved, the `canal` pods should timeout and restart to establish their connections.
### nginx-ingress-controller Pods show RESTARTS
The most common cause of this issue is the `canal` pods have failed to establish the overlay network. See [canal Pods show READY `2/3`](#canal-pods-show-ready-23) for troubleshooting.
### Failed to dial to /var/run/docker.sock: ssh: rejected: administratively prohibited (open failed)
### Failed to dial to /var/run/docker.sock: ssh: rejected: administratively prohibited (open failed)
@@ -29,14 +29,35 @@ Review the list of known issues for each Rancher version, which can be found in
Note that upgrades _to_ or _from_ any chart in the [rancher-alpha repository](../resources/choose-a-rancher-version.md#helm-chart-repositories) aren't supported.
Note that upgrades _to_ or _from_ any chart in the [rancher-alpha repository](../resources/choose-a-rancher-version.md#helm-chart-repositories) aren't supported.
### Upgrade Path
:::important
**Important:** The only tested and supported Rancher upgrade path between minor versions (e.g. v2.9.x to v2.10.x) is to upgrade from the latest available patch version of your current running minor release to the latest available patch version of the next minor release.
Before initiating a minor version upgrade, verify that you are running the most recent patch release of your current version.
You can query the available chart versions with the Helm CLI:
1. Update your local Helm repo cache.
```
helm repo update
```
1. Search for available versions in your [specific repository](../resources/choose-a-rancher-version.md#helm-chart-repositories) (e.g., rancher-stable):
If your installation is not on the latest patch version of the current minor release, you must upgrade to that version before proceeding to the next minor version.
:::
### Helm Version
### Helm Version
The upgrade instructions assume you are using Helm 3.
The upgrade instructions assume you are using Helm 3.
<DeprecationHelm2 />
For migration of installs started with Helm 2, refer to the official [Helm 2 to 3 migration docs.](https://helm.sh/blog/migrate-from-helm-v2-to-helm-v3/) The [Helm 2 upgrade page here](https://github.com/rancher/rancher-docs/tree/main/archived_docs/en/version-2.0-2.4/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades/helm2.md) provides a copy of the older upgrade instructions that used Helm 2, and it is intended to be used if upgrading to Helm 3 is not feasible.
### For air-gapped installs: Populate private registry
### For air-gapped installs: Populate private registry
For [air-gapped installs only,](../other-installation-methods/air-gapped-helm-cli-install/air-gapped-helm-cli-install.md) collect and populate images for the new Rancher server version. Follow the guide to [populate your private registry](../other-installation-methods/air-gapped-helm-cli-install/publish-images.md) with the images for the Rancher version that you want to upgrade to.
For [air-gapped installs only,](../other-installation-methods/air-gapped-helm-cli-install/air-gapped-helm-cli-install.md) collect and populate images for the new Rancher server version. Follow the guide to [populate your private registry](../other-installation-methods/air-gapped-helm-cli-install/publish-images.md) with the images for the Rancher version that you want to upgrade to.
@@ -107,8 +128,21 @@ You'll use the backup as a restore point if something goes wrong during upgrade.
### 3. Review Rancher Feature Chart Versions Before Upgrade
### 3. Upgrade Rancher
Rancher feature charts follow specific release lines that align with Rancher versions. Major versions of feature charts correspond to Rancher minor versions and follow a defined versioning scheme.
Before upgrading Rancher, review any installed Rancher feature charts and upgrade them to the latest available version within their current chart release line. This helps ensure compatibility and avoids potential issues during or after the Rancher upgrade.
To review installed feature charts:
1. In the Rancher UI, go to **Apps & Marketplace**.
2. Select **Installed Apps**.
3. Review the chart versions and upgrade to the latest patch release within the same chart major version if needed.
For more information, see the [Helm Charts in Rancher – Versioning Scheme](../../../how-to-guides/new-user-guides/helm-charts-in-rancher/helm-charts-in-rancher.md#versioning-scheme).
### 4. Upgrade Rancher
This section describes how to upgrade normal (Internet-connected) or air-gapped installations of Rancher with Helm.
This section describes how to upgrade normal (Internet-connected) or air-gapped installations of Rancher with Helm.
@@ -132,17 +166,17 @@ There will be more values that are listed with this command. This is just an exa
:::
:::
:::tip
:::tip
Your deployment name may vary; for example, if you're deploying Rancher through the AWS Marketplace, the deployment name is 'rancher-stable'.
Your deployment name may vary; for example, if you're deploying Rancher through the AWS Marketplace, the deployment name is 'rancher-stable'.
Thus:
Thus:
```
```
helm get values rancher-stable -n cattle-system
helm get values rancher-stable -n cattle-system
hostname: rancher.my.org
hostname: rancher.my.org
```
```
:::
:::
If you are upgrading cert-manager to the latest version from v1.5 or below, follow the [cert-manager upgrade docs](../resources/upgrade-cert-manager.md#option-c-upgrade-cert-manager-from-versions-15-and-below) to learn how to upgrade cert-manager without needing to perform an uninstall or reinstall of Rancher. Otherwise, follow the [steps to upgrade Rancher](#steps-to-upgrade-rancher) below.
If you are upgrading cert-manager to the latest version from v1.5 or below, follow the [cert-manager upgrade docs](../resources/upgrade-cert-manager.md#option-c-upgrade-cert-manager-from-versions-15-and-below) to learn how to upgrade cert-manager without needing to perform an uninstall or reinstall of Rancher. Otherwise, follow the [steps to upgrade Rancher](#steps-to-upgrade-rancher) below.
@@ -165,17 +199,17 @@ The above is an example, there may be more values from the previous step that ne
:::
:::
:::tip
:::tip
If you deploy Rancher through the AWS Marketplace, the deployment name is 'rancher-stable'.
If you deploy Rancher through the AWS Marketplace, the deployment name is 'rancher-stable'.
Alternatively, it's possible to export the current values to a file and reference that file during upgrade. For example, to only change the Rancher version:
Alternatively, it's possible to export the current values to a file and reference that file during upgrade. For example, to only change the Rancher version:
@@ -185,7 +219,7 @@ Alternatively, it's possible to export the current values to a file and referenc
@@ -193,18 +227,10 @@ Alternatively, it's possible to export the current values to a file and referenc
--version=2.6.8
--version=2.6.8
```
```
### 4. Verify the Upgrade
### 5. Verify the Upgrade
Log into Rancher to confirm that the upgrade succeeded.
Log into Rancher to confirm that the upgrade succeeded.
:::tip
Having network issues following upgrade?
See [Restoring Cluster Networking](https://github.com/rancher/rancher-docs/tree/main/archived_docs/en/version-2.0-2.4/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/upgrades/namespace-migration.md).
:::
## Known Upgrade Issues
## Known Upgrade Issues
A list of known issues for each Rancher version can be found in the release notes on [GitHub](https://github.com/rancher/rancher/releases) and on the [Rancher forums.](https://forums.rancher.com/c/announcements/12)
A list of known issues for each Rancher version can be found in the release notes on [GitHub](https://github.com/rancher/rancher/releases) and on the [Rancher forums.](https://forums.rancher.com/c/announcements/12)
@@ -127,18 +127,14 @@ This option is only effective on the initial Rancher install. See [Issue 16522](
To customize or use a different ingress with Rancher server you can set your own Ingress annotations.
To customize or use a different ingress with Rancher server you can set your own Ingress annotations.
Please refer to the Traefik documentation for the full list of Ingress NGINX annotations that are [supported](https://doc.traefik.io/traefik/reference/routing-configuration/kubernetes/ingress-nginx/#annotations-support) and [unsupported](https://doc.traefik.io/traefik/reference/routing-configuration/kubernetes/ingress-nginx/#unsupported-annotations) by Traefik's kubernetesIngressNginx provider.
Rancher requires internet access for some functionality (Helm charts). Use `proxy` to set your proxy server or use `extraEnv` to set the `HTTPS_PROXY` environment variable to point to your proxy server.
Rancher requires internet access for some functionality (Helm charts). Use `proxy` to set your proxy server or use `extraEnv` to set the `HTTPS_PROXY` environment variable to point to your proxy server.
@@ -211,34 +207,6 @@ If you are using a Private CA signed certificate (or if `agent-tls-mode` is set
Your load balancer must support long lived websocket connections and will need to insert proxy headers so Rancher can route links correctly.
Your load balancer must support long lived websocket connections and will need to insert proxy headers so Rancher can route links correctly.
### Configuring Ingress for External TLS when Using NGINX v0.22
In NGINX v0.22, the behavior of NGINX has [changed](https://github.com/kubernetes/ingress-nginx/blob/06efac9f0b6f8f84b553f58ccecf79dc42c75cc6/Changelog.md) regarding forwarding headers and external TLS termination. Therefore, in the scenario that you are using external TLS termination configuration with NGINX v0.22, you must enable the `use-forwarded-headers` option for ingress:
For RKE installations, edit the `cluster.yml` to add the following settings.
```yaml
ingress:
provider: nginx
options:
use-forwarded-headers: 'true'
```
For RKE2 installations, you can create a custom `rke2-ingress-nginx-config.yaml` file at `/var/lib/rancher/rke2/server/manifests/rke2-ingress-nginx-config.yaml` containing this required setting to enable using forwarded headers with external TLS termination. Without this required setting applied, the external LB will continuously respond with redirect loops it receives from the ingress controller. (This can be created before or after rancher is installed, rke2 server agent will notice this addition and automatically apply it.)
```yaml
---
apiVersion: helm.cattle.io/v1
kind: HelmChartConfig
metadata:
name: rke2-ingress-nginx
namespace: kube-system
spec:
valuesContent: |-
controller:
config:
use-forwarded-headers: "true"
```
### Required Headers
### Required Headers
- `Host`
- `Host`
@@ -255,66 +223,3 @@ spec:
### Health Checks
### Health Checks
Rancher will respond `200` to health checks on the `/healthz` endpoint.
Rancher will respond `200` to health checks on the `/healthz` endpoint.
### Example NGINX config
This NGINX configuration is tested on NGINX 1.14.
:::caution
This NGINX configuration is only an example and may not suit your environment. For complete documentation, see [NGINX Load Balancing - HTTP Load Balancing](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-load-balancer/).
:::
- Replace `IP_NODE1`, `IP_NODE2` and `IP_NODE3` with the IP addresses of the nodes in your cluster.
- Replace both occurrences of `FQDN` to the DNS name for Rancher.
- Replace `/certs/fullchain.pem` and `/certs/privkey.pem` to the location of the server certificate and the server certificate key respectively.
# This allows the ability for the execute shell window to remain open for up to 15 minutes. Without this parameter, the default is 1 minute and will automatically close.
@@ -10,10 +10,7 @@ Changing the default TLS settings depends on the chosen installation method.
## Running Rancher in a highly available Kubernetes cluster
## Running Rancher in a highly available Kubernetes cluster
When you install Rancher inside of a Kubernetes cluster, TLS is offloaded at the cluster's ingress controller. The possible TLS settings depend on the used ingress controller:
When you install a Rancher managed Kubernetes cluster, TLS is offloaded at the cluster's ingress controller. Traefik is the default ingress for K3s and can be used with RKE2, refer to [TLS Options](https://doc.traefik.io/traefik/https/tls/#tls-options) for further information.
* nginx-ingress-controller (default for RKE1 and RKE2): [Default TLS Version and Ciphers](https://kubernetes.github.io/ingress-nginx/user-guide/tls/#default-tls-version-and-ciphers).
* traefik (default for K3s): [TLS Options](https://doc.traefik.io/traefik/https/tls/#tls-options).
@@ -284,21 +284,26 @@ In these cases, you have to explicitly allow this traffic in your host firewall,
When using the [AWS EC2 node driver](../../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-amazon-ec2-cluster.md) to provision cluster nodes in Rancher, you can choose to let Rancher create a security group called `rancher-nodes`. The following rules are automatically added to this security group.
When using the [AWS EC2 node driver](../../../how-to-guides/new-user-guides/launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/create-an-amazon-ec2-cluster.md) to provision cluster nodes in Rancher, you can choose to let Rancher create a security group called `rancher-nodes`. The following rules are automatically added to this security group.
| Type | Protocol | Port Range | Source/Destination | Rule Type |
| Type | Protocol | Port Range | Source/Destination | Rule Type |
@@ -42,7 +42,7 @@ If you will use ARM64 hosts, the registry must support manifests. As of April 20
1. Go to our [releases page,](https://github.com/rancher/rancher/releases) find the Rancher v2.x.x release that you want to install, and click **Assets**. Note: Don't use releases marked `rc` or `Pre-release`, as they are not stable for production environments.
1. Go to our [releases page,](https://github.com/rancher/rancher/releases) find the Rancher v2.x.x release that you want to install, and click **Assets**. Note: Don't use releases marked `rc` or `Pre-release`, as they are not stable for production environments.
2. From the release's **Assets** section, download the following files, which are required to install Rancher in an airgap environment:
2. From the release's **Assets** section, download the following files, which are required to install Rancher in an air-gap environment:
| Release File | Description |
| Release File | Description |
| ---------------- | -------------- |
| ---------------- | -------------- |
@@ -83,16 +83,39 @@ In a Kubernetes Install, if you elect to use the Rancher default self-signed TLS
### 3. Save the images to your workstation
### 3. Save the images to your workstation
1. Make `rancher-save-images.sh` an executable:
(Optional) Verify the image list before pulling:
```
```bash
wc -l rancher-images.txt
head rancher-images.txt
```
1. Make `rancher-save-images.sh` executable:
```bash
chmod +x rancher-save-images.sh
chmod +x rancher-save-images.sh
```
```
1. Run `rancher-save-images.sh` with the `rancher-images.txt` image list to create a tarball of all the required images:
1. Run `rancher-save-images.sh` with the `rancher-images.txt` image list to create a tarball of all the required images:
**Result:** Docker begins pulling the images used for an air gap install. Be patient. This process takes a few minutes. When the process completes, your current directory will output a tarball named `rancher-images.tar.gz`. Check that the output is in the directory.
(Optional) Specify a custom output file:
```bash
./rancher-save-images.sh \
--image-list ./rancher-images.txt \
--images rancher-images-custom.tar.gz
```
**Result:** Docker begins pulling the images required for an air-gap installation. The process may take several minutes.
1. Verify that the tarball was created:
```bash
ls -lh rancher-images.tar.gz
```
If some images fail to pull, review the output and retry after resolving any issues.
### 4. Populate the private registry
### 4. Populate the private registry
@@ -163,7 +186,7 @@ Your registry must support manifests. As of April 2020, Amazon Elastic Container
./rancher-save-images.ps1
./rancher-save-images.ps1
```
```
**Result:** Docker begins pulling the images used for an airgap install. Be patient. This process takes a few minutes. When the process completes, your current directory will output a tarball named `rancher-windows-images.tar.gz`. Check that the output is in the directory.
**Result:** Docker begins pulling the images used for an air-gap install. Be patient. This process takes a few minutes. When the process completes, your current directory will output a tarball named `rancher-windows-images.tar.gz`. Check that the output is in the directory.
<a name="windows-3"></a>
<a name="windows-3"></a>
@@ -273,7 +296,7 @@ The workstation must have Docker 18.02+ in order to support manifests, which are
**Result:** Docker begins pulling the images used for an airgap install. Be patient. This process takes a few minutes. When the process completes, your current directory will output a tarball named `rancher-images.tar.gz`. Check that the output is in the directory.
**Result:** Docker begins pulling the images used for an air-gap install. Be patient. This process takes a few minutes. When the process completes, your current directory will output a tarball named `rancher-images.tar.gz`. Check that the output is in the directory.
This section contains the requirements for Helm, which is the tool used to install Rancher on a high-availability Kubernetes cluster.
This section contains the requirements for Helm, which is the tool used to install Rancher on a high-availability Kubernetes cluster.
> The installation instructions have been updated for Helm 3. For migration of installs started with Helm 2, refer to the official [Helm 2 to 3 Migration Docs.](https://helm.sh/blog/migrate-from-helm-v2-to-helm-v3/) [This section](https://github.com/rancher/rancher-docs/tree/main/archived_docs/en/version-2.0-2.4/getting-started/installation-and-upgrade/advanced-options/advanced-use-cases/helm2/helm2.md) provides a copy of the older high-availability Rancher installation instructions that used Helm 2, and it is intended to be used if upgrading to Helm 3 is not feasible.
<DeprecationHelm2 />
## Identifying the Proper Helm v3 Version
## Identifying the Proper Helm v3 Version
Select any Helm v3 version that is officially compatible with the Kubernetes version range you are using from our [Rancher Support Matrix](https://www.suse.com/suse-rancher/support-matrix/all-supported-versions).
Select any Helm v3 version that is officially compatible with the Kubernetes version range you are using from our [Rancher Support Matrix](https://www.suse.com/suse-rancher/support-matrix/all-supported-versions).
@@ -31,5 +27,4 @@ To apply this rule, you may need to reference two external resources:
## Additional Notes
## Additional Notes
- Helm v3.2.x or higher is required to install or upgrade Rancher v2.5.
- Helm v3.2.x or higher is required to install or upgrade Rancher v2.5.
- Helm v2 support was removed in Rancher v2.9.x.
- When using tools that run Helm commands for you (like Terraform), you must make sure they are configured to use the correct Helm version.
- When using tools that run Helm commands for you (like Terraform), you must make sure they are configured to use the correct Helm version.
@@ -96,7 +96,8 @@ To enable draining each node during a cluster upgrade,
:::note
:::note
There is a [known issue](https://github.com/rancher/rancher/issues/25478) in which the Rancher UI doesn't show the state of etcd and controlplane as drained, even though they are being drained.
- There is a [known issue](https://github.com/rancher/rancher/issues/25478) in which the Rancher UI doesn't show the state of etcd and controlplane as drained, even though they are being drained.
- During an upgrade, nodes may be drained even when no user-visible YAML changes are present. This can occur if non-dynamic configuration files are updated or if a new `system-agent-installer` image is introduced. In such cases, Rancher generates a new upgrade plan, resulting in a new plan hash. When `Upgrade Strategy` is set to `Drain nodes`, this plan change can trigger node draining.
SUSE Rancher for AWS (SRA/SRFA) is a fully managed Software-as-a-Service (SaaS) offering available through the [AWS Marketplace](https://aws.amazon.com/marketplace/pp/prodview-yrzugbpzuukww). It provides a centralized control plane to manage, monitor, and scale Kubernetes clusters within an AWS environment.
For deployment prerequisites, architecture requirements, and subscription details, refer to the [AWS Marketplace listing](https://aws.amazon.com/marketplace/pp/prodview-yrzugbpzuukww). For more information, refer to the [product documentation](https://documentation.suse.com/cloudnative/rancher-srfa/).
:::note
SUSE Rancher for AWS is an offering distinct from deploying and managing the Rancher server manually on Amazon EKS. If you intend to install and manage your own Rancher deployment on an EKS cluster, refer to [Installing Rancher on Amazon EKS](../../installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-on-amazon-eks.md).
@@ -65,7 +65,7 @@ Log in to Rancher to begin using the application. After you log in, you'll make
Replace `<SERVER_IP>` with your host IP address.
Replace `<SERVER_IP>` with your host IP address.
2. When prompted, create a password for the default `admin` account there cowpoke!
2. When prompted, create a password for the default `admin` account.
3. Set the **Rancher Server URL**. The URL can either be an IP address or a host name. However, each node added to your cluster must be able to connect to this URL.<br/><br/>If you use a hostname in the URL, this hostname must be resolvable by DNS on the nodes you want to add to you cluster.
3. Set the **Rancher Server URL**. The URL can either be an IP address or a host name. However, each node added to your cluster must be able to connect to this URL.<br/><br/>If you use a hostname in the URL, this hostname must be resolvable by DNS on the nodes you want to add to you cluster.
@@ -97,7 +97,7 @@ You can access your cluster after its state is updated to **Active**.
**Active** clusters are assigned two Projects:
**Active** clusters are assigned two Projects:
- `Default`, containing the `default` namespace
- `Default`, containing the `default` namespace
- `System`, containing the `cattle-system`, `ingress-nginx`, `kube-public`, and `kube-system` namespaces
- `System`, containing the `cattle-system`, `traefik`, `kube-public`, and `kube-system` namespaces
@@ -16,11 +16,15 @@ For configuration details, refer to the [official Kubernetes documentation](http
<Tabs groupId="k8s-distro">
<Tabs groupId="k8s-distro">
<TabItem value="RKE2" default>
<TabItem value="RKE2" default>
### Method 1 (Recommended): Set `audit-policy-file` in `machineGlobalConfig`
### Method 1 (Recommended): Set `audit-policy-file` in `machineGlobalConfig` or `machineSelectorConfig`
You can set `audit-policy-file` in the configuration file. Rancher delivers the file to the path `/var/lib/rancher/rke2/etc/config-files/audit-policy-file` in control plane nodes, and sets the proper options in the RKE2 server.
You can set `audit-policy-file` in the configuration file using either `machineGlobalConfig` or `machineSelectorConfig`.
Example:
When using `machineGlobalConfig`, Rancher delivers the file to the path `/var/lib/rancher/rke2/etc/config-files/audit-policy-file` on **all nodes** (both control plane and worker nodes), and sets the proper options in the RKE2 server. This may cause unwanted worker node reconciliation when the audit policy is modified.
To avoid worker node reconciliation, use `machineSelectorConfig` with a label selector to target only control plane nodes. This ensures that the audit policy file is only delivered to control plane nodes.
Example using `machineGlobalConfig`:
```yaml
```yaml
apiVersion: provisioning.cattle.io/v1
apiVersion: provisioning.cattle.io/v1
kind: Cluster
kind: Cluster
@@ -38,6 +42,28 @@ spec:
- pods
- pods
```
```
Example using `machineSelectorConfig` (recommended to avoid worker node reconciliation):
```yaml
apiVersion: provisioning.cattle.io/v1
kind: Cluster
spec:
rkeConfig:
machineSelectorConfig:
- config:
audit-policy-file: |
apiVersion: audit.k8s.io/v1
kind: Policy
rules:
- level: RequestResponse
resources:
- group: ""
resources:
- pods
machineLabelSelector:
matchLabels:
rke.cattle.io/control-plane-role: 'true'
```
### Method 2: Use the Directives, `machineSelectorFiles` and `machineGlobalConfig`
### Method 2: Use the Directives, `machineSelectorFiles` and `machineGlobalConfig`
:::note
:::note
@@ -103,12 +129,6 @@ spec:
rke.cattle.io/control-plane-role: 'true'
rke.cattle.io/control-plane-role: 'true'
```
```
:::tip
You can also use the directive `machineSelectorConfig` with proper machineLabelSelectors to achieve the same effect.
:::
For more information about cluster configuration, refer to the [RKE2 cluster configuration reference](../../reference-guides/cluster-configuration/rancher-server-configuration/rke2-cluster-configuration.md) pages.
For more information about cluster configuration, refer to the [RKE2 cluster configuration reference](../../reference-guides/cluster-configuration/rancher-server-configuration/rke2-cluster-configuration.md) pages.
</TabItem>
</TabItem>
@@ -178,12 +198,6 @@ spec:
rke.cattle.io/control-plane-role: 'true'
rke.cattle.io/control-plane-role: 'true'
```
```
:::tip
You can also use the directive `machineSelectorConfig` with proper machineLabelSelectors to achieve the same effect.
:::
For more information about cluster configuration, refer to the [K3s cluster configuration reference](../../reference-guides/cluster-configuration/rancher-server-configuration/k3s-cluster-configuration.md) pages.
For more information about cluster configuration, refer to the [K3s cluster configuration reference](../../reference-guides/cluster-configuration/rancher-server-configuration/k3s-cluster-configuration.md) pages.
</TabItem>
</TabItem>
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.