Nginx Directives

  • Entries prefixed with nginx_http_ will be injected into the overall http block directive.

  • Entries prefixed with nginx_proxy_ will be injected into the server block directive handling Kong Gateway’s proxy ports.

  • Entries prefixed with nginx_admin_ will be injected into the server block directive handling Kong Gateway’s Admin API ports.

For example, if you add the following line to your kong.conf file:

It adds the following directive to the proxy server block of Kong Gateway’s Nginx configuration:

  1. large_client_header_buffers 16 128k;

These directives can also be specified using environment variables. For example, if you declare an environment variable like this:

  1. export KONG_NGINX_HTTP_OUTPUT_BUFFERS="4 64k"

This results in the following Nginx directive being added to the http block:

For a list of Nginx directives, see the .

Complex configurations may require adding new server blocks to an Nginx configuration. You can inject include directives into an Nginx configuration that point to Nginx settings files.

For example, if you create a file called my-server.kong.conf with the following contents:

  1. server {
  2.   listen 2112;
  3.   location / {
  4.     # ...more settings...
  5.     return 200;
  6.   }
  7. }

You can make the Kong Gateway node serve this port by adding the following entry to your kong.conf file:

  1. nginx_http_include = /path/to/your/my-server.kong.conf

You can also use environment variables:

When you start Kong Gateway, the server section from that file will be added to that file, meaning that the custom server defined in it will be responding, alongside the regular Kong Gateway ports:

  1. curl -I http://127.0.0.1:2112
  2. HTTP/1.1 200 OK

If you use a relative path in an nginx_http_include property, that path will be interpreted relative to the value of the prefix property of your kong.conf file (or the value of the -p flag of if you used it to override the prefix when starting Kong Gateway).

  • You need to modify Kong Gateway’s default Nginx configuration. Specifically values that are not adjustable in kong.conf, you can modify the template used by Kong Gateway for producing its Nginx configuration and launch Kong Gateway using your customized template.

  • You need to embed Kong Gateway in an already running OpenResty instance, you can reuse Kong Gateway’s generated configuration and include it in your existing configuration.

Kong Gateway can be started, reloaded and restarted with an --nginx-conf argument, which must specify an Nginx configuration template. Such a template uses the templating engine, which is compiled using the Kong Gateway configuration.

The following Lua functions are available in the :

  • pairs, ipairs
  • tostring
  • os.getenv

The default template for Kong Gateway can be found using this command on the system running your Kong Gateway instance: find / -type d -name "templates" | grep kong. For open-source Kong Gateway, you can also see the templates directory.

The template is split in two Nginx configuration files: nginx.lua and nginx_kong.lua. The former is minimal and includes the latter, which contains everything Kong Gateway requires to run. When kong start runs, right before starting Nginx, it copies these two files into the prefix directory, which looks like so:

  1. /usr/local/kong
  2. ├── nginx-kong.conf
  3. └── nginx.conf

If you must tweak global settings that are defined by Kong Gateway but not adjustable via the Kong Gateway configuration in kong.conf, you can inline the contents of the nginx_kong.lua configuration template into a custom template file (in this example called custom_nginx.template) like this:

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

More information