Skip to main content

Redirect

Overview​

The Redirect Traffic Policy action enables you redirect incoming requests to new URLs by modifying the original URLs with regular expressions. Redirection is performed using the Location header.

Configuration Reference​

The Traffic Policy configuration reference for this action.

Supported Phases​

on_http_request

Type​

redirect

Configuration Fields​

  • fromstringCEL

    A regular expression pattern used to match a part of the URL.

    Supports CEL Interpolation.

  • tostringRequiredCEL

    A regular expression pattern used to replace the matched part of the URL.

    Supports CEL Interpolation.

  • status_codeinteger

    A 3xx status code used for redirecting. Default is 302.

  • headersobjectCEL

    Map of key-value headers to be added to the response.

    Maximum 10 headers can be specified.

    Supports CEL Interpolation in header values.

Behavior​

If the specified from regular expression matches the request URL, the URL will be modified according to the to field. If no from field is specified, the entire URL will be treated as a match.

When a match is found and the request URL is modified by the to field, the action will return a temporary 302 redirect by default, unless specified otherwise through the status_code field.

If the request URL is not changed, the action will take no further action.

Note about CEL Interpolation​

All CEL interpolation will occur before regular expressions are evaluated.

Examples​

Redirect using Paths​

The following Traffic Policy configuration demonstrates how to use the redirect action to redirect incoming requests from /products to /store/products.

Example Traffic Policy Document​

---
on_http_request:
  - actions:
      - type: "redirect"
        config:
          from: "/products"
          to: "/store/products"

This configuration will redirect any request from /products to /store/products with the default 302 Found status code.

Example Request​

$ curl -i https://example.ngrok.app/products
HTTP/1.1 302 Found
location: https://example.ngrok.app/store/products

In this example, a request to /products will be redirected to /store/products with a 302 Found status code, and the Location header will indicate the new URL.

Redirect using Regular Expressions​

The following Traffic Policy configuration demonstrates how to use the redirect action to redirects requests from an old API endpoint to a new one.

Example Traffic Policy Document​

---
on_http_request:
  - expressions:
      - "req.url.path.startsWith('/api/')"
    actions:
      - type: "redirect"
        config:
          from: "/api/v1/users?id=([0-9]+)"
          to: "/api/v2/users/$1/"
          status_code: 301
          headers:
            x-redirected: "true"

In this configuration we match requests from /api/v1/users?id=([0-9]+) and redirect them to /api/v2/users/$1/ with a 301 status code. Additionally, a custom header x-redirected: true is added to the response.

Example Request​

$ curl -i https://example.ngrok.app/api/v1/users?id=123
HTTP/1.1 301 Moved Permanently
location: https://example.ngrok.app/api/v2/users/123/
x-redirected: true

The request will be redirected to the new URL /api/v2/users/123/, with a 301 Moved Permanently status and a custom header.

Redirect with CEL Interpolation​

The following Traffic Policy configuration demonstrates how to use the redirect action to redirect users while using CEL Interpolation.

Example Traffic Policy Document​

---
on_http_request:
  - expressions:
      - "req.url.path in ['/api/v2/geo', '/api/v2/geo/']"
    actions:
      - type: "redirect"
        config:
          to: "/api/v2/geo?city=${conn.geo.city}"

This configuration will redirect any request from /api/v2/geo or /api/v2/geo/ to /api/v2/geo?city=${conn.geo.city} using CEL Interpolation to insert the city from the connection's geolocation data.

Example Request​

$ curl -i https://example.ngrok.app/api/v2/geo
HTTP/1.1 302 Found
location: https://example.ngrok.app/api/v2/geo?city=San%20Francisco

In this example, a request to https://example.ngrok.app/api/v2/geo will be redirected to https://example.ngrok.app/api/v2/geo?city=San Francisco, with the 302 Found status code and the Location header indicating the new URL that includes the city from the connection's geolocation data.

Action Result Variables​

The following variables are made available for use in subsequent expressions and CEL interpolations after the action has run. Variable values will only apply to the last action execution, results are not concatenated.

  • actions.ngrok.redirect.matchesarray of strings

    A list of elements that were matched during redirection. These represent the request components (e.g., path or query parameters) that triggered the action and resulted in the redirect.

  • actions.ngrok.redirect.urlstring

    The URL to which the traffic was redirected. This is the destination URL returned as part of the redirect response after the action was executed.

  • actions.ngrok.redirect.error.codestring

    A machine-readable code describing an error that occurred during the action's execution.

  • actions.ngrok.redirect.error.messagestring

    A human-readable message providing details about an error that occurred during the action's execution.