Configuration Reference
Introduction
The Kong configuration file is a YAML file that can be specified when using Kong through the CLI. This file allows you to configure and customize Kong to your needs. From the ports it uses, the database it connects to, and even the internal NGINX server itself.
Where should I place my configuration file?
When using Kong, you can specify the location of your configuration file from any command using the -c
argument. See the CLI reference for more information.
However, when no configuration file is passed to Kong, it will look under /etc/kong/kong.yml
for a fallback configuration file. Should no file be present in this location, Kong will then load a default configuration from its Luarocks install path.
How do I customize my configuration?
If you browse the default configuration, you’ll notice that all properties are commented out (to the exception of the Nginx configuration). Indeed, they are all set to their default value if non-specified. If you need to customize a property, uncomment and update it.
However, beware of respecting the YAML formatting when doing so: if you uncomment a nested property, be sure to uncomment its parents too!
Properties
- custom_plugins
- nginx_working_dir
- proxy_listen
- proxy_listen_ssl
- admin_api_listen
- cluster_listen
- cluster_listen_rpc
- ssl_cert_path
- ssl_key_path
- dns_resolver
- dns_resolvers_available
- cluster
- database
- cassandra
- send_anonymous_reports
- memory_cache_size
- nginx
custom_plugins
Additional plugins that this node needs to load. If you want to load custom plugins that are not supported by Kong, uncomment and update this property with the names of the plugins to load. Plugins will be loaded from the kong.plugins.{name}.*
namespace. See the Plugin development guide for how to build your own plugins.
Default: none.
Example:
custom_plugins:
- custom-plugin
- custom-plugin-2
nginx_working_dir
The Kong working directory. Equivalent to nginx’s prefix path. This is where this running nginx instance will keep server files including logs. Make sure it has the appropriate permissions.
Default:
nginx_working_dir: /usr/local/kong/
proxy_listen
Address and port on which the server will accept HTTP requests, consumers will make requests on this port.
Default:
proxy_listen: "0.0.0.0:8000"
proxy_listen_ssl
Same as proxy_listen, but for HTTPS requests.
Default:
proxy_listen_ssl: "0.0.0.0:8443"
admin_api_listen
Address and port on which the RESTful Admin API will listen to. The admin API is a private API which lets you manage your Kong infrastructure. It needs to be secured appropriately.
Default:
admin_api_listen: "0.0.0.0:8001"
cluster_listen
Address and port used by the node to communicate with other Kong nodes in the cluster with both UDP and TCP messages. All the nodes in the cluster must be able to communicate with this node on this address. Only IPv4 addresses are allowed (no hostnames).
For more information take a look at the Clustering Reference.
Default:
cluster_listen: "0.0.0.0:7946"
cluster_listen_rpc
Address and port used by the node to communicate with the local clustering agent (TCP only, and local only). Used internally by this Kong node. Only IPv4 addresses are allowed (no hostnames).
For more information take a look at the Clustering Reference.
Default:
cluster_listen_rpc: "127.0.0.1:7373"
ssl_cert_path
The path to the SSL certificate that Kong will use when listening on the https
port.
Default:
By default this property is commented out, which will force Kong to use an auto-generated self-signed certificate stored in the working directory (nginx_working_dir
).
# ssl_cert_path: /path/to/certificate.pem
ssl_key_path
The path to the SSL certificate key that Kong will use when listening on the https
port.
Default:
By default this property is commented out, which will force Kong to use an auto-generated self-signed certificate key stored in the working directory (nginx_working_dir
).
# ssl_key_path: /path/to/certificate.key
dns_resolver
The desired DNS resolver to use for this Kong instance as a string, matching one of the DNS resolvers defined under dns_resolvers_available
.
Default:
dns_resolver: dnsmasq
dns_resolvers_available
A dictionary of DNS resolvers Kong can use, and their respective properties. Currently dnsmasq
(default) and server
are supported.
By choosing dnsmasq
, Kong will resolve hostnames using the local /etc/hosts
file and resolv.conf
configuration. By choosing server
, you can specify a custom DNS server.
Default:
dns_resolvers_available:
# server:
# address: "8.8.8.8:53"
dnsmasq:
port: 8053
dns_resolvers_available.server.address
The address to a custom DNS server, in the address:port
format.
dns_resolvers_available.dnsmasq.port
Port where Dnsmasq will listen to. Dnsmasq is only used locally, therefore will always listen on 127.0.0.1
.
cluster
Cluster settings between Kong nodes. For more information take a look at the Clustering Reference.
Default:
## Cluster settings
cluster:
# advertise: ""
# encrypt: "foo"
advertise
Address and port used by the node to communicate with other Kong nodes in the cluster with both UDP and TCP messages. All the nodes in the cluster must be able to communicate with this node on this address. Only IPv4 addresses are allowed (no hostnames).
The advertise flag is used to change the address that we advertise to other nodes in the cluster. By default, the cluster_listen
address is advertised. If the cluster_listen
host is 0.0.0.0
, then the first local, non-loopback, IPv4 address will be advertised to the other nodes. However, in some cases (specifically NAT traversal), there may be a routable address that cannot be bound to. This flag enables gossiping a different address to support this.
encrypt
Key for encrypting network traffic within Kong. Must be a base64-encoded 16-byte key.
database
The name of the desired database to use. Currently, Kong only supports Cassandra as its datastore.
Default:
database: cassandra
cassandra
A dictionary holding the properties for Kong to connect to your Cassandra cluster.
Example:
cassandra:
contact_points:
- "localhost:9042"
keyspace: kong
cassandra.contact_points
The contact points on which Kong should connect to for accessing your Cassandra cluster. Can either be a string or a list of strings containing the host and the port of your node(s).
Example:
contact_points:
- "52.5.149.55:9042"
- "52.5.149.56:9042"
cassandra.keyspace
The keyspace in which Kong operates on your cluster.
Default:
keyspace: kong
Keyspace options
Set those before running Kong or any migration. Those settings will be used to create a keyspace with the desired options when first running the migrations. If your keyspace already exists, you will have to manually update its options.
See the CQL 3.1 documentation for a better understanding of those settings.
cassandra.replication_strategy
The name of the replica placement strategy class to use for the keyspace. Can be “SimpleStrategy” or “NetworkTopologyStrategy”.
Default:
replication_strategy: SimpleStrategy
cassandra.replication_factor
For SimpleStrategy only. The number of replicas of data on multiple nodes.
Default:
replication_factor: 1
cassandra.data_centers
For NetworkTopologyStrategy only. The number of replicas of data on multiple nodes in each data center.
Default: none.
Example:
data_centers:
- dc1
- dc2
SSL Options
cassandra.ssl.enabled
Enable client-to-node encryption with your Cassandra cluster.
Default:
ssl:
enabled: false
cassandra.ssl.verify
Enable SSL certificate verification. If true, a certificate_authority
must also be provided.
Default:
ssl:
verify: false
cassandra.ssl.certificate_authority
Absolute path to the certificate authority file in PEM format. This property will set the certificate to the ngx_lua lua_ssl_trusted_certificate
directive.
Example:
ssl:
enabled: true
verify: true
certificate_authority: "/path/to/cluster-ca-certificate.pem"
Authentication options
cassandra.user
Provide a user here if your cluster uses the PasswordAuthenticator scheme.
Default: none.
Example:
user: cassandra
cassandra.password
Provide a password here if your cluster uses the PasswordAuthenticator scheme.
Default: none.
Example:
password: cassandra
send_anonymous_reports
If set to true
, Kong will collect anonymous error reports which helps us maintain and improve Kong.
Default:
send_anonymous_reports: true
memory_cache_size
A value specifying (in MB) the size of the internal preallocated in-memory cache. Kong uses an in-memory cache to store database entities in order to optimize access to the underlying datastore. The cache size needs to be as big as the size of the entities being used by Kong at any given time. The default value is 128
, and the potential maximum value is the total size of the datastore. This value may not be smaller than 32MB.
Default:
memory_cache_size: 128 # in megabytes
nginx
The NGINX configuration (or nginx.conf
) that will be used for this instance. The placeholders will be computed and this property will be written as a file by Kong at <nginx_working_dir>/nginx.conf
during startup.
Warning: Modifying the NGINX configuration can lead to unexpected results, edit the configuration only if you are confident about doing so.
Default:
nginx: |
worker_processes auto;
error_log logs/error.log error;
daemon on;
worker_rlimit_nofile {{auto_worker_rlimit_nofile}};
env KONG_CONF;
events {
worker_connections {{auto_worker_connections}};
multi_accept on;
}
http {
resolver {{dns_resolver}} ipv6=off;
charset UTF-8;
access_log logs/access.log;
access_log off;
# Timeouts
keepalive_timeout 60s;
client_header_timeout 60s;
client_body_timeout 60s;
send_timeout 60s;
# Proxy Settings
proxy_buffer_size 128k;
proxy_buffers 4 256k;
proxy_busy_buffers_size 256k;
proxy_ssl_server_name on;
# IP Address
real_ip_header X-Forwarded-For;
set_real_ip_from 0.0.0.0/0;
real_ip_recursive on;
# Other Settings
client_max_body_size 0;
underscores_in_headers on;
reset_timedout_connection on;
tcp_nopush on;
################################################
# The following code is required to run Kong #
# Please be careful if you'd like to change it #
################################################
# Lua Settings
lua_package_path ';;';
lua_code_cache on;
lua_max_running_timers 4096;
lua_max_pending_timers 16384;
lua_shared_dict reports_locks 100k;
lua_shared_dict cluster_locks 100k;
lua_shared_dict cache {{memory_cache_size}}m;
lua_shared_dict cassandra 1m;
lua_shared_dict cassandra_prepared 5m;
lua_socket_log_errors off;
{{lua_ssl_trusted_certificate}}
init_by_lua '
kong = require "kong"
local status, err = pcall(kong.init)
if not status then
ngx.log(ngx.ERR, "Startup error: "..err)
os.exit(1)
end
';
init_worker_by_lua 'kong.exec_plugins_init_worker()';
server {
server_name _;
listen {{proxy_listen}};
listen {{proxy_listen_ssl}} ssl;
ssl_certificate_by_lua 'kong.exec_plugins_certificate()';
ssl_certificate {{ssl_cert}};
ssl_certificate_key {{ssl_key}};
ssl_protocols TLSv1 TLSv1.1 TLSv1.2;# omit SSLv3 because of POODLE (CVE-2014-3566)
location / {
default_type 'text/plain';
# These properties will be used later by proxy_pass
set $upstream_host nil;
set $upstream_url nil;
# Authenticate the user and load the API info
access_by_lua 'kong.exec_plugins_access()';
# Proxy the request
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Host $upstream_host;
proxy_pass $upstream_url;
proxy_pass_header Server;
# Add additional response headers
header_filter_by_lua 'kong.exec_plugins_header_filter()';
# Change the response body
body_filter_by_lua 'kong.exec_plugins_body_filter()';
# Log the request
log_by_lua 'kong.exec_plugins_log()';
}
location /robots.txt {
return 200 'User-agent: *\nDisallow: /';
}
error_page 500 /500.html;
location = /500.html {
internal;
content_by_lua '
local responses = require "kong.tools.responses"
responses.send_HTTP_INTERNAL_SERVER_ERROR("An unexpected error occurred")
';
}
}
server {
listen {{admin_api_listen}};
client_max_body_size 10m;
client_body_buffer_size 10m;
location / {
default_type application/json;
content_by_lua '
ngx.header["Access-Control-Allow-Origin"] = "*"
if ngx.req.get_method() == "OPTIONS" then
ngx.header["Access-Control-Allow-Methods"] = "GET,HEAD,PUT,PATCH,POST,DELETE"
ngx.header["Access-Control-Allow-Headers"] = "Content-Type"
ngx.exit(204)
end
local lapis = require "lapis"
lapis.serve("kong.api.app")
';
}
location /nginx_status {
internal;
access_log off;
stub_status;
}
location /robots.txt {
return 200 'User-agent: *\nDisallow: /';
}
}
}