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)
+
diff --git a/sidebars.js b/sidebars.js
index 42d8eea20e0..1b4841190f9 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/rancher-deployment-guides",
+ },
+ items: [
+ "how-to-guides/advanced-user-guides/rancher-deployment-guides/configure-with-existing-gateway",
+ ],
+ },
{
type: "category",
label: "Project Administration",
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",