> ## Documentation Index
> Fetch the complete documentation index at: https://ngrok.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Customizing Request Routing with URL Rewriting
> Configure URL rewriting in Kubernetes to modify request URLs before forwarding them to your upstream services.
URL rewriting allows you to modify request URLs before forwarding them to your upstream service.
This includes changing the hostname, path, or query parameters to ensure that requests are correctly formatted before reaching their destination.
By rewriting URLs at the network edge, you can:
🔄 Standardize API request formats across different backends.
🚀 Ensure compatibility between clients and services.
⚡ Optimize backend routing without requiring changes to application code.
## 🔍 What are the benefits of URL rewriting?
URL rewriting is an essential feature for API gateways, load balancers, and proxy servers, allowing for seamless request transformation before traffic reaches the backend.
Key Benefits:
* **Enable Backward Compatibility:** Allow older clients to use new API paths without breaking compatibility.
* **Simplify Microservices Routing:** Adjust URLs dynamically when forwarding requests to multiple backend services.
* **Support Multi-Tenant Architectures:** Rewrite hostnames or paths based on tenant information.
* **Improve API Gateway Interoperability:** Ensure requests are formatted correctly for third-party APIs and microservices.
* **Path Normalization:** Standardize incoming requests (`/v1/users` → `/api/users`).
* **Hostname Rewriting:** Change hostnames (`old.example.com` → `new.example.com`).
* **Backend Service Path Adjustments:** Route requests to different paths without requiring frontend changes.
## Rewrite full path
The following examples showcase how to create an endpoint that rewrites requests. The hostname, scheme, and port are kept the same, but the entire path of the request is changed.
* Requests to `https://example-hostname.ngrok.io/example` will be rewritten to `https://example-hostname.ngrok.io/rewrite`
* Requests to `https://example-hostname.ngrok.io/example/foo` will be rewritten to `https://example-hostname.ngrok.io/rewrite`
Check out the [URL rewrite Traffic Policy action](/traffic-policy/actions/url-rewrite/) page for more details about how it functions and the parameters it accepts.
```yaml theme={null}
apiVersion: ngrok.k8s.ngrok.com/v1alpha1
kind: AgentEndpoint
metadata:
name: example-agent-endpoint
spec:
url: https://example-hostname.ngrok.io
upstream:
url: http://my-service.my-namespace:8080
trafficPolicy:
inline:
on_http_request:
- actions:
- type: url-rewrite
config:
from: /.*
to: /rewrite
```
Check out the [URL rewrite Traffic Policy action](/traffic-policy/actions/url-rewrite/) page for more details about how it functions and the parameters it accepts.
```yaml theme={null}
apiVersion: ngrok.k8s.ngrok.com/v1alpha1
kind: CloudEndpoint
metadata:
name: example-cloud-endpoint
spec:
url: https://example-hostname.ngrok.io
trafficPolicy:
policy:
on_http_request:
- actions:
- type: url-rewrite
config:
from: /.*
to: /rewrite
```
💡 Ingress resources do not have native URL rewriting capabilities, but they can be extended using a Traffic Policy.
Check out the [URL rewrite Traffic Policy action](/traffic-policy/actions/url-rewrite/) page for more details about how it functions and the parameters it accepts.
### 1. Create an `NgrokTrafficPolicy`
```yaml theme={null}
apiVersion: ngrok.k8s.ngrok.com/v1alpha1
kind: NgrokTrafficPolicy
metadata:
name: example-tp
namespace: default
spec:
policy:
on_http_request:
- actions:
- type: url-rewrite
config:
from: /.*
to: /rewrite
```
### 2. Use the `NgrokTrafficPolicy` on an `Ingress`
```yaml theme={null}
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
annotations:
k8s.ngrok.com/traffic-policy: example-tp
name: example-ingress
namespace: default
spec:
ingressClassName: ngrok
rules:
- host: example-hostname.ngrok.io
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: example-service
port:
number: 80
```
✅ Gateway API natively supports URL rewriting, and this feature is fully supported by the ngrok Kubernetes Operator.
### 1. Create a `Gateway`
If you already have a `Gateway` you can use that instead
```yaml theme={null}
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: example-gateway
namespace: default
spec:
gatewayClassName: ngrok
listeners:
- name: example
hostname: "example-hostname.ngrok.io"
port: 443
protocol: HTTPS
```
### 2. Create an `HTTPRoute` with a URLRewrite Filter
```yaml theme={null}
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: example-route
namespace: default
spec:
hostnames:
- example-hostname.ngrok.io
parentRefs:
- group: gateway.networking.k8s.io
kind: Gateway
name: example-gateway
namespace: default
rules:
- matches:
- path:
type: PathPrefix
value: /example
backendRefs:
- group: ""
kind: Service
name: example-service
port: 443
weight: 1
filters:
- type: URLRewrite
urlRewrite:
path:
type: ReplaceFullPath
replaceFullPath: "/rewrite"
```
## Rewrite path prefix
The following examples showcase how to create an endpoint that rewrites requests. The hostname, scheme, and port are kept the same, but only the prefix is changed.
* Requests to `https://example-hostname.ngrok.io/example` will be rewritten to `https://example-hostname.ngrok.io/rewrite`
* Requests to `https://example-hostname.ngrok.io/example/foo` will be rewritten to `https://example-hostname.ngrok.io/rewrite/foo`
Check out the [URL rewrite Traffic Policy action](/traffic-policy/actions/url-rewrite/) page for more details about how it functions and the parameters it accepts.
```yaml theme={null}
apiVersion: ngrok.k8s.ngrok.com/v1alpha1
kind: AgentEndpoint
metadata:
name: example-agent-endpoint
spec:
url: https://example-hostname.ngrok.io
upstream:
url: http://my-service.my-namespace:8080
trafficPolicy:
inline:
on_http_request:
- actions:
- type: url-rewrite
config:
from: /example(.*)
to: /rewrite$1
```
Check out the [URL rewrite Traffic Policy action](/traffic-policy/actions/url-rewrite/) page for more details about how it functions and the parameters it accepts.
```yaml theme={null}
apiVersion: ngrok.k8s.ngrok.com/v1alpha1
kind: CloudEndpoint
metadata:
name: example-cloud-endpoint
spec:
url: https://example-hostname.ngrok.io
trafficPolicy:
policy:
on_http_request:
- actions:
- type: url-rewrite
config:
from: /example(.*)
to: /rewrite$1
```
💡 Ingress resources do not have native URL rewriting capabilities, but they can be extended using a Traffic Policy.
Check out the [URL rewrite Traffic Policy action](/traffic-policy/actions/url-rewrite/) page for more details about how it functions and the parameters it accepts.
### 1. Create an `NgrokTrafficPolicy`
```yaml theme={null}
apiVersion: ngrok.k8s.ngrok.com/v1alpha1
kind: NgrokTrafficPolicy
metadata:
name: example-tp
namespace: default
spec:
policy:
on_http_request:
- actions:
- type: url-rewrite
config:
from: /example(.*)
to: /rewrite$1
```
### 2. Use the `NgrokTrafficPolicy` on an `Ingress`
```yaml theme={null}
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
annotations:
k8s.ngrok.com/traffic-policy: example-tp
name: example-ingress
namespace: default
spec:
ingressClassName: ngrok
rules:
- host: example-hostname.ngrok.io
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: example-service
port:
number: 80
```
✅ Gateway API natively supports URL rewriting, and this feature is fully supported by the ngrok Kubernetes Operator.
### 1. Create a `Gateway`
If you already have a `Gateway` you can use that instead
```yaml theme={null}
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: example-gateway
namespace: default
spec:
gatewayClassName: ngrok
listeners:
- name: example
hostname: "example-hostname.ngrok.io"
port: 443
protocol: HTTPS
```
### 2. Create an `HTTPRoute` with a URLRewrite Filter
```yaml theme={null}
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: example-route
namespace: default
spec:
hostnames:
- example-hostname.ngrok.io
parentRefs:
- group: gateway.networking.k8s.io
kind: Gateway
name: example-gateway
namespace: default
rules:
- matches:
- path:
type: PathPrefix
value: /example
filters:
- type: URLRewrite
urlRewrite:
path:
type: ReplacePrefixMatch
replacePrefixMatch: "/rewrite"
```
## Rewrite port
The following examples showcase how to create an endpoint that rewrites requests. The hostname, scheme, and path are kept the same, but only the port is changed.
* Requests to `https://example-hostname.ngrok.io:8080` will be rewritten to `https://example-hostname.ngrok.io:9000`
Check out the [URL rewrite Traffic Policy action](/traffic-policy/actions/url-rewrite/) page for more details about how it functions and the parameters it accepts.
```yaml theme={null}
apiVersion: ngrok.k8s.ngrok.com/v1alpha1
kind: AgentEndpoint
metadata:
name: example-agent-endpoint
spec:
url: http://example-hostname.ngrok.io:8080
upstream:
url: http://my-service.my-namespace:8080
trafficPolicy:
inline:
on_http_request:
- actions:
- type: url-rewrite
config:
from: :8080
to: :9090
```
Check out the [URL rewrite Traffic Policy action](/traffic-policy/actions/url-rewrite/) page for more details about how it functions and the parameters it accepts.
```yaml theme={null}
apiVersion: ngrok.k8s.ngrok.com/v1alpha1
kind: CloudEndpoint
metadata:
name: example-cloud-endpoint
spec:
url: http://example-hostname.ngrok.io:8080
trafficPolicy:
policy:
on_http_request:
- actions:
- type: url-rewrite
config:
from: :8080
to: :9090
```
💡 Ingress resources do not have native URL rewriting capabilities, but they can be extended using a Traffic Policy.
Check out the [URL rewrite Traffic Policy action](/traffic-policy/actions/url-rewrite/) page for more details about how it functions and the parameters it accepts.
### 1. Create an `NgrokTrafficPolicy`
```yaml theme={null}
apiVersion: ngrok.k8s.ngrok.com/v1alpha1
kind: NgrokTrafficPolicy
metadata:
name: example-tp
namespace: default
spec:
policy:
on_http_request:
- actions:
- type: url-rewrite
config:
from: :8080
to: :9090
```
### 2. Use the `NgrokTrafficPolicy` on an `Ingress`
```yaml theme={null}
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
annotations:
k8s.ngrok.com/traffic-policy: example-tp
name: example-ingress
namespace: default
spec:
ingressClassName: ngrok
rules:
- host: example-hostname.ngrok.io
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: example-service
port:
number: 80
```
✅ Gateway API natively supports URL rewriting, and this feature is fully supported by the ngrok Kubernetes Operator.
### 1. Create a `Gateway`
If you already have a `Gateway` you can use that instead
```yaml theme={null}
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: example-gateway
namespace: default
spec:
gatewayClassName: ngrok
listeners:
- name: example
hostname: "example-hostname.ngrok.io"
port: 8080
protocol: HTTPS
```
### 2. Create an `HTTPRoute` with a URLRewrite Filter
```yaml theme={null}
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: example-route
namespace: default
spec:
hostnames:
- example-hostname.ngrok.io
parentRefs:
- group: gateway.networking.k8s.io
kind: Gateway
name: example-gateway
namespace: default
rules:
- matches:
- path:
type: PathPrefix
value: /example
filters:
- type: URLRewrite
urlRewrite:
port: 9090
```
## Rewrite hostname
The following examples showcase how to create an endpoint that rewrites requests. The scheme, port, and path are kept the same, but only the hostname is changed.
* Requests to `https://example-hostname.ngrok.io` will be rewritten to `https://other-example-hostname.ngrok.io`
Check out the [URL rewrite Traffic Policy action](/traffic-policy/actions/url-rewrite/) page for more details about how it functions and the parameters it accepts.
```yaml theme={null}
apiVersion: ngrok.k8s.ngrok.com/v1alpha1
kind: AgentEndpoint
metadata:
name: example-agent-endpoint
spec:
url: https://example-hostname.ngrok.io
upstream:
url: http://my-service.my-namespace:8080
trafficPolicy:
inline:
on_http_request:
- actions:
- type: url-rewrite
config:
from: example-hostname.ngrok.io
to: other-example-hostname.ngrok.io
```
Check out the [URL rewrite Traffic Policy action](/traffic-policy/actions/url-rewrite/) page for more details about how it functions and the parameters it accepts.
```yaml theme={null}
apiVersion: ngrok.k8s.ngrok.com/v1alpha1
kind: CloudEndpoint
metadata:
name: example-cloud-endpoint
spec:
url: https://example-hostname.ngrok.io
trafficPolicy:
policy:
on_http_request:
- actions:
- type: url-rewrite
config:
from: example-hostname.ngrok.io
to: other-example-hostname.ngrok.io
```
💡 Ingress resources do not have native URL rewriting capabilities, but they can be extended using a Traffic Policy.
Check out the [URL rewrite Traffic Policy action](/traffic-policy/actions/url-rewrite/) page for more details about how it functions and the parameters it accepts.
### 1. Create an `NgrokTrafficPolicy`
```yaml theme={null}
apiVersion: ngrok.k8s.ngrok.com/v1alpha1
kind: NgrokTrafficPolicy
metadata:
name: example-tp
namespace: default
spec:
policy:
on_http_request:
- actions:
- type: url-rewrite
config:
from: example-hostname.ngrok.io
to: other-example-hostname.ngrok.io
```
### 2. Use the `NgrokTrafficPolicy` on an `Ingress`
```yaml theme={null}
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
annotations:
k8s.ngrok.com/traffic-policy: example-tp
name: example-ingress
namespace: default
spec:
ingressClassName: ngrok
rules:
- host: example-hostname.ngrok.io
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: example-service
port:
number: 80
```
✅ Gateway API natively supports URL rewriting, and this feature is fully supported by the ngrok Kubernetes Operator.
### 1. Create a `Gateway`
If you already have a `Gateway` you can use that instead
```yaml theme={null}
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: example-gateway
namespace: default
spec:
gatewayClassName: ngrok
listeners:
- name: example
hostname: "example-hostname.ngrok.io"
port: 443
protocol: HTTPS
```
### 2. Create an `HTTPRoute` with a URLRewrite Filter
```yaml theme={null}
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: example-route
namespace: default
spec:
hostnames:
- example-hostname.ngrok.io
parentRefs:
- group: gateway.networking.k8s.io
kind: Gateway
name: example-gateway
namespace: default
rules:
- matches:
- path:
type: PathPrefix
value: /example
filters:
- type: URLRewrite
urlRewrite:
hostname: other-example-hostname.ngrok.io
```