このページは、まだ日本語ではご利用いただけません。翻訳中です。
旧バージョンのドキュメントを参照しています。 最新のドキュメントはこちらをご参照ください。
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:
- Service
- Route
- Upstream
- Target
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
defaults
configuration 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 diff
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
-
Create a
kong.yaml
configuration file with the following sample contents:_format_version: "3.0" services: - host: httpbin.konghq.com 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:
deck sync
-
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.
Set defaults
-
In your
kong.yaml
configuration file, add an_info
section withdefaults
:_format_version: "3.0" _info: defaults: services: - host: httpbin.konghq.com 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.yaml
file 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
service
,route
,upstream
, andtarget
objects.For example:
_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: httpbin.konghq.com 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.
Defaults reference
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:
curl -i -X GET http://localhost:8001/schemas/targets