Document updated on
Environment variables in the configuration
When KrakenD runs (whether with run or check), all the behavior is loaded from the configuration file. Through environment variables, you can also set values. There are two different ways of injecting environment vars:
- Use a
KRAKEND_-like reserved environment variable: To override values set in the configuration. - Set your own environment variables when using the
{{env}}function in flexible configuration templates.
Use a reserved environment variable
There are a group of reserved environment variables that are automatically recognized by KrakenD when set.
Examples are when you want to replace the port, the default timeout, or the configuration name (sent to your telemetry) that already exists inthe configuration.
In essence, you can replace any value in the configuration that lives in the root level, and is a string, an integer, or a boolean. To do it you only need to capitalize the property name and add a prefix KRAKEND_.
KRAKEND_CACHE_TTLstring- Overrides
cache_ttlin the configuration. Sets a defaultCache-Control: public, max-age=%dheader to all endpoints where%dis the conversion to seconds of any duration you write, indicating for how long the client (or CDN) can cache the content of the request. You can override this value per endpoint, but setting an endpoint to 0 will use the default value instead. Notice that KrakenD does not cache the content with this parameter, but tells the client how to do it. Defaults to0s(no cache). For KrakenD cache, see backend caching. KRAKEND_DEBUG_ENDPOINTboolean- Overrides
debug_endpointin the configuration. Enables the/__debug/endpoint for this configuration. You can safely enable it in production. KRAKEND_DIALER_FALLBACK_DELAYstring- Overrides
dialer_fallback_delayin the configuration. Specifies the length of time to wait before spawning a RFC 6555 Fast Fallback connection. If zero, a default delay of 300ms is used. KRAKEND_DIALER_KEEP_ALIVEstring- Overrides
dialer_keep_alivein the configuration. The interval between keep-alive probes for an active network connection. If zero, keep-alive probes are sent with a default value (currently 15 seconds), if supported by the protocol and operating system. Network protocols or operating systems that do not support keep-alives ignore this field. If negative, keep-alive probes are disabled. KRAKEND_DIALER_TIMEOUTstring- Overrides
dialer_timeoutin the configuration. The timeout of the dial function for creating connections.The default is no timeout. With or without a timeout, the operating system may impose its own earlier timeout. KRAKEND_DISABLE_COMPRESSIONboolean- Overrides
disable_compressionin the configuration. When true prevents requesting compression with anAccept-Encoding: gziprequest header when the Request contains no existing Accept-Encoding value. If the Transport requests gzip on its own and gets a gzipped response, it’s transparently decoded. However, if the user explicitly requested gzip it is not automatically uncompressed. KRAKEND_DISABLE_KEEP_ALIVESboolean- Overrides
disable_keep_alivesin the configuration. When true it disables HTTP keep-alives and will only use the connection to the server for a single HTTP request. KRAKEND_DISABLE_RESTboolean- Overrides
disable_restin the configuration. Only RESTful URL patterns are valid to access backends. Set to true if your backends aren’t RESTful, e.g.:/url.{some_variable}.json KRAKEND_ECHO_ENDPOINTboolean- Overrides
echo_endpointin the configuration. Enables the/__echo/endpoint for this configuration, that returns information about the incoming request. When using /__echo as a backend you can check the actual headers and content a backend receives after all the zero-trust filtering. KRAKEND_EXPECT_CONTINUE_TIMEOUTstring- Overrides
expect_continue_timeoutin the configuration. If non-zero, specifies the amount of time to wait for a server’s first response headers after fully writing the request headers if the request has anExpect: 100-continueheader. Zero means no timeout and causes the body to be sent immediately, without waiting for the server to approve. This time does not include the time to send the request header. KRAKEND_IDLE_CONNECTION_TIMEOUTstring- Overrides
idle_connection_timeoutin the configuration. The maximum number of idle (keep-alive) connections across all hosts. Zero means no limit. KRAKEND_IDLE_TIMEOUTstring- Overrides
idle_timeoutin the configuration. The maximum amount of time to wait for the next request when keep-alives are enabled. Ifidle_timeoutis zero, the value ofread_timeoutis used. If both are zero, there is no timeout. KRAKEND_LISTEN_IPstring- Overrides
listen_ipin the configuration. The IP address that KrakenD listens to in IPv4 or IPv6. An empty string, or no declaration at all means listening on all interfaces. The inclusion of::is meant for IPv6 format only (this is not the port). Examples of valid addresses are192.0.2.1(IPv4),2001:db8::68(IPv6). The values::and0.0.0.0listen to all addresses and both are valid for IPv4 and IPv6 simultaneously. KRAKEND_MAX_IDLE_CONNECTIONSinteger- Overrides
max_idle_connectionsin the configuration. The maximum number of idle (keep-alive) connections across all hosts. Zero means no limit. KRAKEND_MAX_IDLE_CONNECTIONS_PER_HOSTinteger- Overrides
max_idle_connections_per_hostin the configuration. If non-zero, controls the maximum idle (keep-alive) connections to keep per-host. If zero,250is used instead. KRAKEND_NAMEstring- Overrides
namein the configuration. Used in telemetry. A friendly name, title, date, version or any other short description that helps you recognize the configuration. KRAKEND_PORTinteger- Overrides
portin the configuration. The TCP port where KrakenD is listening to. Recommended value is in the range 1024-65535 to run as an unpriviliged user KRAKEND_READ_HEADER_TIMEOUTstring- Overrides
read_header_timeoutin the configuration. The amount of time allowed to read request headers. The connection’s read deadline is reset after reading the headers and the Handler can decide what is considered too slow for the body. KRAKEND_READ_TIMEOUTstring- Overrides
read_timeoutin the configuration. Is the maximum duration for reading the entire request, including the body. Becauseread_timeoutdoes not let Handlers make per-request decisions on each request body’s acceptable deadline or upload rate, most users will prefer to useread_header_timeout. It is valid to use them both. KRAKEND_RESPONSE_HEADER_TIMEOUTstring- Overrides
response_header_timeoutin the configuration. If non-zero, specifies the amount of time to wait for a server’s response headers after fully writing the request (including its body, if any). This time does not include the time to read the response body. KRAKEND_SEQUENTIAL_STARTboolean- Overrides
sequential_startin the configuration. A sequential start registers all async agents in order, allowing you to have the starting logs in sequential order. A non-sequential start is much faster, but logs are harder to follow. KRAKEND_TIMEOUTstring- Overrides
timeoutin the configuration. Defines a default timeout for all endpoints. Can be overriden per endpoint. KRAKEND_USE_H2Cboolean- Overrides
use_h2cin the configuration. Enable the support for HTTP/2 with no TLS. This option is only advised when you have a load balancer in front of KrakenD doing SSL termination, and you have no option to enable SSL communication between the balancer and KrakenD (no internal certificates available either). Otherwise, enabling this flag is less secure and less performant. KRAKEND_WRITE_TIMEOUTstring- Overrides
write_timeoutin the configuration. Maximum duration before timing out writes of the response. USAGE_DISABLEboolean- Disables the usage telemetry: a request to our stats server during startup and every 12 hours with anonymous, non-sensitive information such as the version, operating system, architecture and uptime (see the source code).
Reserved variable example
For instance, take the following krakend.json configuration as an example:
{
"version": 3,
"timeout": "3s",
"name": "Example gateway.",
"cache_ttl": "0s"
}
You could start the server with the following command wich would allow you to override the values in the configuration:
$KRAKEND_NAME="Build ABC0123" \
KRAKEND_TIMEOUT="500ms" \
KRAKEND_PORT=9000 \
krakend run -c krakend.jsonThe resulting configuration will be:
{
"version": 3,
"timeout": "500ms",
"name": "Build ABC0123"
}
Important: Notice that the port attribute is not present in the configuration, despite passing a KRAKEND_PORT parameter. This is because the port didn’t exist previously in the configuration file, and the environment variables can only override values.
Setting your environment variables
If you need to set content using environment variables at any level, you have can either use the flexible configuration, which includes a series of advanced functions including an env function, or you can not use KrakenD at all and rely on the operating system envsubst command. Obviously you can also write your custom replacement process.
Environment variables with Flexible Configuration
Here is an example with Flexible Configuration:
{
"version": 3,
"name": "Configuration for {{ env "MY_POD_NAMESPACE" }}"
}
When you use the flexible configuration, you can start KrakenD from the template that uses them.
Environment variables with envsubst
Another example is not to use any of the built-in features of KrakenD and rely on your operating system via the command envusbst.
For instance, you have a configuration file krakend.template.json like the following:
{
"version": 3,
"name": "Configuration for $MY_POD_NAMESPACE"
}
Then you can generate the final configuration krakend.json like this:
$export MY_POD_NAMESPACE="my-namespace" && envsubst < krakend.template.json > krakend.jsonThe command, which is generally available in Linux distributions, takes a template file as input and outputs the same file with the environment variables replaced (you cannot override the same file). You have to be aware that missing variables are simply replaced by an empty string.
Note: on Alpine-based containers, like the KrakenD image, you need to do an apk add envsubst to use this command.