The upstream category is used to provide information about the upstream of the resource requested. This is useful when the policy engine is used with a proxy.
The following configuration will point:
http://foo.example.com:8080/.https://bar.example.com:8443/.https://baz.example.com/common while indicating that the host header example.com should be preserved.{
"name": "example",
"host": "example.com",
"path": "/*",
"modules": [
{
"name": "upstream-simple",
"order": 0,
"consumers": {
"foo": {
"strip_path": true,
"url": "http://foo.example.com:8080"
},
"bar": {
"preserve_host": false,
"strip_path": true,
"url": "https://bar.example.com:8443/"
}
},
"default": {
"preserve_host": true,
"strip_path": false,
"url": "https://baz.example.com/common"
}
}
]
}
| Attribute | Required | Type | Default | Description |
|---|---|---|---|---|
url |
Yes | String | The upstream url to point the client to (example: https://upstream.example.com/api). | |
strip_path |
No | Bool | False | If the endpoint path should be stripped from the request path. |
preserve_host |
No | Bool | False | If true, it will indicate that the upstream request should preserve the original host header as sent by the client. If false, the host in the url will be used instead. |
If multiple rate limits apply, the various limits will be separated in the response headers by whitespace.
| Header | Description |
|---|---|
X-Upstream-Host |
The host to connect to. |
X-Upstream-Path |
The upstream path to request. |
X-Upstream-Port |
The port to connect to. |
X-Upstream-Preserve-Host |
Whether the upstream request should preserve the original host header or not. |
X-Upstream-Proto |
The protocol to use when connecting. |
X-Upstream-URL |
The upstream URL to request. |
If the upstream request path is different from the client request path, strip_path may be needed to modify the request path before proxying the request to the upstream. This is needed if for example the public request path /api maps to the upstream path /. Care should be taken to ensure that references, such as hyperlinks and redirects fit this in-flight modification of the request path.
Examples:
| Client request path | Public endpoint path | Upstream app root path | Strip | Upstream request path |
|---|---|---|---|---|
/ |
/* |
/ |
false | / |
/ |
/* |
/ |
true | / |
/foo |
/* |
/ |
false | /foo |
/foo |
/* |
/ |
true | /foo |
/foo |
/foo* |
/ |
false | /foo |
/foo |
/foo* |
/ |
true | / |
/foo |
/foo* |
/bar |
false | /bar/foo |
/foo |
/foo* |
/bar |
true | /bar |
/users/doe/foo |
/users/*/foo |
/bar |
false | /bar/users/doe/foo |
/users/doe/foo |
/users/*/foo |
/bar |
true | /bar/doe/foo |
/users/doe/foo |
/users/*/* |
/bar |
false | /bar/users/doe/foo |
/users/doe/foo |
/users/*/* |
/bar |
true | /bar/doe/foo |
If the upstream service requires the same host header as in the original request, preserve_host should be set to true. The default value is false, which indicates that the host header specified in the module configuration should be used instead.
In the following configuration, the client request will be using the host header example.com while the upstream request will be using the host header accounts.example.com. If preserve_host was true, it would indicate that the upstream request should be using the host header example.com.
{
"name": "accounts",
"host": "example.com",
"path": "/accounts*",
"modules": [
{
"name": "upstream-simple",
"order": 0,
"default": {
"preserve_host": false,
"url": "https://accounts.example.com/"
}
}
]
}