July 12, 2018
2 min read

Kong CE 0.14 Feature Review – Nginx Injected Directives

Mike Bilodeau

As part of our series helping you get up to speed on the new features released in Kong CE 0.14, we want to dive into one of our most exciting and long-awaited features - Dynamic Injection for Nginx Directives. This new feature enables Kong users to easily exercise greater control over their Nginx configurations and eliminate tedious maintenance work to maintain configurations through new Kong releases.

As you are likely aware, Kong ships with a Nginx template that renders when Kong starts. This allows folks to easily get started with Kong, but it also creates challenges for users that want to modify their Nginx configurations. Before this release, there was no mechanism to add or update a Nginx directive within the Nginx.conf used to run Kong. Instead users had to create a custom Nginx template which they needed to update every time that they updated Kong. This created time-consuming maintenance work and the potential for unforeseen issues.

Fortunately, dynamic injection of Nginx directives eliminates these challenges. In CE 0.14 Kong users can now specify any Nginx directive directly in their Kong config file, removing the need to constantly update the Nginx config. To accomplish this, Kong users can specify Nginx directives by using config variables with prefixes, helping to determine the block in which to place a directive.

For Example:

Adding the following line in your kong.conf:

nginx_proxy_large_client_header_buffers=8 24k

will add the following directive to the proxy `server` block of Kong's Nginx configuration file:

large_client_header_buffers 8 24k;

Like all properties in `kong.conf`, this can also be specified via environment variables:


It is also possible to include entire `server` blocks using the Nginx `include ‘directive. Here is a good example. Our Docker users can simply mount a volume on Kong's container and use the `include` directive to include custom Nginx server blocks or directives.

Kong's method of injecting Nginx directives provides dramatically improved flexibility and ease-of-use for users employing granular control over Nginx.

Benefits include:

  • Changes to Nginx are automatically reflected in Kong
  • Custom Nginx modules work out-of-the-box
  • No tedious maintenance work while upgrading Kong versions
  • Avoid changes to existing code
  • Confidence that new Nginx directives will not break Kong

At Kong, we're committed to Open Source and empowering users to make their own decisions. We know that many of our users are Nginx Ninjas that want to exercise more control over Nginx through Kong, and we are happy to make your lives easier. For users with custom Nginx modules, legacy Nginx configurations, or those that want to experiment with changes to their Nginx config, our 0.14 release will enable you to modify Nginx directives easily and without risk to production.

And of course, thank you to our open source contributors, core maintainers (@hisham@bungle@kikito) and other Kong Inc. employees who all contributed a great lot to this release!

Happy Konging!