Nginx Directives

Injecting individual Nginx directives

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

See the NGINX Injected Directives section for all supported namespaces.

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

  1. nginx_proxy_large_client_header_buffers=16 128k

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:

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

Including files via injected Nginx directives

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. # custom server
  2. server {
  3.   listen 2112;
  4.   location / {
  5.     # ...more settings...
  6.     return 200;
  7.   }
  8. }

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:

  1. export KONG_NGINX_HTTP_INCLUDE="/path/to/your/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:

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

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

Custom Nginx templates and embedding Kong Gateway

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

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

Custom Nginx templates

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

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. # ---------------------
  2. # custom_nginx.template
  3. # ---------------------
  5. worker_processes ${{NGINX_WORKER_PROCESSES}}; # can be set by kong.conf
  6. daemon ${{NGINX_DAEMON}};                     # can be set by kong.conf
  8. pid pids/nginx.pid;                      # this setting is mandatory
  9. error_log logs/error.log ${{LOG_LEVEL}}; # can be set by kong.conf
  11. events {
  12.     use epoll;          # a custom setting
  13.     multi_accept on;
  14. }
  16. http {
  18.   # contents of the nginx_kong.lua template follow:
  20.   resolver ${{DNS_RESOLVER}} ipv6=off;
  21.   charset UTF-8;
  22.   error_log logs/error.log ${{LOG_LEVEL}};
  23.   access_log logs/access.log;
  25.   ... # etc
  26. }

You can then start Kong Gateway with:

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

More information