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​

This is the Traffic Policy configuration reference for this action.

Action Type​

redirect

Configuration Fields​

ParameterTypeDescription
fromstringA regular expression string to match inside of the URL. Supports CEL Interpolation.
tostringRequired. A regular expression string to replace the from match with. Supports CEL Interpolation.
status_codeintA 3xx status code used for redirecting. Default is 302.
headersmap[string]stringMap of key-value headers to be added to the response. Supports CEL Interpolation. Maximum 10.
formatstringDetermines interpolation format in to/from fields. Default ngrok.

Supported Phases​

  • on_http_request

Supported Schemes​

  • https
  • http

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.

CEL Interpolation​

You can access Traffic Policy variables and embed CEL expressions in this actions configuration values using CEL Interpolation in the form of ${expression}. Check out the examples below to see how CEL Interpolation works.

Note: All CEL interpolation will occur before regular expressions are evaluated.

For a complete list of variables and how to write expressions, see Expressions and Variables documentation.

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.

NameTypeDescription
actions.ngrok.redirect.matches[]stringList of matched elements.
actions.ngrok.redirect.urlstringThe resulting URL sent back for redirect.
actions.ngrok.redirect.error.codestringCode for an error that occurred during the invocation of an action.
actions.ngrok.redirect.error.messagestringMessage for an error that occurred during the invocation of an action.