Proxy Settings in the API Definition
The proxy
section outlines the API proxying functionality. You can define where Tyk should listen, and where Tyk should proxy traffic to.
-
proxy.preserve_host_header
: Set totrue
to preserve the host header. Ifproxy.preserve_host_header
is set totrue
in an API definition then the host header in the outbound request is retained to be the inbound hostname of the proxy. -
proxy.listen_path
: The path to listen on, e.g./api
or/
. Any requests coming into the host, on the port that Tyk is configured to run on, that go to this path will have the rules defined in the API Definition applied. Versioning assumes that different versions of an API will live on the same URL structure. If you are using URL-based versioning (e.g./v1/function
,/v2/function/
) then it is recommended to set up a separate non-versioned definition for each version as they are essentially separate APIs.
Proxied requests are literal, no re-writing takes place, for example, if a request is sent to the listen path of: /listen-path/widgets/new
and the URL to proxy to is http://your.api.com/api/
then the actual request that will land at your service will be: http://your.api.com/api/listen-path/widgets/new
.
This behaviour can be circumvented so that the listen_path
is stripped from the outgoing request. See the section on strip_listen_path
below.
-
proxy.target_url
: This defines the target URL that the request should be proxied to if it passes all checks in Tyk. -
proxy.strip_listen_path
: By setting this totrue
, Tyk will attempt to replace thelisten-path
in the outgoing request with an empty string. This means that in the above scenario where/listen-path/widgets/new
and the URL to proxy to ishttp://your.api.com/api/
becomeshttp://your.api.com/api/listen-path/widgets/new
, actually changes the outgoing request to be:http://your.api.com/api/widgets/new
. -
proxy.enable_load_balancing
: Set this value totrue
to have a Tyk node distribute traffic across a list of servers. **Required: ** You must fill in thetarget_list
section. -
proxy.target_list
: A list of upstream targets (can be one or many hosts). -
proxy.check_host_against_uptime_tests
: If uptime tests are enabled, Tyk will check the hostname of the outbound request against the downtime list generated by the host checker. If the host is found, then it is skipped. -
proxy.service_discovery
: The service discovery section tells Tyk where to find information about the host to proxy to. In a clustered environment this is useful if servers are coming online and offline dynamically with new IP addresses. The service discovery module can pull out the required host data from any service discovery tool that exposes a RESTful endpoint that outputs a JSON object.
enable_load_balancing: true,
service_discovery: {
use_discovery_service: true,
query_endpoint: "http://127.0.0.1:4001/v2/keys/services/multiobj",
use_nested_query: true,
parent_data_path: "node.value",
data_path: "array.hostname",
port_data_path: "array.port",
use_target_list: true,
cache_timeout: 10
},
-
proxy.service_discovery.use_discovery_service
: Set this totrue
to enable the discovery module. -
proxy.service_discovery.query_endpoint
: The endpoint to call. -
proxy.service_discovery.data_path
: The namespace of the data path. For example, if your service responds with:
{
"action": "get",
"node": {
"key": "/services/single",
"value": "http://httpbin.org:6000",
"modifiedIndex": 6,
"createdIndex": 6
}
}
Then your name space would be node.value
.
proxy.service_discovery.use_nested_query
: Sometimes the data you are retrieving is nested in another JSON object. For example, this is how Etcd responds with a JSON object as a value key:
{
"action": "get",
"node": {
"key": "/services/single",
"value": "{"hostname": "http://httpbin.org", "port": "80"}",
"modifiedIndex": 6,
"createdIndex": 6
}
}
In this case, the data actually lives within this string-encoded JSON object. So in this case, you set the use_nested_query
to true
, and use a combination of the data_path
and parent_data_path
(below)
proxy.service_discovery.parent_data_path
: This is the namespace of where to find the nested value In the above example, it would benode.value
.
You would then change the data_path
setting to be hostname
.
Tyk will decode the JSON string and then apply the data_path
namespace to that object in order to find the value.
proxy.service_discovery.port_data_path
: In the above nested example, we can see that there is a separate PORT value for the service in the nested JSON. In this case you can set theport_data_path
value and Tyk will treatdata_path
as the hostname and zip them together (this assumes that the hostname element does not end in a slash or resource identifier such as/widgets/
).
In the above example, the port_data_path
would be port
.
-
proxy.service_discovery.target_path
: The target path to append to the host:port combination provided by the service discovery engine. -
proxy.service_discovery.use_target_list
: If you are using load_balancing, set this value totrue
and Tyk will treat the data path as a list and inject it into the target list of your API definition. -
proxy.service_discovery.cache_timeout
: Tyk caches target data from a discovery service. In order to make this dynamic you can set a cache value when the data expires and new data is loaded. -
proxy.disable_strip_slash
: This boolean option allows you to add a way to disable the stripping of the slash suffix from a URL.
Internal proxy setup
The transport section allows you to specify a custom proxy and set the minimum TLS versions and any SSL ciphers.
This is an example of proxy.transport
definition followed by explanations for every field.
}
"transport": {
"proxy_url": "http(s)://proxy.url:1234",
"ssl_min_version": 771,
"ssl_ciphers": [
"TLS_RSA_WITH_AES_128_GCM_SHA256",
"TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA"
],
"ssl_insecure_skip_verify": true,
"ssl_force_common_name_check": false
}
-
proxy.transport.proxy_url
: Use this setting to specify your custom forward proxy and port. -
proxy.transport.ssl_min_version
: Use this setting to specify your minimum TLS version:
You need to use the following values for this setting:
TLS Version | Value to Use |
---|---|
1.0 | 769 |
1.1 | 770 |
1.2 | 771 |
1.3 | 772 |
-
proxy.transport.ssl_ciphers
: You can addssl_ciphers
which takes an array of strings as its value. Each string must be one of the allowed cipher suites as defined at https://golang.org/pkg/crypto/tls/#pkg-constants -
proxy.transport.ssl_insecure_skip_verify
: Boolean flag to control at the API definition whether it is possible to use self-signed certs for some APIs, and actual certs for others. This also works forTykMakeHttpRequest
&TykMakeBatchRequest
in virtual endpoints. -
proxy.transport.ssl_force_common_name_check
: Use this setting to force the validation of a hostname against the certificate Common Name.