Routes
How Gateway matches requests and changes them before forwarding.
A route decides which target a request goes to and how it is changed on the way.
Matching
| Match on | Behaviour |
|---|---|
| Path prefix | The request path starts with the route's prefix, for example /api/. |
| Host | Optional. The request's Host header must equal the route's host. |
Path rewrites
A route can replace the matched path prefix before forwarding, so /api/users can reach the target as /users.
Headers
| Rule | Effect |
|---|---|
| Set request headers | Adds the configured headers to the request sent to the target. A client-supplied header with the same name is not removed, so the target can receive both. To replace a client header, also remove it. |
| Remove request headers | Drops client headers with that name before forwarding. |
| Set response headers | Adds the configured headers to the response returned to the client. |
| Remove response headers | Drops target headers with that name from the response. |
| Forwarding headers | On by default. Gateway adds X-Real-IP, X-Forwarded-For, X-Forwarded-Proto and X-Forwarded-Host. |
| Preserve host | Off by default. When on, the client's Host header is sent to the target unchanged. |
Hop-by-hop headers are never forwarded.
Forwarding headers and trust
Gateway removes client-supplied copies of X-Real-IP, X-Forwarded-Proto, X-Forwarded-Host and its authenticated-identity headers, then sets its own values. Those values come from Gateway.
X-Forwarded-For is handled differently. If the client sent an X-Forwarded-For header, Gateway keeps its value and appends the address it saw the request come from:
X-Forwarded-For: <client-supplied values>, <address Gateway saw>Only the right-most X-Forwarded-For entry comes from Gateway
The right-most entry is the one Gateway added. Every earlier entry was supplied by the caller and can be forged. Do not use earlier entries for access control, rate limiting or audit. To get the address Gateway saw, read the right-most X-Forwarded-For entry or X-Real-IP.
Example
In the current Gateway configuration format, a route with a host match, a path rewrite and an added request header looks like this.
{
"routes": [
{
"path_prefix": "/api/",
"host": "api.example.com",
"upstream": "api",
"rewrite_pattern": "/api",
"rewrite_replacement": "",
"upstream_headers": [
{ "name": "X-Environment", "value": "production" }
]
}
]
}Available at release
How you define routes and targets for a Gateway you use through id0n, and how you authenticate, are published with the Gateway interface reference. Field names may change before release.