News KrakenD 2023: Milestones and New Horizons

Community Documentation

Recent changes

You are viewing a previous version of KrakenD Community Edition (v2.4) , go to the latest version

Customizing router behavior

Document updated on Sep 25, 2023

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, 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:

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
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.
404

object
Write any JSON object structure you would like to return to users when they request an endpoint not known by KrakenD. 404 Not Found errors.
405

object
Write any JSON object structure you would like to return to users
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.
Defaults to false
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.
remote_ip_headers

array
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.
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 is true.
use_h2c

boolean
Enable the support for HTTP/2 with no TLS (clear text). This option is less secure and less performant, use with caution.
Defaults to false

Schema: https://www.krakend.io/schema/v2.4/router.json
* indicates a required field.

Caution with disable_redirect_fixed_path
This flag can lead to the malfunctioning of your router. If your API configuration has paths that could collide, leave its value with the safe choice 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 how you get the client IP address.

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, or from X-Forwarded-For or X-Real-IP when there isn’t such a list.
  • When the request travels through different relays (unless you have a single KrakenD exposed to the internet is usually the case), 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 where 1.2.3.4 is the real IP of the user, and 172.20.0.1 the last relay seen.
  • When an IP travels through the relays, 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 a X-Forwarded-For header only, and the network origin has relays in the range 172.20.0.1/16. 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.20.0.1/16"
          ]
      }
  },
  "endpoints": [
    {
      "endpoint": "/ip",
      "backend": [
        {
          "host": ["http://localhost:8080"],
          "url_pattern": "/__echo",
          "allow": ["req_headers.X-Forwarded-For"]
        }
      ]
    }
  ]
}

Example: Hide the version in the X-KrakenD-version header

{
  "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.

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.

Gateway errors != backend errors
This option does not relate to the body of your backend errors. If you are looking for this option, see return detailed errors instead.
{
  "version": 3,
  "extra_config": {
      "router":{
          "return_error_msg":true
      }
}

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
      }
}
Scarf

Unresolved issues?

The documentation is only a piece of the help you can get! Whether you are looking for Open Source or Enterprise support, see more support channels that can help you.

We use cookies to understand how you use our site and to improve your overall experience. By continuing to use our site, you accept our Privacy Policy. More information