Skip to content

replace nginx with traefik based documentation references #1109

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ibrokethecloud wants to merge 1 commit into
base: main
Choose a base branch
from
Open

replace nginx with traefik based documentation references #1109

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 25 additions & 1 deletion docs/advanced/settings.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.)

@jillian-maroket jillian-maroket Aug 20, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
### `ssl-parameters` Deprecated as of v1.9.0 (Use traefik-default-tls-options instead.)
### `ssl-parameters`
**Versions**: Deprecated as of v1.9.0 (Use `traefik-default-tls-options` instead.)

@jillian-maroket jillian-maroket Aug 20, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is how we present the deprecation info for vip-pools.


**Definition**: Enabled SSL/TLS protocols and ciphers of the Harvester UI and API.

Expand Down Expand Up @@ -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
Comment on lines +912 to +924

@jillian-maroket jillian-maroket Aug 20, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
:::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
**Versions**: v1.9.0 and later
**Definition**: Setting that applies default [TLS options](https://doc.traefik.io/traefik/reference/routing-configuration/http/tls/tls-options/) for the Traefik Ingress Controller.
:::info important
This setting replaces the `ssl-parameters` setting for the Ingress NGINX Controller (`ingress-nginx`).
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).
:::

@jillian-maroket jillian-maroket Aug 20, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The NGINX naming is confusing. There are two similarly named controllers.


**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.
Expand Down
4 changes: 2 additions & 2 deletions docs/image/upload-image.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -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:

Expand Down
8 changes: 4 additions & 4 deletions docs/install/requirements.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down Expand Up @@ -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) |
Expand Down
20 changes: 9 additions & 11 deletions docs/troubleshooting/harvester.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
80 changes: 47 additions & 33 deletions docs/troubleshooting/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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: <html>\r\n<head><title>502 Bad Gateway</title></head>\r\n<body>\r\n<center><h1>502 Bad Gateway</h1></center>\r\n<hr><center>nginx</center>\r\n</body>\r\n</html>\r\n"
msg="failed to bootstrap system, will retry: generating plan: response 502: 502 Bad Gateway getting cacerts: <html>\r\n<head><title>502 Bad Gateway</title></head>\r\n<body>\r\n<center><h1>502 Bad Gateway</h1></center>\r\n<hr>\r\n</body>\r\n</html>\r\n"
```

Note that the Rancher version and IP address depend on your environment and might differ from the message above.
Expand Down Expand Up @@ -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`

Expand All @@ -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
Expand Down Expand Up @@ -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:
Expand Down
Loading
Loading