Careful! You are browsing documentation for an outdated version of Kong. Go here to browse the documentation for the latest version.

Configuration Reference

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

Property Reference

This reference describes every property defined in a typical configuration file and their default values.

They are all required.

Summary


proxy_port

Port which Kong proxies requests through, developers using your API will make requests against this port.

Default:

proxy_port: 8000

proxy_ssl_port

Port which Kong proxies requests through under https, developers using your API will make requests against this port.

Default:

proxy_ssl_port: 8443

admin_api_port

Port which the RESTful Admin API is served through.

Note: This port is used to manage your Kong instances, therefore it should be placed behind a firewall or closed off network to ensure security.

Default:

admin_api_port: 8001

dnsmasq_port

Port where Dnsmasq will listen to.

Note: This port is used to properly resolve DNS addresses by Kong, therefore it should be placed behind a firewall or closed off network to ensure security.

Default:

dnsmasq_port: 8053

nginx_working_dir

Similar to the NGINX --prefix option, it defines a directory that will contain server files, such as access and error logs, or the Kong pid file.

Default:

nginx_working_dir: /usr/local/kong/

plugins_available

A list of plugins installed on this node that Kong will load and try to execute during the lifetime of a request. Kong will look for a plugin configuration entry for each plugin in this list during each request to determine whether the plugin should be executed. Removing plugins from this list will reduce load on your Kong instance.

Default:

plugins_available:
  - keyauth
  - basicauth
  - ratelimiting
  - tcplog
  - httplog
  - udplog
  - filelog
  - request_transformer
  - cors
  - requestsizelimiting

send_anonymous_reports

If set to true, Kong will send anonymous error reports to Mashape. This helps Mashape maintaining and improving Kong.

Default:

send_anonymous_reports: true

databases_available

A dictionary of databases Kong can connect to, and their respective properties.

Currently, Kong only supports Cassandra v2.2.x as a database.

Note: If you don't want to manage/scale your own Cassandra cluster, we suggest using Instaclustr for Cassandra in the cloud.

Default:

databases_available:
  cassandra:
    properties:
      hosts:
        - "localhost:9042"
      timeout: 1000
      keyspace: kong
      keepalive: 60000

databases_available.*.properties

A dictionary of properties needed for Kong to connect to a given database (where .* is the name of the database).

databases_available.*.properties.hosts

The hosts(s) 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:

properties:
  hosts:
    - "52.5.149.55"      # will connect on port 9042 (default)
    - "52.5.149.56:9000" # will connect on port 9000

databases_available.*.properties.timeout

Sets the timeout (in milliseconds) for sockets performing operations between Kong and Cassandra.

Default:

timeout: 1000

databases_available.*.properties.keyspace

The keyspace in which Kong operates on your cluster.

Default:

keyspace: kong

databases_available.*.properties.user

User to authenticate with if your cluster has authentication enabled.

Example:

user: cassandra

databases_available.*.properties.password

The password to use if your cluster has authentication enabled.

Example:

password: cassandra

databases_available.*.properties.ssl

Enable client-to-node encryption with your Cassandra cluster.

Default:

ssl: false

databases_available.*.properties.ssl_verify

Enable SSL certificate verification. If true, an ssl_certificate must also be provided.

Default:

ssl_verify: false

databases_available.*.properties.ssl_certificate

Absolute path to the certificate authority file.

Example:

ssl_certificate: "/path/to/cluster-ca-certificate.pem"

databases_available.*.properties.keepalive

The time (in milliseconds) during which Cassandra sockets can be reused by Kong before being closed.

Default:

keepalive: 60000

database

The desired database to use for this Kong instance as a string, matching one of the databases defined under databases_available.

Default:

database: cassandra

database_cache_expiration

A value specifying (in seconds) how long Kong will keep database entities in memory. Setting this to a high value will cause Kong to avoid making multiple queries to the database in order to retrieve an API's target URL. However, this also means you may be required to wait a while before the cached value is flushed and reflects any potential changes made during that time.

Default:

database_cache_expiration: 5 # in seconds

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

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.

Default:

memory_cache_size: 128 # in megabytes

nginx

The NGINX configuration (or nginx.conf) that will be used for this instance.

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}};
    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 128m;
    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 cache {{memory_cache_size}}m;
    lua_socket_log_errors off;


    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
    ';

    server {
      server_name _;
      listen {{proxy_port}};
      listen {{proxy_ssl_port}} ssl;

      ssl_certificate_by_lua 'kong.exec_plugins_certificate()';

      ssl_certificate {{ssl_cert}};
      ssl_certificate_key {{ssl_key}};

      location / {
        default_type 'text/plain';

        # This property will be used later by proxy_pass
        set $backend_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_pass $backend_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_port}};

      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.exit(204)
          end
          local lapis = require "lapis"
          lapis.serve("kong.api.app")
        ';
      }

      location /nginx_status {
        internal;
        stub_status;
      }

      location /robots.txt {
        return 200 'User-agent: *\nDisallow: /';
      }

      # Do not remove, additional configuration placeholder for some plugins
      # {{additional_configuration}};
    }
  }