Nginx directives

You can use Nginx directives in the kong.conf file.

Entries in kong.conf that are prefixed with nginx_http_, nginx_proxy_, or nginx_admin_ are converted to Nginx directives.

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

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

• Entries prefixed with nginx_admin_ are injected into the server block directive handling Kong Gateway’s Admin API ports. See the NGINX Injected Directives section for all supported namespaces.

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

nginx_proxy_large_client_header_buffers=16 128k

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

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:

export KONG_NGINX_HTTP_OUTPUT_BUFFERS="4 64k"

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

output_buffers 4 64k;

For more details on the Nginx configuration file structure and block directives, see the Nginx reference.

For a list of Nginx directives, see the Nginx directives index.

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:

# custom server
server {
  listen 2112;
  location / {
    # ...more settings...
    return 200;
  }
}

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

nginx_http_include =./my-server.kong.conf

You can also use environment variables:

export KONG_NGINX_HTTP_INCLUDE="./my-server.kong.conf"

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:

curl -I http://127.0.0.1:2112
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 kong start if you used it to override the prefix when starting Kong Gateway.

You can use custom Nginx configuration templates directly in two cases:

• You need to modify Kong Gateway’s default Nginx configuration. Specifically, if you need to edit 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. In this case, you can reuse Kong Gateway’s generated configuration and include it in your existing configuration.

Custom Nginx templates

You can pass an --nginx-conf argument to specify an Nginx configuration template when starting, reloading, and restarting Kong Gateway with Kong CLI commands. The template uses the Penlight templating engine, which is compiled using the Kong Gateway configuration.

The following Lua functions are available in the templating engine:

• pairs, ipairs
• tostring
• os.getenv

You can find the default template by using this command on the system running your Kong Gateway instance:

find / -type d -name "templates" | grep kong

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

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

If you need to adjust global settings that are defined by Kong Gateway but aren’t configurable via parameters in kong.conf, you can inline the contents of the nginx_kong.lua configuration template into a custom template file. For example, the following file named custom_nginx.template adjusts some logging settings:

# ---------------------
# 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/nginx.pid;                      # this setting is mandatory
error_log logs/error.log ${{LOG_LEVEL}}; # can be set by kong.conf

events {
    use epoll;          # a custom setting
    multi_accept on;
}

http {

  # contents of the nginx_kong.lua template follow:

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

  ... # etc
}

You can then start Kong Gateway with:

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