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:
- Host or Docker
- Kubernetes (Helm)
For host or Docker deployments, add the plugin attribute to the persistent gateway configuration:
plugin_attr:
redirect:
https_port: 8443
Reload or restart the gateway for the change to take effect.
For Helm deployments, update the chart values that render plugin_attr.redirect. Keep the rest of the values file unchanged.
For the APISIX Helm chart, set:
apisix:
pluginAttrs:
redirect:
https_port: 8443
For the API7 Gateway Helm chart, set:
pluginAttrs:
redirect:
https_port: 8443
Apply the complete values file with the chart used by the gateway release:
helm upgrade <release-name> <chart-name> -n <namespace> -f values.yaml
Parameters
See plugin common configurations for configuration options available to all plugins.
uri
valid value:
at least 2 charactersRedirect destination. Supports built-in variables, such as
$uriand$host.A variable that does not exist resolves to an empty string.
Configure exactly one of
uri,regex_uri, orhttp_to_https.regex_uri
valid value:
exactly 2 itemsRegular 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, orhttp_to_https.http_to_https
If true, redirect HTTP requests to the same host and request URI over HTTPS.
GETandHEADrequests use301; other methods use308.The gateway uses
X-Forwarded-Protoonly 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, orhttp_to_https. Do not configureappend_query_stringwith this field.ret_code
valid value:
greater than or equal to 200HTTP status code returned for
uriandregex_uriredirects. Use a3xxcode for a standard redirect.This field does not affect
http_to_httpsredirects.encode_uri
If true, percent-encode the redirect destination according to RFC 3986 while leaving its query string unchanged.
append_query_string
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 whenhttp_to_httpsis configured.