Skip to main content

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.

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 page for more details about how it functions and the parameters it accepts.
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

​
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 page for more details about how it functions and the parameters it accepts.
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

​
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 page for more details about how it functions and the parameters it accepts.
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

​
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 page for more details about how it functions and the parameters it accepts.
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