You are browsing documentation for an outdated version. See the latest documentation here.
Set Up Object Defaults
Use object defaults to enforce a set of standard values and avoid repetition in your configuration.
You can set configuration defaults for the following core Kong Gateway objects:
decK supports setting object defaults both in self-managed Kong Gateway and with Kong Konnect.
Important: This feature has the following limitations:
- Plugin object defaults are not supported.
- If an existing property’s default value changes in a future Kong Gateway release, decK has no way of knowing that this change has occurred, as its
defaultsconfiguration would overwrite the value in your environment.
Object defaults behavior
Defaults get applied to both new and existing objects. If an object has an explicit setting for a property, the object-level setting takes precedence over the default.
Kong Gateway sets some default values for most objects. You can see
what the defaults are for each object in the
Admin API reference, or use the
/schemas endpoint to
retrieve the latest object schemas for your instance of the Kong Gateway.
Configuring your own defaults is a good way to keep updated on potential
breaking changes between versions. If you upgrade Kong Gateway to a
version which introduces a new property with a default value, a
will catch the difference.
If defaults are not set in the declarative configuration file, any newly configured objects pick up Kong Gateway’s defaults and diverge from the source configuration file. This situation creates a false positive: decK sees a diff where one doesn’t exist. Refer to “Create a file and test without defaults” for an example.
Configure object defaults
The following guide creates a sample
kong.yaml file with a service and
route, shows you what responses look like without defaults set, and then walks
you through setting defaults.
If you are already familiar with the problem or have a configuration file you want to use, skip to setting defaults.
Create a file and test without defaults
Add the following sample service and route to the file:
_format_version: "3.0" services: - host: mockbin.org name: example_service routes: - name: mockpath paths: - /mock
Compare this file with the object configuration in Kong Gateway:
If you’re using a completely empty instance, you should only see the service and route creation messages with no extra JSON data.
Sync your changes with Kong Gateway:
Now, run another diff and note the difference in the response:
Even though you’ve made no changes, the response shows a list of new property configurations. The list of new configurations appears because Kong Gateway applied defaults and decK is unaware of them, so decK treats them like changes to the configuration.
kong.yamlconfiguration file, add an
_format_version: "3.0" _info: defaults: services: - host: mockbin.org name: example_service routes: - name: mockpath paths: - /mock
For production use in larger systems, we recommend that you break out your defaults into a separate
defaults.yamlfile or use tags to apply the defaults wherever they are needed.
Define the properties you want to set for core Kong Gateway objects.
You can define defaults for
_format_version: "3.0" _info: defaults: route: https_redirect_status_code: 426 path_handling: v1 preserve_host: false protocols: - http - https regex_priority: 0 request_buffering: true response_buffering: true strip_path: true service: port: 80 protocol: http connect_timeout: 60000 write_timeout: 60000 read_timeout: 60000 retries: 5 services: - host: mockbin.org name: example_service routes: - name: mockpath paths: - /mock
Save the file and run a diff:
Notice that the diff doesn’t show extra changes anymore.
The following properties are the defaults applied by Kong Gateway (as of v2.5.x), and setting them in your declarative configuration file is required to avoid differences between the configuration file and the Kong Gateway.
Note: The following are only properties that have defaults, and are not all of the available properties for each object.
Find default values for your Gateway version
For the most accurate default values for your version of Kong Gateway, see the
Admin API reference, or use the
/schemas endpoint. For example, you can check the schema for
targets and look for any value that
has defined defaults: