このページは、まだ日本語ではご利用いただけません。翻訳中です。
旧バージョンのドキュメントを参照しています。 最新のドキュメントはこちらをご参照ください。
Configuration Reference for Kong Gateway
Reference for Kong Gateway configuration parameters. Set these parameters in kong.conf
.
To learn more about the kong.conf
file, see the guide on the Kong Configuration File.
General section
prefix
Working directory. Equivalent to Nginx’s prefix path, containing temporary files and logs.
Each Kong process must have a separate working directory.
Default: /usr/local/kong/
log_level
Log level of the Nginx server. Logs are found at <prefix>/logs/error.log
.
See http://nginx.org/en/docs/ngx_core_module.html#error_log for a list of accepted values.
Default: notice
proxy_access_log
Path for proxy port request access logs. Set this value to off
to disable
logging proxy requests.
If this value is a relative path, it will be placed under the prefix
location.
Default: logs/access.log
proxy_error_log
Path for proxy port request error logs. The granularity of these logs is
adjusted by the log_level
property.
Default: logs/error.log
proxy_stream_access_log
Path for tcp streams proxy port access logs. Set this value to off
to disable
logging proxy requests.
If this value is a relative path, it will be placed under the prefix
location.
basic
is defined as '$remote_addr [$time_local] ' '$protocol $status
$bytes_sent $bytes_received ' '$session_time'
Default: logs/access.log basic
proxy_stream_error_log
Path for tcp streams proxy port request error logs. The granularity of these
logs is adjusted by the log_level
property.
Default: logs/error.log
admin_access_log
Path for Admin API request access logs. If Hybrid Mode is enabled and the current node is set to be the Control Plane, then the connection requests from Data Planes are also written to this file with server name “kong_cluster_listener”.
Set this value to off
to disable logging Admin API requests.
If this value is a relative path, it will be placed under the prefix
location.
Default: logs/admin_access.log
admin_error_log
Path for Admin API request error logs. The granularity of these logs is
adjusted by the log_level
property.
Default: logs/error.log
status_access_log
Path for Status API request access logs. The default value of off
implies
that logging for this API is disabled by default.
If this value is a relative path, it will be placed under the prefix
location.
Default: off
status_error_log
Path for Status API request error logs. The granularity of these logs is
adjusted by the log_level
property.
Default: logs/status_error.log
debug_access_log
Path for Debug API request access logs. The default value of off
implies that
logging for this API is disabled by default.
If this value is a relative path, it will be placed under the prefix
location.
Default: off
debug_error_log
Path for Debug API request error logs. The granularity of these logs is
adjusted by the log_level
property.
Default: logs/debug_error.log
vaults
Comma-separated list of vaults this node should load. By default, all the bundled vaults are enabled.
The specified name(s) will be substituted as such in the Lua namespace:
kong.vaults.{name}.*
.
Default: bundled
opentelemetry_tracing
Deprecated: use tracing_instrumentations instead
Default: off
tracing_instrumentations
Comma-separated list of tracing instrumentations this node should load. By default, no instrumentations are enabled.
Valid values to this setting are:
-
off
: do not enable instrumentations. -
request
: only enable request-level instrumentations. -
all
: enable all the following instrumentations. -
db_query
: trace database query. -
dns_query
: trace DNS query. -
router
: trace router execution, including router rebuilding. -
http_client
: trace OpenResty HTTP client requests. -
balancer
: trace balancer retries. -
plugin_rewrite
: trace plugins iterator execution with rewrite phase. -
plugin_access
: trace plugins iterator execution with access phase. -
plugin_header_filter
: trace plugins iterator execution with header_filter phase.
Note: In the current implementation, tracing instrumentations are not enabled in stream mode.
Default: off
opentelemetry_tracing_sampling_rate
Deprecated: use tracing_sampling_rate instead
Default: 1.0
tracing_sampling_rate
Tracing instrumentation sampling rate.
Tracer samples a fixed percentage of all spans following the sampling rate.
Example: 0.25
, this should account for 25% of all traces.
Default: 0.01
plugins
Comma-separated list of plugins this node should load. By default, only plugins
bundled in official distributions are loaded via the bundled
keyword.
Loading a plugin does not enable it by default, but only instructs Kong to load its source code, and allows to configure the plugin via the various related Admin API endpoints.
The specified name(s) will be substituted as such in the Lua namespace:
kong.plugins.{name}.*
.
When the off
keyword is specified as the only value, no plugins will be
loaded.
bundled
and plugin names can be mixed together, as the following examples
suggest:
-
plugins = bundled,custom-auth,custom-log
will include the bundled plugins plus two custom ones -
plugins = custom-auth,custom-log
will only include thecustom-auth
andcustom-log
plugins. -
plugins = off
will not include any plugins
Note: Kong will not start if some plugins were previously configured (i.e.
have rows in the database) and are not specified in this list. Before disabling a plugin, ensure all instances of it are removed before restarting Kong.
Note: Limiting the amount of available plugins can improve P99 latency when
experiencing LRU churning in the database cache (i.e. when the configured
mem_cache_size
) is full.
Default: bundled
pluginserver_names
Comma-separated list of names for pluginserver processes. The actual names are used for log messages and to relate the actual settings.
Default: none
pluginserver_XXX_socket
Path to the unix socket used by the
Default: <prefix>/<XXX>.socket
pluginserver_XXX_start_cmd
Full command (including any needed arguments) to start the
Default: /usr/local/bin/<XXX>
pluginserver_XXX_query_cmd
Full command to “query” the
Default: /usr/local/bin/query_<XXX>
port_maps
With this configuration parameter, you can let the Kong to know about the port from which the packets are forwarded to it. This is fairly common when running Kong in a containerized or virtualized environment.
For example, port_maps=80:8000, 443:8443
instructs Kong that the port 80 is
mapped to 8000 (and the port 443 to 8443), where 8000 and 8443 are the ports
that Kong is listening to.
This parameter helps Kong set a proper forwarded upstream HTTP request header or to get the proper forwarded port with the Kong PDK (in case other means determining it has failed). It changes routing by a destination port to route by a port from which packets are forwarded to Kong, and similarly it changes the default plugin log serializer to use the port according to this mapping instead of reporting the port Kong is listening to.
Default: none
anonymous_reports
Send anonymous usage data such as error stack traces to help improve Kong.
Default: on
proxy_server
Proxy server defined as a URL. Kong will only use this option if any component is explicitly configured to use proxy.
Default: none
proxy_server_ssl_verify
Toggles server certificate verification if proxy_server
is in HTTPS.
See the lua_ssl_trusted_certificate
setting to specify a certificate
authority.
Default: off
error_template_html
Path to the custom html error template to override the default html kong error template.
The template is required to contain one single %s
placeholder for the error
message, as in the following example:
<html>
<body>
<h1>My custom error template</h1>
<p>%s.</p>
</body>
</html>
Default: none
error_template_json
Path to the custom json error template to override the default json kong error template.
Similarly to error_template_html
, the template is required to contain one
single %s
placeholder for the error message.
Default: none
error_template_xml
Path to the custom xml error template to override the default xml kong error template
Similarly to error_template_html
, the template is required to contain one
single %s
placeholder for the error message.
Default: none
error_template_plain
Path to the custom plain error template to override the default plain kong error template
Similarly to error_template_html
, the template is required to contain one
single %s
placeholder for the error message.
Default: none
Hybrid Mode section
role
Use this setting to enable Hybrid Mode, This allows running some Kong nodes in a control plane role with a database and have them deliver configuration updates to other nodes running to DB-less running in a Data Plane role.
Valid values to this setting are:
-
traditional
: do not use Hybrid Mode. -
control_plane
: this node runs in a control plane role. It can use a database and will deliver configuration updates to data plane nodes. -
data_plane
: this is a data plane node. It runs DB-less and receives configuration updates from a control plane node.
Default: traditional
cluster_mtls
Sets the verification between nodes of the cluster.
Valid values to this setting are:
-
shared
: use a shared certificate/key pair specified with thecluster_cert
andcluster_cert_key
settings. Note that CP and DP nodes have to present the same certificate to establish mTLS connections. -
pki
: usecluster_ca_cert
,cluster_server_name
andcluster_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 aspki
but additionally checks for Common Name of data plane certificate specified incluster_allowed_common_names
.
Default: shared
cluster_cert
Cluster certificate to use when establishing secure communication between control and data plane nodes.
You can use the kong hybrid
command to generate the certificate/key pair.
Under shared
mode, it must be the same for all nodes. Under pki
mode it
should be a different certificate for each DP node.
The certificate can be configured on this property with either of the following values:
- absolute path to the certificate
- certificate content
- base64 encoded certificate content
Default: none
cluster_cert_key
Cluster certificate key to use when establishing secure communication between control and data plane nodes.
You can use the kong hybrid
command to generate the certificate/key pair.
Under shared
mode, it must be the same for all nodes. Under pki
mode it
should be a different certificate for each DP node.
The certificate key can be configured on this property with any of the following values:
- absolute path to the certificate key
- certificate key content
- base64 encoded certificate key content
Default: none
cluster_ca_cert
The trusted CA certificate file in PEM format used for Control Plane to verify Data Plane’s certificate and Data Plane to verify Control Plane’s certificate.
Required on data plane if cluster_mtls
is set to pki
.
If Control Plane certificate is issued by a well known CA, user can set
lua_ssl_trusted_certificate=system
on Data Plane and leave this field empty.
This field is ignored if cluster_mtls
is set to shared
.
The certificate can be configured on this property with any of the following values:
- absolute path to the certificate
- certificate content
- base64 encoded certificate content
Default: none
cluster_allowed_common_names
The list of Common Names that are allowed to connect to control plane. Multiple entries may be supplied in a comma-separated string. When not set, Data Plane with same parent domain of Control Plane cert is allowed to connect.
This field is ignored if cluster_mtls
is not set to pki_check_cn
.
Default: none
Hybrid Mode Data Plane section
cluster_server_name
The server name used in the SNI of the TLS connection from a DP node to a CP node.
Must match the Common Name (CN) or Subject Alternative Name (SAN) found in the CP certificate.
If cluster_mtls
is set to shared
, this setting is ignored and
kong_clustering
is used.
Default: none
cluster_control_plane
To be used by data plane nodes only: address of the control plane node from
which configuration updates will be fetched, in host:port
format.
Default: none
cluster_telemetry_endpoint
To be used by data plane nodes only: telemetry address of the control plane
node to which telemetry updates will be posted in host:port
format.
Default: none
cluster_telemetry_server_name
The SNI (Server Name Indication extension) to use for Vitals telemetry data.
Default: none
cluster_dp_labels
Comma separated list of Labels for the data plane.
Labels are key-value pairs that provide additional context information for each DP.
Each label must be configured as a string in the format key:value
.
Labels are only compatible with hybrid mode deployments with Kong Konnect (SaaS), this configuration doesn’t work with self-hosted deployments.
Keys and values follow the AIP standards: https://kong-aip.netlify.app/aip/129/
Example: deployment:mycloud,region:us-east-1
Default: none
Hybrid Mode Control Plane section
cluster_listen
Comma-separated list of addresses and ports on which the cluster control plane server should listen for data plane connections.
The cluster communication port of the control plane must be accessible by all the data planes within the same cluster. This port is mTLS protected to ensure end-to-end security and integrity.
This setting has no effect if role
is not set to control_plane
.
Connection made to this endpoint are logged to the same location as Admin API access logs.
See admin_access_log
config description for more information.
Default: 0.0.0.0:8005
cluster_telemetry_listen
Comma-separated list of addresses and ports on which the cluster control plane server should listen for data plane telemetry connections.
The cluster communication port of the control plane must be accessible by all the data planes within the same cluster.
This setting has no effect if role
is not set to control_plane
.
Default: 0.0.0.0:8006
cluster_data_plane_purge_delay
How many seconds must pass from the time a DP node becomes offline to the time its entry gets removed from the database, as returned by the /clustering/data-planes Admin API endpoint.
This is to prevent the cluster data plane table from growing indefinitely. The default is set to 14 days. That is, if CP haven’t heard from a DP for 14 days, its entry will be removed.
Default: 1209600
cluster_ocsp
Whether to check for revocation status of DP certificates using OCSP (Online Certificate Status Protocol).
If enabled, the DP certificate should contain the “Certificate Authority Information Access” extension and the OCSP method with URI of which the OCSP responder can be reached from CP.
OCSP checks are only performed on CP nodes, it has no effect on DP nodes.
Valid values to this setting are:
-
on
: OCSP revocation check is enabled and DP must pass the check in order to establish connection with CP. -
off
: OCSP revocation check is disabled. -
optional
: OCSP revocation check will be attempted, however, if the required extension is not found inside DP provided certificate or communication with the OCSP responder failed, then DP is still allowed through.
Default: off
cluster_use_proxy
Whether to turn on HTTP CONNECT proxy support for hybrid mode connections.
proxy_server
will be used for Hybrid mode connections if this option is turned
on.
Default: off
cluster_max_payload
This sets the maximum payload size allowed to be sent across from CP to DP in Hybrid mode Default is 4Mb - 4 * 1024 * 1024 due to historical reasons
Default: 4194304
NGINX section
proxy_listen
Comma-separated list of addresses and ports on which the proxy server should listen for HTTP/HTTPS traffic.
The proxy server is the public entry point of Kong, which proxies traffic from your consumers to your backend services. This value accepts IPv4, IPv6, and hostnames.
Some suffixes can be specified for each pair:
-
ssl
will require that all connections made through a particular address/port be made with TLS enabled. -
http2
will allow for clients to open HTTP/2 connections to Kong’s proxy server. -
proxy_protocol
will enable usage of the PROXY protocol for a given address/port. -
deferred
instructs to use a deferred accept on Linux (the TCP_DEFER_ACCEPT socket option). -
bind
instructs to make a separate bind() call for a given address:port pair. -
reuseport
instructs to create an individual listening socket for each worker process allowing the Kernel to better distribute incoming connections between worker processes -
backlog=N
sets the maximum length for the queue of pending TCP connections. This number should not be too small in order to prevent clients seeing “Connection refused” error connecting to a busy Kong instance. Note: on Linux, this value is limited by the setting ofnet.core.somaxconn
Kernel parameter. In order for the largerbacklog
set here to take effect it is necessary to raisenet.core.somaxconn
at the same time to match or exceed thebacklog
number set. -
ipv6only=on|off
whether an IPv6 socket listening on a wildcard address [::] will accept only IPv6 connections or both IPv6 and IPv4 connections -
so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]
configures theTCP 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 valueon
, theSO_KEEPALIVE
option is turned on for the socket. If it is set to the valueoff
, theSO_KEEPALIVE
option is turned off for the socket. Some operating systems support setting of TCP keepalive parameters on a per-socket basis using theTCP_KEEPIDLE
,TCP_KEEPINTVL
, andTCP_KEEPCNT
socket options.
This value can be set to off
, thus disabling the HTTP/HTTPS proxy port for
this node.
If stream_listen is also set to off
, this enables ‘control-plane’ mode for
this node (in which all traffic proxying capabilities are disabled). This node
can then be used only to configure a cluster of Kong nodes connected to the same
datastore.
Example: proxy_listen = 0.0.0.0:443 ssl, 0.0.0.0:444 http2 ssl
See http://nginx.org/en/docs/http/ngx_http_core_module.html#listen for a
description of the accepted formats for this and other *_listen
values.
See https://www.nginx.com/resources/admin-guide/proxy-protocol/ for more
details about the proxy_protocol
parameter.
Not all *_listen
values accept all formats specified in nginx’s
documentation.
Default: 0.0.0.0:8000 reuseport backlog=16384, 0.0.0.0:8443 http2 ssl reuseport backlog=16384
proxy_url
Kong Proxy URL
The lookup, or balancer, address for your Kong Proxy nodes.
This value is commonly used in a microservices or service-mesh oriented architecture.
Accepted format (parts in parentheses are optional):
<scheme>://<IP / HOSTNAME>(:<PORT>(/<PATH>))
Examples:
-
<scheme>://<IP>:<PORT>
->proxy_url = http://127.0.0.1:8000
-
SSL <scheme>://<HOSTNAME>
->proxy_url = https://proxy.domain.tld
-
<scheme>://<HOSTNAME>/<PATH>
->proxy_url = http://dev-machine/dev-285
By default, Kong Manager, and Kong Portal will use the window request host and append the resolved listener port depending on the requested protocol.
Default: none
stream_listen
Comma-separated list of addresses and ports on which the stream mode should listen.
This value accepts IPv4, IPv6, and hostnames.
Some suffixes can be specified for each pair:
-
ssl
will require that all connections made through a particular address/port be made with TLS enabled. -
proxy_protocol
will enable usage of the PROXY protocol for a given address/port. -
bind
instructs to make a separate bind() call for a given address:port pair. -
reuseport
instructs to create an individual listening socket for each worker process allowing the Kernel to better distribute incoming connections between worker processes -
backlog=N
sets the maximum length for the queue of pending TCP connections. This number should not be too small in order to prevent clients seeing “Connection refused” error connecting to a busy Kong instance. Note: on Linux, this value is limited by the setting ofnet.core.somaxconn
Kernel parameter. In order for the largerbacklog
set here to take effect it is necessary to raisenet.core.somaxconn
at the same time to match or exceed thebacklog
number set. -
ipv6only=on|off
whether an IPv6 socket listening on a wildcard address [::] will accept only IPv6 connections or both IPv6 and IPv4 connections -
so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]
configures theTCP 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 valueon
, theSO_KEEPALIVE
option is turned on for the socket. If it is set to the valueoff
, theSO_KEEPALIVE
option is turned off for the socket. Some operating systems support setting of TCP keepalive parameters on a per-socket basis using theTCP_KEEPIDLE
,TCP_KEEPINTVL
, andTCP_KEEPCNT
socket options.
Examples:
stream_listen = 127.0.0.1:7000 reuseport backlog=16384
stream_listen = 0.0.0.0:989 reuseport backlog=65536, 0.0.0.0:20
stream_listen = [::1]:1234 backlog=16384
By default this value is set to off
, thus disabling the stream proxy port for
this node.
See http://nginx.org/en/docs/stream/ngx_stream_core_module.html#listen for a description of the formats that Kong might accept in stream_listen.
Default: off
admin_api_uri
Hierarchical part of a URI which is composed optionally of a host, port, and path at which the Admin API accepts HTTP or HTTPS traffic. When this config is disabled, Kong Manager will use the window protocol + host and append the resolved admin_listen HTTP/HTTPS port.
Default: none
admin_listen
Comma-separated list of addresses and ports on which the Admin interface should listen.
The Admin interface is the API allowing you to configure and manage Kong.
Access to this interface should be restricted to Kong administrators only. This value accepts IPv4, IPv6, and hostnames.
It is highly recommended to avoid exposing the Admin API to public interface(s), by using values such as 0.0.0.0:8001
See https://docs.konghq.com/gateway/latest/production/running-kong/secure-admin-api/ for more information about how to secure your Admin API.
Some suffixes can be specified for each pair:
-
ssl
will require that all connections made through a particular address/port be made with TLS enabled. -
http2
will allow for clients to open HTTP/2 connections to Kong’s proxy server. -
proxy_protocol
will enable usage of the PROXY protocol for a given address/port. -
deferred
instructs to use a deferred accept on Linux (the TCP_DEFER_ACCEPT socket option). -
bind
instructs to make a separate bind() call for a given address:port pair. -
reuseport
instructs to create an individual listening socket for each worker process allowing the Kernel to better distribute incoming connections between worker processes -
backlog=N
sets the maximum length for the queue of pending TCP connections. This number should not be too small in order to prevent clients seeing “Connection refused” error connecting to a busy Kong instance. Note: on Linux, this value is limited by the setting ofnet.core.somaxconn
Kernel parameter. In order for the largerbacklog
set here to take effect it is necessary to raisenet.core.somaxconn
at the same time to match or exceed thebacklog
number set. -
ipv6only=on|off
whether an IPv6 socket listening on a wildcard address [::] will accept only IPv6 connections or both IPv6 and IPv4 connections -
so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]
configures theTCP 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 valueon
, theSO_KEEPALIVE
option is turned on for the socket. If it is set to the valueoff
, theSO_KEEPALIVE
option is turned off for the socket. Some operating systems support setting of TCP keepalive parameters on a per-socket basis using theTCP_KEEPIDLE
,TCP_KEEPINTVL
, andTCP_KEEPCNT
socket options.
This value can be set to off
, thus disabling the Admin interface for this
node, enabling a ‘data-plane’ mode (without configuration capabilities) pulling
its configuration changes from the database.
Example: admin_listen = 127.0.0.1:8444 http2 ssl
Default: 127.0.0.1:8001 reuseport backlog=16384, 127.0.0.1:8444 http2 ssl reuseport backlog=16384
status_listen
Comma-separated list of addresses and ports on which the Status API should listen.
The Status API is a read-only endpoint allowing monitoring tools to retrieve metrics, healthiness, and other non-sensitive information of the current Kong node.
The following suffix can be specified for each pair:
-
ssl
will require that all connections made through a particular address/port be made with TLS enabled. -
http2
will allow for clients to open HTTP/2 connections to Kong’s Status API server.
This value can be set to off
, disabling the Status API for this node.
Example: status_listen = 0.0.0.0:8100 ssl http2
Default: off
debug_listen
Comma-separated list of addresses and ports on which the Debug API should listen.
The following suffix can be specified for each pair:
-
ssl
will require that all connections made through a particular address/port be made with TLS enabled. -
http2
will allow for clients to open HTTP/2 connections to Kong’s Debug API server.
This value can be set to off
, disabling the Debug API for this node.
Example: debug_listen = 0.0.0.0:8200 ssl http2
Default: off
nginx_user
Defines user and group credentials used by worker processes. If group is omitted, a group whose name equals that of user is used.
Example: nginx_user = nginx www
Note: If the kong
user and the kong
group are not available, the
default user and group credentials will be nobody nobody
.
Default: kong kong
nginx_worker_processes
Determines the number of worker processes spawned by Nginx.
See http://nginx.org/en/docs/ngx_core_module.html#worker_processes for detailed usage of the equivalent Nginx directive and a description of accepted values.
Default: auto
nginx_daemon
Determines whether Nginx will run as a daemon or as a foreground process. Mainly useful for development or when running Kong inside a Docker environment.
See http://nginx.org/en/docs/ngx_core_module.html#daemon.
Default: on
mem_cache_size
Size of each of the two in-memory caches for database entities. 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 entries, the total memory Kong uses to cache entities might be double this value.
Default: 128m
ssl_cipher_suite
Defines the TLS ciphers served by Nginx.
Accepted values are modern
, intermediate
, old
, fips
, or custom
.
See https://wiki.mozilla.org/Security/Server_Side_TLS for detailed descriptions
of each cipher suite. fips
cipher suites are as described in
https://wiki.openssl.org/index.php/FIPS_mode_and_TLS.
Default: intermediate
ssl_ciphers
Defines a custom list of TLS ciphers to be served by Nginx. This list must
conform to the pattern defined by openssl ciphers
.
This value is ignored if ssl_cipher_suite
is not custom
.
If you use DHE ciphers, you must also configure the ssl_dhparam
parameter.
Default: none
ssl_protocols
Enables the specified protocols for client-side connections. The set of
supported protocol versions also depends on the version of OpenSSL Kong was
built with. This value is ignored if ssl_cipher_suite
is not custom
.
See http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_protocols
Default: TLSv1.1 TLSv1.2 TLSv1.3
ssl_prefer_server_ciphers
Specifies that server ciphers should be preferred over client ciphers when
using the SSLv3 and TLS protocols. This value is ignored if ssl_cipher_suite
is not custom
.
See http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_prefer_server_ciphers
Default: on
ssl_dhparam
Defines DH parameters for DHE ciphers from the predefined groups: ffdhe2048
,
ffdhe3072
, ffdhe4096
, ffdhe6144
, ffdhe8192
, from the absolute path to a
parameters file, or directly from the parameters content.
This value is ignored if ssl_cipher_suite
is modern
or intermediate
. The
reason is that modern
has no ciphers that needs this, and intermediate
uses
ffdhe2048
.
See http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_dhparam
Default: none
ssl_session_tickets
Enables or disables session resumption through TLS session tickets. This has no impact when used with TLSv1.3.
Kong enables this by default for performance reasons, but it has security implications: https://github.com/mozilla/server-side-tls/issues/135
See http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_session_tickets
Default: on
ssl_session_timeout
Specifies a time during which a client may reuse the session parameters. See the rationale: https://github.com/mozilla/server-side-tls/issues/198
See http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_session_timeout
Default: 1d
ssl_session_cache_size
Sets the size of the caches that store session parameters
See https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_session_cache
Default: 10m
ssl_cert
Comma-separated list of certificates for proxy_listen
values with TLS
enabled.
If more than one certificates are specified, it can be used to provide
alternate type of certificate (for example, ECC certificate) that will be served
to clients that supports them. Note to properly serve using ECC certificates, it
is recommended to also set ssl_cipher_suite
to modern
or intermediate
.
Unless this option is explicitly set, Kong will auto-generate a pair of default certificates (RSA + ECC) first time it starts up and use it for serving TLS requests.
Certificates can be configured on this property with any of the following values:
- absolute path to the certificate
- certificate content
- base64 encoded certificate content
Default: none
ssl_cert_key
Comma-separated list of keys for proxy_listen
values with TLS enabled.
If more than one certificate was specified for ssl_cert
, then this option
should contain the corresponding key for all certificates provided in the same
order.
Unless this option is explicitly set, Kong will auto-generate a pair of default private keys (RSA + ECC) first time it starts up and use it for serving TLS requests.
Keys can be configured on this property with either of the following values:
- absolute path to the certificate key
- certificate key content
- base64 encoded certificate key content
Default: none
client_ssl
Determines if Nginx should attempt to send client-side TLS certificates and perform Mutual TLS Authentication with upstream service when proxying requests.
Default: off
client_ssl_cert
If client_ssl
is enabled, the client certificate for the
proxy_ssl_certificate
directive.
This value can be overwritten dynamically with the client_certificate
attribute of the Service
object.
The certificate can be configured on this property with any of the following values:
- absolute path to the certificate
- certificate content
- base64 encoded certificate content
Default: none
client_ssl_cert_key
If client_ssl
is enabled, the client TLS key for the
proxy_ssl_certificate_key
directive.
This value can be overwritten dynamically with the client_certificate
attribute of the Service
object.
The certificate key can be configured on this property with any of the following values:
- absolute path to the certificate key
- certificate key content
- base64 encoded certificate key content
Default: none
admin_ssl_cert
Comma-separated list of certificates for admin_listen
values with TLS
enabled.
See docs for ssl_cert
for detailed usage.
Default: none
admin_ssl_cert_key
Comma-separated list of keys for admin_listen
values with TLS enabled.
See docs for ssl_cert_key
for detailed usage.
Default: none
status_ssl_cert
Comma-separated list of certificates for status_listen
values with TLS
enabled.
See docs for ssl_cert
for detailed usage.
Default: none
status_ssl_cert_key
Comma-separated list of keys for status_listen
values with TLS enabled.
See docs for ssl_cert_key
for detailed usage.
Default: none
debug_ssl_cert
Comma-separated list of certificates for debug_listen
values with TLS
enabled.
See docs for ssl_cert
for detailed usage.
Default: none
debug_ssl_cert_key
Comma-separated list of keys for debug_listen
values with TLS enabled.
See docs for ssl_cert_key
for detailed usage.
Default: none
headers
Comma-separated list of headers Kong should inject in client responses.
Accepted values are:
-
Server
: InjectsServer: kong/x.y.z
on Kong-produced response (e.g. Admin API, rejected requests from auth plugin). -
Via
: InjectsVia: kong/x.y.z
for successfully proxied requests. -
X-Kong-Proxy-Latency
: Time taken (in milliseconds) by Kong to process a request and run all plugins before proxying the request upstream. -
X-Kong-Response-Latency
: time taken (in millisecond) by Kong to produce a response in case of e.g. plugin short-circuiting the request, or in in case of an error. -
X-Kong-Upstream-Latency
: Time taken (in milliseconds) by the upstream service to send response headers. -
X-Kong-Admin-Latency
: Time taken (in milliseconds) by Kong to process an Admin API request. -
X-Kong-Upstream-Status
: The HTTP status code returned by the upstream service. This is particularly useful for clients to distinguish upstream statuses if the response is rewritten by a plugin. -
server_tokens
: Same as specifying bothServer
andVia
. -
latency_tokens
: Same as specifyingX-Kong-Proxy-Latency
,X-Kong-Response-Latency
,X-Kong-Admin-Latency
andX-Kong-Upstream-Latency
In addition to those, this value can be set to off
, which prevents Kong from
injecting any of the above headers. Note that this does not prevent plugins from
injecting headers of their own.
Example: headers = via, latency_tokens
Default: server_tokens, latency_tokens
trusted_ips
Defines trusted IP addresses blocks that are known to send correct
X-Forwarded-*
headers.
Requests from trusted IPs make Kong forward their X-Forwarded-*
headers
upstream.
Non-trusted requests make Kong insert its own X-Forwarded-*
headers.
This property also sets the set_real_ip_from
directive(s) in the Nginx
configuration. It accepts the same type of values (CIDR blocks) but as a
comma-separated list.
To trust all /!\ IPs, set this value to 0.0.0.0/0,::/0
.
If the special value unix:
is specified, all UNIX-domain sockets will be
trusted.
See http://nginx.org/en/docs/http/ngx_http_realip_module.html#set_real_ip_from for examples of accepted values.
Default: none
real_ip_header
Defines the request header field whose value will be used to replace the client address.
This value sets the ngx_http_realip_module
directive of the same name in the
Nginx configuration.
If this value receives proxy_protocol
:
- at least one of the
proxy_listen
entries must have theproxy_protocol
flag enabled. - the
proxy_protocol
parameter will be appended to thelisten
directive of the Nginx template.
See http://nginx.org/en/docs/http/ngx_http_realip_module.html#real_ip_header for a description of this directive.
Default: X-Real-IP
real_ip_recursive
This value sets the ngx_http_realip_module
directive of the same name in the
Nginx configuration.
See http://nginx.org/en/docs/http/ngx_http_realip_module.html#real_ip_recursive for a description of this directive.
Default: off
error_default_type
Default MIME type to use when the request Accept
header is missing and Nginx
is returning an error for the request.
Accepted values are text/plain
, text/html
, application/json
, and
application/xml
.
Default: text/plain
upstream_keepalive_pool_size
Sets the default size of the upstream keepalive connection pools.
Upstream keepalive connection pools are segmented by the dst ip/dst port/SNI
attributes of a connection.
A value of 0
will disable upstream keepalive connections by default, forcing
each upstream request to open a new connection.
Default: 60
upstream_keepalive_max_requests
Sets the default maximum number of requests than can be proxied upstream through one keepalive connection.
After the maximum number of requests is reached, the connection will be closed.
A value of 0
will disable this behavior, and a keepalive connection can be
used to proxy an indefinite number of requests.
Default: 100
upstream_keepalive_idle_timeout
Sets the default timeout (in seconds) for which an upstream keepalive connection should be kept open. When the timeout is reached while the connection has not been reused, it will be closed.
A value of 0
will disable this behavior, and an idle keepalive connection may
be kept open indefinitely.
Default: 60
allow_debug_header
Enable the Kong-Debug
header function.
If it is on
, kong will add Kong-Route-Id
Kong-Route-Name
Kong-Service-Id
Kong-Service-Name
debug headers to response when the client
request header Kong-Debug: 1
is present.
Default: off
NGINX Injected Directives section
Nginx directives can be dynamically injected in the runtime nginx.conf file without requiring a custom Nginx configuration template.
All configuration properties respecting the naming scheme
nginx_<namespace>_<directive>
will result in <directive>
being injected in
the Nginx configuration block corresponding to the property’s <namespace>
.
Example: nginx_proxy_large_client_header_buffers = 8 24k
Will inject the following directive in Kong’s proxy server {}
block:
large_client_header_buffers 8 24k;
The following namespaces are supported:
-
nginx_main_<directive>
: Injects<directive>
in Kong’s configurationmain
context. -
nginx_events_<directive>
: Injects<directive>
in Kong’sevents {}
block. -
nginx_http_<directive>
: Injects<directive>
in Kong’shttp {}
block. -
nginx_proxy_<directive>
: Injects<directive>
in Kong’s proxyserver {}
block. -
nginx_upstream_<directive>
: Injects<directive>
in Kong’s proxyupstream {}
block. -
nginx_admin_<directive>
: Injects<directive>
in Kong’s Admin APIserver {}
block. -
nginx_status_<directive>
: Injects<directive>
in Kong’s Status APIserver {}
block (only effective ifstatus_listen
is enabled). -
nginx_debug_<directive>
: Injects<directive>
in Kong’s Debug APIserver {}
block (only effective ifdebug_listen
is enabled). -
nginx_stream_<directive>
: Injects<directive>
in Kong’s stream modulestream {}
block (only effective ifstream_listen
is enabled). -
nginx_sproxy_<directive>
: Injects<directive>
in Kong’s stream moduleserver {}
block (only effective ifstream_listen
is enabled). -
nginx_supstream_<directive>
: Injects<directive>
in Kong’s stream moduleupstream {}
block.
As with other configuration properties, Nginx directives can be injected via
environment variables when capitalized and prefixed with KONG_
.
Example: KONG_NGINX_HTTP_SSL_PROTOCOLS
-> nginx_http_ssl_protocols
Will inject the following directive in Kong’s http {}
block:
ssl_protocols <value>;
If different sets of protocols are desired between the proxy and Admin API
server, you may specify nginx_proxy_ssl_protocols
and/or
nginx_admin_ssl_protocols
, both of which taking precedence over the http {}
block.
nginx_main_worker_rlimit_nofile
Changes the limit on the maximum number of open files for worker processes.
The special and default value of auto
sets this value to ulimit -n
with the
upper bound limited to 16384 as a measure to protect against excess memory use,
and the lower bound of 1024 as a good default.
See http://nginx.org/en/docs/ngx_core_module.html#worker_rlimit_nofile
Default: auto
nginx_events_worker_connections
Sets the maximum number of simultaneous connections that can be opened by a worker process.
The special and default value of auto
sets this value to ulimit -n
with the
upper bound limited to 16384 as a measure to protect against excess memory use,
and the lower bound of 1024 as a good default.
See http://nginx.org/en/docs/ngx_core_module.html#worker_connections
Default: auto
nginx_http_client_header_buffer_size
Sets buffer size for reading the client request headers.
See http://nginx.org/en/docs/http/ngx_http_core_module.html#client_header_buffer_size
Default: 1k
nginx_http_large_client_header_buffers
Sets the maximum number and size of buffers used for reading large clients requests headers.
See http://nginx.org/en/docs/http/ngx_http_core_module.html#large_client_header_buffers
Default: 4 8k
nginx_http_client_max_body_size
Defines the maximum request body size allowed by requests proxied by Kong, specified in the Content-Length request header. If a request exceeds this limit, Kong will respond with a 413 (Request Entity Too Large). Setting this value to 0 disables checking the request body size.
See http://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size
Default: 0
nginx_admin_client_max_body_size
Defines the maximum request body size for Admin API.
Default: 10m
nginx_http_charset
Adds the specified charset to the “Content-Type” response header field. If this charset is different from the charset specified in the source_charset directive, a conversion is performed.
The parameter off
cancels the addition of charset to the “Content-Type”
response header field.
See http://nginx.org/en/docs/http/ngx_http_charset_module.html#charset
Default: UTF-8
nginx_http_client_body_buffer_size
Defines the buffer size for reading the request body. If the client request
body is larger than this value, the body will be buffered to disk. Note that
when the body is buffered to disk, Kong plugins that access or manipulate the
request body may not work, so it is advisable to set this value as high as
possible (e.g., set it as high as client_max_body_size
to force request bodies
to be kept in memory). Do note that high-concurrency environments will require
significant memory allocations to process many concurrent large request bodies.
See http://nginx.org/en/docs/http/ngx_http_core_module.html#client_body_buffer_size
Default: 8k
nginx_admin_client_body_buffer_size
Defines the buffer size for reading the request body on Admin API.
Default: 10m
nginx_http_lua_regex_match_limit
Global MATCH_LIMIT
for PCRE regex matching. The default of 100000
should
ensure at worst any regex Kong executes could finish within roughly 2 seconds.
Default: 100000
nginx_http_lua_regex_cache_max_entries
Specifies the maximum number of entries allowed in the worker process level compiled regex cache.
It is recommended to set it to at least (number of regex paths * 2) to avoid high CPU usages.
Default: 8192
Datastore section
Kong can run with a database to store coordinated data between Kong nodes in a cluster, or without a database, where each node stores its information independently in memory.
When using a database, Kong will store data for all its entities (such as Routes, Services, Consumers, and Plugins) in a database, and all Kong nodes belonging to the same cluster must connect themselves to the same database.
When not using a database, Kong is said to be in “DB-less mode”: it will keep
its entities in memory, and each node needs to have this data entered via a
declarative configuration file, which can be specified through the
declarative_config
property, or via the Admin API using the /config
endpoint.
When using Postgres as the backend storage, you can optionally enable Kong to serve read queries from a separate database instance.
When the number of proxies is large, this can greatly reduce the load on the main Postgres instance and achieve better scalability. It may also reduce the latency jitter if the Kong proxy node’s latency to the main Postgres instance is high.
The read-only Postgres instance only serves read queries and write queries still goes to the main connection. The read-only Postgres instance can be eventually consistent while replicating changes from the main instance.
At least the pg_ro_host
config is needed to enable this feature.
By default, all other database config for the read-only connection are
inherited from the corresponding main connection config described above but may
be optionally overwritten explicitly using the pg_ro_*
config below.
database
Determines the database (or no database) for this node.
Accepted values are postgres
and off
.
Default: postgres
Postgres settings
name | description | default |
---|---|---|
pg_host | Host of the Postgres server. | 127.0.0.1 |
pg_port | Port of the Postgres server. | 5432 |
pg_timeout | Defines the timeout (in ms), for connecting, reading and writing. | 5000 |
pg_user | Postgres user. | kong |
pg_password | Postgres user’s password. | none |
pg_database | The database name to connect to. | kong |
pg_schema | The database schema to use. If unspecified, Kong will respect the search_path value of your PostgreSQL instance. |
none |
pg_ssl | 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. | off |
pg_ssl_version | 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 . |
tlsv1_2 |
pg_ssl_required | 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. |
off |
pg_ssl_verify | Toggles server certificate verification if pg_ssl is enabled. See the lua_ssl_trusted_certificate setting to specify a certificate authority. |
off |
pg_ssl_cert | 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. | none |
pg_ssl_cert_key | If pg_ssl_cert is set, the absolute path to the PEM encoded client TLS private key for the PostgreSQL connection. |
none |
pg_max_concurrent_queries | 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. |
0 |
pg_semaphore_timeout | 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. | 60000 |
pg_keepalive_timeout | 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
|
none |
pg_pool_size | 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
|
none |
pg_backlog | 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. |
none |
pg_ro_host | Same as pg_host , but for the read-only connection. Note: Refer to the documentation section above for detailed usage. |
none |
pg_ro_port | Same as pg_port , but for the read-only connection. |
<pg_port> |
pg_ro_timeout | Same as pg_timeout , but for the read-only connection. |
<pg_timeout> |
pg_ro_user | Same as pg_user , but for the read-only connection. |
<pg_user> |
pg_ro_password | Same as pg_password , but for the read-only connection. |
<pg_password> |
pg_ro_database | Same as pg_database , but for the read-only connection. |
<pg_database> |
pg_ro_schema | Same as pg_schema , but for the read-only connection. |
<pg_schema> |
pg_ro_ssl | Same as pg_ssl , but for the read-only connection. |
<pg_ssl> |
pg_ro_ssl_required | Same as pg_ssl_required , but for the read-only connection. |
<pg_ssl_required> |
pg_ro_ssl_verify | Same as pg_ssl_verify , but for the read-only connection. |
<pg_ssl_verify> |
pg_ro_ssl_version | Same as pg_ssl_version , but for the read-only connection. |
<pg_ssl_version> |
pg_ro_max_concurrent_queries | 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. |
<pg_max_concurrent_queries> |
pg_ro_semaphore_timeout | Same as pg_semaphore_timeout , but for the read-only connection. |
<pg_semaphore_timeout> |
pg_ro_keepalive_timeout | Same as pg_keepalive_timeout , but for the read-only connection. |
<pg_keepalive_timeout> |
pg_ro_pool_size | Same as pg_pool_size , but for the read-only connection. |
<pg_pool_size> |
pg_ro_backlog | Same as pg_backlog , but for the read-only connection. |
<pg_backlog> |
Cassandra settings
Deprecation warning: Cassandra as a backend database for Kong Gateway is deprecated. Support for Cassandra will be removed in a future release.
Our target for Cassandra removal is the Kong Gateway 3.4 release. Starting with the Kong Gateway 3.0 release, some new features might not be supported with Cassandra.
name | description | default |
---|---|---|
cassandra_contact_points | A comma-separated list of contact points to your cluster. You may specify IP addresses or hostnames. Note that the port component of SRV records will be ignored in favor of cassandra_port . When connecting to a multi-DC cluster, ensure that contact points from the local datacenter are specified first in this list. |
127.0.0.1 |
cassandra_port | The port on which your nodes are listening on. All your nodes and contact points must listen on the same port. Will be created if it doesn’t exist. | 9042 |
cassandra_keyspace | The keyspace to use in your cluster. | kong |
cassandra_write_consistency | Consistency setting to use when writing to the Cassandra cluster. | ONE |
cassandra_read_consistency | Consistency setting to use when reading from the Cassandra cluster. | ONE |
cassandra_timeout | Defines the timeout (in ms) for reading and writing. | 5000 |
cassandra_ssl | Toggles client-to-node TLS connections between Kong and Cassandra. | off |
cassandra_ssl_verify | Toggles server certificate verification if cassandra_ssl is enabled. See the lua_ssl_trusted_certificate setting to specify a certificate authority. |
off |
cassandra_username | Username when using the PasswordAuthenticator scheme. |
kong |
cassandra_password | Password when using the PasswordAuthenticator scheme. |
none |
cassandra_lb_policy | Load balancing policy to use when distributing queries across your Cassandra cluster. Accepted values are: RoundRobin , RequestRoundRobin , DCAwareRoundRobin , and RequestDCAwareRoundRobin . Policies prefixed with “Request” make efficient use of established connections throughout the same request. Prefer “DCAware” policies if and only if you are using a multi-datacenter cluster. |
RequestRoundRobin |
cassandra_local_datacenter | When using the DCAwareRoundRobin or RequestDCAwareRoundRobin load balancing policy, you must specify the name of the local (closest) datacenter for this Kong node. |
none |
cassandra_refresh_frequency | Frequency (in seconds) at which the cluster topology will be checked for new or decommissioned nodes. A value of 0 will disable this check, and the cluster topology will never be refreshed. |
60 |
cassandra_repl_strategy | When migrating for the first time, Kong will use this setting to create your keyspace. Accepted values are SimpleStrategy and NetworkTopologyStrategy . |
SimpleStrategy |
cassandra_repl_factor | When migrating for the first time, Kong will create the keyspace with this replication factor when using the SimpleStrategy . |
1 |
cassandra_data_centers | When migrating for the first time, will use this setting when using the NetworkTopologyStrategy . The format is a comma-separated list made of <dc_name>:<repl_factor> . |
dc1:2,dc2:3 |
cassandra_schema_consensus_timeout | Defines the timeout (in ms) for the waiting period to reach a schema consensus between your Cassandra nodes. This value is only used during migrations. | 10000 |
declarative_config
The path to the declarative configuration file which holds the specification of
all entities (Routes, Services, Consumers, etc.) to be used when the database
is set to off
.
Entities are stored in Kong’s in-memory cache, so you must ensure that enough
memory is allocated to it via the mem_cache_size
property. You must also
ensure that items in the cache never expire, which means that db_cache_ttl
should preserve its default value of 0.
If the Hybrid mode role
is set to data_plane
and there’s no configuration
cache file, this configuration is used before connecting to the Control Plane
node as a user-controlled fallback.
Default: none
declarative_config_string
The declarative configuration as a string
Default: none
declarative_config_encryption_mode
Set encryption of the declarative config mapped file on filesystem.
aes-256-gcm
= Use AES-256-GCM to encrypt chacha20-poly1305
= Use
chacha20-poly1305 to encrypt off
= does not encrypt
Default: off
lmdb_environment_path
Directory where the LMDB database files used by DB-less and Hybrid mode to store Kong configurations reside.
This path is relative under the Kong prefix
.
Default: dbless.lmdb
lmdb_map_size
Maximum size of the LMDB memory map, used to store the DB-less and Hybird mode configurations. Default is 128m.
Default: 128m
Datastore Cache section
In order to avoid unnecessary communication with the datastore, Kong caches entities (such as APIs, Consumers, Credentials…) for a configurable period of time. It also handles invalidations if such an entity is updated.
This section allows for configuring the behavior of Kong regarding the caching of such configuration entities.
db_update_frequency
Frequency (in seconds) at which to check for updated entities with the datastore.
When a node creates, updates, or deletes an entity via the Admin API, other nodes need to wait for the next poll (configured by this value) to eventually purge the old cached entity and start using the new one.
Default: 5
db_update_propagation
Time (in seconds) taken for an entity in the datastore to be propagated to replica nodes of another datacenter.
When in a distributed environment such as a multi-datacenter Cassandra cluster, this value should be the maximum number of seconds taken by Cassandra to propagate a row to other datacenters.
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.
Default: 0
db_cache_ttl
Time-to-live (in seconds) of an entity from the datastore when cached by this node.
Database misses (no entity) are also cached according to this setting if you do
not configure db_cache_neg_ttl
.
If set to 0 (default), such cached entities or misses never expire.
Default: 0
db_cache_neg_ttl
Time-to-live (in seconds) of a datastore miss (no entity).
If not specified (default), db_cache_ttl
value will be used instead.
If set to 0, misses will never expire.
Default: none
db_resurrect_ttl
Time (in seconds) for which stale entities from the datastore should be resurrected for when they cannot be refreshed (e.g., the datastore is unreachable). When this TTL expires, a new attempt to refresh the stale entities will be made.
Default: 30
db_cache_warmup_entities
Entities to be pre-loaded from the datastore into the in-memory cache at Kong start-up.
This speeds up the first access of endpoints that use the given entities.
When the services
entity is configured for warmup, the DNS entries for values
in its host
attribute are pre-resolved asynchronously as well.
Cache size set in mem_cache_size
should be set to a value large enough to
hold all instances of the specified entities.
If the size is insufficient, Kong will log a warning.
Default: services
DNS Resolver section
By default, the DNS resolver will use the standard configuration files
/etc/hosts
and /etc/resolv.conf
. The settings in the latter file will be
overridden by the environment variables LOCALDOMAIN
and RES_OPTIONS
if they
have been set.
Kong will resolve hostnames as either SRV
or A
records (in that order, and
CNAME
records will be dereferenced in the process).
In case a name was resolved as an SRV
record it will also override any given
port number by the port
field contents received from the DNS server.
The DNS options SEARCH
and NDOTS
(from the /etc/resolv.conf
file) will be
used to expand short names to fully qualified ones. So it will first try the
entire SEARCH
list for the SRV
type, if that fails it will try the SEARCH
list for A
, etc.
For the duration of the ttl
, the internal DNS resolver will loadbalance each
request it gets over the entries in the DNS record. For SRV
records the
weight
fields will be honored, but it will only use the lowest priority
field entries in the record.
dns_resolver
Comma separated list of nameservers, each entry in ip[:port]
format to be
used by Kong. If not specified the nameservers in the local resolv.conf
file
will be used.
Port defaults to 53 if omitted. Accepts both IPv4 and IPv6 addresses.
Default: none
dns_hostsfile
The hosts file to use. This file is read once and its content is static in memory.
To read the file again after modifying it, Kong must be reloaded.
Default: /etc/hosts
dns_order
The order in which to resolve different record types. The LAST
type means the
type of the last successful lookup (for the specified name). The format is a
(case insensitive) comma separated list.
Default: LAST,SRV,A,CNAME
dns_valid_ttl
By default, DNS records are cached using the TTL value of a response. If this property receives a value (in seconds), it will override the TTL for all records.
Default: none
dns_stale_ttl
Defines, in seconds, how long a record will remain in cache past its TTL. This value will be used while the new DNS record is fetched in the background.
Stale data will be used from expiry of a record until either the refresh query
completes, or the dns_stale_ttl
number of seconds have passed.
Default: 4
dns_cache_size
Defines the maximum allowed number of DNS records stored in memory cache.
Least recently used DNS records are discarded from cache if it is full. Both errors and data are cached, therefore a single name query can easily take up 10-15 slots.
Default: 10000
dns_not_found_ttl
TTL in seconds for empty DNS responses and “(3) name error” responses.
Default: 30
dns_error_ttl
TTL in seconds for error responses.
Default: 1
dns_no_sync
If enabled, then upon a cache-miss every request will trigger its own dns query.
When disabled multiple requests for the same name/type will be synchronised to a single query.
Default: off
Vaults section
A secret is any sensitive piece of information required for API gateway operations. Secrets may be part of the core Kong Gateway configuration, used in plugins, or part of the configuration associated with APIs serviced by the gateway.
Some of the most common types of secrets used by Kong Gateway include:
- Data store usernames and passwords, used with PostgreSQL and Redis
- Private X.509 certificates
- API keys
Sensitive plugin configuration fields are generally used for authentication, hashing, signing, or encryption. Kong Gateway lets you store certain values in a vault. Here are the vault specific configuration options.
vault_env_prefix
Defines the environment variable vault’s default prefix. For example if you
have all your secrets stored in environment variables prefixed with SECRETS_
,
it can be configured here so that it isn’t necessary to repeat them in Vault
references.
Default: none
vault_aws_region
The AWS region your vault is located in.
Default: none
vault_gcp_project_id
The project ID from your Google API Console.
Default: none
vault_hcv_protocol
The protocol to connect with. Accepts one of http
or https
.
Default: http
vault_hcv_host
The hostname of your HashiCorp vault.
Default: 127.0.0.1
vault_hcv_port
The port number of your HashiCorp vault.
Default: 8200
vault_hcv_namespace
Namespace for the HashiCorp Vault. Vault Enterprise requires a namespace to successfully connect to it.
Default: none
vault_hcv_mount
The mount point.
Default: secret
vault_hcv_kv
The secrets engine version. Accepts v1
or v2
.
Default: v1
vault_hcv_token
A token string.
Default: none
vault_hcv_auth_method
Defines the authentication mechanism when connecting to the HashiCorp Vault service.
Accepted values are: token
, or kubernetes
.
Default: token
vault_hcv_kube_role
Defines the HashiCorp Vault role for the Kubernetes service account of the
running pod. vault_hcv_auth_method
must be set to kubernetes
for this to
activate.
Default: none
vault_hcv_kube_api_token_file
Defines where the Kubernetes service account token should be read from the pod’s filesystem, if using a non-standard container platform setup.
Default: none
Tuning & Behavior section
worker_consistency
Defines whether this node should rebuild its state synchronously or
asynchronously (the balancers and the router are rebuilt on updates that affects
them, e.g., updates to Routes, Services or Upstreams, via the Admin API or
loading a declarative configuration file). (This option is deprecated and will
be removed in future releases. The new default is eventual
.)
Accepted values are:
-
strict
: the router will be rebuilt synchronously, causing incoming requests to be delayed until the rebuild is finished. (This option is deprecated and will be removed in future releases. The new default iseventual
) -
eventual
: the router will be rebuilt asynchronously via a recurring background job running every second inside of each worker.
Note that strict
ensures that all workers of a given node will always proxy
requests with an identical router, but that increased long tail latency can be
observed if frequent Routes and Services updates are expected.
Using eventual
will help preventing long tail latency issues in such cases,
but may cause workers to route requests differently for a short period of time
after Routes and Services updates.
Default: eventual
worker_state_update_frequency
Defines, in seconds, how often the worker state changes are checked with a background job. When a change is detected, a new router or balancer will be built, as needed. Raising this value will decrease the load on database servers and result in less jitter in proxy latency, but it might take more time to propagate changes to each individual worker.
Default: 5
router_flavor
Selects the router implementation to use when performing request routing.
Incremental router rebuild is available when the flavor is set to either
expressions
or traditional_compatible
which could significantly shorten
rebuild time for large number of routes.
Accepted values are:
-
traditional_compatible
: the DSL based expression router engine will be used under the hood. However the router config interface will be the same astraditional
and expressions are automatically generated at router build time. Theexpression
field on theRoute
object is not visible. -
expressions
: the DSL based expression router engine will be used under the hood. Traditional router config interface is not visible and you must write Router Expression manually and provide them in theexpression
field on theRoute
object. -
traditional
: the pre-3.0 Router engine will be used. Config interface will be the same as pre-3.0 Kong and theexpression
field on theRoute
object is not visible.
Deprecation warning: In Kong 3.0, traditional
mode should be avoided and only
be used in case traditional_compatible
did not work as expected.
This flavor of router will be removed in the next major release of Kong.
Default: traditional_compatible
lua_max_req_headers
Maximum number of request headers to parse by default.
This argument can be set to an integer between 1 and 1000.
When proxying the Kong sends all the request headers and this setting does not have any effect. It is used to limit Kong and its plugins from reading too many request headers.
Default: 100
lua_max_resp_headers
Maximum number of response headers to parse by default.
This argument can be set to an integer between 1 and 1000.
When proxying, Kong returns all the response headers and this setting does not have any effect. It is used to limit Kong and its plugins from reading too many response headers.
Default: 100
lua_max_uri_args
Maximum number of request uri arguments to parse by default.
This argument can be set to an integer between 1 and 1000.
When proxying, Kong sends all the request query arguments and this setting does not have any effect.
It is used to limit Kong and its plugins from reading too many query arguments.
Default: 100
lua_max_post_args
Maximum number of request post arguments to parse by default.
This argument can be set to an integer between 1 and 1000.
When proxying, Kong sends all the request post arguments and this setting does not have any effect.
It is used to limit Kong and its plugins from reading too many post arguments.
Default: 100
Miscellaneous section
Additional settings inherited from lua-nginx-module allowing for more flexibility and advanced usage.
See the lua-nginx-module documentation for more information: https://github.com/openresty/lua-nginx-module
lua_ssl_trusted_certificate
Comma-separated list of certificate authorities for Lua cosockets in PEM format.
The special value system
attempts to search for the “usual default” provided
by each distro, according to an arbitrary heuristic. In the current
implementation, The following pathnames will be tested in order, and the first
one found will be used:
- /etc/ssl/certs/ca-certificates.crt (Debian/Ubuntu/Gentoo)
- /etc/pki/tls/certs/ca-bundle.crt (Fedora/RHEL 6)
- /etc/ssl/ca-bundle.pem (OpenSUSE)
- /etc/pki/tls/cacert.pem (OpenELEC)
- /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem (CentOS/RHEL 7)
- /etc/ssl/cert.pem (OpenBSD, Alpine)
system
can be used by itself or in conjunction with other CA filepaths.
When pg_ssl_verify
or cassandra_ssl_verify
are enabled, these certificate
authority files will be used for verifying Kong’s database connections.
Certificates can be configured on this property with any of the following values:
system
- absolute path to the certificate
- certificate content
- base64 encoded certificate content
See https://github.com/openresty/lua-nginx-module#lua_ssl_trusted_certificate
Default: system
lua_ssl_verify_depth
Sets the verification depth in the server certificates chain used by Lua
cosockets, set by lua_ssl_trusted_certificate
.
This includes the certificates configured for Kong’s database connections.
If the maximum depth is reached before reaching the end of the chain, verification will fail. This helps mitigate certificate based DoS attacks.
See https://github.com/openresty/lua-nginx-module#lua_ssl_verify_depth
Default: 1
lua_ssl_protocols
Defines the TLS versions supported when handshaking with OpenResty’s TCP cosocket APIs.
This affects connections made by Lua code, such as connections to the database Kong uses, or when sending logs using a logging plugin. It does not affect connections made to the upstream Service or from downstream clients.
Default: TLSv1.1 TLSv1.2 TLSv1.3
lua_package_path
Sets the Lua module search path (LUA_PATH). Useful when developing or using custom plugins not stored in the default search path.
See https://github.com/openresty/lua-nginx-module#lua_package_path
Default: ./?.lua;./?/init.lua;
lua_package_cpath
Sets the Lua C module search path (LUA_CPATH).
See https://github.com/openresty/lua-nginx-module#lua_package_cpath
Default: none
lua_socket_pool_size
Specifies the size limit for every cosocket connection pool associated with every remote server.
See https://github.com/openresty/lua-nginx-module#lua_socket_pool_size
Default: 30
enforce_rbac
Specifies whether Admin API RBAC is enforced.
Accepts one of entity
, both
, on
, or off
.
-
on
: only endpoint-level authorization is enforced. -
entity
: entity-level authorization applies. -
both
: enables both endpoint and entity-level authorization. -
off
: disables both endpoint and entity-level authorization.
When enabled, Kong will deny requests to the Admin API when a nonexistent or invalid RBAC authorization token is passed, or the RBAC user with which the token is associated does not have permissions to access/modify the requested resource.
Default: off
rbac_auth_header
Defines the name of the HTTP request header from which the Admin API will attempt to authenticate the RBAC user.
Default: Kong-Admin-Token
event_hooks_enabled
When enabled, event hook entities represent a relationship between an event (source and event) and an action (handler). Similar to web hooks, event hooks can be used to communicate Kong Gateway service events. When a particular event happens on a service, the event hook calls a URL with information about that event. Event hook configurations differ depending on the handler. The events that are triggered send associated data.
See: https://docs.konghq.com/gateway/latest/admin-api/event-hooks/reference/
Default: on
fips
Turn on FIPS mode; this mode is only available on a FIPS build.
Default: off
Kong Manager section
The Admin GUI for Kong Enterprise.
admin_gui_listen
Kong Manager Listeners
Comma-separated list of addresses and ports on which Kong will expose Kong Manager. This web application lets you configure and manage Kong, and therefore should be kept secured.
Suffixes can be specified for each pair, similarly to the admin_listen
directive.
Default: 0.0.0.0:8002, 0.0.0.0:8445 ssl
admin_gui_url
Kong Manager URL
The lookup, or balancer, address for Kong Manager.
Accepted format (items in parentheses are optional):
<scheme>://<IP / HOSTNAME>(:<PORT>)
Examples:
http://127.0.0.1:8003
https://kong-admin.test
http://dev-machine
By default, Kong Manager will use the window request host and append the resolved listener port depending on the requested protocol.
Default: none
admin_gui_path
Kong Manager base path
This configuration parameter allows the user to customize the path prefix where
Kong Manager is served. When updating this parameter, it’s recommended to update
the path in admin_gui_url
as well.
Accepted format:
- Path must start with a
/
- Path must not end with a
/
(except for the/
) - Path can only contain letters, digits, hyphens (
-
),
underscores (_
), and slashes (/
)
- Path must not contain continuous slashes (e.g.,
//
and///
)
Examples:
/
/manager
/kong-manager
/kong/manager
Default: /
admin_gui_ssl_cert
The SSL certificate for admin_gui_listen
values with SSL enabled.
Values:
- absolute path to the certificate
- certificate content
- base64 encoded certificate content
Default: none
admin_gui_ssl_cert_key
The SSL key for admin_gui_listen
values with SSL enabled.
Values:
- absolute path to the certificate key
- certificate key content
- base64 encoded certificate key content
Default: none
admin_gui_flags
Alters the layout Admin GUI (JSON) The only supported value is {
"IMMUNITY_ENABLED": true }
to enable Kong Immunity in the Admin GUI.
Default: {}
admin_gui_access_log
Kong Manager Access Logs
Here you can set an absolute or relative path for Kong Manager access logs.
When the path is relative, logs are placed in the prefix
location.
Setting this value to off
disables access logs for Kong Manager.
Default: logs/admin_gui_access.log
admin_gui_error_log
Kong Manager Error Logs
Here you can set an absolute or relative path for Kong Manager access logs.
When the path is relative, logs are placed in the prefix
location.
Setting this value to off
disables error logs for Kong Manager.
Granularity can be adjusted through the log_level
directive.
Default: logs/admin_gui_error.log
admin_gui_auth
Kong Manager Authentication Plugin Name
Secures access to Kong Manager by specifying an authentication plugin to use.
Supported Plugins:
-
basic-auth
: Basic Authentication plugin -
ldap-auth-advanced
: LDAP Authentication plugin -
openid-connect
: OpenID Connect Authentication plugin
Default: none
admin_gui_auth_conf
Kong Manager Authentication Plugin Config (JSON)
Specifies the configuration for the authentication plugin specified in
admin_gui_auth
.
For information about Plugin Configuration consult the associated plugin documentation.
Example for basic-auth
:
admin_gui_auth_conf = { "hide_credentials": true }
Default: none
admin_gui_auth_password_complexity
Kong Manager Authentication Password Complexity (JSON)
When admin_gui_auth = basic-auth
, this property defines the rules required
for Kong Manager passwords. Choose from preset rules or write your own.
Example using preset rules:
admin_gui_auth_password_complexity = { "kong-preset": "min_8" }
All values for kong-preset require the password to contain characters from at least three of the following categories:
-
Uppercase characters (A through Z)
-
Lowercase characters (a through z)
-
Base-10 digits (0 through 9)
-
Special characters (for example, &, $, #, %)
Supported preset rules:
-
min_8
: minimum length of 8 -
min_12
: minimum length of 12 -
min_20
: minimum length of 20
To write your own rules, see https://manpages.debian.org/jessie/passwdqc/passwdqc.conf.5.en.html.
NOTE: Only keywords “min”, “max” and “passphrase” are supported.
Example:
admin_gui_auth_password_complexity = { "min": "disabled,24,11,9,8" }
Default: none
admin_gui_session_conf
Kong Manager Session Config (JSON)
Specifies the configuration for the Session plugin as used by Kong Manager.
For information about plugin configuration, consult the Kong Session plugin documentation.
Example:
admin_gui_session_conf = { "cookie_name": "kookie", \
"secret": "changeme" }
Default: none
admin_gui_auth_header
Defines the name of the HTTP request header from which the Admin API will attempt to identify the Kong Admin user.
Default: Kong-Admin-User
admin_gui_auth_login_attempts
Number of times a user can attempt to login to Kong Manager. 0 means infinite attempts allowed.
Default: 0
admin_gui_header_txt
Kong Manager Header Text Sets text for Kong Manager Header Banner. Header Banner is not shown if this config is empty.
Default: none
admin_gui_header_bg_color
Kong Manager Header Background Color Sets background color for Kong Manager Header Banner Accepts css color keyword, #-hexadecimal or rgb format. Invalid values are ignored by Manager.
Default: none
admin_gui_header_txt_color
Kong Manager Header Text Color Sets text color for Kong Manager Header Banner.
Accepts css color keyword, #-hexadecimal or rgb format. Invalid values are ignored by Kong Manager.
Default: none
admin_gui_footer_txt
Kong Manager Footer Text Sets text for Kong Manager Footer Banner. Footer Banner is not shown if this config is empty
Default: none
admin_gui_footer_bg_color
Kong Manager Footer Background Color Sets background color for Kong Manager Footer Banner.
Accepts css color keyword, #-hexadecimal or rgb format. Invalid values are ignored by Manager.
Default: none
admin_gui_footer_txt_color
Kong Manager Footer Text Color Sets text color for Kong Manager Footer Banner.
Accepts css color keyword, #-hexadecimal or rgb format. Invalid values are ignored by Kong Manager.
Default: none
admin_gui_login_banner_title
Kong Manager Login Banner Title Text Sets title text for Kong Manager Login Banner.
Login Banner is not shown if both admin_gui_login_banner_title
and
admin_gui_login_banner_body
are empty.
Default: none
admin_gui_login_banner_body
Kong Manager Login Banner Body Text Sets body text for Kong Manager Login Banner.
Login Banner is not shown if both admin_gui_login_banner_title
and
admin_gui_login_banner_body
are empty.
Default: none
Vitals section
vitals
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.
Default: on
vitals_strategy
Determines whether to use the Kong database or a separate storage engine for Vitals metrics.
Accepted values are database
, prometheus
, or influxdb
.
Default: database
vitals_tsdb_address
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.
Default: none
vitals_tsdb_user
Influxdb user
Default: none
vitals_tsdb_password
Influxdb password
Default: none
vitals_statsd_address
Defines the host and port (and an optional protocol) of the StatsD server to
which Kong should write Vitals metrics. 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).
Default: none
vitals_statsd_prefix
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.
Default: kong
vitals_statsd_udp_packet_size
Defines the maximum buffer size in which Vitals statsd metrics will be held and sent in batches.
This value is defined in bytes.
Default: 1024
vitals_prometheus_scrape_interval
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.
Default: 5
Konnect section
konnect_mode
When enabled, the dataplane is connected to Konnect
Default: off
Analytics For Konnect section
analytics_flush_interval
Determine the frequency of flushing local data to Konnect in seconds.
Default: 1
analytics_buffer_size_limit
Max number of messages can be buffered locally before dropping data in case there is no network connection to Konnect.
Default: 100000
Developer Portal section
portal
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.
Default: off
portal_gui_listen
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.
Default: 0.0.0.0:8003, 0.0.0.0:8446 ssl
portal_gui_protocol
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
Default: http
portal_gui_host
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
Default: 127.0.0.1:8003
portal_cors_origins
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.
Default: none
portal_gui_use_subdomains
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
Default: off
portal_gui_ssl_cert
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
Default: none
portal_gui_ssl_cert_key
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
Default: none
portal_gui_access_log
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.
Default: logs/portal_gui_access.log
portal_gui_error_log
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.
Default: logs/portal_gui_error.log
portal_api_listen
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.
Default: 0.0.0.0:8004, 0.0.0.0:8447 ssl
portal_api_url
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
Default: none
portal_api_ssl_cert
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
Default: none
portal_api_ssl_cert_key
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
Default: none
portal_api_access_log
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.
Default: logs/portal_api_access.log
portal_api_error_log
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.
Default: logs/portal_api_error.log
portal_is_legacy
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.
Default: off
portal_app_auth
Developer Portal application registration auth provider and strategy. Must be set to enable application_registration plugin Currently accepts kong-oauth2 or external-oauth2
Default: kong-oauth2
Default Developer Portal Authentication section
Referenced on workspace creation to set Dev Portal authentication defaults in the database for that particular workspace.
portal_auth
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
Default: none
portal_auth_password_complexity
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:
-
Uppercase characters (A through Z)
-
Lowercase characters (a through z)
-
Base-10 digits (0 through 9)
-
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" }
Default: none
portal_auth_conf
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 }
Default: none
portal_auth_login_attempts
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.
Default: 0
portal_session_conf
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" }
Default: none
portal_auto_approve
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.
Default: off
portal_token_exp
Duration in seconds for the expiration of the Dev Portal reset password token.
Default is 21600
(six hours).
Default: 21600
portal_email_verification
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.
Default: off
Default Portal Smtp Configuration section
Referenced on workspace creation to set SMTP defaults in the database for that particular workspace.
portal_invite_email
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.
Default: on
portal_access_request_email
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.
Default: on
portal_approved_email
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.
Default: on
portal_reset_email
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.
When disabled, developers will not be able to reset their account passwords. Kong Admins will have to manually create new credentials for the Developer in the Kong Manager.
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.
Default: on
portal_reset_success_email
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>
Default: on
portal_application_status_email
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.
Default: off
portal_application_request_email
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 overridden 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.
Default: off
portal_emails_from
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.
Default: none
portal_emails_reply_to
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.
Default: none
portal_smtp_admin_emails
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
Default: none
Admin Smtp Configuration section
admin_emails_from
The email address for the From
header for admin emails.
Default: ""
admin_emails_reply_to
Email address for the Reply-To
header for admin emails.
Default: none
admin_invitation_expiry
Expiration time for the admin invitation link (in seconds). 0 means no expiration.
Example, 72 hours: 72 * 60 * 60 = 259200
Default: 259200
General Smtp Configuration section
smtp_mock
This flag will mock the sending of emails. This can be used for testing before the SMTP client is fully configured.
Default: on
smtp_host
The hostname of the SMTP server to connect to.
Default: localhost
smtp_port
The port number on the SMTP server to connect to.
Default: 25
smtp_starttls
When set to on
, STARTTLS is used to encrypt communication with the SMTP
server. This is normally used in conjunction with port 587.
Default: off
smtp_username
Username used for authentication with SMTP server
Default: none
smtp_password
Password used for authentication with SMTP server
Default: none
smtp_ssl
When set to on
, SMTPS is used to encrypt communication with the SMTP server.
This is normally used in conjunction with port 465.
Default: off
smtp_auth_type
The method used to authenticate with the SMTP server Valid options are plain
,
login
, or nil
Default: none
smtp_domain
The domain used in the EHLO
connection and part of the Message-ID
header
Default: localhost.localdomain
smtp_timeout_connect
The timeout (in milliseconds) for connecting to the SMTP server.
Default: 60000
smtp_timeout_send
The timeout (in milliseconds) for sending data to the SMTP server.
Default: 60000
smtp_timeout_read
The timeout (in milliseconds) for reading data from the SMTP server.
Default: 60000
smtp_admin_emails
Comma separated list of admin emails to receive notifications.
Example admin1@example.com, admin2@example.com
Default: none
Data & Admin Audit section
When enabled, Kong will store detailed audit data regarding Admin API and database access. In most cases, updates to the database are associated with Admin API requests. As such, database object audit log data is tied to a given HTTP via a unique identifier, providing built-in association of Admin API and database traffic.
audit_log
When enabled, Kong will log information about Admin API access and database row insertions, updates, and deletes.
Default: off
audit_log_ignore_methods
Comma-separated list of HTTP methods that will not generate audit log entries. By default, all HTTP requests will be logged.
Default: none
audit_log_ignore_paths
Comma-separated list of request paths that will not generate audit log entries. By default, all HTTP requests will be logged.
Default: none
audit_log_ignore_tables
Comma-separated list of database tables that will not generate audit log entries. By default, updates to all database tables will be logged (the term “updates” refers to the creation, update, or deletion of a row).
Default: none
audit_log_payload_exclude
Comma-separated list of keys that will be filtered out of the payload. Keys that were filtered will be recorded in the audit log.
Default: token, secret, password
audit_log_record_ttl
Length, in seconds, of the TTL for audit log records. Records in the database older than their TTL are automatically purged.
Example, 30 days: 30 * 24 * 60 * 60 = 2592000
Default: 2592000
audit_log_signing_key
Defines the path to a private RSA signing key that can be used to insert a signature of audit records, adjacent to the record. The corresponding public key should be stored offline, and can be used the validate audit entries in the future. If this value is undefined, no signature will be generated.
Default: none
Granular Tracing section
Deprecation warning: Granular tracing is deprecated. This means the feature will eventually be removed.
Our target for Granular tracing removal is the Kong Gateway 4.0 release.
Granular tracing offers a mechanism to expose metrics and detailed debug data about the lifecycle of Kong in a human- or machine-consumable format.
tracing
When enabled, Kong will generate granular debug data about various portions of the request lifecycle, such as DB or DNS queries, plugin execution, core handler timing, etc.
Default: off
tracing_write_strategy
Defines how Kong will write tracing data at the conclusion of the request. The
default option, file
, writes a human-readable depiction of tracing data to a
configurable location on the node’s file system. Other strategies write tracing
data as a JSON document to the configured endpoint. Valid entries for this
option are file
, file_raw
, http
, tcp
, tls
, and udp
.
Default: file
tracing_write_endpoint
Defines the endpoint to which tracing data will be written.
- For the
file
andfile_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
, andudp
strategies, this value is defined as a string in the form of:<HOST>:<PORT>
- For the
http
strategy, this value is defined in the form of:<scheme>://<IP / HOSTNAME>(:<PORT>(/<PATH>))
Traces sent via HTTP are delivered via POST method with an application/json
Content-Type.
Default: none
tracing_time_threshold
The minimum time, in microseconds, over which a trace must execute in order to
write the trace data to the configured endpoint. This configuration can be used
to lower the noise present in trace data by removing trace objects that are not
interesting from a timing perspective. The default value of 0
removes this
limitation, causing traces of any duration to be written.
Default: 0
tracing_types
Defines the types of traces that are written.
Trace types not defined in this list are ignored, regardless of their lifetime.
The default special value of all
results in all trace types being written,
regardless of type.
The following trace types are included:
-
query
: trace the database query -
legacy_query
: (deprecated) trace the database query with legacy DAO -
router
: trace Kong routing the request; internal routing time -
balancer
: trace the execution of the overall balancer phase -
balancer.getPeer
: trace Kong selecting an upstream peer from the ring-balancer -
balancer.toip
: trace balancer to resolve peer’s host to IP -
connect.toip
: trace cosocket to resolve target’s host to IP -
access.before
: trace the preprocessing of access phase, like parameter parsing, route matching, and balance preparation -
access.after
: trace the postprocess of access phase, like balancer execution and internal variable assigning -
cassandra_iterate
: trace Cassandra driver to paginate over results -
plugin
: trace plugins phase handlers
Default: all
tracing_debug_header
Defines the name of the HTTP request header that must be present in order to generate traces within a request. Setting this value provides a mechanism to selectively generate request traces at the client’s request. Note that the value of the header does not matter, only that the header is present in the request. When this value is not set and tracing is enabled, Kong will generate trace data for all requests flowing through the proxy and Admin API. Note that data from certificate handling phases is not logged when this setting is enabled.
Default: none
generate_trace_details
When enabled, Kong will write context- specific details into traces. Trace details offer more data about the context of the trace. This can significantly increase the size of trace reports. Note also that trace details may contain potentially sensitive information, such as raw SQL queries; care should be taken to store traces properly when this option is enabled.
Default: off
Route Collision Detection/Prevention section
route_validation_strategy
The strategy used to validate routes when creating or updating them.
Different strategies are available to tune how to enforce splitting traffic of workspaces.
-
smart
is the default option and uses the algorithm described in https://docs.konghq.com/gateway/latest/kong-enterprise/workspaces/ -
off
disables any check -
path
enforces routes to comply with the pattern described in config enforce_route_path_pattern
Default: smart
enforce_route_path_pattern
Specifies the Lua pattern which will be enforced on the paths
attribute of a
Route object. You can also add a placeholder for the workspace in the pattern,
which will be rendered during runtime based on the workspace to which the
route
belongs.
This setting is only relevant if route_validation_strategy
is set to path
.
Example For Pattern /$(workspace)/v%d/.*
valid paths are:
-
/group1/v1/
if route belongs to workspacegroup1
. -
/group2/v1/some_path
if route belongs to workspacegroup2
.
Default: none
Database Encryption & Keyring Management section
When enabled, Kong will transparently encrypt sensitive fields, such as Consumer credentials, TLS private keys, and RBAC user tokens, among others. A full list of encrypted fields is available from the Kong Enterprise documentation site.
Encrypted data is transparently decrypted before being displayed to the Admin API or made available to plugins or core routing logic.
While this feature is GA, do note that we currently do not provide normal semantic versioning compatibility guarantees on the keyring feature’s APIs in that Kong may make a breaking change to the feature in a minor version. Also note that mis-management of keyring data may result in irrecoverable data loss.
keyring_enabled
When enabled, Kong will encrypt sensitive field values before writing them to the database, and subsuquently decrypt them when retrieving data for the Admin API, Developer Portal, or proxy business logic. Symmetric encryption keys are managed based on the strategy defined below.
Default: off
keyring_strategy
Defines the strategy implementation by which Kong nodes will manage symmetric encryption keys. Please see the Kong Enterprise documentation for a detailed description of each strategies. Acceptable values for this option are ‘cluster’ and ‘vault’.
Default: cluster
keyring_public_key
Defines the public key of an RSA keypair.
This keypair is used for symmetric keyring import/export, e.g., for disaster recovery and optional bootstrapping.
Values:
- absolute path to the public key
- public key content
- base64 encoded public key content
Default: none
keyring_private_key
Defines the private key of an RSA keypair.
This keypair is used for symmetric keyring import/export, e.g., for disaster recovery and optional bootstrapping.
Values:
- absolute path to the private key
- private key content
- base64 encoded private key content
Default: none
keyring_recovery_public_key
Defines the public key to optionally encrypt all keyring materials and backup in the database.
Values:
- absolute path to the public key
- public key content
- base64 encoded public key content
Default: none
keyring_blob_path
Defines the filesystem path at which Kong will backup the initial keyring material.
This option is useful largely for development purposes.
Default: none
keyring_vault_host
Defines the Vault host at which Kong will fetch the encryption material. This value should be defined in the format:
<scheme>://<IP / HOSTNAME>:<PORT>
Default: none
keyring_vault_mount
Defines the name of the Vault v2 KV secrets engine at which symmetric keys are found.
Default: none
keyring_vault_path
Defines the names of the Vault v2 KV path at which symmetric keys are found.
Default: none
keyring_vault_auth_method
Defines the authentication mechanism when connecting to the HashiCorp Vault service.
Accepted values are: token
, or kubernetes
:
-
token
: Uses the static token defined in thekeyring_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 thekeyring_vault_kube_role
configuration property.
Default: token
keyring_vault_token
Defines the token value used to communicate with the v2 KV Vault HTTP(S) API.
Default: none
keyring_vault_kube_role
Defines the HashiCorp Vault role that will be assumed using the Kubernetes service account of the running pod.
keyring_vault_auth_method
must be set to kubernetes
for this to activate.
Default: default
keyring_vault_kube_api_token_file
Defines where the Kubernetes service account token should be read from the pod’s filesystem, if using a non-standard container platform setup.
Default: /run/secrets/kubernetes.io/serviceaccount/token
untrusted_lua
Controls loading of Lua functions from admin-supplied sources such as the Admin API. LuaJIT bytecode loading is always disabled.
Warning: LuaJIT is not designed as a secure runtime for running malicious code, therefore you should properly protect your Admin API endpoint even with sandboxing enabled. The sandbox only provides protection against trivial attackers or unintentional modification of the Kong global environment.
Accepted values are: off
, sandbox
, or on
:
-
off
: Disallow loading of any arbitrary Lua functions. Theoff
option disables any functionality that runs arbitrary Lua code, including the Serverless Functions plugins and any transformation plugin that allows custom Lua functions. -
sandbox
: Allow loading of Lua functions, but use a sandbox when executing them. The sandboxed function has restricted access to the global environment and only has access to standard Lua functions that will generally not cause harm to the Kong Gateway node. -
on
: Functions have unrestricted access to the global environment and can load any Lua modules. This is similar to the behavior in Kong Gateway prior to 2.3.0.
The default sandbox
environment does not allow importing other modules or
libraries, or executing anything at the OS level (for example, file read/write).
The global environment is also not accessible.
Examples of untrusted_lua = sandbox
behavior:
- You can’t access or change global values such as
kong.configuration.pg_password
* You can run harmless lua:local foo = 1 + 1
. However, OS level functions are not allowed, like:os.execute('rm -rf /*')
.
For a full allowed/disallowed list, see: https://github.com/kikito/sandbox.lua/blob/master/sandbox.lua
To customize the sandbox environment, use the untrusted_lua_sandbox_requires
and untrusted_lua_sandbox_environment
parameters below.
Default: sandbox
untrusted_lua_sandbox_requires
Comma-separated list of modules allowed to be loaded with require
inside the
sandboxed environment. Ignored if untrusted_lua
is not sandbox
.
For example, say you have configured the Serverless pre-function plugin and it
contains the following requires
:
local template = require "resty.template"
local split = require "kong.tools.utils".split
To run the plugin, add the modules to the allowed list:
untrusted_lua_sandbox_requires = resty.template, kong.tools.utils
Warning: Allowing certain modules may create opportunities to escape the
sandbox. For example, allowing os
or luaposix
may be unsafe.
Default: none
untrusted_lua_sandbox_environment
Comma-separated list of global Lua variables that should be made available
inside the sandboxed environment. Ignored if untrusted_lua
is not sandbox
.
Warning: Certain variables, when made available, may create opportunities to escape the sandbox.
Default: none
openresty_path
Path to the OpenResty installation that Kong will use. When this is empty (the default), Kong determines the OpenResty installation by searching for a system-installed OpenResty and falling back to searching $PATH for the nginx binary.
Setting this attribute disables the search behavior and explicitly instructs Kong which OpenResty installation to use.
Default: none
node_id
Node ID for the Kong node. Every Kong node in a Kong cluster must have a unique and valid UUID. When empty, node ID is automatically generated.
Default: none
cluster_fallback_config_import
Enable fallback configuration imports
This should only be enabled for data plane
Default: off
cluster_fallback_config_import
Enable fallback configuration imports
This should only be enabled for data plane
Default: off
cluster_fallback_config_storage
Storage definition used by cluster_fallback_config_import
and
cluster_fallback_config_export
Currently supported storage type: S3-like storages and 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 endpoint URL for S3-like) for S3 are passing with
environment variables: AWS_ACCESS_KEY_ID
and 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 is provided via the environment variable
GCP_SERVICE_ACCOUNT
Default: none
cluster_fallback_config_export
Enable fallback configuration exports.
Default: off
cluster_fallback_config_export_delay
The fallback configuration export interval.
If it’s set to 60 and configuration A is exported and there’re new configurations B, C and D in the next 60 seconds, it will wait until 60 seconds passed and export D, skipping B and C.
Default: 60
max_queued_batches
Maximum number of batches to keep on an internal plugin queue before dropping old batches. This is meant as a global, last-resort control to prevent queues from consuming infinite memory. When batches are being dropped, an error message “exceeded max_queued_batches (%d), dropping oldest” will be logged. The error message will also include a string that identifies the plugin causing the problem. Queues are used by the http-log, statsd, opentelemetry and datadog plugins.
Default: 100