Configuration Reference

Table of Contents

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:


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.

Back to TOC

Verifying your configuration

You can verify the integrity of your settings with the check command:

$ kong check <path/to/kong.conf>
configuration at <path/to/kong.conf> is valid

This command will take into account the environment variables you have currently set, and will error out in case your settings are invalid.

Additionally, you can also use the CLI in debug mode to have more insight as to what properties Kong is being started with:

$ kong start -c <kong.conf> --vv
2016/08/11 14:53:36 [verbose] no config file found at /etc/kong.conf
2016/08/11 14:53:36 [verbose] no config file found at /etc/kong/kong.conf
2016/08/11 14:53:36 [debug] admin_listen = ""
2016/08/11 14:53:36 [debug] cluster_listen = ""
2016/08/11 14:53:36 [debug] cluster_listen_rpc = ""
2016/08/11 14:53:36 [debug] cluster_profile = "wan"
2016/08/11 14:53:36 [debug] cluster_ttl_on_failure = 3600
2016/08/11 14:53:36 [debug] database = "postgres"
2016/08/11 14:53:36 [debug] dnsmasq = true
2016/08/11 14:53:36 [debug] dnsmasq_port = 8053
2016/08/11 14:53:36 [debug] log_level = "notice"

Back to TOC

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.


log_level = debug # in kong.conf

Can be overriden with:

$ export KONG_LOG_LEVEL=error

Back to TOC

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 Penlight templating 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: It is splitted in two Nginx configuration files: nginx.lua and nginx_kong.lua. The former is minimalistic and includes the later, which contains everything Kong requires to run. Moments before starting Nginx, those two files are copied into the prefix directory, which looks like so:

├── 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:

# ---------------------
# custom_nginx.template
# ---------------------

worker_processes ${{NGINX_WORKER_PROCESSES}}; # can be set by kong.conf
daemon ${{NGINX_DAEMON}};                     # can be set by kong.conf

pid pids/;                      # this setting is mandatory
error_log logs/error.log ${{LOG_LEVEL}}; # can be set by kong.conf

events {
    use epoll; # custom setting
    multi_accept on;

http {
    # include default Kong Nginx config
    include 'nginx-kong.conf';

    # custom server
    server {
        server_name custom_server;
        listen 8888;
        location / {
          ... # etc

You can then start Kong with:

$ kong start -c kong.conf --nginx-conf custom_nginx.template

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:

# ---------------------
# custom_nginx.template
# ---------------------

worker_processes ${{NGINX_WORKER_PROCESSES}}; # can be set by kong.conf
daemon ${{NGINX_DAEMON}};                     # can be set by kong.conf

pid pids/;                      # this setting is mandatory
error_log logs/error.log ${{LOG_LEVEL}}; # can be set by kong.conf

events {}

http {
  resolver ${{DNS_RESOLVER}} ipv6=off;
  charset UTF-8;
  error_log logs/error.log ${{LOG_LEVEL}};
  access_log logs/access.log;

  ... # etc

Back to TOC

Embed 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). However, you will need the final configuration and not the template. For this, use the compile command, which outputs a fully-compiled Nginx sub-configuration to stdout:

$ bin/kong compile --conf kong.conf > /usr/local/openresty/conf/nginx-kong.conf

# now start OpenResty with a configuration that "includes" nginx-kong.conf
$ nginx -c /usr/local/openresty/conf/nginx.conf
Note: When embedding Kong this way, you will have to ensure the required third-party services are already running and configured correctly according to the kong.conf used to compile the Nginx sub-configuration. This include the database, serf, and dnsmasq if enabled.

Back to TOC

Properties reference

General section


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 of the Nginx server. Logs can be found at <prefix>/logs/error.log

See for a list of accepted values.

Default: notice


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


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

Default: on

Back to TOC

Nginx section


Address and port on which Kong will accept HTTP requests. This is the public-facing entrypoint of Kong, to which your consumers will make requests to.

See for a description of the accepted formats for this and other *_listen values.




Address and port on which Kong will accept HTTPS requests if ssl is enabled.




Address and port on which Kong will expose an entrypoint to the Admin API. This API lets you configure and manage Kong, and should be kept private and secured.




Determines the number of worker processes spawned by Nginx. See for detailed usage of this directive and a description of accepted values.

Default: auto


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


Default: on


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


Determines if Nginx should be listening for HTTPS traffic on the proxy_listen_ssl address. If disabled, Nginx will only bind itself on proxy_listen, and all SSL settings will be ignored.

Default: on


If ssl is enabled, the absolute path to the SSL certificate for the proxy_listen_ssl address. If none is specified and ssl is enabled, Kong will generate a default certificate and key.

Default: none


If ssl is enabled, the absolute path to the SSL key for the proxy_listen_ssl address.

Default: none

Back to TOC

Datastore section

Kong will store all of its data (such as APIs, consumers and plugins) in either Cassandra or PostgreSQL.

All Kong nodes belonging to the same cluster must connect themselves to the same database.


Determines which of PostgreSQL or Cassandra this node will use as its datastore. Accepted values are postgres and cassandra.

Default: postgres

Postgres settings
name description
pg_host Host of the Postgres server
pg_port Port of the Postgres server
pg_user Postgres user
pg_password Postgres user's password
pg_database Database to connect to. must exist
pg_ssl Enable SSL connections to the server
pg_ssl_verify If pg_ssl is enabled, toggle server certificate verification. See lua_ssl_trusted_certificate setting.

Cassandra settings
name description
cassandra_contact_points Comma-separated list of contacts points to your cluster
cassandra_port Port on which your nodes are listening.
cassandra_keyspace Keyspace to use in your cluster. Will be created if doesn't exist.
cassandra_consistency Consistency setting to use when reading/writing
cassandra_timeout Timeout (in ms) for reading/writing
cassandra_ssl Enable SSL connections to the nodes
cassandra_ssl_verify If cassandra_ssl is enabled, toggle server certificate verification. See lua_ssl_trusted_certificate setting.
cassandra_username Username when using the PasswordAuthenticator scheme
cassandra_password Password when using the PasswordAuthenticator scheme
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

Back to TOC

Clustering section

In addition to pointing to the same database, each Kong node must join the same cluster.

Kong's clustering works on the IP layer (hostnames are not supported, only IPs) and expects a flat network topology without any NAT between the datacenters.

A common pattern is to create a VPN between the two datacenters such that the flat network assumption is not violated.

See the clustering reference for more informations:


Address and port used to communicate with other nodes in the cluster. All other Kong nodes in the same cluster must be able to communicate over both TCP and UDP on this address. Only IPv4 addresses are supported.



Address and port used to communicate with the cluster through the agent running on this node. Only contains TCP traffic local to this node.



By default, the cluster_listen address is advertised over the cluster. If the cluster_listen host is '', then the first local, non-loopback IPv4 address will be advertised to other nodes. However, in some cases (specifically NAT traversal), there may be a routable address that cannot be bound to. This flag enables advertising a different address to support this.

Default: none


Base64-encoded 16-bytes key to encrypt cluster traffic with.

Default: none


Time to live (in seconds) of a node in the cluster when it stops sending healthcheck pings, possibly caused by a node or network failure. If a node is not able to send a new healthcheck ping before the expiration, other nodes in the cluster will stop attempting to connect to it.

Recommended to be at least 60.

Default: 3600


The timing profile for inter-cluster pings and timeouts. If a lan or local profile is used over the Internet, a high rate of failures is risked as the timing contraints would be too tight.

Accepted values are local, lan, wan.

Default: wan

Back to TOC

DNS resolver section


Toggles if Kong should start/stop dnsmasq, which can be used as the Nginx DNS resolver. Using dnsmasq allows Nginx to resolve domains defined in /etc/hosts.

dnsmasq must be installed and available in your $PATH.

Default: on


The port on which dnsmasq should listen to for queries.

Default: 8053


Configure a name server to be used by Nginx.

Only valid when dnsmasq is disabled.


Back to TOC

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


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.


Default: none


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.


Default: 1


When disabled, every request will run in a separate Lua VM instance: all Lua modules will be loaded from scratch. Useful for adopting an edit-and-refresh approach while developing a plugin.

Turning this directive off has a severe impact on performance.


Default: on


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


Default: none


Sets the Lua C module search path (LUA_CPATH).


Default: none

Back to TOC