You are browsing documentation for an older version. See the latest documentation here.

Configuration Reference for Kong Gateway

Reference for Kong Gateway configuration parameters. Set these parameters in kong.conf.

To learn more about the kong.conf file, see the guide on using the Kong Configuration File.

You can also manage all Kong Gateway configuration parameters using environment variables.

General section

prefix

Working directory. Equivalent to Nginx’s prefix path, containing temporary files and logs.

Each Kong process must have a separate working directory.

Default: /usr/local/kong/

log_level

Log level of the Nginx server. Logs are found at <prefix>/logs/error.log.

See http://nginx.org/en/docs/ngx_core_module.html#error_log for a list of accepted values.

Default: notice

proxy_access_log

Path for proxy port request access logs. Set this value to off to disable logging proxy requests.

If this value is a relative path, it will be placed under the prefix location.

Default: logs/access.log

proxy_error_log

Path for proxy port request error logs. The granularity of these logs is adjusted by the log_level property.

Default: logs/error.log

proxy_stream_access_log

Path for tcp streams proxy port access logs. Set this value to off to disable logging proxy requests.

If this value is a relative path, it will be placed under the prefix location.

basic is defined as '$remote_addr [$time_local] ' '$protocol $status $bytes_sent $bytes_received ' '$session_time'

Default: logs/access.log basic

proxy_stream_error_log

Path for tcp streams proxy port request error logs. The granularity of these logs is adjusted by the log_level property.

Default: logs/error.log

admin_access_log

Path for Admin API request access logs. If Hybrid Mode is enabled and the current node is set to be the Control Plane, then the connection requests from Data Planes are also written to this file with server name “kong_cluster_listener”.

Set this value to off to disable logging Admin API requests.

If this value is a relative path, it will be placed under the prefix location.

Default: logs/admin_access.log

admin_error_log

Path for Admin API request error logs. The granularity of these logs is adjusted by the log_level property.

Default: logs/error.log

status_access_log

Path for Status API request access logs. The default value of off implies that logging for this API is disabled by default.

If this value is a relative path, it will be placed under the prefix location.

Default: off

status_error_log

Path for Status API request error logs. The granularity of these logs is adjusted by the log_level property.

Default: logs/status_error.log

debug_access_log

Path for Debug API request access logs. The default value of off implies that logging for this API is disabled by default.

If this value is a relative path, it will be placed under the prefix location.

Default: off

debug_error_log

Path for Debug API request error logs. The granularity of these logs is adjusted by the log_level property.

Default: logs/debug_error.log

vaults

Comma-separated list of vaults this node should load. By default, all the bundled vaults are enabled.

The specified name(s) will be substituted as such in the Lua namespace: kong.vaults.{name}.*.

Default: bundled

opentelemetry_tracing

Deprecated: use tracing_instrumentations instead

Default: off

tracing_instrumentations

Comma-separated list of tracing instrumentations this node should load. By default, no instrumentations are enabled.

Valid values to this setting are:

• off: do not enable instrumentations.
• request: only enable request-level instrumentations.
• all: enable all the following instrumentations.
• db_query: trace database query.
• dns_query: trace DNS query.
• router: trace router execution, including router rebuilding.
• http_client: trace OpenResty HTTP client requests.
• balancer: trace balancer retries.
• plugin_rewrite: trace plugins iterator execution with rewrite phase.
• plugin_access: trace plugins iterator execution with access phase.
• plugin_header_filter: trace plugins iterator execution with header_filter phase.

Note: In the current implementation, tracing instrumentations are not enabled in stream mode.

Default: off

opentelemetry_tracing_sampling_rate

Deprecated: use tracing_sampling_rate instead

Default: 1.0

tracing_sampling_rate

Tracing instrumentation sampling rate.

Tracer samples a fixed percentage of all spans following the sampling rate.

Example: 0.25, this should account for 25% of all traces.

Default: 0.01

plugins

Comma-separated list of plugins this node should load. By default, only plugins bundled in official distributions are loaded via the bundled keyword.

Loading a plugin does not enable it by default, but only instructs Kong to load its source code, and allows to configure the plugin via the various related Admin API endpoints.

The specified name(s) will be substituted as such in the Lua namespace: kong.plugins.{name}.*.

When the off keyword is specified as the only value, no plugins will be loaded.

bundled and plugin names can be mixed together, as the following examples suggest:

• plugins = bundled,custom-auth,custom-log will include the bundled plugins plus two custom ones
• plugins = custom-auth,custom-log will only include the custom-auth and custom-log plugins.
• plugins = off will not include any plugins

Note: Kong will not start if some plugins were previously configured (i.e.

have rows in the database) and are not specified in this list. Before disabling a plugin, ensure all instances of it are removed before restarting Kong.

Note: Limiting the amount of available plugins can improve P99 latency when experiencing LRU churning in the database cache (i.e. when the configured mem_cache_size) is full.

Default: bundled

dedicated_config_processing

Enables or disables a special worker process for configuration processing. This process increases memory usage a little bit while allowing to reduce latencies by moving some background tasks, such as CP/DP connection handling, to an additional worker process specific to handling these background tasks.

Currently this has effect only on data planes.

Default: on

pluginserver_names

Comma-separated list of names for pluginserver processes. The actual names are used for log messages and to relate the actual settings.

Default: none

pluginserver_XXX_socket

Path to the unix socket used by the pluginserver.

Default: <prefix>/<XXX>.socket

pluginserver_XXX_start_cmd

Full command (including any needed arguments) to start the pluginserver

Default: /usr/local/bin/<XXX>

pluginserver_XXX_query_cmd

Full command to “query” the pluginserver. Should produce a JSON with the dump info of all plugins it manages

Default: /usr/local/bin/query_<XXX>

port_maps

With this configuration parameter, you can let the Kong to know about the port from which the packets are forwarded to it. This is fairly common when running Kong in a containerized or virtualized environment.

For example, port_maps=80:8000, 443:8443 instructs Kong that the port 80 is mapped to 8000 (and the port 443 to 8443), where 8000 and 8443 are the ports that Kong is listening to.

This parameter helps Kong set a proper forwarded upstream HTTP request header or to get the proper forwarded port with the Kong PDK (in case other means determining it has failed). It changes routing by a destination port to route by a port from which packets are forwarded to Kong, and similarly it changes the default plugin log serializer to use the port according to this mapping instead of reporting the port Kong is listening to.

Default: none

anonymous_reports

Send anonymous usage data such as error stack traces to help improve Kong.

Default: on

proxy_server

Proxy server defined as a URL. Kong will only use this option if any component is explicitly configured to use proxy.

Default: none

proxy_server_ssl_verify

Toggles server certificate verification if proxy_server is in HTTPS.

See the lua_ssl_trusted_certificate setting to specify a certificate authority.

Default: off

error_template_html

Path to the custom html error template to override the default html kong error template.

The template may contain up to two %s placeholders. The first one will expand to the error message. The second one will expand to the request ID. Both placeholders are optional, but recommended.

Adding more than two placeholders will result in a runtime error when trying to render the template:

<html>
   <body>
     <h1>My custom error template</h1>
     <p>error: %s</p>
     <p>request_id: %s</p>
   </body>
</html>

Default: none

error_template_json

Path to the custom json error template to override the default json kong error template.

Similarly to error_template_html, the template may contain up to two %s placeholders for the error message and the request ID respectively.

Default: none

error_template_xml

Path to the custom xml error template to override the default xml kong error template

Similarly to error_template_html, the template may contain up to two %s placeholders for the error message and the request ID respectively.

Default: none

error_template_plain

Path to the custom plain error template to override the default plain kong error template

Similarly to error_template_html, the template may contain up to two %s placeholders for the error message and the request ID respectively.

Default: none

Hybrid Mode section

role

Use this setting to enable Hybrid Mode, This allows running some Kong nodes in a control plane role with a database and have them deliver configuration updates to other nodes running to DB-less running in a Data Plane role.

Valid values to this setting are:

• traditional: do not use Hybrid Mode.
• control_plane: this node runs in a control plane role. It can use a database and will deliver configuration updates to data plane nodes.
• data_plane: this is a data plane node. It runs DB-less and receives configuration updates from a control plane node.

Default: traditional

cluster_mtls

Sets the verification between nodes of the cluster.

Valid values to this setting are:

• shared: use a shared certificate/key pair specified with the cluster_cert and cluster_cert_key settings. Note that CP and DP nodes have to present the same certificate to establish mTLS connections.
• pki: use cluster_ca_cert, cluster_server_name and cluster_cert for verification. These are different certificates for each DP node, but issued by a cluster-wide common CA certificate: cluster_ca_cert.
• pki_check_cn: similar as pki but additionally checks for Common Name of data plane certificate specified in cluster_allowed_common_names.

Default: shared

cluster_cert

Cluster certificate to use when establishing secure communication between control and data plane nodes.

You can use the kong hybrid command to generate the certificate/key pair.

Under shared mode, it must be the same for all nodes. Under pki mode it should be a different certificate for each DP node.

The certificate can be configured on this property with any of the following values:

• absolute path to the certificate
• certificate content
• base64 encoded certificate content

Default: none

cluster_cert_key

Cluster certificate key to use when establishing secure communication between control and data plane nodes.

You can use the kong hybrid command to generate the certificate/key pair.

Under shared mode, it must be the same for all nodes. Under pki mode it should be a different certificate for each DP node.

The certificate key can be configured on this property with either of the following values:

• absolute path to the certificate key
• certificate key content
• base64 encoded certificate key content

Default: none

cluster_ca_cert

The trusted CA certificate file in PEM format used for Control Plane to verify Data Plane’s certificate and Data Plane to verify Control Plane’s certificate.

Required on data plane if cluster_mtls is set to pki.

If Control Plane certificate is issued by a well known CA, user can set lua_ssl_trusted_certificate=system on Data Plane and leave this field empty.

This field is ignored if cluster_mtls is set to shared.

The certificate can be configured on this property with any of the following values:

• absolute path to the certificate
• certificate content
• base64 encoded certificate content

Default: none

cluster_allowed_common_names

The list of Common Names that are allowed to connect to control plane. Multiple entries may be supplied in a comma-separated string. When not set, Data Plane with same parent domain of Control Plane cert is allowed to connect.

This field is ignored if cluster_mtls is not set to pki_check_cn.

Default: none

Hybrid Mode Data Plane section

cluster_server_name

The server name used in the SNI of the TLS connection from a DP node to a CP node.

Must match the Common Name (CN) or Subject Alternative Name (SAN) found in the CP certificate.

If cluster_mtls is set to shared, this setting is ignored and kong_clustering is used.

Default: none

cluster_control_plane

To be used by data plane nodes only: address of the control plane node from which configuration updates will be fetched, in host:port format.

Default: none

cluster_telemetry_endpoint

To be used by data plane nodes only: telemetry address of the control plane node to which telemetry updates will be posted in host:port format.

Default: none

cluster_telemetry_server_name

The SNI (Server Name Indication extension) to use for Vitals telemetry data.

Default: none

cluster_dp_labels

Comma separated list of Labels for the data plane.

Labels are key-value pairs that provide additional context information for each DP.

Each label must be configured as a string in the format key:value.

Labels are only compatible with hybrid mode deployments with Kong Konnect (SaaS), this configuration doesn’t work with self-hosted deployments.

Keys and values follow the AIP standards: https://kong-aip.netlify.app/aip/129/

Example: deployment:mycloud,region:us-east-1

Default: none

Hybrid Mode Control Plane section

cluster_listen

Comma-separated list of addresses and ports on which the cluster control plane server should listen for data plane connections.

The cluster communication port of the control plane must be accessible by all the data planes within the same cluster. This port is mTLS protected to ensure end-to-end security and integrity.

This setting has no effect if role is not set to control_plane.

Connection made to this endpoint are logged to the same location as Admin API access logs.

See admin_access_log config description for more information.

Default: 0.0.0.0:8005

cluster_telemetry_listen

Comma-separated list of addresses and ports on which the cluster control plane server should listen for data plane telemetry connections.

The cluster communication port of the control plane must be accessible by all the data planes within the same cluster.

This setting has no effect if role is not set to control_plane.

Default: 0.0.0.0:8006

cluster_data_plane_purge_delay

How many seconds must pass from the time a DP node becomes offline to the time its entry gets removed from the database, as returned by the /clustering/data-planes Admin API endpoint.

This is to prevent the cluster data plane table from growing indefinitely. The default is set to 14 days. That is, if CP haven’t heard from a DP for 14 days, its entry will be removed.

Default: 1209600

cluster_ocsp

Whether to check for revocation status of DP certificates using OCSP (Online Certificate Status Protocol).

If enabled, the DP certificate should contain the “Certificate Authority Information Access” extension and the OCSP method with URI of which the OCSP responder can be reached from CP.

OCSP checks are only performed on CP nodes, it has no effect on DP nodes.

Valid values to this setting are:

• on: OCSP revocation check is enabled and DP must pass the check in order to establish connection with CP.
• off: OCSP revocation check is disabled.
• optional: OCSP revocation check will be attempted, however, if the required extension is not found inside DP provided certificate or communication with the OCSP responder failed, then DP is still allowed through.

Default: off

cluster_use_proxy

Whether to turn on HTTP CONNECT proxy support for hybrid mode connections. proxy_server will be used for Hybrid mode connections if this option is turned on.

Default: off

cluster_max_payload

This sets the maximum compressed payload size allowed to be sent across from CP to DP in Hybrid mode. Default is 16MB - 16 * 1024 * 1024.

Default: 16777216

NGINX section

proxy_listen

Comma-separated list of addresses and ports on which the proxy server should listen for HTTP/HTTPS traffic.

The proxy server is the public entry point of Kong, which proxies traffic from your consumers to your backend services. This value accepts IPv4, IPv6, and hostnames.

Some suffixes can be specified for each pair:

• ssl will require that all connections made through a particular address/port be made with TLS enabled.
• http2 will allow for clients to open HTTP/2 connections to Kong’s proxy server.
• proxy_protocol will enable usage of the PROXY protocol for a given address/port.
• deferred instructs to use a deferred accept on Linux (the TCP_DEFER_ACCEPT socket option).
• bind instructs to make a separate bind() call for a given address:port pair.
• reuseport instructs to create an individual listening socket for each worker process allowing the Kernel to better distribute incoming connections between worker processes
• backlog=N sets the maximum length for the queue of pending TCP connections. This number should not be too small in order to prevent clients seeing “Connection refused” error connecting to a busy Kong instance. Note: on Linux, this value is limited by the setting of net.core.somaxconn Kernel parameter. In order for the larger backlog set here to take effect it is necessary to raise net.core.somaxconn at the same time to match or exceed the backlog number set.
• ipv6only=on|off whether an IPv6 socket listening on a wildcard address [::] will accept only IPv6 connections or both IPv6 and IPv4 connections
• so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt] configures the TCP keepalive behavior for the listening socket. If this parameter is omitted then the operating system’s settings will be in effect for the socket. If it is set to the value on, the SO_KEEPALIVE option is turned on for the socket. If it is set to the value off, the SO_KEEPALIVE option is turned off for the socket. Some operating systems support setting of TCP keepalive parameters on a per-socket basis using the TCP_KEEPIDLE, TCP_KEEPINTVL, and TCP_KEEPCNT socket options.

This value can be set to off, thus disabling the HTTP/HTTPS proxy port for this node.

If stream_listen is also set to off, this enables ‘control-plane’ mode for this node (in which all traffic proxying capabilities are disabled). This node can then be used only to configure a cluster of Kong nodes connected to the same datastore.

Example: proxy_listen = 0.0.0.0:443 ssl, 0.0.0.0:444 http2 ssl

See http://nginx.org/en/docs/http/ngx_http_core_module.html#listen for a description of the accepted formats for this and other *_listen values.

See https://www.nginx.com/resources/admin-guide/proxy-protocol/ for more details about the proxy_protocol parameter.

Not all *_listen values accept all formats specified in nginx’s documentation.

Default: 0.0.0.0:8000 reuseport backlog=16384, 0.0.0.0:8443 http2 ssl reuseport backlog=16384

proxy_url

Kong Proxy URL

The lookup, or balancer, address for your Kong Proxy nodes.

This value is commonly used in a microservices or service-mesh oriented architecture.

Accepted format (parts in parentheses are optional):

<scheme>://<IP / HOSTNAME>(:<PORT>(/<PATH>))

Examples:

• <scheme>://<IP>:<PORT> -> proxy_url = http://127.0.0.1:8000
• SSL <scheme>://<HOSTNAME> -> proxy_url = https://proxy.domain.tld
• <scheme>://<HOSTNAME>/<PATH> -> proxy_url = http://dev-machine/dev-285

By default, Kong Manager, and Kong Portal will use the window request host and append the resolved listener port depending on the requested protocol.

Default: none

stream_listen

Comma-separated list of addresses and ports on which the stream mode should listen.

This value accepts IPv4, IPv6, and hostnames.

Some suffixes can be specified for each pair:

• ssl will require that all connections made through a particular address/port be made with TLS enabled.
• proxy_protocol will enable usage of the PROXY protocol for a given address/port.
• bind instructs to make a separate bind() call for a given address:port pair.
• reuseport instructs to create an individual listening socket for each worker process allowing the Kernel to better distribute incoming connections between worker processes
• backlog=N sets the maximum length for the queue of pending TCP connections. This number should not be too small in order to prevent clients seeing “Connection refused” error connecting to a busy Kong instance. Note: on Linux, this value is limited by the setting of net.core.somaxconn Kernel parameter. In order for the larger backlog set here to take effect it is necessary to raise net.core.somaxconn at the same time to match or exceed the backlog number set.
• ipv6only=on|off whether an IPv6 socket listening on a wildcard address [::] will accept only IPv6 connections or both IPv6 and IPv4 connections
• so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt] configures the TCP keepalive behavior for the listening socket. If this parameter is omitted then the operating system’s settings will be in effect for the socket. If it is set to the value on, the SO_KEEPALIVE option is turned on for the socket. If it is set to the value off, the SO_KEEPALIVE option is turned off for the socket. Some operating systems support setting of TCP keepalive parameters on a per-socket basis using the TCP_KEEPIDLE, TCP_KEEPINTVL, and TCP_KEEPCNT socket options.

Examples:

stream_listen = 127.0.0.1:7000 reuseport backlog=16384
stream_listen = 0.0.0.0:989 reuseport backlog=65536, 0.0.0.0:20
stream_listen = [::1]:1234 backlog=16384

By default this value is set to off, thus disabling the stream proxy port for this node.

See http://nginx.org/en/docs/stream/ngx_stream_core_module.html#listen for a description of the formats that Kong might accept in stream_listen.

Default: off

admin_api_uri

Deprecated: Use admin_gui_api_url instead

Default: none

admin_listen

Comma-separated list of addresses and ports on which the Admin interface should listen.

The Admin interface is the API allowing you to configure and manage Kong.

Access to this interface should be restricted to Kong administrators only. This value accepts IPv4, IPv6, and hostnames.

It is highly recommended to avoid exposing the Admin API to public interface(s), by using values such as 0.0.0.0:8001

See https://docs.konghq.com/gateway/latest/production/running-kong/secure-admin-api/ for more information about how to secure your Admin API

Some suffixes can be specified for each pair:

• ssl will require that all connections made through a particular address/port be made with TLS enabled.
• http2 will allow for clients to open HTTP/2 connections to Kong’s proxy server.
• proxy_protocol will enable usage of the PROXY protocol for a given address/port.
• deferred instructs to use a deferred accept on Linux (the TCP_DEFER_ACCEPT socket option).
• bind instructs to make a separate bind() call for a given address:port pair.
• reuseport instructs to create an individual listening socket for each worker process allowing the Kernel to better distribute incoming connections between worker processes
• backlog=N sets the maximum length for the queue of pending TCP connections. This number should not be too small in order to prevent clients seeing “Connection refused” error connecting to a busy Kong instance. Note: on Linux, this value is limited by the setting of net.core.somaxconn Kernel parameter. In order for the larger backlog set here to take effect it is necessary to raise net.core.somaxconn at the same time to match or exceed the backlog number set.
• ipv6only=on|off whether an IPv6 socket listening on a wildcard address [::] will accept only IPv6 connections or both IPv6 and IPv4 connections
• so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt] configures the TCP keepalive behavior for the listening socket. If this parameter is omitted then the operating system’s settings will be in effect for the socket. If it is set to the value on, the SO_KEEPALIVE option is turned on for the socket. If it is set to the value off, the SO_KEEPALIVE option is turned off for the socket. Some operating systems support setting of TCP keepalive parameters on a per-socket basis using the TCP_KEEPIDLE, TCP_KEEPINTVL, and TCP_KEEPCNT socket options.

This value can be set to off, thus disabling the Admin interface for this node, enabling a ‘data-plane’ mode (without configuration capabilities) pulling its configuration changes from the database.

Example: admin_listen = 127.0.0.1:8444 http2 ssl

Default: 127.0.0.1:8001 reuseport backlog=16384, 127.0.0.1:8444 http2 ssl reuseport backlog=16384

status_listen

Comma-separated list of addresses and ports on which the Status API should listen.

The Status API is a read-only endpoint allowing monitoring tools to retrieve metrics, healthiness, and other non-sensitive information of the current Kong node.

The following suffix can be specified for each pair:

• ssl will require that all connections made through a particular address/port be made with TLS enabled.
• http2 will allow for clients to open HTTP/2 connections to Kong’s Status API server.
• proxy_protocol will enable usage of the PROXY protocol.

This value can be set to off, disabling the Status API for this node.

Example: status_listen = 0.0.0.0:8100 ssl http2

Default: 127.0.0.1:8007 reuseport backlog=16384

debug_listen

Comma-separated list of addresses and ports on which the Debug API should listen.

The following suffix can be specified for each pair:

• ssl will require that all connections made through a particular address/port be made with TLS enabled.
• http2 will allow for clients to open HTTP/2 connections to Kong’s Debug API server.

This value can be set to off, disabling the Debug API for this node.

Example: debug_listen = 0.0.0.0:8200 ssl http2

Default: off

debug_listen_local

Expose debug_listen functionalities via a Unix domain socket under the Kong prefix.

This option allows local user to use “kong debug” command to invoke various debug functionalities without needing to enable debug_listen ahead of time.

Default: on

nginx_user

Defines user and group credentials used by worker processes. If group is omitted, a group whose name equals that of user is used.

Example: nginx_user = nginx www

Note: If the kong user and the kong group are not available, the default user and group credentials will be nobody nobody.

Default: kong kong

nginx_worker_processes

Determines the number of worker processes spawned by Nginx.

See http://nginx.org/en/docs/ngx_core_module.html#worker_processes for detailed usage of the equivalent Nginx directive and a description of accepted values.

Default: auto

nginx_daemon

Determines whether Nginx will run as a daemon or as a foreground process. Mainly useful for development or when running Kong inside a Docker environment.

See http://nginx.org/en/docs/ngx_core_module.html#daemon.

Default: on

mem_cache_size

Size of each of the two shared memory caches for traditional mode database entities and runtime data, kong_core_cache and kong_cache.

The accepted units are k and m, with a minimum recommended value of a few MBs.

Note: As this option controls the size of two different cache zones, the total memory Kong uses to cache entities might be double this value.

The created zones are shared by all worker processes and do not become larger when more worker is used.

Default: 128m

ssl_cipher_suite

Defines the TLS ciphers served by Nginx.

Accepted values are modern, intermediate, old, fips or custom.

If you want to enable TLSv1.1, this value has to be old.

See https://wiki.mozilla.org/Security/Server_Side_TLS for detailed descriptions of each cipher suite. fips cipher suites are as described in https://wiki.openssl.org/index.php/FIPS_mode_and_TLS.

Default: intermediate

ssl_ciphers

Defines a custom list of TLS ciphers to be served by Nginx. This list must conform to the pattern defined by openssl ciphers.

This value is ignored if ssl_cipher_suite is not custom.

If you use DHE ciphers, you must also configure the ssl_dhparam parameter.

Default: none

ssl_protocols

Enables the specified protocols for client-side connections. The set of supported protocol versions also depends on the version of OpenSSL Kong was built with. This value is ignored if ssl_cipher_suite is not custom.

If you want to enable TLSv1.1, you should set ssl_cipher_suite to old.

See http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_protocols

Default: TLSv1.2 TLSv1.3

ssl_prefer_server_ciphers

Specifies that server ciphers should be preferred over client ciphers when using the SSLv3 and TLS protocols. This value is ignored if ssl_cipher_suite is not custom.

See http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_prefer_server_ciphers

Default: on

ssl_dhparam

Defines DH parameters for DHE ciphers from the predefined groups: ffdhe2048, ffdhe3072, ffdhe4096, ffdhe6144, ffdhe8192, from the absolute path to a parameters file, or directly from the parameters content.

This value is ignored if ssl_cipher_suite is modern or intermediate. The reason is that modern has no ciphers that needs this, and intermediate uses ffdhe2048.

See http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_dhparam

Default: none

ssl_session_tickets

Enables or disables session resumption through TLS session tickets. This has no impact when used with TLSv1.3.

Kong enables this by default for performance reasons, but it has security implications: https://github.com/mozilla/server-side-tls/issues/135

See http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_session_tickets

Default: on

ssl_session_timeout

Specifies a time during which a client may reuse the session parameters. See the rationale: https://github.com/mozilla/server-side-tls/issues/198

See http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_session_timeout

Default: 1d

ssl_session_cache_size

Sets the size of the caches that store session parameters

See https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_session_cache

Default: 10m

ssl_cert

Comma-separated list of certificates for proxy_listen values with TLS enabled.

If more than one certificates are specified, it can be used to provide alternate type of certificate (for example, ECC certificate) that will be served to clients that supports them. Note to properly serve using ECC certificates, it is recommended to also set ssl_cipher_suite to modern or intermediate.

Unless this option is explicitly set, Kong will auto-generate a pair of default certificates (RSA + ECC) first time it starts up and use it for serving TLS requests.

Certificates can be configured on this property with any of the following values:

• absolute path to the certificate
• certificate content
• base64 encoded certificate content

Default: none

ssl_cert_key

Comma-separated list of keys for proxy_listen values with TLS enabled.

If more than one certificate was specified for ssl_cert, then this option should contain the corresponding key for all certificates provided in the same order.

Unless this option is explicitly set, Kong will auto-generate a pair of default private keys (RSA + ECC) first time it starts up and use it for serving TLS requests.

Keys can be configured on this property with any of the following values:

• absolute path to the certificate key
• certificate key content
• base64 encoded certificate key content

Default: none

client_ssl

Determines if Nginx should attempt to send client-side TLS certificates and perform Mutual TLS Authentication with upstream service when proxying requests.

Default: off

client_ssl_cert

If client_ssl is enabled, the client certificate for the proxy_ssl_certificate directive.

This value can be overwritten dynamically with the client_certificate attribute of the Service object.

The certificate can be configured on this property with any of the following values:

• absolute path to the certificate
• certificate content
• base64 encoded certificate content

Default: none

client_ssl_cert_key

If client_ssl is enabled, the client TLS key for the proxy_ssl_certificate_key directive.

This value can be overwritten dynamically with the client_certificate attribute of the Service object.

The certificate key can be configured on this property with either of the following values:

• absolute path to the certificate key
• certificate key content
• base64 encoded certificate key content

Default: none

admin_ssl_cert

Comma-separated list of certificates for admin_listen values with TLS enabled.

See docs for ssl_cert for detailed usage.

Default: none

admin_ssl_cert_key

Comma-separated list of keys for admin_listen values with TLS enabled.

See docs for ssl_cert_key for detailed usage.

Default: none

status_ssl_cert

Comma-separated list of certificates for status_listen values with TLS enabled.

See docs for ssl_cert for detailed usage.

Default: none

status_ssl_cert_key

Comma-separated list of keys for status_listen values with TLS enabled.

See docs for ssl_cert_key for detailed usage.

Default: none

debug_ssl_cert

Comma-separated list of certificates for debug_listen values with TLS enabled.

See docs for ssl_cert for detailed usage.

Default: none

debug_ssl_cert_key

Comma-separated list of keys for debug_listen values with TLS enabled.

See docs for ssl_cert_key for detailed usage.

Default: none

headers

Comma-separated list of headers Kong should inject in client responses.

Accepted values are:

• Server: Injects Server: kong/x.y.z on Kong-produced response (e.g. Admin API, rejected requests from auth plugin).
• Via: Injects Via: kong/x.y.z for successfully proxied requests.
• X-Kong-Proxy-Latency: Time taken (in milliseconds) by Kong to process a request and run all plugins before proxying the request upstream.
• X-Kong-Response-Latency: time taken (in millisecond) by Kong to produce a response in case of e.g. plugin short-circuiting the request, or in in case of an error.
• X-Kong-Upstream-Latency: Time taken (in milliseconds) by the upstream service to send response headers.
• X-Kong-Admin-Latency: Time taken (in milliseconds) by Kong to process an Admin API request.
• X-Kong-Upstream-Status: The HTTP status code returned by the upstream service. This is particularly useful for clients to distinguish upstream statuses if the response is rewritten by a plugin.
• X-Kong-Request-Id: Unique identifier of the request.
• server_tokens: Same as specifying both Server and Via.
• latency_tokens: Same as specifying X-Kong-Proxy-Latency, X-Kong-Response-Latency, X-Kong-Admin-Latency and X-Kong-Upstream-Latency

In addition to those, this value can be set to off, which prevents Kong from injecting any of the above headers. Note that this does not prevent plugins from injecting headers of their own.

Example: headers = via, latency_tokens

Default: server_tokens, latency_tokens, X-Kong-Request-Id

headers_upstream

Comma-separated list of headers Kong should inject in requests to upstream.

At this time, the only accepted value is:

• X-Kong-Request-Id: Unique identifier of the request.

In addition, this value can be set to off, which prevents Kong from injecting the above header. Note that this does not prevent plugins from injecting headers of their own.

Default: X-Kong-Request-Id

trusted_ips

Defines trusted IP addresses blocks that are known to send correct X-Forwarded-* headers.

Requests from trusted IPs make Kong forward their X-Forwarded-* headers upstream.

Non-trusted requests make Kong insert its own X-Forwarded-* headers.

This property also sets the set_real_ip_from directive(s) in the Nginx configuration. It accepts the same type of values (CIDR blocks) but as a comma-separated list.

To trust all /!\ IPs, set this value to 0.0.0.0/0,::/0.

If the special value unix: is specified, all UNIX-domain sockets will be trusted.

See http://nginx.org/en/docs/http/ngx_http_realip_module.html#set_real_ip_from for examples of accepted values.

Default: none

real_ip_header

Defines the request header field whose value will be used to replace the client address.

This value sets the ngx_http_realip_module directive of the same name in the Nginx configuration.

If this value receives proxy_protocol:

• at least one of the proxy_listen entries must have the proxy_protocol flag enabled.
• the proxy_protocol parameter will be appended to the listen directive of the Nginx template.

See http://nginx.org/en/docs/http/ngx_http_realip_module.html#real_ip_header for a description of this directive.

Default: X-Real-IP

real_ip_recursive

This value sets the ngx_http_realip_module directive of the same name in the Nginx configuration.

See http://nginx.org/en/docs/http/ngx_http_realip_module.html#real_ip_recursive for a description of this directive.

Default: off

error_default_type

Default MIME type to use when the request Accept header is missing and Nginx is returning an error for the request.

Accepted values are text/plain, text/html, application/json, and application/xml.

Default: text/plain

upstream_keepalive_pool_size

Sets the default size of the upstream keepalive connection pools.

Upstream keepalive connection pools are segmented by the dst ip/dst port/SNI attributes of a connection.

A value of 0 will disable upstream keepalive connections by default, forcing each upstream request to open a new connection.

Default: 512

upstream_keepalive_max_requests

Sets the default maximum number of requests than can be proxied upstream through one keepalive connection.

After the maximum number of requests is reached, the connection will be closed.

A value of 0 will disable this behavior, and a keepalive connection can be used to proxy an indefinite number of requests.

Default: 1000

upstream_keepalive_idle_timeout

Sets the default timeout (in seconds) for which an upstream keepalive connection should be kept open. When the timeout is reached while the connection has not been reused, it will be closed.

A value of 0 will disable this behavior, and an idle keepalive connection may be kept open indefinitely.

Default: 60

allow_debug_header

Enable the Kong-Debug header function.

if it is on, kong will add Kong-Route-Id Kong-Route-Name Kong-Service-Id Kong-Service-Name debug headers to response when the client request header Kong-Debug: 1 is present.

Default: off

NGINX Injected Directives section

Nginx directives can be dynamically injected in the runtime nginx.conf file without requiring a custom Nginx configuration template.

All configuration properties respecting the naming scheme nginx_<namespace>_<directive> will result in <directive> being injected in the Nginx configuration block corresponding to the property’s <namespace>.

Example: nginx_proxy_large_client_header_buffers = 8 24k

Will inject the following directive in Kong’s proxy server {} block:

large_client_header_buffers 8 24k;

The following namespaces are supported:

• nginx_main_<directive>: Injects <directive> in Kong’s configuration main context.
• nginx_events_<directive>: Injects <directive> in Kong’s events {} block.
• nginx_http_<directive>: Injects <directive> in Kong’s http {} block.
• nginx_proxy_<directive>: Injects <directive> in Kong’s proxy server {} block.
• nginx_location_<directive>: Injects <directive> in Kong’s proxy / location block (nested under Kong’s proxy server {} block).
• nginx_upstream_<directive>: Injects <directive> in Kong’s proxy upstream {} block.
• nginx_admin_<directive>: Injects <directive> in Kong’s Admin API server {} block.
• nginx_status_<directive>: Injects <directive> in Kong’s Status API server {} block (only effective if status_listen is enabled).
• nginx_debug_<directive> : Injects <directive> in Kong’s Debug API server {} block (only effective if debug_listen or debug_listen_local is enabled).
• nginx_stream_<directive>: Injects <directive> in Kong’s stream module stream {} block (only effective if stream_listen is enabled).
• nginx_sproxy_<directive>: Injects <directive> in Kong’s stream module server {} block (only effective if stream_listen is enabled).
• nginx_supstream_<directive>: Injects <directive> in Kong’s stream module upstream {} block.

As with other configuration properties, Nginx directives can be injected via environment variables when capitalized and prefixed with KONG_.

Example: KONG_NGINX_HTTP_SSL_PROTOCOLS -> nginx_http_ssl_protocols

Will inject the following directive in Kong’s http {} block:

ssl_protocols <value>;

If different sets of protocols are desired between the proxy and Admin API server, you may specify nginx_proxy_ssl_protocols and/or nginx_admin_ssl_protocols, both of which taking precedence over the http {} block.

nginx_main_worker_rlimit_nofile

Changes the limit on the maximum number of open files for worker processes.

The special and default value of auto sets this value to ulimit -n with the upper bound limited to 16384 as a measure to protect against excess memory use, and the lower bound of 1024 as a good default.

See http://nginx.org/en/docs/ngx_core_module.html#worker_rlimit_nofile

Default: auto

nginx_events_worker_connections

Sets the maximum number of simultaneous connections that can be opened by a worker process.

The special and default value of auto sets this value to ulimit -n with the upper bound limited to 16384 as a measure to protect against excess memory use, and the lower bound of 1024 as a good default.

See http://nginx.org/en/docs/ngx_core_module.html#worker_connections

Default: auto

nginx_http_client_header_buffer_size

Sets buffer size for reading the client request headers.

See http://nginx.org/en/docs/http/ngx_http_core_module.html#client_header_buffer_size

Default: 1k

nginx_http_large_client_header_buffers

Sets the maximum number and size of buffers used for reading large clients requests headers.

See http://nginx.org/en/docs/http/ngx_http_core_module.html#large_client_header_buffers

Default: 4 8k

nginx_http_client_max_body_size

Defines the maximum request body size allowed by requests proxied by Kong, specified in the Content-Length request header. If a request exceeds this limit, Kong will respond with a 413 (Request Entity Too Large). Setting this value to 0 disables checking the request body size.

See http://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size

Default: 0

nginx_admin_client_max_body_size

Defines the maximum request body size for Admin API.

Default: 10m

nginx_http_charset

Adds the specified charset to the “Content-Type” response header field. If this charset is different from the charset specified in the source_charset directive, a conversion is performed.

The parameter off cancels the addition of charset to the “Content-Type” response header field.

See http://nginx.org/en/docs/http/ngx_http_charset_module.html#charset

Default: UTF-8

nginx_http_client_body_buffer_size

Defines the buffer size for reading the request body. If the client request body is larger than this value, the body will be buffered to disk. Note that when the body is buffered to disk, Kong plugins that access or manipulate the request body may not work, so it is advisable to set this value as high as possible (e.g., set it as high as client_max_body_size to force request bodies to be kept in memory). Do note that high-concurrency environments will require significant memory allocations to process many concurrent large request bodies.

See http://nginx.org/en/docs/http/ngx_http_core_module.html#client_body_buffer_size

Default: 8k

nginx_admin_client_body_buffer_size

Defines the buffer size for reading the request body on Admin API.

Default: 10m

nginx_http_lua_regex_match_limit

Global MATCH_LIMIT for PCRE regex matching. The default of 100000 should ensure at worst any regex Kong executes could finish within roughly 2 seconds.

Default: 100000

nginx_http_lua_regex_cache_max_entries

Specifies the maximum number of entries allowed in the worker process level PCRE JIT compiled regex cache.

It is recommended to set it to at least (number of regex paths * 2) to avoid high CPU usages if you manually specified router_flavor to traditional. expressions and traditional_compat router does not make use of the PCRE library and their behavior is unaffected by this setting.

Default: 8192

nginx_http_keepalive_requests

Sets the maximum number of client requests that can be served through one keep-alive connection. After the maximum number of requests are made, the connection is closed.

Closing connections periodically is necessary to free per-connection memory allocations. Therefore, using too high maximum number of requests could result in excessive memory usage and not recommended.

See: https://nginx.org/en/docs/http/ngx_http_core_module.html#keepalive_requests

Default: 10000

Datastore section

Kong can run with a database to store coordinated data between Kong nodes in a cluster, or without a database, where each node stores its information independently in memory.

When using a database, Kong will store data for all its entities (such as Routes, Services, Consumers, and Plugins) in PostgreSQL, and all Kong nodes belonging to the same cluster must connect themselves to the same database.

Kong supports PostgreSQL versions 9.5 and above.

When not using a database, Kong is said to be in “DB-less mode”: it will keep its entities in memory, and each node needs to have this data entered via a declarative configuration file, which can be specified through the declarative_config property, or via the Admin API using the /config endpoint.

When using Postgres as the backend storage, you can optionally enable Kong to serve read queries from a separate database instance.

When the number of proxies is large, this can greatly reduce the load on the main Postgres instance and achieve better scalability. It may also reduce the latency jitter if the Kong proxy node’s latency to the main Postgres instance is high.

The read-only Postgres instance only serves read queries and write queries still goes to the main connection. The read-only Postgres instance can be eventually consistent while replicating changes from the main instance.

At least the pg_ro_host config is needed to enable this feature.

By default, all other database config for the read-only connection are inherited from the corresponding main connection config described above but may be optionally overwritten explicitly using the pg_ro_* config below.

database

Determines the database (or no database) for this node. Accepted values are postgres and off.

Default: postgres

Postgres settings

declarative_config

The path to the declarative configuration file which holds the specification of all entities (Routes, Services, Consumers, etc.) to be used when the database is set to off.

Entities are stored in Kong’s LMDB cache, so you must ensure that enough headroom is allocated to it via the lmdb_map_size property.

If the Hybrid mode role is set to data_plane and there’s no configuration cache file, this configuration is used before connecting to the Control Plane node as a user-controlled fallback.

Default: none

declarative_config_string

The declarative configuration as a string

Default: none

lmdb_environment_path

Directory where the LMDB database files used by DB-less and Hybrid mode to store Kong configurations reside.

This path is relative under the Kong prefix.

Default: dbless.lmdb

lmdb_map_size

Maximum size of the LMDB memory map, used to store the DB-less and Hybird mode configurations. Default is 2048m.

This config defines the limit of LMDB file size, the actual file size growth will be on-demand and proportional to the actual config size.

Note this value can be set very large, say a couple of GBs to accommodate future database growth and Multi Version Concurrency Control (MVCC) headroom needs.

The file size of the LMDB database file should stabilize after a few config reload/Hybrid mode syncs and the actual memory used by the LMDB database will be smaller than the file size due to dynamic swapping of database pages by the OS.

Default: 2048m

Datastore Cache section

In order to avoid unnecessary communication with the datastore, Kong caches entities (such as APIs, Consumers, Credentials…) for a configurable period of time. It also handles invalidations if such an entity is updated.

This section allows for configuring the behavior of Kong regarding the caching of such configuration entities.

db_update_frequency

Frequency (in seconds) at which to check for updated entities with the datastore.

When a node creates, updates, or deletes an entity via the Admin API, other nodes need to wait for the next poll (configured by this value) to eventually purge the old cached entity and start using the new one.

Default: 5

db_update_propagation

Time (in seconds) taken for an entity in the datastore to be propagated to replica nodes of another datacenter.

When set, this property will increase the time taken by Kong to propagate the change of an entity.

Single-datacenter setups or PostgreSQL servers should suffer no such delays, and this value can be safely set to 0.

Postgres setups with read replicas should set this value to maximum expected replication lag between the writer and reader instances.

Default: 0

db_cache_ttl

Time-to-live (in seconds) of an entity from the datastore when cached by this node.

Database misses (no entity) are also cached according to this setting if you do not configure db_cache_neg_ttl.

If set to 0 (default), such cached entities or misses never expire.

Default: 0

db_cache_neg_ttl

Time-to-live (in seconds) of a datastore miss (no entity).

If not specified (default), db_cache_ttl value will be used instead.

If set to 0, misses will never expire.

Default: none

db_resurrect_ttl

Time (in seconds) for which stale entities from the datastore should be resurrected for when they cannot be refreshed (e.g., the datastore is unreachable). When this TTL expires, a new attempt to refresh the stale entities will be made.

Default: 30

db_cache_warmup_entities

Entities to be pre-loaded from the datastore into the in-memory cache at Kong start-up.

This speeds up the first access of endpoints that use the given entities.

When the services entity is configured for warmup, the DNS entries for values in its host attribute are pre-resolved asynchronously as well.

Cache size set in mem_cache_size should be set to a value large enough to hold all instances of the specified entities.

If the size is insufficient, Kong will log a warning.

Default: services

DNS Resolver section

By default, the DNS resolver will use the standard configuration files /etc/hosts and /etc/resolv.conf. The settings in the latter file will be overridden by the environment variables LOCALDOMAIN and RES_OPTIONS if they have been set.

Kong will resolve hostnames as either SRV or A records (in that order, and CNAME records will be dereferenced in the process).

In case a name was resolved as an SRV record it will also override any given port number by the port field contents received from the DNS server.

The DNS options SEARCH and NDOTS (from the /etc/resolv.conf file) will be used to expand short names to fully qualified ones. So it will first try the entire SEARCH list for the SRV type, if that fails it will try the SEARCH list for A, etc.

For the duration of the ttl, the internal DNS resolver will loadbalance each request it gets over the entries in the DNS record. For SRV records the weight fields will be honored, but it will only use the lowest priority field entries in the record.

dns_resolver

Comma separated list of nameservers, each entry in ip[:port] format to be used by Kong. If not specified the nameservers in the local resolv.conf file will be used.

Port defaults to 53 if omitted. Accepts both IPv4 and IPv6 addresses.

Default: none

dns_hostsfile

The hosts file to use. This file is read once and its content is static in memory.

To read the file again after modifying it, Kong must be reloaded.

Default: /etc/hosts

dns_order

The order in which to resolve different record types. The LAST type means the type of the last successful lookup (for the specified name). The format is a (case insensitive) comma separated list.

Default: LAST,SRV,A,CNAME

dns_valid_ttl

By default, DNS records are cached using the TTL value of a response. If this property receives a value (in seconds), it will override the TTL for all records.

Default: none

dns_stale_ttl

Defines, in seconds, how long a record will remain in cache past its TTL. This value will be used while the new DNS record is fetched in the background.

Stale data will be used from expiry of a record until either the refresh query completes, or the dns_stale_ttl number of seconds have passed.

This configuration enables Kong to be more resilient during resolver downtime.

Default: 3600

dns_cache_size

Defines the maximum allowed number of DNS records stored in memory cache.

Least recently used DNS records are discarded from cache if it is full. Both errors and data are cached, therefore a single name query can easily take up 10-15 slots.

Default: 10000

dns_not_found_ttl

TTL in seconds for empty DNS responses and “(3) name error” responses.

Default: 30

dns_error_ttl

TTL in seconds for error responses.

Default: 1

dns_no_sync

If enabled, then upon a cache-miss every request will trigger its own dns query.

When disabled multiple requests for the same name/type will be synchronised to a single query.

Default: off

Vaults section

A secret is any sensitive piece of information required for API gateway operations. Secrets may be part of the core Kong Gateway configuration, used in plugins, or part of the configuration associated with APIs serviced by the gateway.

Some of the most common types of secrets used by Kong Gateway include:

• Data store usernames and passwords, used with PostgreSQL and Redis
• Private X.509 certificates
• API keys

Sensitive plugin configuration fields are generally used for authentication, hashing, signing, or encryption. Kong Gateway lets you store certain values in a vault. Here are the vault specific configuration options.

vault_env_prefix

Defines the environment variable vault’s default prefix. For example if you have all your secrets stored in environment variables prefixed with SECRETS_, it can be configured here so that it isn’t necessary to repeat them in Vault references.

Default: none

vault_aws_region

The AWS region your vault is located in.

Default: none

vault_aws_endpoint_url

The AWS SecretsManager service endpoint url.

If not specified, the value used by vault will be the official AWS SecretsManager service url which is https://secretsmanager.<region>.amazonaws.com You can specify a complete URL(including the “http/https” scheme) to override the endpoint that vault will connect to.

Default: none

vault_aws_assume_role_arn

The target AWS IAM role ARN that will be assumed. Typically this is used for operating between multiple roles or cross-accounts.

If you are not using assume role you should not specify this value.

Default: none

vault_aws_role_session_name

The role session name used for role assuming. The default value is KongVault.

Default: KongVault

vault_aws_ttl

Time-to-live (in seconds) of a secret from the AWS vault when cached by this node.

AWS vault misses (no secret) are also cached according to this setting if you do not configure vault_aws_neg_ttl.

If set to 0 (default), such cached secrets or misses never expire.

Default: 0

vault_aws_neg_ttl

Time-to-live (in seconds) of a AWS vault miss (no secret).

If not specified (default), vault_aws_ttl value will be used instead.

If set to 0, misses will never expire.

Default: none

vault_aws_resurrect_ttl

Time (in seconds) for which stale secrets from the AWS vault should be resurrected for when they cannot be refreshed (e.g., the AWS vault is unreachable). When this TTL expires, a new attempt to refresh the stale secrets will be made.

Default: none

vault_gcp_project_id

The project ID from your Google API Console.

Default: none

vault_gcp_ttl

Time-to-live (in seconds) of a secret from the GCP vault when cached by this node.

GCP vault misses (no secret) are also cached according to this setting if you do not configure vault_gcp_neg_ttl.

If set to 0 (default), such cached secrets or misses never expire.

Default: 0

vault_gcp_neg_ttl

Time-to-live (in seconds) of a AWS vault miss (no secret).

If not specified (default), vault_gcp_ttl value will be used instead.

If set to 0, misses will never expire.

Default: none

vault_gcp_resurrect_ttl

Time (in seconds) for which stale secrets from the GCP vault should be resurrected for when they cannot be refreshed (e.g., the GCP vault is unreachable). When this TTL expires, a new attempt to refresh the stale secrets will be made.

Default: none

vault_hcv_protocol

The protocol to connect with. Accepts one of http or https.

Default: http

vault_hcv_host

The hostname of your HashiCorp vault.

Default: 127.0.0.1

vault_hcv_port

The port number of your HashiCorp vault.

Default: 8200

vault_hcv_namespace

Namespace for the HashiCorp Vault. Vault Enterprise requires a namespace to successfully connect to it.

Default: none

vault_hcv_mount

The mount point.

Default: secret

vault_hcv_kv

The secrets engine version. Accepts v1 or v2.

Default: v1

vault_hcv_token

A token string.

Default: none

vault_hcv_auth_method

Defines the authentication mechanism when connecting to the HashiCorp Vault service.

Accepted values are: token, kubernetes or approle.

Default: token

vault_hcv_kube_role

Defines the HashiCorp Vault role for the Kubernetes service account of the running pod. vault_hcv_auth_method must be set to kubernetes for this to activate.

Default: none

vault_hcv_kube_auth_path

Place where the Kubernetes auth method will be accessible: /v1/auth/

Default: kubernetes

vault_hcv_kube_api_token_file

Defines where the Kubernetes service account token should be read from the pod’s filesystem, if using a non-standard container platform setup.

Default: none

vault_hcv_approle_auth_path

Place where the Approle auth method will be accessible: /v1/auth/

Default: approle

vault_hcv_approle_role_id

The Role ID of the Approle in HashiCorp Vault.

Default: none

vault_hcv_approle_secret_id

The Secret ID of the Approle in HashiCorp Vault.

Default: none

vault_hcv_approle_secret_id_file

Defines where the Secret ID should be read from the pod’s filesystem. This is usually used with HashiCorp Vault’s response wrapping.

Default: none

vault_hcv_approle_response_wrapping

Defines whether the Secret ID read from configuration or file is actually a response-wrapping token instead of a real Secret ID.

Default: false

vault_hcv_ttl

Time-to-live (in seconds) of a secret from the HashiCorp vault when cached by this node.

HashiCorp vault misses (no secret) are also cached according to this setting if you do not configure vault_hcv_neg_ttl.

If set to 0 (default), such cached secrets or misses never expire.

Default: 0

vault_hcv_neg_ttl

Time-to-live (in seconds) of a HashiCorp vault miss (no secret).

If not specified (default), vault_hcv_ttl value will be used instead.

If set to 0, misses will never expire.

Default: none

vault_hcv_resurrect_ttl

Time (in seconds) for which stale secrets from the HashiCorp vault should be resurrected for when they cannot be refreshed (e.g., the HashiCorp vault is unreachable). When this TTL expires, a new attempt to refresh the stale secrets will be made.

Default: none

vault_azure_vault_uri

The URI the vault is reachable from.

Default: none

vault_azure_client_id

The client ID from your registered Application. Visit your Azure Dashboard and select App Registrations to check your client ID.

Default: none

vault_azure_tenant_id

The DirectoryId and TenantId both equate to the GUID representing the ActiveDirectory Tenant. Depending on context, either term may be used by Microsoft documentation and products, which can be confusing. In other words, the “Tenant ID” IS the “Directory ID”

Default: none

vault_azure_type

Azure Key Vault enables Microsoft Azure applications and users to store and use several types of secret/key data: keys, secrets, and certificates. Kong currently only supports the Secrets

Default: secrets

vault_azure_ttl

Time-to-live (in seconds) of a secret from the Azure Key Vault when cached by this node.

Key Vault misses (no secret) are also cached according to this setting if you do not configure vault_azure_neg_ttl.

If set to 0 (default), such cached secrets or misses never expire.

Default: 0

vault_azure_neg_ttl

Time-to-live (in seconds) of a Azure Key Vault miss (no secret).

If not specified (default), vault_azure_ttl value will be used instead.

If set to 0, misses will never expire.

Default: none

vault_azure_resurrect_ttl

Time (in seconds) for which stale secrets from the Azure Key Vault should be resurrected for when they cannot be refreshed (e.g., the the vault is unreachable). When this TTL expires, a new attempt to refresh the stale secrets will be made.

Default: none

Tuning & Behavior section

worker_consistency

Defines whether this node should rebuild its state synchronously or asynchronously (the balancers and the router are rebuilt on updates that affects them, e.g., updates to Routes, Services or Upstreams, via the Admin API or loading a declarative configuration file). (This option is deprecated and will be removed in future releases. The new default is eventual.)

Accepted values are:

• strict: the router will be rebuilt synchronously, causing incoming requests to be delayed until the rebuild is finished. (This option is deprecated and will be removed in future releases. The new default is eventual)
• eventual: the router will be rebuilt asynchronously via a recurring background job running every second inside of each worker.

Note that strict ensures that all workers of a given node will always proxy requests with an identical router, but that increased long tail latency can be observed if frequent Routes and Services updates are expected.

Using eventual will help preventing long tail latency issues in such cases, but may cause workers to route requests differently for a short period of time after Routes and Services updates.

Default: eventual

worker_state_update_frequency

Defines how often the worker state changes are checked with a background job. When a change is detected, a new router or balancer will be built, as needed. Raising this value will decrease the load on database servers and result in less jitter in proxy latency, but it might take more time to propagate changes to each individual worker.

Default: 5

router_flavor

Selects the router implementation to use when performing request routing. Incremental router rebuild is available when the flavor is set to either expressions or traditional_compatible which could significantly shorten rebuild time for large number of routes.

Accepted values are:

• traditional_compatible: the DSL based expression router engine will be used under the hood. However the router config interface will be the same as traditional and expressions are automatically generated at router build time. The expression field on the Route object is not visible.
• expressions: the DSL based expression router engine will be used under the hood. Traditional router config interface is not visible and you must write Router Expression manually and provide them in the expression field on the Route object.
• traditional: the pre-3.0 Router engine will be used. Config interface will be the same as pre-3.0 Kong and the expression field on the Route object is not visible.

Deprecation warning: In Kong 3.0, traditional mode should be avoided and only be used in case traditional_compatible did not work as expected.

This flavor of router will be removed in the next major release of Kong.

Default: traditional_compatible

lua_max_req_headers

Maximum number of request headers to parse by default.

This argument can be set to an integer between 1 and 1000.

When proxying the Kong sends all the request headers and this setting does not have any effect. It is used to limit Kong and its plugins from reading too many request headers.

Default: 100

lua_max_resp_headers

Maximum number of response headers to parse by default.

This argument can be set to an integer between 1 and 1000.

When proxying, Kong returns all the response headers and this setting does not have any effect. It is used to limit Kong and its plugins from reading too many response headers.

Default: 100

lua_max_uri_args

Maximum number of request uri arguments to parse by default.

This argument can be set to an integer between 1 and 1000.

When proxying, Kong sends all the request query arguments and this setting does not have any effect.

It is used to limit Kong and its plugins from reading too many query arguments.

Default: 100

lua_max_post_args

Maximum number of request post arguments to parse by default.

This argument can be set to an integer between 1 and 1000.

When proxying, Kong sends all the request post arguments and this setting does not have any effect.

It is used to limit Kong and its plugins from reading too many post arguments.

Default: 100

Miscellaneous section

Additional settings inherited from lua-nginx-module allowing for more flexibility and advanced usage.

See the lua-nginx-module documentation for more information: https://github.com/openresty/lua-nginx-module

lua_ssl_trusted_certificate

Comma-separated list of certificate authorities for Lua cosockets in PEM format.

The special value system attempts to search for the “usual default” provided by each distro, according to an arbitrary heuristic. In the current implementation, The following pathnames will be tested in order, and the first one found will be used:

• /etc/ssl/certs/ca-certificates.crt (Debian/Ubuntu/Gentoo)
• /etc/pki/tls/certs/ca-bundle.crt (Fedora/RHEL 6)
• /etc/ssl/ca-bundle.pem (OpenSUSE)
• /etc/pki/tls/cacert.pem (OpenELEC)
• /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem (CentOS/RHEL 7)
• /etc/ssl/cert.pem (OpenBSD, Alpine)

system can be used by itself or in conjunction with other CA filepaths.

When pg_ssl_verify is enabled, these certificate authority files will be used for verifying Kong’s database connections.

Certificates can be configured on this property with any of the following values:

• system
• absolute path to the certificate
• certificate content
• base64 encoded certificate content

See https://github.com/openresty/lua-nginx-module#lua_ssl_trusted_certificate

Default: system

lua_ssl_verify_depth

Sets the verification depth in the server certificates chain used by Lua cosockets, set by lua_ssl_trusted_certificate.

This includes the certificates configured for Kong’s database connections.

If the maximum depth is reached before reaching the end of the chain, verification will fail. This helps mitigate certificate based DoS attacks.

See https://github.com/openresty/lua-nginx-module#lua_ssl_verify_depth

Default: 1

lua_ssl_protocols

Defines the TLS versions supported when handshaking with OpenResty’s TCP cosocket APIs.

This affects connections made by Lua code, such as connections to the database Kong uses, or when sending logs using a logging plugin. It does not affect connections made to the upstream Service or from downstream clients.

Default: TLSv1.2 TLSv1.3

lua_package_path

Sets the Lua module search path (LUA_PATH). Useful when developing or using custom plugins not stored in the default search path.

See https://github.com/openresty/lua-nginx-module#lua_package_path

Default: ./?.lua;./?/init.lua;

lua_package_cpath

Sets the Lua C module search path (LUA_CPATH).

See https://github.com/openresty/lua-nginx-module#lua_package_cpath

Default: none

lua_socket_pool_size

Specifies the size limit for every cosocket connection pool associated with every remote server.

See https://github.com/openresty/lua-nginx-module#lua_socket_pool_size

Default: 256

enforce_rbac

Specifies whether Admin API RBAC is enforced.

Accepts one of entity, both, on, or off.

• on: only endpoint-level authorization is enforced.
• entity: entity-level authorization applies.
• both: enables both endpoint and entity-level authorization.
• off: disables both endpoint and entity-level authorization.

When enabled, Kong will deny requests to the Admin API when a nonexistent or invalid RBAC authorization token is passed, or the RBAC user with which the token is associated does not have permissions to access/modify the requested resource.

Default: off

rbac_auth_header

Defines the name of the HTTP request header from which the Admin API will attempt to authenticate the RBAC user.

Default: Kong-Admin-Token

event_hooks_enabled

When enabled, event hook entities represent a relationship between an event (source and event) and an action (handler). Similar to web hooks, event hooks can be used to communicate Kong Gateway service events. When a particular event happens on a service, the event hook calls a URL with information about that event. Event hook configurations differ depending on the handler. The events that are triggered send associated data.

See: https://docs.konghq.com/gateway/latest/admin-api/event-hooks/reference/

Default: on

fips

Turn on FIPS mode; this mode is only available on a FIPS build.

Default: off

Kong Manager section

The Admin GUI for Kong Enterprise.

admin_gui_listen

Kong Manager Listeners

Comma-separated list of addresses and ports on which Kong will expose Kong Manager. This web application lets you configure and manage Kong, and therefore should be kept secured.

Suffixes can be specified for each pair, similarly to the admin_listen directive.

Default: 0.0.0.0:8002, 0.0.0.0:8445 ssl

admin_gui_url

Kong Manager URL

The lookup, or balancer, address for Kong Manager.

Accepted format (items in parentheses are optional):

<scheme>://<IP / HOSTNAME>(:<PORT>)

Examples:

• http://127.0.0.1:8003
• https://kong-admin.test
• http://dev-machine

By default, Kong Manager will use the window request host and append the resolved listener port depending on the requested protocol.

Default: none

admin_gui_path

Kong Manager base path

This configuration parameter allows the user to customize the path prefix where Kong Manager is served. When updating this parameter, it’s recommended to update the path in admin_gui_url as well.

Accepted format:

• Path must start with a /
• Path must not end with a / (except for the /)
• Path can only contain letters, digits, hyphens (-),

underscores (_), and slashes (/)

• Path must not contain continuous slashes (e.g., // and ///)

Examples:

• /
• /manager
• /kong-manager
• /kong/manager

Default: /

admin_gui_api_url

Hierarchical part of a URI which is composed optionally of a host, port, and path at which the Admin API accepts HTTP or HTTPS traffic. When this config is disabled, Kong Manager will use the window protocol + host and append the resolved admin_listen HTTP/HTTPS port.

Default: none

admin_gui_ssl_protocols

Defines the TLS versions supported for Kong Manager

Default: TLSv1.2 TLSv1.3

admin_gui_ssl_cert

The SSL certificate for admin_gui_listen values with SSL enabled.

values:

• absolute path to the certificate
• certificate content
• base64 encoded certificate content

Default: none

admin_gui_ssl_cert_key

The SSL key for admin_gui_listen values with SSL enabled.

values:

• absolute path to the certificate key
• certificate key content
• base64 encoded certificate key content

Default: none

admin_gui_flags

Alters the layout Admin GUI (JSON) The only supported value is { "IMMUNITY_ENABLED": true } to enable Kong Immunity in the Admin GUI.

Default: {}

admin_gui_access_log

Kong Manager Access Logs

Here you can set an absolute or relative path for Kong Manager access logs. When the path is relative, logs are placed in the prefix location.

Setting this value to off disables access logs for Kong Manager.

Default: logs/admin_gui_access.log

admin_gui_error_log

Kong Manager Error Logs

Here you can set an absolute or relative path for Kong Manager access logs. When the path is relative, logs are placed in the prefix location.

Setting this value to off disables error logs for Kong Manager.

Granularity can be adjusted through the log_level directive.

Default: logs/admin_gui_error.log

admin_gui_auth

Kong Manager Authentication Plugin Name

Secures access to Kong Manager by specifying an authentication plugin to use.

Supported Plugins:

• basic-auth: Basic Authentication plugin
• ldap-auth-advanced: LDAP Authentication plugin
• openid-connect: OpenID Connect Authentication plugin

Default: none

admin_gui_auth_conf

Kong Manager Authentication Plugin Config (JSON)

Specifies the configuration for the authentication plugin specified in admin_gui_auth.

For information about Plugin Configuration consult the associated plugin documentation.

Example for basic-auth:

admin_gui_auth_conf = { "hide_credentials": true }

Default: none

admin_gui_auth_password_complexity

Kong Manager Authentication Password Complexity (JSON)

When admin_gui_auth = basic-auth, this property defines the rules required for Kong Manager passwords. Choose from preset rules or write your own.

Example using preset rules:

admin_gui_auth_password_complexity = { "kong-preset": "min_8" }

All values for kong-preset require the password to contain characters from at least three of the following categories:

1. Uppercase characters (A through Z)

2. Lowercase characters (a through z)

3. Base-10 digits (0 through 9)

4. Special characters (for example, &, $, #, %)

Supported preset rules:

• min_8: minimum length of 8
• min_12: minimum length of 12
• min_20: minimum length of 20

To write your own rules, see https://manpages.debian.org/jessie/passwdqc/passwdqc.conf.5.en.html.

NOTE: Only keywords “min”, “max” and “passphrase” are supported.

Example:

admin_gui_auth_password_complexity = { "min": "disabled,24,11,9,8" }

Default: none

admin_gui_session_conf

Kong Manager Session Config (JSON)

Specifies the configuration for the Session plugin as used by Kong Manager.

For information about plugin configuration, consult the Kong Session plugin documentation.

Example:

admin_gui_session_conf = { "cookie_name": "kookie", \
                            "secret": "changeme" }

Default: none

admin_gui_auth_header

Defines the name of the HTTP request header from which the Admin API will attempt to identify the Kong Admin user.

Default: Kong-Admin-User

admin_gui_auth_login_attempts

Number of times a user can attempt to login to Kong Manager. 0 means infinite attempts allowed.

Default: 0

admin_gui_header_txt

Kong Manager Header Text Sets text for Kong Manager Header Banner. Header Banner is not shown if this config is empty.

Default: none

admin_gui_header_bg_color

Kong Manager Header Background Color Sets background color for Kong Manager Header Banner Accepts css color keyword, #-hexadecimal or rgb format. Invalid values are ignored by Manager.

Default: none

admin_gui_header_txt_color

Kong Manager Header Text Color Sets text color for Kong Manager Header Banner.

Accepts css color keyword, #-hexadecimal or rgb format. Invalid values are ignored by Kong Manager.

Default: none

admin_gui_footer_txt

Kong Manager Footer Text Sets text for Kong Manager Footer Banner. Footer Banner is not shown if this config is empty

Default: none

admin_gui_footer_bg_color

Kong Manager Footer Background Color Sets background color for Kong Manager Footer Banner.

Accepts css color keyword, #-hexadecimal or rgb format. Invalid values are ignored by Manager.

Default: none

admin_gui_footer_txt_color

Kong Manager Footer Text Color Sets text color for Kong Manager Footer Banner.

Accepts css color keyword, #-hexadecimal or rgb format. Invalid values are ignored by Kong Manager.

Default: none

admin_gui_login_banner_title

Kong Manager Login Banner Title Text Sets title text for Kong Manager Login Banner.

Login Banner is not shown if both admin_gui_login_banner_title and admin_gui_login_banner_body are empty.

Default: none

admin_gui_login_banner_body

Kong Manager Login Banner Body Text Sets body text for Kong Manager Login Banner.

Login Banner is not shown if both admin_gui_login_banner_title and admin_gui_login_banner_body are empty.

Default: none

Konnect section

konnect_mode

When enabled, the dataplane is connected to Konnect

Default: off

Analytics For Konnect section

analytics_flush_interval

Determine the frequency of flushing local data to Konnect in seconds.

Default: 1

analytics_buffer_size_limit

Max number of messages can be buffered locally before dropping data in case there is no network connection to Konnect.

Default: 100000

analytics_debug

Outputs analytics payload to Kong logs.

Default: off

Admin Smtp Configuration section

admin_emails_from

The email address for the From header for admin emails.

Default: ""

admin_emails_reply_to

Email address for the Reply-To header for admin emails.

Default: none

admin_invitation_expiry

Expiration time for the admin invitation link (in seconds). 0 means no expiration.

Example, 72 hours: 72 * 60 * 60 = 259200

Default: 259200

General Smtp Configuration section

smtp_mock

This flag will mock the sending of emails. This can be used for testing before the SMTP client is fully configured.

Default: on

smtp_host

The hostname of the SMTP server to connect to.

Default: localhost

smtp_port

The port number on the SMTP server to connect to.

Default: 25

smtp_starttls

When set to on, STARTTLS is used to encrypt communication with the SMTP server. This is normally used in conjunction with port 587.

Default: off

smtp_username

Username used for authentication with SMTP server

Default: none

smtp_password

Password used for authentication with SMTP server

Default: none

smtp_ssl

When set to on, SMTPS is used to encrypt communication with the SMTP server. This is normally used in conjunction with port 465.

Default: off

smtp_auth_type

The method used to authenticate with the SMTP server Valid options are plain, login, or nil

Default: none

smtp_domain

The domain used in the EHLO connection and part of the Message-ID header

Default: localhost.localdomain

smtp_timeout_connect

The timeout (in milliseconds) for connecting to the SMTP server.

Default: 60000

smtp_timeout_send

The timeout (in milliseconds) for sending data to the SMTP server.

Default: 60000

smtp_timeout_read

The timeout (in milliseconds) for reading data from the SMTP server.

Default: 60000

smtp_admin_emails

Comma separated list of admin emails to receive notifications.

Example admin1@example.com, admin2@example.com

Default: none

Data & Admin Audit section

When enabled, Kong will store detailed audit data regarding Admin API and database access. In most cases, updates to the database are associated with Admin API requests. As such, database object audit log data is tied to a given HTTP via a unique identifier, providing built-in association of Admin API and database traffic.

audit_log

When enabled, Kong will log information about Admin API access and database row insertions, updates, and deletes.

Default: off

audit_log_ignore_methods

Comma-separated list of HTTP methods that will not generate audit log entries. By default, all HTTP requests will be logged.

Default: none

audit_log_ignore_paths

Comma-separated list of request paths that will not generate audit log entries. By default, all HTTP requests will be logged.

Default: none

audit_log_ignore_tables

Comma-separated list of database tables that will not generate audit log entries. By default, updates to all database tables will be logged (the term “updates” refers to the creation, update, or deletion of a row).

Default: none

audit_log_payload_exclude

Comma-separated list of keys that will be filtered out of the payload. Keys that were filtered will be recorded in the audit log.

Default: token, secret, password

audit_log_record_ttl

Length, in seconds, of the TTL for audit log records. Records in the database older than their TTL are automatically purged.

Example, 30 days: 30 * 24 * 60 * 60 = 2592000

Default: 2592000

audit_log_signing_key

Defines the path to a private RSA signing key that can be used to insert a signature of audit records, adjacent to the record. The corresponding public key should be stored offline, and can be used the validate audit entries in the future. If this value is undefined, no signature will be generated.

Default: none

Granular Tracing section

{:.warning} > Deprecation warning: Granular tracing is deprecated. This means the feature will eventually be removed.

Our target for Granular tracing removal is the Kong Gateway 4.0 release.

Granular tracing offers a mechanism to expose metrics and detailed debug data about the lifecycle of Kong in a human- or machine-consumable format.

tracing

When enabled, Kong will generate granular debug data about various portions of the request lifecycle, such as DB or DNS queries, plugin execution, core handler timing, etc.

Default: off

tracing_write_strategy

Defines how Kong will write tracing data at the conclusion of the request. The default option, file, writes a human-readable depiction of tracing data to a configurable location on the node’s file system. Other strategies write tracing data as a JSON document to the configured endpoint. Valid entries for this option are file, file_raw, http, tcp, tls, and udp.

Default: file

tracing_write_endpoint

Defines the endpoint to which tracing data will be written.

• For the file and file_raw tracing write strategies, this value must be a valid location on the node’s file system to which Kong must have write access.
• For the tcp, tls, and udp strategies, this value is defined as a string in the form of: <HOST>:<PORT>
• For the http strategy, this value is defined in the form of: <scheme>://<IP / HOSTNAME>(:<PORT>(/<PATH>))

Traces sent via HTTP are delivered via POST method with an application/json Content-Type.

Default: none

tracing_time_threshold

The minimum time, in microseconds, over which a trace must execute in order to write the trace data to the configured endpoint. This configuration can be used to lower the noise present in trace data by removing trace objects that are not interesting from a timing perspective. The default value of 0 removes this limitation, causing traces of any duration to be written.

Default: 0

tracing_types

Defines the types of traces that are written.

Trace types not defined in this list are ignored, regardless of their lifetime. The default special value of all results in all trace types being written, regardless of type.

The following trace types are included:

• query: trace the database query
• legacy_query: (deprecated) trace the database query with legacy DAO
• router: trace Kong routing the request; internal routing time
• balancer: trace the execution of the overall balancer phase
• balancer.getPeer: trace Kong selecting an upstream peer from the ring-balancer
• balancer.toip: trace balancer to resolve peer’s host to IP
• connect.toip: trace cosocket to resolve target’s host to IP
• access.before: trace the preprocessing of access phase, like parameter parsing, route matching, and balance preparation
• access.after: trace the postprocess of access phase, like balancer execution and internal variable assigning
• plugin: trace plugins phase handlers

Default: all

tracing_debug_header

Defines the name of the HTTP request header that must be present in order to generate traces within a request. Setting this value provides a mechanism to selectively generate request traces at the client’s request. Note that the value of the header does not matter, only that the header is present in the request. When this value is not set and tracing is enabled, Kong will generate trace data for all requests flowing through the proxy and Admin API. Note that data from certificate handling phases is not logged when this setting is enabled.

Default: none

generate_trace_details

When enabled, Kong will write context- specific details into traces. Trace details offer more data about the context of the trace. This can significantly increase the size of trace reports. Note also that trace details may contain potentially sensitive information, such as raw SQL queries; care should be taken to store traces properly when this option is enabled.

Default: off

Route Collision Detection/Prevention section

route_validation_strategy

The strategy used to validate routes when creating or updating them.

Different strategies are available to tune how to enforce splitting traffic of workspaces.

• smart is the default option and uses the algorithm described in https://docs.konghq.com/gateway/latest/admin-api/workspaces/examples/#important-note-conflicting-services-or-routes-in-workspaces.
• off disables any check.
• path enforces routes to comply with the pattern described in config enforce_route_path_pattern.
• static relies on the PostgreSQL database.

Before creating a new route, it checks if the route is unique across all workspaces based on the following params: paths, methods, and hosts. If all fields of the new route overlap with an existing one, a 409 is returned with the route of the collision. The array order is not important for the overlap filter.

Default: smart

enforce_route_path_pattern

Specifies the Lua pattern which will be enforced on the paths attribute of a Route object. You can also add a placeholder for the workspace in the pattern, which will be rendered during runtime based on the workspace to which the route belongs.

This setting is only relevant if route_validation_strategy is set to path.

Example For Pattern /$(workspace)/v%d/.* valid paths are:

1. /group1/v1/ if route belongs to workspace group1.

2. /group2/v1/some_path if route belongs to workspace group2.

Default: none

Database Encryption & Keyring Management section

When enabled, Kong will transparently encrypt sensitive fields, such as Consumer credentials, TLS private keys, and RBAC user tokens, among others. A full list of encrypted fields is available from the Kong Enterprise documentation site.

Encrypted data is transparently decrypted before being displayed to the Admin API or made available to plugins or core routing logic.

While this feature is GA, do note that we currently do not provide normal semantic versioning compatibility guarantees on the keyring feature’s APIs in that Kong may make a breaking change to the feature in a minor version. Also note that mis-management of keyring data may result in irrecoverable data loss.

keyring_enabled

When enabled, Kong will encrypt sensitive field values before writing them to the database, and subsuquently decrypt them when retrieving data for the Admin API, Developer Portal, or proxy business logic. Symmetric encryption keys are managed based on the strategy defined below.

Default: off

keyring_strategy

Defines the strategy implementation by which Kong nodes will manage symmetric encryption keys. Please see the Kong Enterprise documentation for a detailed description of each strategies. Acceptable values for this option are ‘cluster’ and ‘vault’.

Default: cluster

keyring_public_key

Defines the public key of an RSA keypair.

This keypair is used for symmetric keyring import/export, e.g., for disaster recovery and optional bootstrapping.

values:

• absolute path to the public key
• public key content
• base64 encoded public key content

Default: none

keyring_private_key

Defines the private key of an RSA keypair.

This keypair is used for symmetric keyring import/export, e.g., for disaster recovery and optional bootstrapping.

values:

• absolute path to the private key
• private key content
• base64 encoded private key content

Default: none

keyring_recovery_public_key

Defines the public key to optionally encrypt all keyring materials and backup in the database.

values:

• absolute path to the public key
• public key content
• base64 encoded public key content

Default: none

keyring_blob_path

Defines the filesystem path at which Kong will backup the initial keyring material.

This option is useful largely for development purposes.

Default: none

keyring_vault_host

Defines the Vault host at which Kong will fetch the encryption material. This value should be defined in the format:

<scheme>://<IP / HOSTNAME>:<PORT>

Default: none

keyring_vault_mount

Defines the name of the Vault v2 KV secrets engine at which symmetric keys are found.

Default: none

keyring_vault_path

Defines the names of the Vault v2 KV path at which symmetric keys are found.

Default: none

keyring_vault_auth_method

Defines the authentication mechanism when connecting to the HashiCorp Vault service.

Accepted values are: token, or kubernetes:

• token: Uses the static token defined in the keyring_vault_token configuration property.

• kubernetes: Uses the Kubernetes authentication mechanism, with the running pod’s mapped service account, to assume the HashiCorp Vault role name that is defined in the keyring_vault_kube_role configuration property.

Default: token

keyring_vault_token

Defines the token value used to communicate with the v2 KV Vault HTTP(S) API.

Default: none

keyring_vault_kube_role

Defines the HashiCorp Vault role that will be assumed using the Kubernetes service account of the running pod.

keyring_vault_auth_method must be set to kubernetes for this to activate.

Default: default

keyring_vault_kube_api_token_file

Defines where the Kubernetes service account token should be read from the pod’s filesystem, if using a non-standard container platform setup.

Default: /run/secrets/kubernetes.io/serviceaccount/token

untrusted_lua

Controls loading of Lua functions from admin-supplied sources such as the Admin API. LuaJIT bytecode loading is always disabled.

Warning: LuaJIT is not designed as a secure runtime for running malicious code, therefore you should properly protect your Admin API endpoint even with sandboxing enabled. The sandbox only provides protection against trivial attackers or unintentional modification of the Kong global environment.

Accepted values are: off, sandbox, or on:

• off: Disallow loading of any arbitrary Lua functions. The off option disables any functionality that runs arbitrary Lua code, including the Serverless Functions plugins and any transformation plugin that allows custom Lua functions.

• sandbox: Allow loading of Lua functions, but use a sandbox when executing them. The sandboxed function has restricted access to the global environment and only has access to standard Lua functions that will generally not cause harm to the Kong Gateway node.

• on: Functions have unrestricted access to the global environment and can load any Lua modules. This is similar to the behavior in Kong Gateway prior to 2.3.0.

The default sandbox environment does not allow importing other modules or libraries, or executing anything at the OS level (for example, file read/write). The global environment is also not accessible.

Examples of untrusted_lua = sandbox behavior:

• You can’t access or change global values such as kong.configuration.pg_password * You can run harmless lua: local foo = 1 + 1. However, OS level functions are not allowed, like: os.execute('rm -rf /*').

For a full allowed/disallowed list, see: https://github.com/kikito/sandbox.lua/blob/master/sandbox.lua

To customize the sandbox environment, use the untrusted_lua_sandbox_requires and untrusted_lua_sandbox_environment parameters below.

Default: sandbox

untrusted_lua_sandbox_requires

Comma-separated list of modules allowed to be loaded with require inside the sandboxed environment. Ignored if untrusted_lua is not sandbox.

For example, say you have configured the Serverless pre-function plugin and it contains the following requires:

local template = require "resty.template"
local split = require "kong.tools.utils".split

To run the plugin, add the modules to the allowed list:

untrusted_lua_sandbox_requires = resty.template, kong.tools.utils

Warning: Allowing certain modules may create opportunities to escape the sandbox. For example, allowing os or luaposix may be unsafe.

Default: none

untrusted_lua_sandbox_environment

Comma-separated list of global Lua variables that should be made available inside the sandboxed environment. Ignored if untrusted_lua is not sandbox.

Warning: Certain variables, when made available, may create opportunities to escape the sandbox.

Default: none

openresty_path

Path to the OpenResty installation that Kong will use. When this is empty (the default), Kong determines the OpenResty installation by searching for a system-installed OpenResty and falling back to searching $PATH for the nginx binary.

Setting this attribute disables the search behavior and explicitly instructs Kong which OpenResty installation to use.

Default: none

node_id

Node ID for the Kong node. Every Kong node in a Kong cluster must have a unique and valid UUID. When empty, node ID is automatically generated.

Default: none

Cluster Fallback Configuration section

cluster_fallback_config_import

Enable fallback configuration imports.

This should only be enabled for data planes.

Default: off

cluster_fallback_config_storage

Storage definition used by cluster_fallback_config_import and cluster_fallback_config_export.

Supported storage types:

• S3-like storages
• GCP storage service

To use S3 with a bucket named b and place all configs to with a key prefix named p, set it to: s3://b/p To use GCP for the same bucket and prefix, set it to: gcs://b/p

The credentials (and the endpoint URL for S3-like) for S3 are passed with environment variables: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_CONFIG_STORAGE_ENDPOINT (extension), where AWS_CONFIG_STORAGE_ENDPOINT is the endpoint that hosts S3-like storage.

The credentials for GCP are provided via the environment variable GCP_SERVICE_ACCOUNT.

Default: none

cluster_fallback_export_s3_config

fallback config export S3 config This is used only when cluster_fallback_config_storage is S3-like schema.

If set, it will add config table to kong exporter config S3 putObject request.

The config table should be in JSON format and can be unserialized into a table.

It should contain the necessary parameters as described in the documentation.

https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#putObject-property.

For example, if you want to set the ServerSideEncryption headers / KMS Key ID for the S3 putObject request, you can set the config table to: {"ServerSideEncryption": "aws:kms", "SSEKMSKeyId": "your-kms-key-id"}

Default: none

cluster_fallback_config_export

Enable fallback configuration exports.

Default: off

cluster_fallback_config_export_delay

The fallback configuration export interval.

If the interval is set to 60 and configuration A is exported and there are new configurations B, C, and D in the next 60 seconds, it will wait until 60 seconds passed and export D, skipping B and C.

Default: 60

WebAssembly (Wasm) section

wasm

Enable/disable wasm support. This must be enabled in order to use wasm filters and filter chains.

Default: off

wasm_filters_path

Path to the directory containing wasm filter modules.

At startup, Kong discovers available wasm filters by scanning this directory for files with the .wasm file extension.

The name of a wasm filter module is derived from the filename itself, with the .wasm extension removed. So, given the following tree:

/path/to/wasm_filters
├── my_module.wasm
├── my_other_module.wasm
└── not_a_wasm_module.txt

The resulting filter modules available for use in Kong will be:

• my_module
• my_other_module

Notes:

• No recursion is performed. Only .wasm files at the top level are registered
• This path may be a symlink to a directory.

Default: none

Wasm Injected Directives section

The Nginx Wasm module (i.e. ngx_wasm_module) has its own settings, which can be tuned via wasm_* directives in the Nginx configuration file. Kong supports configuration of these directives via its Nginx directive injection mechanism.

The following namespaces are supported:

• nginx_wasm_<directive>: Injects <directive> into the wasm {} block.
• nginx_wasm_shm_kv_<name>: Injects shm_kv <name> into the wasm {} block, allowing operators to define custom shared memory zones which are usable by the get_shared_data/set_shared_data Proxy-Wasm SDK functions.
• nginx_wasm_wasmtime_<flag>: Injects flag <flag> into the wasmtime {} block, allowing various Wasmtime-specific flags to be set.
• nginx_<http|proxy>_<directive>: Injects <directive> into the http {} or server {} blocks, as specified in the Nginx injected directives section.

The documentation for all supported directives can be found in the Nginx Wasm module repository:

https://github.com/Kong/ngx_wasm_module/blob/main/docs/DIRECTIVES.md

The Wasmtime flag documentation can be found here:

https://docs.wasmtime.dev/c-api/config_8h.html

There are several noteworthy ngx_wasm_module behaviors which can be tuned via http {}/server {} level directive injection (identical behavior in either level), for example:

• nginx_http_proxy_wasm_socket_<connect|read|send>_timeout: sets connection/read/send timeouts for Wasm dispatches.
• nginx_http_proxy_wasm_socket_buffer_size: sets a buffer size for reading Wasm dispatch responses.

The values for these settings are inherited from their nginx_*_lua_* counterparts if they have not been explicitly set. For instance, if you set nginx_http_lua_socket_connect_timeout, the value of this setting will be propagated to nginx_http_wasm_socket_connect_timeout unless you also set nginx_http_wasm_socket_connect_timeout.

Some TLS-related settings receive special treatment as well:

• lua_ssl_trusted_certificate: when set, the value is propagated to the nginx_wasm_tls_trusted_certificate directive.
• lua_ssl_verify_depth: when set (to a value greater than zero), several TLS-related nginx_wasm_* settings are enabled:
  • nginx_wasm_tls_verify_cert
  • nginx_wasm_tls_verify_host
  • nginx_wasm_tls_no_verify_warn

Like other kong.conf fields, all injected Nginx directives documented here can be set via environment variable. For instance, setting:

KONG_NGINX_WASM_TLS_VERIFY_CERT=<value>

Will inject the following in to the wasm {} block:

tls_verify_cert <value>;

There are several Nginx directives supported by ngx_wasm_module which should not be used because they are irrelevant to or unsupported by Kong, or they may conflict with Kong’s own management of Proxy-Wasm. Use of these directives may result in unintentional breakage:

• wasm_call
• module
• proxy_wasm
• resolver_add
• proxy_wasm_request_headers_in_access
• shm_queue

Request Debugging section

Request debugging is a mechanism that allows admin to collect the timing of proxy path request in the response header (X-Kong-Request-Debug-Output) and optionally, the error log.

This feature provides insights into the time spent within various components of Kong, such as plugins, DNS resolution, load balancing, and more. It also provides contextual information such as domain name tried during these processes.

request_debug

When enabled, Kong will provide detailed timing information for its components to the client and the error log if the following headers are present in the proxy request:

• X-Kong-Request-Debug: If the value is set to *, timing information will be collected and exported for the current request. If this header is not present or contains unknown value, timing information will not be collected for the current request. You can also specify a list of filters, separated by commas, to filter the scope of the time information that is collected. The following filters are supported:
  • rewrite: Collect timing information from the rewrite phase.
  • access: Collect timing information from the access phase.
  • balancer: Collect timing information from the balancer phase.
  • response: Collect timing information from the response phase.
  • header_filter: Collect timing information from the header_filter phase.
  • body_filter: Collect timing information from the body_filter phase.
  • log: Collect timing information from the log phase.
  • upstream: Collect timing information from the upstream phase.

• X-Kong-Request-Debug-Log: If set to true, timing information will also be logged in the Kong error log with a log level of notice. Defaults to false.

• X-Kong-Request-Debug-Token: Token for authenticating the client making the debug request to prevent abuse. Debug requests originating from loopback addresses do not require this header.

Default: on

request_debug_token

The Request Debug Token is used in the X-Kong-Request-Debug-Token header to prevent abuse.

If this value is not set (the default), a random token will be generated when Kong starts, restarts, or reloads. If a token is specified manually, then the provided token will be used.

You can locate the generated debug token in two locations:

• Kong error log: Debug token will be logged in the error log (notice level) when Kong starts, restarts, or reloads. The log line will have the: [request-debug] prefix to aid searching.
• Filesystem: Debug token will also be stored in a file located at {prefix}/.request_debug_token and updated when Kong starts, restarts, or reloads.

Default: <random>