Kong Gateway configuration reference

Working directory. Equivalent to Nginx’s prefix path, containing temporary files and logs. Each Kong process must have a separate working directory.

Log level of the Nginx server. Logs are found at <prefix>/logs/error.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.

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

Path for TCP streams proxy port access logs. Set 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'

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

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.

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

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.

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

Path for Debug API request access logs. The default value 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.

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

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}.*.

Deprecated: use tracing_instrumentations instead.

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

Valid values for this setting are:

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

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

Deprecated: use tracing_sampling_rate instead.

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

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

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

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

Path to the unix socket used by the pluginserver.

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

Full command to “query” the

With this configuration parameter, you can let Kong Gateway know 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.

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

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

Toggles server certificate verification if proxy_server is in HTTPS. See the lua_ssl_trusted_certificate setting to specify a certificate authority.

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>

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.

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.

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.

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.

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

Sets the verification method between nodes of the cluster.

Valid values for 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 must 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 to pki but additionally checks for the common name of the data plane certificate specified in cluster_allowed_common_names.

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

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

The trusted CA certificate file in PEM format used for:

• Control plane to verify data plane’s certificate
• Data plane to verify control plane’s certificate

Required on data plane if cluster_mtls is set to pki. If the control plane certificate is issued by a well-known CA, set lua_ssl_trusted_certificate=system on the 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

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, only data plane with the same parent domain as the control plane cert is allowed to connect.

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

The setting to enable or disable the incremental synchronization of configuration changes. Instead of sending the entire entity config to data planes on each config update, incremental config sync lets you send only the changed configuration to data planes for hybrid mode deployments. The valid values are on and off. To enable, set this value to on.

In hybrid mode, this setting must be configured on both control plane and data plane nodes.

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.

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.

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.

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

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

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.

Connections made to this endpoint are logged to the same location as Admin API access logs. See admin_access_log config description for more information.

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.

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 the CP hasn’t heard from a DP for 14 days, its entry will be removed.

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

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.

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

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 to prevent clients seeing “Connection refused” errors when connecting to a busy Kong instance. Note: On Linux, this value is limited by the setting of the 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 specifies 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, 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.

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.

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 to prevent clients seeing “Connection refused” errors when connecting to a busy Kong instance. Note: On Linux, this value is limited by the setting of the 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 specifies 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.

Deprecated: Use admin_gui_api_url instead

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 interfaces, 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 to prevent clients seeing “Connection refused” errors when connecting to a busy Kong instance. Note: On Linux, this value is limited by the setting of the 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 specifies 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, 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

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

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

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.

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.

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.

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 workers are used.

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.

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.

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

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

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 need this, and intermediate uses ffdhe2048.

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

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

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

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

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

If more than one certificate is specified, it can be used to provide alternate types of certificates (for example, ECC certificates) that will be served to clients that support them. Note that 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) the first time it starts up and use them 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

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) the first time it starts up and use them 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

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

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

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 any of the following values:

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

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

See docs for ssl_cert for detailed usage.

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

See docs for ssl_cert_key for detailed usage.

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

See docs for ssl_cert for detailed usage.

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

See docs for ssl_cert_key for detailed usage.

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

See docs for ssl_cert for detailed usage.

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

See docs for ssl_cert_key for detailed usage.

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

Accepted values are:

• Server: Injects Server: kong/x.y.z on Kong-produced responses (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 milliseconds) by Kong to produce a response in case of, e.g., a plugin short-circuiting the request, or 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.
• X-Kong-Total-Latency: Time elapsed (in milliseconds) between the first bytes being read from the client and the log write after the last bytes were sent to the client. Calculated as the difference between the current timestamp and the timestamp when the request was created.
• X-Kong-Third-Party-Latency: Cumulative sum of all third-party latencies, including DNS resolution, HTTP client calls, Socket operations, and Redis operations.
• X-Kong-Client-Latency: Time that Kong waits to receive headers and body from the client, and also how long Kong waits for the client to read/receive the response from Kong.
• 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.
• advanced_latency_tokens: Same as specifying X-Kong-Proxy-Latency, X-Kong-Response-Latency, X-Kong-Admin-Latency, X-Kong-Upstream-Latency. X-Kong-Total-Latency, X-Kong-Third-Party-Latency, and X-Kong-Client-Latency.

In addition to these, 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

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.

Defines trusted IP address 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.

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.

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

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.

Sets the default maximum number of requests that 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.

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.

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

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

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

Size of the shared memory cache for consumers and credentials.

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

Note: This is only used when the “externalized consumers” feature is active.

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

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

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

Sets the maximum number and size of buffers used for reading large client request headers. See http://nginx.org/en/docs/http/ngx_http_core_module.html#large_client_header_buffers

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

Defines the maximum request body size for Admin API.

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

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

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

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.

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 do not make use of the PCRE library and their behavior is unaffected by this setting.

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 a maximum number of requests could result in excessive memory usage and is not recommended. See: https://nginx.org/en/docs/http/ngx_http_core_module.html#keepalive_requests

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

Host of the Postgres server.

Port of the Postgres server.

Defines the timeout (in ms), for connecting, reading and writing.

Postgres user.

Postgres user’s password.

Determines whether the AWS IAM database Authentication will be used. When switch to on, the username defined in pg_user will be used as the database account, and the database connection will be forced to using TLS. pg_password will not be used when the switch is on. Note that the corresponding IAM policy must be correct, otherwise connecting will fail.

The target AWS IAM role ARN that will be assumed when using AWS IAM database authentication. 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.

The role session name used for role assuming in AWS IAM Database Authentication. The default value is KongPostgres.

The custom STS endpoint URL used for role assuming in AWS IAM Database Authentication.

Note that this value will override the default STS endpoint URL(which should be https://sts.amazonaws.com, or https://sts.<region>.amazonaws.com if you have AWS_STS_REGIONAL_ENDPOINTS set to regional).

If you are not using private VPC endpoint for STS service, you should not specify this value.

The database name to connect to.

The database schema to use. If unspecified, Kong will respect the search_path value of your PostgreSQL instance.

Toggles client-server TLS connections between Kong and PostgreSQL. Because PostgreSQL uses the same port for TLS and non-TLS, this is only a hint. If the server does not support TLS, the established connection will be a plain one.

When using ssl between Kong and PostgreSQL, the version of tls to use. Accepted values are tlsv1_1, tlsv1_2, tlsv1_3, or ‘any’. When any is set, the client negotiates the highest version with the server which can’t be lower than tlsv1_1.

When pg_ssl is on this determines if TLS must be used between Kong and PostgreSQL. It aborts the connection if the server does not support SSL connections.

Toggles server certificate verification if pg_ssl is enabled. See the lua_ssl_trusted_certificate setting to specify a certificate authority.

The absolute path to the PEM encoded client TLS certificate for the PostgreSQL connection. Mutual TLS authentication against PostgreSQL is only enabled if this value is set.

If pg_ssl_cert is set, the absolute path to the PEM encoded client TLS private key for the PostgreSQL connection.

Sets the maximum number of concurrent queries that can be executing at any given time. This limit is enforced per worker process; the total number of concurrent queries for this node will be will be: pg_max_concurrent_queries * nginx_worker_processes.

The default value of 0 removes this concurrency limitation.

Defines the timeout (in ms) after which PostgreSQL query semaphore resource acquisition attempts will fail. Such failures will generally result in the associated proxy or Admin API request failing with an HTTP 500 status code. Detailed discussion of this behavior is available in the online documentation.

Specify the maximal idle timeout (in ms) for the postgres connections in the pool. If this value is set to 0 then the timeout interval is unlimited.

If not specified this value will be same as lua_socket_keepalive_timeout

Specifies the size limit (in terms of connection count) for the Postgres server. Note that this connection pool is intended per Nginx worker rather than per Kong instance.

If not specified, the default value is the same as lua_socket_pool_size

If specified, this value will limit the total number of open connections to the Postgres server to pg_pool_size. If the connection pool is full, subsequent connect operations will be inserted in a queue with size equal to this option’s value.

If the number of queued connect operations reaches pg_backlog, exceeding connections will fail.

If not specified, then number of open connections to the Postgres server is not limited.

Same as pg_host, but for the read-only connection. Note: Refer to the documentation section above for detailed usage.

Same as pg_port, but for the read-only connection.

Same as pg_timeout, but for the read-only connection.

Same as pg_user, but for the read-only connection.

Same as pg_password, but for the read-only connection.

Same as pg_iam_auth, but for the read-only connection.

Same as `pg_iam_auth_assume_role_arn’, but for the read-only connection.

Same as pg_iam_auth_role_session_name, but for the read-only connection.

Same as pg_iam_auth_sts_endpoint_url, but for the read-only connection.

Same as pg_database, but for the read-only connection.

Same as pg_schema, but for the read-only connection.

Same as pg_ssl, but for the read-only connection.

Same as pg_ssl_required, but for the read-only connection.

Same as pg_ssl_verify, but for the read-only connection.

Same as pg_ssl_version, but for the read-only connection.

Same as pg_max_concurrent_queries, but for the read-only connection. Note: read-only concurrency is not shared with the main (read-write) connection.

Same as pg_semaphore_timeout, but for the read-only connection.

Same as pg_keepalive_timeout, but for the read-only connection.

Same as pg_pool_size, but for the read-only connection.

Same as pg_backlog, but for the read-only connection.

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.

The declarative configuration as a string

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.

Maximum size of the LMDB memory map, used to store the DB-less and hybrid 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 reloads/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.

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.

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 the maximum expected replication lag between the writer and reader instances.

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.

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.

Time (in seconds) for which stale entities from the datastore should be resurrected 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.

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.

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.

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.

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.

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.

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.

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.

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

TTL in seconds for error responses.

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 synchronized to a single query.

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.

The AWS region your vault is located in.

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.

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.

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

The custom STS endpoint URL used for role assuming in AWS Vault.

Note that this value will override the default STS endpoint URL(which should be https://sts.amazonaws.com, or https://sts.<region>.amazonaws.com if you have AWS_STS_REGIONAL_ENDPOINTS set to regional).

If you are not using private VPC endpoint for STS service, you should not specify this value.

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.

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.

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.

The project ID from your Google API Console.

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.

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.

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.

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

The hostname of your HashiCorp vault.

The port number of your HashiCorp vault.

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

The mount point.

The secrets engine version. Accepts v1 or v2.

A token string.

Defines the authentication mechanism when connecting to the Hashicorp Vault service. Accepted values are: token, kubernetes or approle.

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.

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

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

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

The Role ID of the Approle in HashiCorp Vault.

The Secret ID of the Approle in HashiCorp Vault.

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

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

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.

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.

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.

The URI the vault is reachable from.

The client ID from your registered Application. Visit your Azure Dashboard and select App Registrations to check your client 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”

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

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.

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.

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.

The configured trusted certificate role name.

The contents of the certificate to use in Hashicorp Vault auth if auth_method is set to cert.

The contents of the private key for use in Hashicorp Vault auth if auth_method is set to cert.

Defines whether this node should rebuild its state synchronously or asynchronously (the balancers and the router are rebuilt on updates that affect 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 increased long-tail latency can be observed if frequent routes and services updates are expected. Using eventual will help prevent 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.

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.

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 a 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. The traditional router config interface is still visible, and you can also write router Expressions manually and provide them in the expression field on the route object.

• traditional: the pre-3.0 router engine will be used. The 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 if traditional_compatible does not work as expected. This flavor of the router will be removed in the next major release of Kong.

Maximum number of request headers to parse by default.

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

When proxying, 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.

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.

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.

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.

When enabled, plugin options stored as vault secrets are loaded only when they are first requested. This can improve startup performance when using many vault references. When disabled, all vault secrets are loaded during initialization.

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 file paths.

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

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

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.

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

Sets the Lua C module search path (LUA_CPATH).

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

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

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.

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

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/api/admin-ee/latest/#/Event-hooks/get-event-hooks

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

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.

Kong Manager URL

Comma-separated list of addresses (the lookup or balancer) for Kong Manager.

Accepted format (items in square brackets are optional):

<scheme>://<IP / HOSTNAME>[:<PORT>][<PATH>][, <scheme>://<IP / HOSTNAME>[:<PORT>][<PATH>]]

Examples:

• http://127.0.0.1:8003
• https://kong-admin.test
• http://dev-machine
• http://127.0.0.1:8003, https://exmple.com/manager

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

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.

The SSL certificate for admin_gui_listen values with SSL enabled.

values:

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

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

Alters the layout Admin GUI (JSON) to enable Kong Immunity in the Admin GUI.

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.

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.

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

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 }

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

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

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

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

Sets the text for the Kong Manager header banner. Header banner is not shown if this config is empty.

Sets the background color for the Kong Manager header banner. Accepts CSS color keyword, #-hexadecimal, or RGB format. Invalid values are ignored by Manager.

Sets the text color for the Kong Manager header banner. Accepts CSS color keyword, #-hexadecimal, or RGB format. Invalid values are ignored by Kong Manager.

Sets the text for the Kong Manager footer banner. Footer banner is not shown if this config is empty.

Sets the background color for the Kong Manager footer banner. Accepts CSS color keyword, #-hexadecimal, or RGB format. Invalid values are ignored by manager.

Sets the text color for the Kong Manager footer banner. Accepts CSS color keyword, #-hexadecimal, or RGB format. Invalid values are ignored by Kong Manager.

Sets the title text for the Kong Manager login banner. Login banner is not shown if both admin_gui_login_banner_title and admin_gui_login_banner_body are empty.

Sets the body text for the Kong Manager login banner. Login banner is not shown if both admin_gui_login_banner_title and admin_gui_login_banner_body are empty.

Defines the TLS versions supported for Kong Manager

Number of times a user can attempt to change password. 0 means infinite attempts allowed.

Length, in seconds, of the TTL for changing password attempts records. Records in the database older than their TTL are automatically purged.

Example, 1 days: 1 * 24 * 60 * 60 = 86400.

Length, in seconds, of the TTL for changing login attempts records. Records in the database older than their TTL are automatically purged.

This argument can be set to an integer between 0 and 100000000.

Example, 7 days: 7 * 24 * 60 * 60 = 604800.

Enable or disable the Content-Security-Policy (CSP) header for Kong Manager

This configuration controls the presence of the CSP header when serving Kong Manager. The default CSP header value will be used unless customized.

To modify the value of the served CSP header, refer to the admin_gui_csp_header_value configuration.

Set this configuration to on to enable the CSP header.

The value of the Content-Security-Policy (CSP) header for Kong Manager.

This configuration controls the value of the CSP header when serving Kong Manager. If omitted or left empty, the default CSP header value will be used.

This is an advanced configuration intended for cases where the default CSP header value does not meet your requirements. Use with caution.

For more information on the CSP header, see: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy

Hides all Konnect call to actions in Kong Manager. This setting is only relevant for on-prem installations of Kong Enterprise.

When enabled, Kong will store and report metrics about its performance.

When running Kong in a multi-node setup, vitals entails two separate meanings depending on the node.

On a Proxy-only node, vitals determines whether to collect data for Vitals.

On an Admin-only node, vitals determines whether to display Vitals metrics and visualizations on the dashboard.

Determines whether to use the Kong database or a separate storage engine for Vitals metrics. Accepted values are database, prometheus, or influxdb.

Defines the host and port of the TSDB server to which Vitals data is written and read. This value is only applied when the vitals_strategy option is set to prometheus or influxdb. This value accepts IPv4, IPv6, and hostname values. If the vitals_strategy is set to prometheus, this value determines the address of the Prometheus server from which Vitals data will be read. For influxdb strategies, this value controls both the read and write source for Vitals data.

Influxdb user

Influxdb password

Defines the host and port (and an optional protocol) of the StatsD server to which Kong should write Vitals metics. This value is only applied when the vitals_strategy is set to prometheus. This value accepts IPv4, IPv6, and, hostnames. Additionally, the suffix tcp can be specified; doing so will result in Kong sending StatsD metrics via TCP instead of the UDP (default).

Defines the prefix value attached to all Vitals StatsD events. This prefix is useful when writing metrics to a multi-tenant StatsD exporter or server.

Defines the maximum buffer size in which Vitals statsd metrics will be held and sent in batches. This value is defined in bytes.

Defines the scrape_interval query parameter sent to the Prometheus server when reading Vitals data. This should be same as the scrape interval (in seconds) of the Prometheus server.

When enabled, the dataplane is connected to Konnect

Specify the maximum frequency, in seconds, at which local analytics and licensing data are flushed to the database or Konnect, depending on the installation mode. Kong also triggers a flush when the number of messages in the buffer is less than analytics_buffer_size_limit, regardless of whether the specified time interval has elapsed.

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

Outputs analytics payload to Kong logs.

Developer Portal Switch

When enabled:

Kong will expose the Dev Portal interface and read-only APIs on the portal_gui_listen address, and endpoints on the Admin API to manage assets.

When enabled along with portal_auth:

Kong will expose management endpoints for developer accounts on the Admin API and the Dev Portal API.

Developer Portal GUI Listeners

Comma-separated list of addresses on which Kong will expose the Developer Portal GUI. Suffixes can be specified for each pair, similarly to the admin_listen directive.

Developer Portal GUI protocol

The protocol used in conjunction with portal_gui_host to construct the lookup, or balancer address for your Kong Proxy nodes.

Examples: http,https

Developer Portal GUI host

The host used in conjunction with portal_gui_protocol to construct the lookup, or balancer address for your Kong Proxy nodes.

Examples:

• <IP>:<PORT> -> portal_gui_host = 127.0.0.1:8003
• <HOSTNAME> -> portal_gui_host = portal_api.domain.tld
• <HOSTNAME>/<PATH> -> portal_gui_host = dev-machine/dev-285

Developer Portal CORS Origins

A comma separated list of allowed domains for Access-Control-Allow-Origin header. This can be used to resolve CORS issues in custom networking environments.

Examples:

• list of domains: portal_cors_origins = http://localhost:8003, https://localhost:8004
• single domain: portal_cors_origins = http://localhost:8003
• all domains: portal_cors_origins = *

NOTE: In most cases, the Developer Portal is able to derive valid CORS origins by using portal_gui_protocol, portal_gui_host, and if applicable, portal_gui_use_subdomains. In these cases, portal_cors_origins is not needed and can remain unset.

Developer Portal GUI subdomain toggle

By default Kong Portal uses the first namespace in the request path to determine workspace. By turning portal_gui_subdomains on, Kong Portal will expect workspace to be included in the request url as a subdomain.

Example (off):

• <scheme>://<HOSTNAME>/<WORKSPACE>/<PATH> -> http://kong-portal.com/example-workspace/index

Example (on):

• <scheme>://<WORKSPACE>.<HOSTNAME> -> http://example-workspace.kong-portal.com/index

Developer Portal GUI SSL Certificate

The SSL certificate for portal_gui_listen values with SSL enabled.

values:

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

Developer Portal GUI SSL Certificate Key

The SSL key for portal_gui_listen values with SSL enabled.

values:

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

Developer Portal GUI Access Log location

Here you can set an absolute or relative path for your Portal GUI access logs.

Setting this value to off will disable logging Portal GUI access logs.

When using relative pathing, logs will be placed under the prefix location.

Developer Portal GUI Error Log location

Here you can set an absolute or relative path for your Portal GUI error logs.

Setting this value to off will disable logging Portal GUI error logs.

When using relative pathing, logs will be placed under the prefix location.

Granularity can be adjusted through the log_level directive.

Developer Portal API Listeners

Comma-separated list of addresses on which Kong will expose the Developer Portal API. Suffixes can be specified for each pair, similarly to the admin_listen directive.

Developer Portal API URL

The lookup, or balancer, address for your Developer Portal nodes.

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

portal_api_url is the address on which your Kong Dev Portal API is accessible by Kong. You should only set this value if your Kong Dev Portal API lives on a different node than your Kong Proxy.

Accepted format (parts in parenthesis are optional):

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

Examples:

• <scheme>://<IP>:<PORT> -> portal_api_url = http://127.0.0.1:8003
• SSL <scheme>://<HOSTNAME> -> portal_api_url = https://portal_api.domain.tld
• <scheme>://<HOSTNAME>/<PATH> -> portal_api_url = http://dev-machine/dev-285

By default this value points to the local interface:

• http://0.0.0.0:8004

Developer Portal API SSL Certificate

The SSL certificate for portal_api_listen values with SSL enabled.

values:

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

Developer Portal API SSL Certificate Key

The SSL key for portal_api_listen values with SSL enabled.

values:

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

Developer Portal API Access Log location

Here you can set an absolute or relative path for your Portal API access logs.

Setting this value to off will disable logging Portal API access logs.

When using relative pathing, logs will be placed under the prefix location.

Developer Portal API Error Log location

Here you can set an absolute or relative path for your Portal API error logs.

Setting this value to off will disable logging Portal API error logs.

When using relative pathing, logs will be placed under the prefix location.

Granularity can be adjusted through the log_level directive.

Developer Portal legacy support

Setting this value to on will cause all new portals to render using the legacy rendering system by default.

Setting this value to off will cause all new portals to render using the current rendering system.

Developer Portal application registration auth provider and strategy. Must be set to enable application_registration plugin

Developer Portal Authentication Plugin Name

Specifies the authentication plugin to apply to your Developer Portal. Developers will use the specified form of authentication to request access, register, and login to your Developer Portal.

Supported Plugins:

• Basic Authentication: portal_auth = basic-auth
• OIDC Authentication: portal_auth = openid-connect

Kong Portal Authentication Password Complexity (JSON)

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

Example using preset rules:

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

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

Developer Portal Authentication Plugin Config (JSON)

Specifies the plugin configuration object in JSON format to be applied to your Developer Portal authentication.

For information about Plugin Configuration consult the associated plugin documentation.

Example for basic-auth:

portal_auth_conf = { "hide_credentials": true }

Number of times a user can attempt to login to the Dev Portal before password must be reset.

0 (default) means infinite attempts allowed.

Note: Any value greater than 0 will only affect Dev Portals secured with basic-auth.

Portal Session Config (JSON)

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

For information about Plugin Configuration consult the Kong Session Plugin documentation.

Example:

portal_session_conf = { "cookie_name": "portal_session", \
                         "secret": "changeme", \
                         "storage": "kong" }

Developer Portal Auto Approve Access

When set to on, a developer will automatically be marked as “approved” after completing registration. Access can still be revoked through Kong Manager or the Admin API.

When set to off, a Kong admin will have to manually approve the Developer using Kong Manager or the Admin API.

Duration in seconds for the expiration of the Dev Portal reset password token. Default is 21600 (six hours).

Portal Developer Email Verification.

When enabled Developers will receive an email upon registration to verify their account. Developers will not be able to use the Developer Portal until they verify their account, even if auto-approve is enabled.

Note: SMTP must be turned on in order to use this feature.

When enabled, Kong admins can invite developers to a Dev Portal by using the Invite button in Kong Manager.

The email looks like the following:

Subject: Invite to access Dev Portal <WORKSPACE_NAME>

Hello Developer!

You have been invited to create a Dev Portal account at %s.
Please visit `<DEV_PORTAL_URL/register>` to create your account.

When enabled, Kong admins specified by smtp_admin_emails will receive an email when a developer requests access to a Dev Portal.

When disabled, Kong admins will have to manually check the Kong Manager to view any requests.

The email looks like the following:

Subject: Request to access Dev Portal <WORKSPACE NAME>

Hello Admin!

<DEVELOPER NAME> has requested Dev Portal access for <WORKSPACE_NAME>.
Please visit <KONG_MANAGER_URL/developers/requested> to review this request.

When enabled, developers will receive an email when access to a Dev Portal has been approved.

When disabled, developers will receive no indication that they have beenapproved. It is suggested to only disable this feature if portal_auto_approve is enabled.

The email looks like the following:

Subject: Dev Portal access approved

Hello Developer!
You have been approved to access <WORKSPACE_NAME>.
Please visit <DEV PORTAL URL/login> to login.

When enabled, developers will be able to use the Reset Password flow on a Dev Portal and will receive an email with password reset instructions.

Note: When disabled, developers will not be able to reset their account passwords. The password resetting email is the only way to reset developer passwords.

The email looks like the following:

Subject: Password Reset Instructions for Dev Portal <WORKSPACE_NAME>.

Hello Developer,

Please click the link below to reset your Dev Portal password.

<DEV_PORTAL_URL/reset?token=12345>

This link will expire in <portal_reset_token_exp>

If you didn't make this request, keep your account secure by clicking
the link above to change your password.

When enabled, developers will receive an email after successfully resetting their Dev Portal account password.

When disabled, developers will still be able to reset their account passwords, but will not receive a confirmation email.

The email looks like the following:

Subject: Dev Portal password change success

Hello Developer,
We are emailing you to let you know that your Dev Portal password at <DEV_PORTAL_URL> has been changed.

Click the link below to sign in with your new credentials.

<DEV_PORTAL_URL>

When enabled, developers will receive an email when the status changes for their appliciation service requests.

When disabled, developers will still be able to view the status in their developer portal application page.

The email looks like the following:

Subject: Dev Portal application request <REQUEST_STATUS> (<DEV_PORTAL_URL>)

Hello Developer,
We are emailing you to let you know that your request for application access from the
Developer Portal account at <DEV_PORTAL_URL> is <REQUEST_STATUS>.

Application: <APPLICATION_NAME>
Service: <SERVICE_NAME>

You will receive another email when your access has been approved.

When enabled, Kong admins specified by smtp_admin_emails will receive an email when a developer requests access to service through an application.

When disabled, Kong admins will have to manually check the Kong Manager to view any requests.

By default, smtp_admin_emails will be the recipients. This can be overriden by portal_smtp_admin_emails, which can be set dynamically per workspace through the Admin API.

The email looks like the following:

Subject: Request to access Dev Portal (<DEV_PORTAL_URL>) service from <DEVELOPER_EMAIL>

Hello Admin,

<DEVELOPER NAME> (<DEVELOPER_EMAIL>) has requested application access for <DEV_PORTAL_URL>.

Requested workspace: <WORKSPACE_NAME>
Requested application: <APPLICATION_NAME>
Requested service: <SERVICE_NAME>

Please visit <KONG_MANAGER_URL/WORKSPACE_NAME/applications/APPLICATION_ID#requested> to review this request.

The name and email address for the From header included in all Dev Portal emails.

Example: portal_emails_from = Your Name <example@example.com>

Note: Some SMTP servers will not use this value, but instead insert the email and name associated with the account.

Email address for the Reply-To header for portal emails

Example: portal_emails_reply_to = example@example.com

Note: Some SMTP servers will not use this value, but instead insert the email associated with the account.

Comma separated list of admin emails to receive portal notifications. Can be dynamically set per workspace through the Admin API.

If not set, smtp_admin_emails will be used.

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

The email address for the From header for admin emails.

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

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

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

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

The hostname of the SMTP server to connect to.

The port number on the SMTP server to connect to.

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

Username used for authentication with SMTP server

Password used for authentication with SMTP server

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

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

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

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

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

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

Comma separated list of admin emails to receive notifications. Example admin1@example.com, admin2@example.com

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

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

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

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

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

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

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 to validate audit entries in the future. If this value is undefined, no signature will be generated.

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.

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.

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.

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.

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

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.

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.

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/kong-enterprise/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.

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.

Note: The collision detection is only supported for plain text routes, do not rely on this feature to validate regex routes.

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.

When enabled, Kong will encrypt sensitive field values before writing them to the database, and subsequently 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.

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 strategy. Acceptable values for this option are cluster and vault.

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

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

Defines the filesystem path at which Kong will back up the initial keyring material. This option is useful largely for development purposes.

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

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

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

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

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.

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

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.

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

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 Kong PDK, OpenResty, and 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 /*).

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

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.string".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.

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.

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.

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.

Defines the public key to optionally encrypt all keyring materials and back them up in the database.

Values:

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

Enables keyring encryption for license payloads stored in the database.

Warning: For Kong deployments that rely entirely on the database for license provisioning (i.e. not using KONG_LICENSE_DATA or KONG_LICENSE_PATH), enabling this option will delay license activation until after the node’s keyring has been activated.

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 an 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 for X-Kong-Request-Debug:
• 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. ** Note: Debug requests originating from loopback addresses do not require this header. Deploying Kong behind other proxies may result in exposing the debug interface to the public.**

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.

Enable fallback configuration imports.

This should only be enabled for data planes.

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.

Enable fallback configuration exports.

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.

Fallback config export S3 configuration. This is used only when cluster_fallback_config_storage is an S3-like schema. If set, it will add the config table to the 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"}

Enable or disable the new 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.

Examples:

resolver_address = 8.8.8.8
resolver_address = 8.8.8.8, [::1]
resolver_address = 8.8.8.8:53, [::1]:53

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.

The supported query types.

For a domain name, Kong will only query either IP addresses (A or AAAA) or SRV records, but not both.

It will query SRV records only when the domain matches the “_._." format, for example, "_ldap._tcp.example.com".

For IP addresses (A or AAAA) resolution, it first attempts IPv4 (A) and then queries IPv6 (AAAA).

By default, DNS records are cached using the TTL value of a response. This optional parameter (in seconds) allows overriding it.

TTL in seconds for error responses and empty responses.

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 resolver_stale_ttl number of seconds have passed.

This configuration enables Kong to be more resilient during the DNS server downtime.

The DNS client uses a two-layer cache system: L1 - worker-level LRU Lua VM cache L2 - across-workers shared memory cache

This value specifies the maximum allowed number of DNS responses stored in the L1 LRU lua VM cache.

A single name query can easily take up 1~10 slots, depending on attempted query types and extended domains from /etc/resolv.conf options domain or search.

This value specifies the size of the L2 shared memory cache for DNS responses, kong_dns_cache.

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

5MB shared memory size could store ~20000 DNS responeses with single A record or ~10000 DNS responeses with 2~3 A records.

10MB shared memory size could store ~40000 DNS responeses with single A record or ~20000 DNS responeses with 2~3 A records.