Redirect
The redirect plugin can return an HTTP redirect from a route or service before the request reaches the upstream. It can move clients from an old path to a new endpoint, build destinations from request variables or regular-expression captures, and redirect HTTP traffic to HTTPS.
Request Handling
Configure exactly one redirect mode:
| Mode | Behavior |
|---|---|
uri | Redirects every matching request to a fixed or variable-based destination. |
regex_uri | Rewrites the request path with a regular expression and redirects only when the expression matches. A request that does not match continues to the upstream service. |
http_to_https | Redirects an HTTP request to the same host and request URI over HTTPS. |
Fixed and regular-expression redirects use the configured response code, with 302 as the default. A request continues to the upstream when its regular expression does not match. Automatic HTTP-to-HTTPS redirects use 301 for GET and HEAD requests and 308 for other methods; requests already using HTTPS also continue to the upstream.
Examples
The examples first configure a regex-based permanent redirect that preserves the original query string. The second example redirects HTTP requests to the same host and request URI over HTTPS.
Redirect a Legacy Path
The route maps /legacy/<path> to /v2/<path>. The gateway returns the redirect directly, so the configured upstream is not contacted when the regular expression matches.
Create and enter a working directory for the example:
mkdir redirect-example
cd redirect-example
If Admin API authentication is enabled, export an admin-role key as ADMIN_API_KEY before using the Admin API tab.
- Admin API
- ADC
Create the route:
curl "http://127.0.0.1:9180/apisix/admin/routes/redirect-legacy-route" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"uri": "/legacy/*",
"plugins": {
"redirect": {
"regex_uri": ["^/legacy/(.*)", "/v2/$1"],
"ret_code": 308,
"append_query_string": true
}
},
"upstream": {
"type": "roundrobin",
"nodes": {
"httpbin.org:80": 1
}
}
}'
Configure ADC to connect to the target backend. The remaining ADC commands read the connection settings from these environment variables:
- APISIX
- API7 Gateway
If Admin API authentication is enabled, export an admin-role key as ADMIN_API_KEY before configuring ADC.
export ADC_BACKEND=apisix
export ADC_SERVER="http://127.0.0.1:9180"
export ADC_TOKEN="${ADMIN_API_KEY}"
export ADC_BACKEND=api7ee
export ADC_SERVER="https://{DASHBOARD_ADDR}"
export ADC_TOKEN="{DASHBOARD_TOKEN}"
export ADC_GATEWAY_GROUP="{GATEWAY_GROUP}"
Create the service and route:
services:
- name: redirect-service
labels:
docs-example: redirect
routes:
- name: redirect-legacy-route
uris:
- /legacy/*
plugins:
redirect:
regex_uri:
- ^/legacy/(.*)
- /v2/$1
ret_code: 308
append_query_string: true
upstream:
type: roundrobin
nodes:
- host: httpbin.org
port: 80
weight: 1
Preview the changes and confirm that they only affect resources for this example:
adc diff -f adc.yaml \
--include-resource-type service \
--label-selector docs-example=redirect
Review diff.yaml, then synchronize the labeled service:
adc sync -f adc.yaml \
--include-resource-type service \
--label-selector docs-example=redirect
Send a request to the legacy path:
curl --head "http://127.0.0.1:9080/legacy/orders?source=docs"
The response should use 308 Permanent Redirect and preserve the captured path and query string in Location:
HTTP/1.1 308 Permanent Redirect
Location: /v2/orders?source=docs
Redirect HTTP to HTTPS
Create a second route that redirects HTTP requests to the same host and request URI over HTTPS:
- Admin API
- ADC
curl "http://127.0.0.1:9180/apisix/admin/routes/redirect-https-route" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"uri": "/secure",
"plugins": {
"redirect": {
"http_to_https": true
}
},
"upstream": {
"type": "roundrobin",
"nodes": {
"httpbin.org:80": 1
}
}
}'
In adc.yaml, add another route to the existing service:
routes:
- name: redirect-https-route
uris:
- /secure
plugins:
redirect:
http_to_https: true
Preview and synchronize the updated file:
adc diff -f adc.yaml \
--include-resource-type service \
--label-selector docs-example=redirect
adc sync -f adc.yaml \
--include-resource-type service \
--label-selector docs-example=redirect
Send an HTTP request with a representative host name:
curl --silent --head "http://127.0.0.1:9080/secure" \
-H "Host: api.example.com" | \
grep -E "^(HTTP/|Location:)"
The response is a permanent redirect to HTTPS for the same host and path:
HTTP/1.1 301 Moved Permanently
Location: https://api.example.com:9443/secure
The response redirects to HTTPS on the selected non-default port. Port 443 would be omitted because HTTPS implies it.