Skip to content
Kong Logo | Kong Docs Logo
search
  • We're Hiring!
  • Docs
    • Kong Gateway
    • Kong Konnect
    • Kong Mesh
    • Plugin Hub
    • decK
    • Kubernetes Ingress Controller
    • Insomnia
    • Kuma

    • Docs contribution guidelines
  • Plugin Hub
  • Support
  • Community
  • Kong Academy
Get a Demo Start Free Trial
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Plugin Hub
  • decK
  • Kubernetes Ingress Controller
  • Insomnia
  • Kuma

  • Docs contribution guidelines
  • 3.2.x (latest)
  • 3.1.x
  • 3.0.x
  • 2.8.x
  • 2.7.x
  • 2.6.x
  • Older Enterprise versions (2.1-2.5)
  • Older OSS versions (2.1-2.5)
  • Archive (pre-2.1)
    • Overview of Kong Gateway
      • Version Support Policy
      • Supported Installation Options
      • Supported Linux Distributions
    • Stability
    • Release Notes
      • Services
        • Overview
        • Configure Routes with Expressions
      • Upstreams
      • Plugins
      • Routing Traffic
      • Load Balancing
      • Health Checks and Circuit Breakers
      • Kong Performance Testing
    • Glossary
    • Get Kong
    • Services and Routes
    • Rate Limiting
    • Proxy Caching
    • Key Authentication
    • Load-Balancing
      • Overview
        • Overview
        • Deploy Kong Gateway in Hybrid mode
      • DB-less Deployment
      • Traditional
      • Overview
        • Helm
        • OpenShift with Helm
        • kubectl apply
        • Kubernetes Deployment Options
        • Using docker run
        • Build your own Docker images
        • Amazon Linux
        • Debian
        • Red Hat
        • Ubuntu
      • Running Kong as a non-root user
      • Securing the Admin API
      • Using systemd
      • Start Kong Gateway Securely
      • Programatically Creating Admins
      • Enabling RBAC
      • Overview
      • Download your License
      • Deploy Enterprise License
      • Using the License API
      • Monitor Licenses Usage
      • Default Ports
      • DNS Considerations
      • Network and Firewall
      • CP/DP Communication through a Forward Proxy
    • Kong Configuration File
    • Environment Variables
    • Serving a Website and APIs from Kong
      • Overview
      • Prometheus
      • StatsD
      • Datadog
      • Overview
      • Writing a Custom Trace Exporter
      • Tracing API Reference
    • Resource Sizing Guidelines
    • Security Update Process
    • Blue-Green Deployments
    • Canary Deployments
    • Clustering Reference
      • Log Reference
      • Dynamic log level updates
      • Customize Gateway Logs
      • Upgrade Kong Gateway 3.1.x
      • Migrate from OSS to Enterprise
    • Overview
      • Overview
      • Metrics
      • Analytics with InfluxDB
      • Analytics with Prometheus
      • Estimate Analytics Storage in PostgreSQL
      • Overview
      • Getting Started
      • Advanced Usage
        • Overview
        • Environment Variables
        • AWS Secrets Manager
        • Google Secrets Manager
        • Hashicorp Vault
        • Securing the Database with AWS Secrets Manager
      • Reference Format
      • Overview
      • Get Started with Dynamic Plugin Ordering
      • Overview
      • Enable the Dev Portal
      • Publish an OpenAPI Spec
      • Structure and File Types
      • Themes Files
      • Working with Templates
      • Using the Editor
        • Basic Auth
        • Key Auth
        • OIDC
        • Sessions
        • Adding Custom Registration Fields
        • Manage Developers
        • Developer Roles and Content Permissions
        • Authorization Provider Strategy
        • Enable Application Registration
        • Enable Key Authentication for Application Registration
          • External OAuth2 Support
          • Set up Okta and Kong for External Oauth
          • Set up Azure AD and Kong for External Authentication
        • Manage Applications
        • Theme Editing
        • Migrating Templates Between Workspaces
        • Markdown Rendering Module
        • Customizing Portal Emails
        • Adding and Using JavaScript Assets
        • Single Page App in Dev Portal
        • Alternate OpenAPI Renderer
      • SMTP
      • Workspaces
      • Helpers CLI
      • Portal API Documentation
    • Audit Logging
    • Keyring and Data Encryption
    • Workspaces
    • Consumer Groups
    • Event Hooks
    • FIPS 140-2
    • Overview
    • Enable Kong Manager
      • Services and Routes
      • Rate Limiting
      • Proxy Caching
      • Authentication with Consumers
      • Load Balancing
      • Overview
      • Create a Super Admin
      • Workspaces and Teams
      • Reset Passwords and RBAC Tokens
      • Basic Auth
        • Configure LDAP
        • LDAP Service Directory Mapping
        • Configure OIDC
        • OIDC Authenticated Group Mapping
      • Sessions
        • Overview
        • Enable RBAC
        • Add a Role and Permissions
        • Create a User
        • Create an Admin
    • Networking Configuration
    • Workspaces
    • Create Consumer Groups
    • Sending Email
    • Overview
    • File Structure
    • Implementing Custom Logic
    • Plugin Configuration
    • Accessing the Data Store
    • Storing Custom Entities
    • Caching Custom Entities
    • Extending the Admin API
    • Writing Tests
    • (un)Installing your Plugin
      • Overview
      • kong.client
      • kong.client.tls
      • kong.cluster
      • kong.ctx
      • kong.ip
      • kong.jwe
      • kong.log
      • kong.nginx
      • kong.node
      • kong.request
      • kong.response
      • kong.router
      • kong.service
      • kong.service.request
      • kong.service.response
      • kong.table
      • kong.tracing
      • kong.vault
      • kong.websocket.client
      • kong.websocket.upstream
      • Go
      • Javascript
      • Python
      • Running Plugins in Containers
      • External Plugin Performance
    • Overview
        • Overview
        • OpenID Connect with Curity
        • OpenID Connect with Azure AD
        • OpenID Connect with Google
        • OpenID Connect with Okta
        • OpenID Connect with Auth0
        • OpenID Connect with Cognito
      • Authentication Reference
      • Allow Multiple Authentication Plugins
    • Rate Limiting Plugin
      • Add a Body Value
    • GraphQL
      • gRPC Plugins
      • Configure a gRPC service
    • Overview
    • Information Routes
    • Health Routes
    • Tags
    • Debug Routes
    • Services
    • Routes
    • Consumers
    • Plugins
    • Certificates
    • CA Certificates
    • SNIs
    • Upstreams
    • Targets
    • Vaults
    • Keys
    • Licenses
    • Workspaces
    • RBAC
    • Admins
    • Developers
    • Consumer Groups
    • Event Hooks
    • Keyring and Data Encryption
    • Audit Logs
    • kong.conf
    • Injecting Nginx Directives
    • CLI
    • File Permissions Reference
    • Key Management
    • Performance Testing Framework
    • Router Expressions Language
    • FAQ

github-edit-pageEdit this page

report-issueReport an issue

enterprise-switcher-iconSwitch to OSS

On this page
  • Injecting individual Nginx directives
  • Including files via injected Nginx directives
  • Custom Nginx templates
Kong Gateway
3.1.x
  • Home
  • Kong Gateway
  • Reference
  • Nginx Directives
You are browsing documentation for an outdated version. See the latest documentation here.

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.

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.

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:

# 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 = /path/to/your/my-server.kong.conf

You can also use environment variables:

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:

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

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:

/usr/local/kong
├── nginx-kong.conf
└── 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:

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

More information

  • How to use kong.conf
  • How to serve an API and a website with Kong

Thank you for your feedback.
Was this page useful?
  • Kong
    THE CLOUD CONNECTIVITY COMPANY

    Kong powers reliable digital connections across APIs, hybrid and multi-cloud environments.

    • Company
    • Customers
    • Events
    • Investors
    • Careers Hiring!
    • Partners
    • Press
    • Contact
  • Products
    • Kong Konnect
    • Kong Gateway
    • Kong Mesh
    • Get Started
    • Pricing
  • Resources
    • eBooks
    • Webinars
    • Briefs
    • Blog
    • API Gateway
    • Microservices
  • Open Source
    • Install Kong Gateway
    • Kong Community
    • Kubernetes Ingress
    • Kuma
    • Insomnia
  • Solutions
    • Decentralize
    • Secure & Govern
    • Create a Dev Platform
    • API Gateway
    • Kubernetes
    • Service Mesh
Star
  • Terms•Privacy
© Kong Inc. 2023