From 715c942c1b2f0efae476dc5c3a2338c867c45c36 Mon Sep 17 00:00:00 2001 From: Dan Pock Date: Tue, 20 Jan 2026 10:49:36 -0500 Subject: [PATCH 1/3] Add advanced docs for External Gateway usage via Gateway API --- .../configure-with-existing-gateway.md | 268 ++++++++++++++++++ .../rancher-deployment-guides.md | 10 + 2 files changed, 278 insertions(+) create mode 100644 docs/how-to-guides/advanced-user-guides/rancher-deployment-guides/configure-with-existing-gateway.md create mode 100644 docs/how-to-guides/advanced-user-guides/rancher-deployment-guides/rancher-deployment-guides.md diff --git a/docs/how-to-guides/advanced-user-guides/rancher-deployment-guides/configure-with-existing-gateway.md b/docs/how-to-guides/advanced-user-guides/rancher-deployment-guides/configure-with-existing-gateway.md new file mode 100644 index 00000000000..68fce21e8ad --- /dev/null +++ b/docs/how-to-guides/advanced-user-guides/rancher-deployment-guides/configure-with-existing-gateway.md @@ -0,0 +1,268 @@ +--- +title: Using an External Gateway with Rancher +--- + + + + + +## Using an External Gateway with Rancher + +When using the Gateway API network exposure type, Rancher can create and manage its own Gateway resource. However, if you have an existing Gateway that you manage independently (for example, a shared Gateway used by multiple applications), you will need to create your own HTTPRoute resources to route traffic to Rancher. + +This section covers how to create the required HTTPRoute resources manually when using an externally managed Gateway. + +### Prerequisites + +- An existing Gateway resource configured and operational in your cluster +- Knowledge of your Gateway's: + - Name and namespace + - Listener names (sectionName) for HTTP and/or HTTPS traffic +- Rancher installed with `networkExposure.type` set to something other than `gateway` (e.g., `none` or `ingress`) + +### Cross-Namespace Gateway Requirements + +If your Gateway is in a different namespace than Rancher (e.g., Gateway in `gateway-system`, Rancher in `cattle-system`), the Gateway must be configured to accept HTTPRoutes from the Rancher namespace. By default, Gateway API only allows routes from the same namespace as the Gateway. + +The Gateway owner must configure `allowedRoutes` on the relevant listeners. There are two options: + +**Option 1: Allow routes from all namespaces** + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: Gateway +metadata: + name: shared-gateway + namespace: gateway-system +spec: + gatewayClassName: example + listeners: + - name: https + port: 443 + protocol: HTTPS + allowedRoutes: + namespaces: + from: All + - name: http + port: 80 + protocol: HTTP + allowedRoutes: + namespaces: + from: All +``` + +**Option 2: Allow routes from specific namespaces (more restrictive)** + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: Gateway +metadata: + name: shared-gateway + namespace: gateway-system +spec: + gatewayClassName: example + listeners: + - name: https + port: 443 + protocol: HTTPS + allowedRoutes: + namespaces: + from: Selector + selector: + matchLabels: + shared-gateway-access: "true" + - name: http + port: 80 + protocol: HTTP + allowedRoutes: + namespaces: + from: Selector + selector: + matchLabels: + shared-gateway-access: "true" +``` + +When using the selector approach, ensure the Rancher namespace has the required label: + +```bash +kubectl label namespace cattle-system shared-gateway-access=true +``` + +> **Note:** If the Gateway and Rancher are in the same namespace, no additional configuration is needed—the default `allowedRoutes` setting (`from: Same`) will permit the HTTPRoute attachment. + +### Determining Your Rancher Service Values + +Before creating HTTPRoute resources, identify the following values from your Rancher installation: + +| Value | How to Determine | Example | +|-------|------------------|---------| +| **Release Name** | The name used in `helm install ` | `rancher` | +| **Namespace** | The namespace where Rancher is installed | `cattle-system` | +| **Hostname** | The `hostname` value from your Helm values | `rancher.example.com` | +| **TLS Mode** | The `tls` value from your Helm values | `ingress`, `external`, or `secret` | +| **Service HTTP Disabled** | The `service.disableHTTP` value | `true` or `false` | + +The Rancher service name follows the pattern: `-rancher` (or just `` if the release name already contains "rancher"). + +### HTTPRoute Configuration + +#### Primary HTTPRoute + +Create an HTTPRoute to direct traffic from your Gateway to the Rancher service. The configuration depends on your TLS setup: + +**When TLS terminates at the Gateway or within Kubernetes (`tls: ingress`, `tls: secret`, or `tls: letsEncrypt`):** + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + name: rancher + namespace: cattle-system # Must match Rancher's namespace +spec: + parentRefs: + - name: + namespace: + sectionName: # Your Gateway's HTTPS listener + hostnames: + - # e.g., rancher.example.com + rules: + - matches: + - path: + type: PathPrefix + value: / + backendRefs: + - name: rancher # Your Rancher service name + port: 80 # Use 443 if service.disableHTTP=true +``` + +**When TLS terminates externally (`tls: external`):** + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + name: rancher + namespace: cattle-system +spec: + parentRefs: + - name: + namespace: + sectionName: # Your Gateway's HTTP listener + hostnames: + - + rules: + - matches: + - path: + type: PathPrefix + value: / + backendRefs: + - name: rancher + port: 80 +``` + +#### HTTP to HTTPS Redirect Route (Optional) + +If TLS terminates at or within Kubernetes (not externally), you may want to redirect HTTP traffic to HTTPS. Create an additional HTTPRoute: + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + name: rancher-http-redirect + namespace: cattle-system +spec: + parentRefs: + - name: + namespace: + sectionName: # Your Gateway's HTTP listener + hostnames: + - + rules: + - filters: + - type: RequestRedirect + requestRedirect: + scheme: https + statusCode: 301 +``` + +### Using extraObjects + +You can include these HTTPRoute resources directly in your Rancher Helm installation using the `extraObjects` value. This keeps all resources managed together: + +```yaml +# values.yaml +hostname: rancher.example.com +tls: ingress + +extraObjects: + - apiVersion: gateway.networking.k8s.io/v1 + kind: HTTPRoute + metadata: + name: rancher + spec: + parentRefs: + - name: my-shared-gateway + namespace: gateway-system + sectionName: https + hostnames: + - rancher.example.com + rules: + - matches: + - path: + type: PathPrefix + value: / + backendRefs: + - name: rancher + port: 80 + + - apiVersion: gateway.networking.k8s.io/v1 + kind: HTTPRoute + metadata: + name: rancher-http-redirect + spec: + parentRefs: + - name: my-shared-gateway + namespace: gateway-system + sectionName: http + hostnames: + - rancher.example.com + rules: + - filters: + - type: RequestRedirect + requestRedirect: + scheme: https + statusCode: 301 +``` + +### Backend Port Selection + +The port in `backendRefs` depends on your `service.disableHTTP` setting: + +| `service.disableHTTP` | Backend Port | +|-----------------------|--------------| +| `false` (default) | `80` | +| `true` | `443` | + +### Listener Selection Summary + +| TLS Configuration | Primary Route Listener | Redirect Route | +|-------------------|------------------------|----------------| +| `tls: external` | HTTP listener | Not needed | +| `tls: ingress` | HTTPS listener | HTTP listener (optional) | +| `tls: secret` | HTTPS listener | HTTP listener (optional) | +| `tls: letsEncrypt`| HTTPS listener | HTTP listener (optional) | + +### Troubleshooting + +**HTTPRoute not being accepted:** +- Verify the Gateway name and namespace are correct +- Ensure the `sectionName` matches an existing listener on your Gateway +- Check that the listener allows routes from the Rancher namespace (see Gateway's `allowedRoutes` configuration) + +**Connection refused or timeouts:** +- Confirm the Rancher service exists and has endpoints: `kubectl get endpoints rancher -n cattle-system` +- Verify the backend port matches your `service.disableHTTP` setting + +**Certificate errors:** +- If using `tls: ingress` or `tls: secret`, ensure your Gateway's HTTPS listener has the appropriate certificate configured +- Verify the certificate covers your Rancher hostname diff --git a/docs/how-to-guides/advanced-user-guides/rancher-deployment-guides/rancher-deployment-guides.md b/docs/how-to-guides/advanced-user-guides/rancher-deployment-guides/rancher-deployment-guides.md new file mode 100644 index 00000000000..3204dced2e4 --- /dev/null +++ b/docs/how-to-guides/advanced-user-guides/rancher-deployment-guides/rancher-deployment-guides.md @@ -0,0 +1,10 @@ +--- +title: Rancher Deployment Guides +--- + + + + + +- [Using an External Gateway with Rancher](configure-with-existing-gateway.md) + From e33daa65dd3c653fd38a897a20c562ce7511a2b1 Mon Sep 17 00:00:00 2001 From: Petr Kovar Date: Tue, 24 Mar 2026 17:59:04 +0100 Subject: [PATCH 2/3] Update sidebars.js --- sidebars.js | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/sidebars.js b/sidebars.js index 42d8eea20e0..2c61eb0bc0d 100644 --- a/sidebars.js +++ b/sidebars.js @@ -649,6 +649,17 @@ const sidebars = { id: "how-to-guides/advanced-user-guides/advanced-user-guides", }, items: [ + { + type: "category", + label: "Rancher Deployment Guides", + link: { + type: "doc", + id: "how-to-guides/advanced-user-guides/rancher-deployment-guides", + }, + items: [ + "how-to-guides/advanced-user-guides/rancher-deployment-guides/configure-with-existing-gateway", + ], + }, { type: "category", label: "Project Administration", From a82a5207c80294f8de5ea27815dec677f2a7c0a0 Mon Sep 17 00:00:00 2001 From: Petr Kovar Date: Tue, 24 Mar 2026 18:14:13 +0100 Subject: [PATCH 3/3] Backport to version-2.14 --- sidebars.js | 2 +- .../configure-with-existing-gateway.md | 268 ++++++++++++++++++ .../rancher-deployment-guides.md | 10 + versioned_sidebars/version-2.14-sidebars.json | 11 + 4 files changed, 290 insertions(+), 1 deletion(-) create mode 100644 versioned_docs/version-2.14/how-to-guides/advanced-user-guides/rancher-deployment-guides/configure-with-existing-gateway.md create mode 100644 versioned_docs/version-2.14/how-to-guides/advanced-user-guides/rancher-deployment-guides/rancher-deployment-guides.md diff --git a/sidebars.js b/sidebars.js index 2c61eb0bc0d..1b4841190f9 100644 --- a/sidebars.js +++ b/sidebars.js @@ -654,7 +654,7 @@ const sidebars = { label: "Rancher Deployment Guides", link: { type: "doc", - id: "how-to-guides/advanced-user-guides/rancher-deployment-guides", + id: "how-to-guides/advanced-user-guides/rancher-deployment-guides/rancher-deployment-guides", }, items: [ "how-to-guides/advanced-user-guides/rancher-deployment-guides/configure-with-existing-gateway", diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/rancher-deployment-guides/configure-with-existing-gateway.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/rancher-deployment-guides/configure-with-existing-gateway.md new file mode 100644 index 00000000000..68fce21e8ad --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/rancher-deployment-guides/configure-with-existing-gateway.md @@ -0,0 +1,268 @@ +--- +title: Using an External Gateway with Rancher +--- + + + + + +## Using an External Gateway with Rancher + +When using the Gateway API network exposure type, Rancher can create and manage its own Gateway resource. However, if you have an existing Gateway that you manage independently (for example, a shared Gateway used by multiple applications), you will need to create your own HTTPRoute resources to route traffic to Rancher. + +This section covers how to create the required HTTPRoute resources manually when using an externally managed Gateway. + +### Prerequisites + +- An existing Gateway resource configured and operational in your cluster +- Knowledge of your Gateway's: + - Name and namespace + - Listener names (sectionName) for HTTP and/or HTTPS traffic +- Rancher installed with `networkExposure.type` set to something other than `gateway` (e.g., `none` or `ingress`) + +### Cross-Namespace Gateway Requirements + +If your Gateway is in a different namespace than Rancher (e.g., Gateway in `gateway-system`, Rancher in `cattle-system`), the Gateway must be configured to accept HTTPRoutes from the Rancher namespace. By default, Gateway API only allows routes from the same namespace as the Gateway. + +The Gateway owner must configure `allowedRoutes` on the relevant listeners. There are two options: + +**Option 1: Allow routes from all namespaces** + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: Gateway +metadata: + name: shared-gateway + namespace: gateway-system +spec: + gatewayClassName: example + listeners: + - name: https + port: 443 + protocol: HTTPS + allowedRoutes: + namespaces: + from: All + - name: http + port: 80 + protocol: HTTP + allowedRoutes: + namespaces: + from: All +``` + +**Option 2: Allow routes from specific namespaces (more restrictive)** + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: Gateway +metadata: + name: shared-gateway + namespace: gateway-system +spec: + gatewayClassName: example + listeners: + - name: https + port: 443 + protocol: HTTPS + allowedRoutes: + namespaces: + from: Selector + selector: + matchLabels: + shared-gateway-access: "true" + - name: http + port: 80 + protocol: HTTP + allowedRoutes: + namespaces: + from: Selector + selector: + matchLabels: + shared-gateway-access: "true" +``` + +When using the selector approach, ensure the Rancher namespace has the required label: + +```bash +kubectl label namespace cattle-system shared-gateway-access=true +``` + +> **Note:** If the Gateway and Rancher are in the same namespace, no additional configuration is needed—the default `allowedRoutes` setting (`from: Same`) will permit the HTTPRoute attachment. + +### Determining Your Rancher Service Values + +Before creating HTTPRoute resources, identify the following values from your Rancher installation: + +| Value | How to Determine | Example | +|-------|------------------|---------| +| **Release Name** | The name used in `helm install ` | `rancher` | +| **Namespace** | The namespace where Rancher is installed | `cattle-system` | +| **Hostname** | The `hostname` value from your Helm values | `rancher.example.com` | +| **TLS Mode** | The `tls` value from your Helm values | `ingress`, `external`, or `secret` | +| **Service HTTP Disabled** | The `service.disableHTTP` value | `true` or `false` | + +The Rancher service name follows the pattern: `-rancher` (or just `` if the release name already contains "rancher"). + +### HTTPRoute Configuration + +#### Primary HTTPRoute + +Create an HTTPRoute to direct traffic from your Gateway to the Rancher service. The configuration depends on your TLS setup: + +**When TLS terminates at the Gateway or within Kubernetes (`tls: ingress`, `tls: secret`, or `tls: letsEncrypt`):** + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + name: rancher + namespace: cattle-system # Must match Rancher's namespace +spec: + parentRefs: + - name: + namespace: + sectionName: # Your Gateway's HTTPS listener + hostnames: + - # e.g., rancher.example.com + rules: + - matches: + - path: + type: PathPrefix + value: / + backendRefs: + - name: rancher # Your Rancher service name + port: 80 # Use 443 if service.disableHTTP=true +``` + +**When TLS terminates externally (`tls: external`):** + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + name: rancher + namespace: cattle-system +spec: + parentRefs: + - name: + namespace: + sectionName: # Your Gateway's HTTP listener + hostnames: + - + rules: + - matches: + - path: + type: PathPrefix + value: / + backendRefs: + - name: rancher + port: 80 +``` + +#### HTTP to HTTPS Redirect Route (Optional) + +If TLS terminates at or within Kubernetes (not externally), you may want to redirect HTTP traffic to HTTPS. Create an additional HTTPRoute: + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + name: rancher-http-redirect + namespace: cattle-system +spec: + parentRefs: + - name: + namespace: + sectionName: # Your Gateway's HTTP listener + hostnames: + - + rules: + - filters: + - type: RequestRedirect + requestRedirect: + scheme: https + statusCode: 301 +``` + +### Using extraObjects + +You can include these HTTPRoute resources directly in your Rancher Helm installation using the `extraObjects` value. This keeps all resources managed together: + +```yaml +# values.yaml +hostname: rancher.example.com +tls: ingress + +extraObjects: + - apiVersion: gateway.networking.k8s.io/v1 + kind: HTTPRoute + metadata: + name: rancher + spec: + parentRefs: + - name: my-shared-gateway + namespace: gateway-system + sectionName: https + hostnames: + - rancher.example.com + rules: + - matches: + - path: + type: PathPrefix + value: / + backendRefs: + - name: rancher + port: 80 + + - apiVersion: gateway.networking.k8s.io/v1 + kind: HTTPRoute + metadata: + name: rancher-http-redirect + spec: + parentRefs: + - name: my-shared-gateway + namespace: gateway-system + sectionName: http + hostnames: + - rancher.example.com + rules: + - filters: + - type: RequestRedirect + requestRedirect: + scheme: https + statusCode: 301 +``` + +### Backend Port Selection + +The port in `backendRefs` depends on your `service.disableHTTP` setting: + +| `service.disableHTTP` | Backend Port | +|-----------------------|--------------| +| `false` (default) | `80` | +| `true` | `443` | + +### Listener Selection Summary + +| TLS Configuration | Primary Route Listener | Redirect Route | +|-------------------|------------------------|----------------| +| `tls: external` | HTTP listener | Not needed | +| `tls: ingress` | HTTPS listener | HTTP listener (optional) | +| `tls: secret` | HTTPS listener | HTTP listener (optional) | +| `tls: letsEncrypt`| HTTPS listener | HTTP listener (optional) | + +### Troubleshooting + +**HTTPRoute not being accepted:** +- Verify the Gateway name and namespace are correct +- Ensure the `sectionName` matches an existing listener on your Gateway +- Check that the listener allows routes from the Rancher namespace (see Gateway's `allowedRoutes` configuration) + +**Connection refused or timeouts:** +- Confirm the Rancher service exists and has endpoints: `kubectl get endpoints rancher -n cattle-system` +- Verify the backend port matches your `service.disableHTTP` setting + +**Certificate errors:** +- If using `tls: ingress` or `tls: secret`, ensure your Gateway's HTTPS listener has the appropriate certificate configured +- Verify the certificate covers your Rancher hostname diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/rancher-deployment-guides/rancher-deployment-guides.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/rancher-deployment-guides/rancher-deployment-guides.md new file mode 100644 index 00000000000..3204dced2e4 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/rancher-deployment-guides/rancher-deployment-guides.md @@ -0,0 +1,10 @@ +--- +title: Rancher Deployment Guides +--- + + + + + +- [Using an External Gateway with Rancher](configure-with-existing-gateway.md) + diff --git a/versioned_sidebars/version-2.14-sidebars.json b/versioned_sidebars/version-2.14-sidebars.json index 98ea9022fde..86c655da394 100644 --- a/versioned_sidebars/version-2.14-sidebars.json +++ b/versioned_sidebars/version-2.14-sidebars.json @@ -616,6 +616,17 @@ "id": "how-to-guides/advanced-user-guides/advanced-user-guides" }, "items": [ + { + "type": "category", + "label": "Rancher Deployment Guides", + "link": { + "type": "doc", + "id": "how-to-guides/advanced-user-guides/rancher-deployment-guides/rancher-deployment-guides" + }, + "items": [ + "how-to-guides/advanced-user-guides/rancher-deployment-guides/configure-with-existing-gateway" + ] + }, { "type": "category", "label": "Project Administration",