Configuration loading

Kong comes with a default configuration file that can be found at
/etc/kong/kong.conf.default if you installed Kong via one of the official
packages. To start configuring Kong, you can copy this file:

$ cp /etc/kong/kong.conf.default /etc/kong/kong.conf

Kong will operate with default settings should all the values in your
configuration be commented-out. Upon starting, Kong looks for several
default locations that might contain a configuration file:

/etc/kong/kong.conf
/etc/kong.conf

You can override this behavior by specifying a custom path for your
configuration file using the -c / --conf argument in the CLI:

$ kong start --conf /path/to/kong.conf

The configuration format is straightforward: simply uncomment any property
(comments are defined by the # character) and modify it to your needs.
Booleans values can be specified as on/off or true/false for convenience.

Environment variables

When loading properties out of a configuration file, Kong will also look for
environment variables of the same name. This allows you to fully configure Kong
via environment variables, which is very convenient for container-based
infrastructures, for example.

All environment variables prefixed with KONG_, capitalized and bearing the
same name as a setting will override it.

Custom Nginx configuration & embedding Kong

Tweaking the Nginx configuration is an essential part of setting up your Kong
instances since it allows you to optimize its performance for your
infrastructure, or embed Kong in an already running OpenResty instance.

Custom Nginx configuration

Kong can be started, reloaded and restarted with an --nginx-conf argument,
which must specify an Nginx configuration template. Such a template uses the
Penlighttemplating engine, which is compiled using
the given Kong configuration, before being dumped in your Kong prefix
directory, moments before starting Nginx.

The default template can be found at:
https://github.com/Kong/kong/tree/master/kong/templates. It is split in two
Nginx configuration files: nginx.lua and nginx_kong.lua. The former is
minimalistic and includes the latter, which contains everything Kong requires
to run. When kong start runs, right before starting Nginx, it copies these
two files into the prefix directory, which looks like so:

/usr/local/kong
├── nginx-kong.conf
├── nginx.conf

If you wish to include other server blocks in your Nginx configuration, or if
you must tweak global settings that are not exposed by the Kong configuration,
here is a suggestion:

If you wish to customize the Kong Nginx sub-configuration file to, eventually,
add other Lua handlers or customize the lua_* directives, you can inline the
nginx_kong.lua configuration in this custom_nginx.template example file:

Embedding Kong in OpenResty

If you are running your own OpenResty servers, you can also easily embed Kong
by including the Kong Nginx sub-configuration using the include directive
(similar to the examples of the previous section). If you have a valid
top-level NGINX configuration that simply includes the Kong-specific
configuration:

# my_nginx.conf
http {
include 'nginx-kong.conf';
}

you can start your instance like so:

$ nginx -p /usr/local/openresty -c my_nginx.conf

And Kong will be running in that instance (as configured in nginx-kong.conf).

Serving both a website and your APIs from Kong

A common use case for API providers is to make Kong serve both a website
and the APIs themselves over the Proxy port — 80 or 443 in
production. For example, https://my-api.com (Website) and
https://my-api.com/api/v1 (API).

To achieve this, we cannot simply declare a new virtual server block,
like we did in the previous section. A good solution is to use a custom
Nginx configuration template which inlines nginx_kong.lua and adds a new
location block serving the website alongside the Kong Proxy location
block:

Properties reference

General section

prefix

Working directory. Equivalent to Nginx’s prefix path, containing temporary files
and logs. Each Kong process must have a separate working directory.

Default: /usr/local/kong

log_level

Log level of the Nginx server. Logs can be found at <prefix>/logs/error.log

See http://nginx.org/en/docs/ngx_core_module.html#error_log for a list of
accepted values.

Default: notice

proxy_access_log

Path for proxy port request access logs. Set this value to off to disable
logging proxy requests. If this value is a relative path, it will be placed
under the prefix location.

Default: logs/access.log

proxy_error_log

Path for proxy port request error logs. Granularity of these logs is adjusted
by the log_level directive.

Default: logs/error.log

admin_access_log

Path for Admin API request access logs. Set this value to off to disable
logging Admin API requests. If this value is a relative path, it will be placed
under the prefix location.

Default: logs/admin_access.log

admin_error_log

Path for Admin API request error logs. Granularity of these logs is adjusted by
the log_level directive.

Default: logs/error.log

custom_plugins

Comma-separated list of additional plugins this node should load. Use this
property to load custom plugins that are not bundled with Kong. Plugins will
be loaded from the kong.plugins.{name}.* namespace.

Default: none

Example: my-plugin,hello-world,custom-rate-limiting

anonymous_reports

Send anonymous usage data such as error stack traces to help improve Kong.

Nginx section

proxy_listen

Comma-separated list of addresses and ports on which the proxy server should
listen. The proxy server is the public entrypoint of Kong, which proxies
traffic from your consumers to your backend services. This value accepts IPv4,
IPv6, and hostnames.

Some suffixes can be specified for each pair:

ssl will require that all connections made through a particular
address/port be made with TLS enabled.

http2 will allow for clients to open HTTP/2 connections to Kong’s proxy
server.

Finally, proxy_protocol will enable usage of the PROXY protocol for a
given address/port.

the proxy port for this node, enabling a ‘control-plane’ mode (without traffic
proxying capabilities) which can configure a cluster of nodes connected to the
same database.

See http://nginx.org/en/docs/http/ngx_http_core_module.html#listen for
a description of the accepted formats for this and other *_listen values.

admin_listen

Comma-separated list of addresses and ports on which the Admin interface
should listen. The Admin interface is the API allowing you to configure and
manage Kong. Access to this interface should be restricted to Kong
administrators only. This value accepts IPv4, IPv6, and hostnames. Some
suffixes can be specified for each pair:

ssl will require that all connections made through a particular
address/port be made with TLS enabled.

http2 will allow for clients to open HTTP/2 connections to Kong’s
proxy server.

Finally, proxy_protocol will enable usage of the PROXY protocol for a
given address/port.

This value can be set to off, thus disabling the Admin interface for this
node, enabling a ‘data-plane’ mode (without configuration capabilities)
pulling its configuration changes from the database.

Default: 127.0.0.1:8001, 127.0.0.1:8444 ssl

Example: 127.0.0.1:8444 http2 ssl

nginx_user

Defines user and group credentials used by worker processes. If group is omitted, a
group whose name equals that of user is used.

Default: nobody nobody

Example: nginx www

nginx_worker_processes

Determines the number of worker processes spawned by Nginx.
See http://nginx.org/en/docs/ngx_core_module.html#worker_processes for detailed
usage of this directive and a description of accepted values.

Default: auto

nginx_daemon

Determines whether Nginx will run as a daemon or as a foreground process.
Mainly useful for development or when running Kong inside a Docker environment.

See http://nginx.org/en/docs/ngx_core_module.html#daemon.

Default: on

mem_cache_size

Size of the in-memory cache for database entities. The accepted units are k and
m, with a minimum recommended value of a few MBs.

Default: 128m

ssl_cipher_suite

Defines the TLS ciphers served by Nginx. Accepted values are modern,
intermediate, old, or custom.
See https://wiki.mozilla.org/Security/Server_Side_TLS for detailed
descriptions of each cipher suite.

Default: modern

ssl_ciphers

Defines a custom list of TLS ciphers to be served by Nginx. This list must
conform to the pattern defined by openssl ciphers. This value is ignored if
ssl_cipher_suite is not custom.

Default: none

ssl_cert

The absolute path to the SSL certificate for proxy_listen values with SSL enabled.

Default: none

ssl_cert_key

The absolute path to the SSL key for proxy_listen values with SSL enabled.

Default: none

client_ssl

client_ssl_cert

If client_ssl is enabled, the absolute path to the client SSL certificate for
the proxy_ssl_certificate directive. Note that this value is statically
defined on the node, and currently cannot be configured on a per-API basis.

Default: none

client_ssl_cert_key

If client_ssl is enabled, the absolute path to the client SSL key for the
proxy_ssl_certificate_key address. Note this value is statically defined on
the node, and currently cannot be configured on a per-API basis.

Default: none

admin_ssl_cert

The absolute path to the SSL certificate for admin_listen values with SSL enabled.

Default: none

admin_ssl_cert_key

The absolute path to the SSL key for admin_listen values with SSL enabled.

Default: none

upstream_keepalive

Sets the maximum number of idle keepalive connections to upstream servers that
are preserved in the cache of each worker process. When this number is
exceeded, the least recently used connections are closed.

Default: 60

server_tokens

Enables or disables emitting Kong version on error pages and in the Server
or Via (in case the request was proxied) response header field.

real_ip_recursive

client_max_body_size

Defines the maximum request body size allowed by requests proxied by Kong, specified in the
Content-Length request header. If a request exceeds this limit, Kong will respond with a
413 (Request Entity Too Large). Setting this value to 0 disables checking the request body
size.

Note: See the Nginx docs
for further description of this parameter. Numeric values may be suffixed with
k or m to denote limits in terms of kilobytes or megabytes.

Default: 0

client_body_buffer_size

Defines the buffer size for reading the request body. If the client request body is
larger than this value, the body will be buffered to disk. Note that when the body is
buffered to disk Kong plugins that access or manipulate the request body may not work, so
it is advisable to set this value as high as possible (e.g., set it as high as
client_max_body_size to force request bodies to be kept in memory). Do note that
high-concurrency environments will require significant memory allocations to process
many concurrent large request bodies.

Note: See the Nginx docs
for further description of this parameter. Numeric values may be suffixed with
k or m to denote limits in terms of kilobytes or megabytes.

Default: 8k

error_default_type

Default MIME type to use when the request Accept header is missing and Nginx is
returning an error for the request. Accepted values are text/plain,
text/html, application/json, and application/xml.

Consistency setting to use when reading/writing to the Cassandra cluster.

cassandra_lb_policy

Load balancing policy to use when distributing queries across your Cassandra cluster. Accepted values are RoundRobin and DCAwareRoundRobin. Prefer the later if and only if you are using a multi-datacenter cluster, and set the cassandra_local_datacenter if so.

cassandra_local_datacenter

When using the DCAwareRoundRobin policy, you must specify the name of the cluster local (closest) to this Kong node.

cassandra_repl_strategy

If creating the keyspace for the first time, specify a replication strategy.

cassandra_repl_factor

Specify a replication factor for the SimpleStrategy.

cassandra_data_centers

Specify data centers for the NetworkTopologyStrategy.

cassandra_schema_consensus_timeout

Define the timeout (in ms) for the waiting period to each a schema consensus between your Cassandra nodes. This value is only used during migrations.

Datastore cache section

In order to avoid unnecessary communication with the datastore, Kong caches
entities (such as APIs, Consumers, Credentials, etc…) for a configurable
period of time. It also handles invalidations if such an entity is updated.

This section allows for configuring the behavior of Kong regarding the
caching of such configuration entities.

db_update_frequency

Frequency (in seconds) at which to check for
updated entities with the datastore.
When a node creates, updates, or deletes an
entity via the Admin API, other nodes need
to wait for the next poll (configured by
this value) to eventually purge the old
cached entity and start using the new one.

Default: 5 seconds

db_update_propagation

Time (in seconds) taken for an entity in the
datastore to be propagated to replica nodes
of another datacenter.
When in a distributed environment such as
a multi-datacenter Cassandra cluster, this
value should be the maximum number of
seconds taken by Cassandra to propagate a
row to other datacenters.
When set, this property will increase the
time taken by Kong to propagate the change
of an entity.
Single-datacenter setups or PostgreSQL
servers should suffer no such delays, and
this value can be safely set to 0.

Default: 0 seconds

db_cache_ttl

Time-to-live (in seconds) of an entity from
the datastore when cached by this node.
Database misses (no entity) are also cached
according to this setting.
If set to 0, such cached entities/misses
never expire.

DNS resolver section

Kong will resolve hostnames as either SRV or A records (in that order, and
CNAME records will be dereferenced in the process).
In case a name was resolved as an SRV record it will also override any given
port number by the port field contents received from the DNS server.

The DNS options SEARCH and NDOTS (from the /etc/resolv.conf file) will
be used to expand short names to fully qualified ones. So it will first try the
entire SEARCH list for the SRV type, if that fails it will try the SEARCH
list for A, etc.

For the duration of the ttl, the internal DNS resolver will loadbalance each
request it gets over the entries in the DNS record. For SRV records the
weight fields will be honored, but it will only use the lowest priority
field entries in the record.

dns_resolver

Comma separated list of nameservers, each
entry in ip[:port] format to be used by
Kong. If not specified the nameservers in
the local resolv.conf file will be used.
Port defaults to 53 if omitted. Accepts
both IPv4 and IPv6 addresses.

Default: none

dns_hostsfile

The hosts file to use. This file is read once and its content is static
in memory. To read the file again after modifying it, Kong must be reloaded.

Default: /etc/hosts

dns_order

The order in which to resolve different
record types. The LAST type means the
type of the last successful lookup (for the
specified name). The format is a (case
insensitive) comma separated list.

Default: LAST,SRV,A,CNAME

dns_stale_ttl

Defines, in seconds, how long a record will
remain in cache past its TTL. This value
will be used while the new DNS record is
fetched in the background.
Stale data will be used from expiry of a
record until either the refresh query
completes, or the dns_stale_ttl number of
seconds have passed.

Default: 4

dns_not_found_ttl

TTL in seconds for empty DNS responses and
“(3) name error” responses.

Default: 30

dns_error_ttl

TTL in seconds for error responses.

Default: 1

dns_no_sync

If enabled, then upon a cache-miss every
request will trigger its own dns query.
When disabled multiple requests for the
same name/type will be synchronised to a
single query.

Development & miscellaneous section

Additional settings inherited from lua-nginx-module allowing for more
flexibility and advanced usage.

See the lua-nginx-module documentation for more information:
https://github.com/openresty/lua-nginx-module

lua_ssl_trusted_certificate

Absolute path to the certificate authority file for Lua cosockets in PEM
format. This certificate will be the one used for verifying Kong’s database
connections, when pg_ssl_verify or cassandra_ssl_verify are enabled.

See https://github.com/openresty/lua-nginx-module#lua_ssl_trusted_certificate

Default: none

lua_ssl_verify_depth

Sets the verification depth in the server certificates chain used by Lua
cosockets, set by lua_ssl_trusted_certificate.

This includes the certificates configured for Kong’s database connections.

See https://github.com/openresty/lua-nginx-module#lua_ssl_verify_depth

Default: 1

lua_package_path

Sets the Lua module search path (LUA_PATH). Useful when developing or using
custom plugins not stored in the default search path.

See https://github.com/openresty/lua-nginx-module#lua_package_path

Default: none

lua_package_cpath

Sets the Lua C module search path (LUA_CPATH).

See https://github.com/openresty/lua-nginx-module#lua_package_cpath

Default: none

lua_socket_pool_size

Specifies the size limit for every cosocket connection pool associated with
every remote server.

See https://github.com/openresty/lua-nginx-module#lua_socket_pool_size