Document updated on Nov 2, 2023
Router Options
The optional router configuration allows you to set global flags that change how KrakenD processes the requests globally at the router layer.
Generally speaking you don’t need this. But there is an exception in every case, and you might need to change some values.
Configuration for the router
The router
controls the behavior of KrakenD toward users. Its settings affect all activity in the gateway. For instance, you can obfuscate the X-KrakenD-version header, set a custom body for 404 errors, remove the requests from the logs, or define how to calculate client IPs to name a few examples.
To change the router behavior, you must add the namespace router
inside the extra_config
at the root of the configuration file. For instance:
{
"version": 3,
"extra_config": {
"router": {
"hide_version_header": true
}
}
}
All the options you can set under router
are:
Fields of Router Options
app_engine
boolean- The app_engine boolean trusts headers starting with X-AppEngine… for better integration with that PaaS.
auto_options
boolean- When true, enables the autogenerated OPTIONS endpoint for all the registered paths
decompress_gzip
integer- Enterprise Only. Decompresses any Gzipped content before sending it to the backend when the
Content-Encoding
hasgzip
in the first position. You can also set this value per endpoint.Defaults to0
disable_access_log
boolean- Stops registering access requests to KrakenD and leaving any logs out from the output.Defaults to
false
disable_gzip
boolean- Enterprise only. All the output to the end user on the Enterprise Edition uses gzip when accepted by the client. Use this flag to remove gzip compression.Defaults to
false
disable_handle_method_not_allowed
boolean- Whether to checks if another method is allowed for the current route, if the current request can not be routed. If this is the case, the request is answered with Method Not Allowed and HTTP status code 405. If no other Method is allowed, the request is a 404.
disable_health
boolean- When true you don’t have any exposed health endpoint. You can still use a TCP checker or build an endpoint yourself.Defaults to
false
disable_path_decoding
boolean- Disables automatic validation of the url params looking for url encoded ones.
disable_redirect_fixed_path
boolean- If true, the router tries to fix the current request path, if no handle is registered for it
disable_redirect_trailing_slash
boolean- Disables automatic redirection if the current route can’t be matched but a handler for the path with (without) the trailing slash exists.
error_body
object- Sets custom error bodies for 404 and 405 errors.
forwarded_by_client_ip
boolean- When set to true, the client IP will be parsed from the default request’s headers, or the custom ones (
remote_ip_headers
). If the IP has passed through a trusted proxy (e.g.: a proxy, load balancer, or a third party application) it will be extracted. If no IP can be fetched, it falls back to the IP obtained from the request’s remote address. When declared you must configuretrusted_proxies
too.Defaults tofalse
health_path
string- The path where you’d like to expose the health endpoint.Defaults to
"/__health"
hide_version_header
boolean- Removes the version of KrakenD used in the X-KrakenD-version headers.Defaults to
false
logger_skip_paths
array- Defines the set of paths that are removed from the logging.
max_multipart_memory
integer- Sets the maxMemory param that is given to http.Request’s Multipart Form method call.
max_payload
integer- Enterprise Only. Limits the maximum number of bytes a user can send to the gateway.
0
means no limit. You can also set this value per endpoint.Defaults to0
remote_ip_headers
array- List of headers used to obtain the client IP when
forwarded_by_client_ip
is set totrue
and the remote address is matched by at least one of the network origins oftrusted_proxies
. remove_extra_slash
boolean- A parameter can be parsed from the URL even with extra slashes.Defaults to
false
return_error_msg
boolean- When there is an error in the gateway (such as a timeout, a non-200 status code, etc.) it returns to the client the reason for the failure. The error is written in the body as is.Defaults to
false
trusted_proxies
array- List of network origins (IPv4 addresses, IPv4 CIDRs, IPv6 addresses or IPv6 CIDRs) from which to trust request’s headers that contain alternative client IP when
forwarded_by_client_ip
istrue
. When declared you must configureforwarded_by_client_ip
set totrue
, and optionallyremote_ip_headers
. use_h2c
boolean Deprecated- This flag has moved to the root level, and will be deleted from router in future versions.Defaults to
false
disable_redirect_fixed_path
disable_redirect_fixed_path=true
to avoid possible panics.Return the real client IP
The flags forwarded_by_client_ip
, remote_ip_headers
, and trusted_proxies
determine together how you get the client IP address.
forwarded_by_client_ip
or trusted_proxies
, you must declare both. The attribute remote_ip_headers
is only necessary when you want to overwrite the default headers.How the IP is retrieved internally
The flow the gateway follows to extract the client IP is as follows:
- The gateway fetches the IP from the connecting remote address
- Then it checks the IP from the headers listed under
remote_ip_headers
. When this list is not in the configuration, it looks inX-Forwarded-For
andX-Real-IP
(default lookup headers). - Unless you have a single KrakenD exposed to the internet or working locally, the client request will travel through different relays. These relays generally modify the header to append where they received the request from (whether it is the originating client, a load balancer, another proxy, etc.). So, you usually have a comma-separated list of IPs in the header containing the IP as they travel from one relay to the other. For instance, if there is just one hop before KrakenD, the header the gateway sees could look like
X-Forwarded-For: 1.2.3.4,172.20.0.1
where1.2.3.4
is the real IP of the user, and172.20.0.1
the last relay seen. - The list of
trusted_proxies
sets which IPs are part of these network hops, and the last IP before a known trusted proxy is the actual IP. - If checking the trusted proxies does not work, it will return the remote address in the first step.
Here’s an example of behavior. Suppose the gateway receives a header X-Forwarded-For: A,B,C,D
(IPs are expressed as letters for simplification). If your trusted_proxies
configuration contains ranges for C
and D
, then the returned IP is B
, as A
could have been spoofed by the client.
The real IP is stored in the X-Forwarded-For
header that KrakenD uses.
The following example shows a configuration that takes the user IP from an X-Forwarded-For
header only, and the network origin has relays in the range 172.16.0.1/12
(IPv4 Private Address Space). The endpoint /ip
returns the IP received. You can test this locally:
{
"$schema": "https://www.krakend.io/schema/v2.3/krakend.json",
"version": 3,
"echo_endpoint": true,
"extra_config": {
"router":{
"forwarded_by_client_ip": true,
"remote_ip_headers": [
"X-Forwarded-For"
],
"trusted_proxies": [
"172.16.0.1/12"
]
}
},
"endpoints": [
{
"endpoint": "/ip",
"backend": [
{
"host": ["http://localhost:8080"],
"url_pattern": "/__echo",
"allow": ["req_headers.X-Forwarded-For"]
}
]
}
]
}
Hide the version in the X-KrakenD-version
header
You can remove the KrakenD version your installation uses by adding the hide_version_header
flag as follows:
{
"version": 3,
"extra_config": {
"router": {
"hide_version_header": true
}
}
}
The banner header will show an undefined
version when the flag is set to true
. To remove the header entirely, you must remove it in the CDN or layer in front of KrakenD.
Custom JSON body for 404 and 405 errors
You can also define generic responses for 404 and 405 errors by defining the response object you will return to clients using the error_body
property. Here is an example:
{
"version": 3,
"extra_config": {
"router": {
"error_body": {
"404": {
"msg": "Unknown endpoint",
"status": 404
},
"405": {
"oh-my-god": "What on earth are you requesting?"
}
}
}
}
}
Returning the gateway error message
The secure choice of KrakenD is that all errors generated at the gateway are not returned to the client in the body. By setting return_error_msg
(boolean) to true
, when there is an error in the gateway (such as a timeout, a non-200 status code, etc.), it returns the client the reason for the failure. The error is written in the body as is.
This option will return the gateway interpretation of the error (such as there was an invalid status code). Nevertheless, when this option is mixed with a backend flag return_error_code
set to true
, the backend error is returned, but its encoding is lost.
Consider using return_error_details
to create a key with the error and support aggregation, or just use no-op
encoding if you need errors as returned by the backend.
{
"version": 3,
"extra_config": {
"router":{
"return_error_msg":true
}
}
Remove requests from logs
There are two options to remove content from logs: the logger_skip_paths
(list of paths you don’t want to see in the logs) and disable_access_log
, which stops registering access requests.
{
"version": 3,
"extra_config": {
"router":{
"logger_skip_paths":[
"/__health"
],
"disable_access_log": true
}
}