From ae23294c3005f3b883b92be27529619cce8b407a Mon Sep 17 00:00:00 2001 From: Gaurav Mehta Date: Thu, 20 Aug 2026 13:43:10 +1000 Subject: [PATCH] update docs to deprecate nginx related settings and add new traefik backed settings Signed-off-by: Gaurav Mehta --- docs/advanced/settings.md | 26 ++++++++- docs/image/upload-image.md | 4 +- docs/install/requirements.md | 8 +-- docs/troubleshooting/harvester.md | 20 ++++--- docs/troubleshooting/installation.md | 80 ++++++++++++++++------------ docs/upgrade/automatic.md | 62 --------------------- 6 files changed, 87 insertions(+), 113 deletions(-) diff --git a/docs/advanced/settings.md b/docs/advanced/settings.md index 5e47c77cdb..445f2b011a 100644 --- a/docs/advanced/settings.md +++ b/docs/advanced/settings.md @@ -649,7 +649,7 @@ Changing this setting might cause single-node clusters to temporarily become una } ``` -### `ssl-parameters` +### `ssl-parameters` Deprecated as of v1.9.0 (Use traefik-default-tls-options instead.) **Definition**: Enabled SSL/TLS protocols and ciphers of the Harvester UI and API. @@ -907,6 +907,30 @@ When generating a support bundle, Harvester creates a ZIP file with the naming f The value can be set through environment variables and is used to help identify support bundles from specific clusters or environments. +### `traefik-default-tls-options` + +:::info important + +Replaces `ssl-parameters` setting applicable for nginx ingress controller. + +If you misconfigure this setting and are unable to access the Harvester UI and API, see [Troubleshooting](../troubleshooting/harvester.md#i-cant-access-harvester-after-i-changed-ssltls-enabled-protocols-and-ciphers). + +::: + +`ssl-parameters` + +**Versions**: v1.9.0 and later + +**Definition**: Setting that applies default [TLSOptions](https://doc.traefik.io/traefik/reference/routing-configuration/http/tls/tls-options/) for traefik ingress controller + +**Default value**: ``{"minVersion":"VersionTLS12", "maxVersion":"VersionTLS13", "sniStrict":false,"cipherSuites":[],"clientAuth":{"secretNames":[],"clientAuthType":""}}`` + +**Example**: + +``` +`{"minVersion":"VersionTLS12", "maxVersion":"VersionTLS13", "sniStrict":true,"cipherSuites":["TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256"],"clientAuth":{"secretNames":[],"clientAuthType":""}}` +``` + ### `upgrade-checker-enabled` **Definition**: Setting that automatically checks for available Harvester upgrades. diff --git a/docs/image/upload-image.md b/docs/image/upload-image.md index ee3fe3207f..26a05532fe 100644 --- a/docs/image/upload-image.md +++ b/docs/image/upload-image.md @@ -117,7 +117,7 @@ You can upload images from the [**Multi-Cluster Management**](../rancher/virtual The maximum request body size should be specific to the cluster that is hosting Rancher (for example, RKE2 clusters have a default limit of 1 MB but no such limit exists in K3s clusters). -The current workaround is to upload images from the **Harvester UI**. If you choose to upload images from the Rancher UI, you may need to configure related settings on the ingress server (for example, [`proxy-body-size`](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#custom-max-body-size) in NGINX). +The current workaround is to upload images from the **Harvester UI**. If you choose to upload images from the Rancher UI, you may need to configure related settings on the ingress server (for example, [`transport.respondingTimeouts.readTimeout`](https://doc.traefik.io/traefik/reference/install-configuration/entrypoints/#opt-transport-respondingTimeouts-readTimeout) in Traefik). The current default is 30m. If Rancher is deployed on an RKE2 cluster, perform the following steps: @@ -140,7 +140,7 @@ If you upload a very large image (over 10 GB) from the **Multi-Cluster Managemen This behavior is related to *proxy-request-buffering* in the ingress configuration, which is also specific to the cluster that is hosting Rancher. -The current workaround is to upload images from the **Harvester UI**. If you choose to upload images from the Rancher UI, you may need to configure related settings on the ingress server (for example, [`proxy-request-buffering`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_request_buffering) in NGINX). +The current workaround is to upload images from the **Harvester UI**. If you choose to upload images from the Rancher UI, you may need to configure related settings on the ingress server (for example, [`transport.respondingTimeouts.readTimeout`](https://doc.traefik.io/traefik/reference/install-configuration/entrypoints/#opt-transport-respondingTimeouts-readTimeout) in Traefik). The current default is 30m. If Rancher is deployed on an RKE2 cluster, perform the following steps: diff --git a/docs/install/requirements.md b/docs/install/requirements.md index d993808970..5455c16cbb 100644 --- a/docs/install/requirements.md +++ b/docs/install/requirements.md @@ -67,8 +67,8 @@ Ports that bind only to `127.0.0.1` are accessible from localhost only and do no | Protocol | Port | Bind Address | Source | Description | |:---------|:-----|:-------------|:-------|:------------| | TCP | 22 | `0.0.0.0` | All | SSH | -| TCP | 80 | `0.0.0.0` | All | Harvester UI HTTP (nginx proxy) | -| TCP | 443 | `0.0.0.0` | All | Harvester UI HTTPS (nginx proxy) | +| TCP | 80 | `0.0.0.0` | All | Harvester UI HTTP (traefik proxy) | +| TCP | 443 | `0.0.0.0` | All | Harvester UI HTTPS (traefik proxy) | | TCP | 2112 | `0.0.0.0` | All | kube-vip Prometheus metrics | | TCP | 2379 | `127.0.0.1`, node IP | Harvester management nodes | etcd client port | | TCP | 2380 | `127.0.0.1`, node IP | Harvester management nodes | etcd peer port | @@ -96,8 +96,8 @@ Ports that bind only to `127.0.0.1` are accessible from localhost only and do no | Protocol | Port | Bind Address | Source | Description | |:---------|:-----|:-------------|:-------|:------------| | TCP | 22 | `0.0.0.0` | All | SSH | -| TCP | 80 | `0.0.0.0` | All | Harvester UI HTTP (nginx proxy) | -| TCP | 443 | `0.0.0.0` | All | Harvester UI HTTPS (nginx proxy) | +| TCP | 80 | `0.0.0.0` | All | Harvester UI HTTP (traefik proxy) | +| TCP | 443 | `0.0.0.0` | All | Harvester UI HTTPS (traefik proxy) | | TCP | 6443 | `127.0.0.1`, `[::1]` | localhost | Kubernetes API server (RKE2 agent proxy) | | TCP | 6444 | `127.0.0.1`, `[::1]` | localhost | RKE2 agent API proxy | | TCP | 9091 | `0.0.0.0` | All | calico-node metrics (Prometheus) | diff --git a/docs/troubleshooting/harvester.md b/docs/troubleshooting/harvester.md index 1f7fbda934..d846878779 100644 --- a/docs/troubleshooting/harvester.md +++ b/docs/troubleshooting/harvester.md @@ -337,36 +337,34 @@ For Rancher's multi-cluster and multi-tenant integration, please refer to the do ## I can't access Harvester after I changed SSL/TLS enabled protocols and ciphers If you changed -[SSL/TLS enabled protocols and ciphers settings](../advanced/settings.md#ssl-parameters) +[SSL/TLS enabled protocols and ciphers settings](../advanced/settings.md#traefik-default-tls-options) and you no longer have access to Harvester GUI and API, -it's highly possible that NGINX Ingress Controller has stopped working due to the misconfigured SSL/TLS protocols and ciphers. +it's highly possible that Treafik Ingress Controller has stopped working due to the misconfigured SSL/TLS protocols and ciphers. Follow these steps to reset the setting: 1. Following [FAQ](../faq.md) to SSH into Harvester node and switch to `root` user. ``` $ sudo -s ``` -2. Editing setting `ssl-parameters` manually using `kubectl`: +2. Editing setting `traefik-default-tls-options` manually using `kubectl`: ``` -# kubectl edit settings ssl-parameters +# kubectl edit settings.harvester traefik-default-tls-options ``` -3. Deleting the line `value: ...` so that NGINX Ingress Controller +3. Deleting the line `value: ...` so that Traefik Ingress Controller will use the default protocols and ciphers. ``` apiVersion: harvesterhci.io/v1beta1 -default: '{}' +default: '{"minVersion":"VersionTLS12", "maxVersion":"VersionTLS13", "sniStrict":false,"cipherSuites":[],"clientAuth":{"secretNames":[],"clientAuthType":""}}' kind: Setting -metadata: - name: ssl-parameters ... -value: '{"protocols":"TLS99","ciphers":"WRONG_CIPHER"}' # <- Delete this line +value: '{"minVersion":"VersionTLS12", "maxVersion":"VersionTLS13", "sniStrict":true,"cipherSuites":["TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256"],"clientAuth":{"secretNames":[],"clientAuthType":""}}' # <- Delete this line ``` 4. Save the change and you should see the following response after exit from the editor: ``` -setting.harvesterhci.io/ssl-parameters edited +setting.harvesterhci.io/traefik-default-tls-options edited ``` -You can further check the logs of Pod `rke2-ingress-nginx-controller` to see if NGINX Ingress Controller is working correctly. +You can further check the logs of Pod `rke2-traefik` to see if Traefik Ingress Controller is working correctly. ## Network interfaces are not showing up diff --git a/docs/troubleshooting/installation.md b/docs/troubleshooting/installation.md index ae3315ea20..e4e4ec0a8c 100644 --- a/docs/troubleshooting/installation.md +++ b/docs/troubleshooting/installation.md @@ -49,7 +49,7 @@ If the cluster token setup in the agent node is not matching the server node tok ```shell msg="Bootstrapping Rancher (v2.7.5/v1.25.9+rke2r1)" -msg="failed to bootstrap system, will retry: generating plan: response 502: 502 Bad Gateway getting cacerts: \r\n502 Bad Gateway\r\n\r\n

502 Bad Gateway

\r\n
nginx
\r\n\r\n\r\n" +msg="failed to bootstrap system, will retry: generating plan: response 502: 502 Bad Gateway getting cacerts: \r\n502 Bad Gateway\r\n\r\n

502 Bad Gateway

\r\n
\r\n\r\n\r\n" ``` Note that the Rancher version and IP address depend on your environment and might differ from the message above. @@ -168,7 +168,7 @@ Harvester uses the following chart CRDs: - `rke2-runtimeclasses` - `rke2-multus` - `rke2-metrics-server` - - `rke2-ingress-nginx` + - `rke2-traefik` - `rke2-coredns` - `rke2-cannal` @@ -185,25 +185,26 @@ You can use the `helm list -A` command to retrieve a list of installed charts. Example of output: ```shell -NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION -fleet cattle-fleet-system 4 2025-09-24 09:07:10.801764068 +0000 UTC deployed fleet-107.0.0+up0.13.0 0.13.0 -fleet-agent-local cattle-fleet-local-system 1 2025-09-24 08:59:28.686781982 +0000 UTC deployed fleet-agent-local-v0.0.0+s-d4f65a6f642cca930c78e6e2f0d3f9bbb7d3ba47cf1cce34ac3d6b8770ce5 -fleet-crd cattle-fleet-system 1 2025-09-24 08:58:28.396419747 +0000 UTC deployed fleet-crd-107.0.0+up0.13.0 0.13.0 -harvester harvester-system 1 2025-09-24 08:59:37.718646669 +0000 UTC deployed harvester-0.0.0-master-ac070598 master-ac070598 -harvester-crd harvester-system 1 2025-09-24 08:59:35.341316526 +0000 UTC deployed harvester-crd-0.0.0-master-ac070598 master-ac070598 -kubeovn-operator-crd kube-system 1 2025-09-24 08:59:34.783356576 +0000 UTC deployed kubeovn-operator-crd-1.13.13 v1.13.13 -mcc-local-managed-system-upgrade-controller cattle-system 1 2025-09-24 08:59:10.656784284 +0000 UTC deployed system-upgrade-controller-107.0.0 v0.16.0 -rancher cattle-system 1 2025-09-24 08:57:20.690330683 +0000 UTC deployed rancher-2.12.0 8815e66-dirty -rancher-logging-crd cattle-logging-system 1 2025-09-24 08:59:36.262080367 +0000 UTC deployed rancher-logging-crd-107.0.1+up4.10.0-rancher.10 -rancher-monitoring-crd cattle-monitoring-system 1 2025-09-24 08:59:35.287099045 +0000 UTC deployed rancher-monitoring-crd-107.1.0+up69.8.2-rancher.15 -rancher-provisioning-capi cattle-provisioning-capi-system 1 2025-09-24 08:59:00.561162307 +0000 UTC deployed rancher-provisioning-capi-107.0.0+up0.8.0 1.10.2 -rancher-webhook cattle-system 2 2025-09-24 09:02:38.774660489 +0000 UTC deployed rancher-webhook-107.0.0+up0.8.0 0.8.0 -rke2-canal kube-system 1 2025-09-24 08:57:25.248839867 +0000 UTC deployed rke2-canal-v3.30.2-build2025071100 v3.30.2 -rke2-coredns kube-system 1 2025-09-24 08:57:25.341016864 +0000 UTC deployed rke2-coredns-1.42.302 1.12.2 -rke2-ingress-nginx kube-system 3 2025-09-24 09:01:31.331647555 +0000 UTC deployed rke2-ingress-nginx-4.12.401 1.12.4 -rke2-metrics-server kube-system 1 2025-09-24 08:57:42.162046899 +0000 UTC deployed rke2-metrics-server-3.12.203 0.7.2 -rke2-multus kube-system 1 2025-09-24 08:57:25.341560394 +0000 UTC deployed rke2-multus-v4.2.106 4.2.1 -rke2-runtimeclasses kube-system 1 2025-09-24 08:57:40.137168056 +0000 UTC deployed rke2-runtimeclasses-0.1.000 0.1.0 +NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION +fleet cattle-fleet-system 7 2026-08-19 04:27:43.255592759 +0000 UTC deployed fleet-110.0.0+up0.16.0 0.16.0 +fleet-agent-local cattle-fleet-local-system 1 2026-08-19 03:55:07.87234703 +0000 UTC deployed fleet-agent-local-v0.0.0+s-8485a5dc16708bb7c6c863f3d8b5710a8fba51dfddb8712ac22b4c69b6fca +fleet-crd cattle-fleet-system 1 2026-08-19 03:54:40.436201083 +0000 UTC deployed fleet-crd-110.0.0+up0.16.0 0.16.0 +harvester harvester-system 1 2026-08-19 03:56:15.415558184 +0000 UTC deployed harvester-0.0.0-master-5f26ee4b-dirty master-5f26ee4b-dirty +harvester-crd harvester-system 1 2026-08-19 03:55:55.981360295 +0000 UTC deployed harvester-crd-0.0.0-master-5f26ee4b-dirty master-5f26ee4b-dirty +kubeovn-operator-crd kube-system 1 2026-08-19 03:55:53.905562097 +0000 UTC deployed kubeovn-operator-crd-1.16.2-dev.0 v1.16.2-dev.0 +mcc-local-managed-system-upgrade-controller cattle-system 2 2026-08-19 03:56:25.679669008 +0000 UTC deployed system-upgrade-controller-110.0.0 v0.20.1 +rancher cattle-system 1 2026-08-19 03:52:32.850730397 +0000 UTC deployed rancher-2.15.0 9994cd9-dirty +rancher-logging-crd cattle-logging-system 1 2026-08-19 03:56:02.878958079 +0000 UTC deployed rancher-logging-crd-109.0.0+up4.10.0-rancher.23 +rancher-monitoring-crd cattle-monitoring-system 1 2026-08-19 03:55:54.297017024 +0000 UTC deployed rancher-monitoring-crd-109.0.3+up80.9.1-rancher.14 +rancher-turtles cattle-turtles-system 2 2026-08-19 03:57:06.91719977 +0000 UTC deployed rancher-turtles-110.0.0+up0.27.0 0.27.0 +rancher-webhook cattle-system 2 2026-08-19 03:56:34.680194227 +0000 UTC deployed rancher-webhook-110.0.0+up0.11.0 0.11.0 +rke2-canal kube-system 1 2026-08-19 03:52:38.934327727 +0000 UTC deployed rke2-canal-v3.32.1-build2026072200 v3.32.1 +rke2-coredns kube-system 1 2026-08-19 03:52:39.185411951 +0000 UTC deployed rke2-coredns-1.46.201 1.13.1 +rke2-metrics-server kube-system 1 2026-08-19 03:53:06.805134402 +0000 UTC deployed rke2-metrics-server-3.13.105 0.8.1 +rke2-multus kube-system 1 2026-08-19 03:53:04.854508241 +0000 UTC deployed rke2-multus-v4.3.008 4.3.0 +rke2-runtimeclasses kube-system 1 2026-08-19 03:53:07.436814679 +0000 UTC deployed rke2-runtimeclasses-0.1.000 0.1.0 +rke2-traefik kube-system 2 2026-08-19 03:55:56.389203275 +0000 UTC deployed rke2-traefik-40.1.009 v3.7.1 +rke2-traefik-crd kube-system 1 2026-08-19 03:53:06.682741753 +0000 UTC deployed rke2-traefik-crd-40.1.009 v3.7.1 0.1.0 ``` ### HelmChart CRD @@ -244,56 +245,69 @@ Status: JobName: helm-install-rke2-coredns Namespace: kube-system -Name: rke2-ingress-nginx +Name: rke2-metrics-server Status: - Type: JobCreated Status: True Reason: Job created - Message: Applying HelmChart using Job kube-system/helm-install-rke2-ingress-nginx + Message: Applying HelmChart using Job kube-system/helm-install-rke2-metrics-server - Type: Failed Status: False Reason: Message: -JobName: helm-install-rke2-ingress-nginx +JobName: helm-install-rke2-metrics-server Namespace: kube-system -Name: rke2-metrics-server +Name: rke2-multus Status: - Type: JobCreated Status: True Reason: Job created - Message: Applying HelmChart using Job kube-system/helm-install-rke2-metrics-server + Message: Applying HelmChart using Job kube-system/helm-install-rke2-multus - Type: Failed Status: False Reason: Message: -JobName: helm-install-rke2-metrics-server +JobName: helm-install-rke2-multus Namespace: kube-system -Name: rke2-multus +Name: rke2-runtimeclasses Status: - Type: JobCreated Status: True Reason: Job created - Message: Applying HelmChart using Job kube-system/helm-install-rke2-multus + Message: Applying HelmChart using Job kube-system/helm-install-rke2-runtimeclasses - Type: Failed Status: False Reason: Message: -JobName: helm-install-rke2-multus +JobName: helm-install-rke2-runtimeclasses Namespace: kube-system -Name: rke2-runtimeclasses +Name: rke2-traefik Status: - Type: JobCreated Status: True Reason: Job created - Message: Applying HelmChart using Job kube-system/helm-install-rke2-runtimeclasses + Message: Applying HelmChart using Job kube-system/helm-install-rke2-traefik - Type: Failed Status: False Reason: Message: -JobName: helm-install-rke2-runtimeclasses +JobName: helm-install-rke2-traefik + +Namespace: kube-system +Name: rke2-traefik-crd +Status: + - Type: JobCreated + Status: True + Reason: Job created + Message: Applying HelmChart using Job kube-system/helm-install-rke2-traefik-crd + - Type: Failed + Status: False + Reason: + Message: +JobName: helm-install-rke2-traefik-crd ``` You can use the information in the following ways: diff --git a/docs/upgrade/automatic.md b/docs/upgrade/automatic.md index 29a2bb5d5f..9667492669 100644 --- a/docs/upgrade/automatic.md +++ b/docs/upgrade/automatic.md @@ -535,68 +535,6 @@ To prevent the issue from occurring, ensure that the `EvictionRequested` flag is ::: -## Re-enable RKE2 ingress-nginx Admission Webhooks (CVE-2025-1974) - -If you [disabled the RKE2 ingress-nginx admission webhooks](https://harvesterhci.io/kb/2025/03/25/cve-2025-1974) to mitigate [CVE-2025-1974](https://nvd.nist.gov/vuln/detail/CVE-2025-1974), you must re-enable the webhook after upgrading to Harvester v1.5.0 or later. - -1. Confirm that Harvester is using nginx-ingress v1.12.1 or later. - - ```sh - $ kubectl -n kube-system get po -l"app.kubernetes.io/name=rke2-ingress-nginx" -ojsonpath='{.items[].spec.containers[].image}' - rancher/nginx-ingress-controller:v1.12.1-hardened1 - ``` - -1. Run `kubectl -n kube-system edit helmchartconfig rke2-ingress-nginx` to **remove** the following configurations from the `HelmChartConfig` resource. - - * `.spec.valuesContent.controller.admissionWebhooks.enabled: false` - * `.spec.valuesContent.controller.extraArgs.enable-annotation-validation: true` - -1. Verify that the new `.spec.ValuesContent` configuration is similar to the following example. - - ```yaml - apiVersion: helm.cattle.io/v1 - kind: HelmChartConfig - metadata: - name: rke2-ingress-nginx - namespace: kube-system - spec: - valuesContent: |- - controller: - admissionWebhooks: - port: 8444 - extraArgs: - default-ssl-certificate: cattle-system/tls-rancher-internal - config: - proxy-body-size: "0" - proxy-request-buffering: "off" - publishService: - pathOverride: kube-system/ingress-expose - ``` - - :::info important - If the `HelmChartConfig` resource contains other custom ingress-nginx configuration, you must retain them when editing the resource. - ::: - -1. Exit the `kubectl edit` command execution to save the configuration. - - Harvester automatically applies the change once the content is saved. - -1. Verify that the `rke2-ingress-nginx-admission` webhook configuration is re-enabled. - - ```sh - $ kubectl get validatingwebhookconfiguration rke2-ingress-nginx-admission - NAME WEBHOOKS AGE - rke2-ingress-nginx-admission 1 6s - ``` - -1. Verify that the ingress-nginx pods are restarted successfully. - - ```sh - kubectl -n kube-system get po -lapp.kubernetes.io/instance=rke2-ingress-nginx - NAME READY STATUS RESTARTS AGE - rke2-ingress-nginx-controller-l2cxz 1/1 Running 0 94s - ``` - ## Upgrade is Stuck in the "Pre-drained" State The upgrade process may become stuck in the "Pre-drained" state. Kubernetes is supposed to drain the workload on the node, but some factors may cause the process to stall.