Managing Kong Gateway configuration

Kong Gateway comes with the configuration file kong.conf. You can use this file to configure individual properties of a Kong Gateway instance. By default, this file is located at /etc/kong/kong.conf.default.

In Konnect, you can use kong.conf to manage the configuration of each data place instance, however, you can’t edit the properties of the control plane.

For all available configuration parameters in kong.conf, see the Configuration Parameter reference.

To configure Kong Gateway, copy and rename the default configuration file:

cp /etc/kong/kong.conf.default /etc/kong/kong.conf

The file contains Kong Gateway configuration properties and documentation. Commented out parameters in kong.conf, Kong Gateway will use the default settings, until they are uncommented and modified. In this example, the log_level value is commented out, by default sets the log_level to notice.

#log_level = notice              # Log level of the Nginx server. Logs are
                                 # found at `<prefix>/logs/error.log`.

To configure a property, uncomment it and modify the value:

log_level = warn

Apply changes to a configuration using the kong restart command, available from the Kong CLI. This restarts the Kong Gateway instance and applies configuration.

If you’re running Kong Gateway in a quickstart Docker container for testing, update Kong Gateway configuration using environment variables and use kong reload instead of kong restart.

All parameters defined in kong.conf can be managed via environment variables. When loading properties from kong.conf, Kong Gateway checks existing environment variables first.

To configure a setting using an environment variable, declare an environment variable with the name of the setting, prefixed with KONG_. This will override the existing value in kong.conf.

For example, to override the log_level parameter:

log_level = debug # in kong.conf

Set KONG_LOG_LEVEL as an environment variable, then restart or reload Kong Gateway.

export KONG_LOG_LEVEL=error

By default, Kong Gateway looks for kong.conf in two locations: /etc/kong/kong.conf and /etc/kong.conf.

You can override this behavior by specifying a custom path for your configuration file using the -c / --conf argument with most Kong CLI commands:

kong start --conf ./kong.conf

To verify that your configuration is valid, use the kong check command. The kong check command evaluates all parameters set in kong.conf including any set as environment variables.

For example:

kong check /etc/kong/kong.conf

If your configuration is valid, you will see the following response:

configuration at /etc/kong/kong.conf is valid

You can use the Kong CLI in debug mode to output all configuration properties, including all properties set using environment variables.

Pass the --vv flag to any Kong CLI command to enable verbose debug mode:

kong prepare --conf /etc/kong/kong.conf --vv

This will output your entire Kong configuration to the terminal. For example, running kong prepare with the --vv flag will output this:

2025/01/31 06:52:01 [debug] reading environment variables
2025/01/31 06:52:01 [debug] KONG_DATABASE ENV found with "off"
2025/01/31 06:52:01 [debug] KONG_PREFIX ENV found with "/usr/local/kong"
2025/01/31 06:52:01 [debug] KONG_ROLE ENV found with "data_plane"
[...]