Enterprise Documentation
Customizing router behavior
Document updated on Jan 12, 2023
About this feature
| Since | v2.0 |
|---|---|
| Namespace | router |
| Log prefix | [SERVICE: Gin] |
| Scope | service |
| Source | krakend/krakend-cors |
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 in every case, there is an exception, 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, or remove the requests from the logs, 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 Flags
"router"
| The app_engine boolean trusts headers starting with X-AppEngine… for better integration with that PaaS. | ||||
| When true, enables the autogenerated OPTIONS endpoint for all the registered paths | ||||
| Stops registering access requests to KrakenD and leaving any logs out from the output. Defaults to false | ||||
| 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 | ||||
| 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. | ||||
| 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 | ||||
| Disables automatic validation of the url params looking for url encoded ones. | ||||
| If true, the router tries to fix the current request path, if no handle is registered for it | ||||
| Disables automatic redirection if the current route can’t be matched but a handler for the path with (without) the trailing slash exists. | ||||
| Sets custom error bodies for 404 and 405 errors.
| ||||
| When set to true, client IP will be parsed from the request’s headers. If no IP can be fetched, it falls back to the IP obtained from the request’s remote address. Defaults to false | ||||
| The path where you’d like to expose the health endpoint. Defaults to "/__health" | ||||
| Removes the version of KrakenD used in the X-KrakenD-version headers. Defaults to false | ||||
| Defines the set of paths that are removed from the logging. | ||||
| Sets the maxMemory param that is given to http.Request’s Multipart Form method call. | ||||
| List of headers used to obtain the client IP when forwarded_by_client_ip is set to true and the remote address is matched by at least one of the network origins of trusted_proxies. | ||||
| A parameter can be parsed from the URL even with extra slashes. Defaults to false | ||||
| 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 | ||||
| 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 is true. |
disable_redirect_fixed_pathdisable_redirect_fixed_path=true to avoid possible panics.Example: Hide the version in the X-KrakenD-version header
{
"version": 3,
"extra_config": {
"router": {
"hide_version_header": true
}
}
}
When the flag is set to true, the banner header will show an undefined version. To remove the header entirely, you must remove it in the CDN or layer in front of KrakenD.
Example: Custom JSON body for 404 and 405 errors
{
"version": 3,
"extra_config": {
"router": {
"error_body": {
"404": {
"msg": "Unknown endpoint",
"status": 404
},
"405": {
"oh-my-god": "What on earth are you requesting?"
}
}
}
}
}
Example: 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.
{
"version": 3,
"extra_config": {
"router":{
"return_error_msg":true
}
}
Example: Obtaining the real IP
The flags - forwarded_by_client_ip, remote_ip_headers, and trusted_proxies determine how to get the client IP address (read its documentation above)
The following example shows a configuration that takes the user IP from the X-Custom-Ip header only when the network origin is 172.20.0.1/16:
{
"version": 3,
"extra_config": {
"router":{
"forwarded_by_client_ip": true,
"remote_ip_headers": [
"X-Custom-Ip"
],
"trusted_proxies": [
"172.20.0.1/16"
]
}
}
Example: 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
}
}
