Skip to main content

Redirect Configuration

The redirect plugin returns configurable HTTP redirects for routes and services, including regular-expression destinations and HTTP-to-HTTPS upgrades. Configuration covers static settings and plugin parameters.

Static Configurations​

Set plugin_attr.redirect.https_port when http_to_https redirects should use a specific HTTPS port. If this value is omitted, the plugin randomly selects an enabled apisix.ssl.listen port or uses 443 when no enabled listener provides a port. This setting only changes the port in Location; configure the gateway to listen for HTTPS on the same port.

The file to update depends on how the gateway is deployed:

For host or Docker deployments, add the plugin attribute to the persistent gateway configuration:

config.yaml
plugin_attr:
redirect:
https_port: 8443

Reload or restart the gateway for the change to take effect.

Parameters​

See plugin common configurations for configuration options available to all plugins.

  • uri

    string

    valid value:

    at least 2 characters

    Redirect destination. Supports built-in variables, such as $uri and $host.

    A variable that does not exist resolves to an empty string.

    Configure exactly one of uri, regex_uri, or http_to_https.

  • regex_uri

    array[string]

    valid value:

    exactly 2 items

    Regular expression and replacement used to generate the redirect destination from the request path. The first item is the match pattern and the second item is the replacement.

    If the request path does not match, the plugin does not redirect the request. Configure exactly one of uri, regex_uri, or http_to_https.

  • http_to_https

    boolean


    If true, redirect HTTP requests to the same host and request URI over HTTPS. GET and HEAD requests use 301; other methods use 308.

    The gateway uses X-Forwarded-Proto only when the direct peer is in the trusted forwarding addresses; otherwise, it uses the observed connection scheme. Trust a TLS-terminating proxy to prevent repeated redirects for requests that clients already sent over HTTPS.

    Configure exactly one of uri, regex_uri, or http_to_https. Do not configure append_query_string with this field.

  • ret_code

    integer

    default: 302

    valid value:

    greater than or equal to 200

    HTTP status code returned for uri and regex_uri redirects. Use a 3xx code for a standard redirect.

    This field does not affect http_to_https redirects.

  • encode_uri

    boolean

    default: false


    If true, percent-encode the redirect destination according to RFC 3986 while leaving its query string unchanged.

  • append_query_string

    boolean

    default: false


    If true, append the original request query string to the redirect destination. If the destination already has a query string, append the original values with &.

    Do not enable this field when the destination already includes the original query string, such as through $request_uri, or when http_to_https is configured.