このページは、まだ日本語ではご利用いただけません。翻訳中です。
Object Defaults
Kong Gateway sets some default values for most objects, including Kong
plugins. You can see what the defaults are for each object in the
Admin API reference, or use the
/schemas
endpoint to
check the latest object schemas for your instance of the Kong Gateway.
decK recognizes value defaults and doesn’t interpret them as changes to
configuration. If you push a config for an object to Kong Gateway with
sync
, Kong Gateway applies its default values to the object,
but a further diff
or sync
does not show any changes.
If you upgrade Kong Gateway to a version that introduces a new
property with a default value, a diff
will catch the difference.
You can also configure your own custom defaults to enforce a set of standard values and avoid repetition in your configuration.
Value order of precedence
decK assigns values in the following order of precedence, from highest to lowest:
- Values set for a specific instance of an object in the state file
(for example, for a service named
example_service
defined inkong.yml
). - Values set in the
{_info: defaults:}
object in the state file. - Self-managed Kong Gateway only: Values are checked against the Kong Admin API schemas.
- Konnect Cloud only: Values are checked against the Kong Admin API for plugins, and against hardcoded defaults for Service, Route, Upstream, and Target objects.
Test default value handling
Create a sample kong.yaml
file with a service, route, and plugin, push it to
Kong Gateway, and then pull Kong Gateway’s configuration down
again to see how decK interprets default values.
-
Create a
kong.yaml
configuration file with the following sample service, route, and plugin:_format_version: "3.0" services: - host: httpbin.konghq.com name: example_service routes: - name: mockpath paths: - /mock plugins: - name: basic-auth config: hide_credentials: true
-
Compare this file with the object configuration in Kong Gateway:
If you’re using a completely empty instance, you should only see the service, route, and
basic-auth
plugin creation messages with no extra JSON data. -
Sync your changes with Kong Gateway:
deck gateway sync kong.yaml
-
Now, run another diff and note the response:
Notice that the diff doesn’t show any changes. This is because decK checked the values against the service and route schemas and didn’t find any differences.
-
You can check that any missing default values were set by exporting Kong Gateway’s object configuration into a file. If you want to avoid overwriting your current state file, specify a different filename:
deck gateway dump -o kong-test.yaml
Even though
diff
didn’t show any changes, the result now has default values populated for the service, route, and Basic Auth plugin:_format_version: "3.0" plugins: - config: anonymous: null hide_credentials: true enabled: true name: basic-auth protocols: - grpc - grpcs - http - https services: - connect_timeout: 60000 host: httpbin.konghq.com name: example_service port: 80 protocol: http read_timeout: 60000 retries: 5 routes: - https_redirect_status_code: 426 name: mockpath path_handling: v0 paths: - /mock preserve_host: false protocols: - http - https regex_priority: 0 request_buffering: true response_buffering: true strip_path: true write_timeout: 60000
Set custom defaults
You can set custom configuration defaults for the following core Kong Gateway objects:
- Service
- Route
- Upstream
- Target
Default values get applied to both new and existing objects. See the order of precedence for more detail on how they get applied.
You can choose to define custom default values for any subset of entity fields, or define all of them. decK still finds the default values using a combination of your defined fields and the object’s schema, based on the order of precedence.
decK supports setting custom object defaults both in self-managed Kong Gateway and with Kong Konnect.
Important: This feature has the following limitations:
- Custom 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.
-
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 Kong Gateway objects.
You can define custom defaults for
service
,route
,upstream
, andtarget
objects.For example, you could define default values for a few fields of the Service object:
_format_version: "3.0" _info: defaults: service: port: 8080 protocol: https retries: 10 services: - host: httpbin.konghq.com name: example_service routes: - name: mockpath paths: - /mock
Or you could define custom default values for all available fields:
_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: 8080 protocol: https connect_timeout: 60000 write_timeout: 60000 read_timeout: 60000 retries: 10 services: - host: httpbin.konghq.com name: example_service routes: - name: mockpath paths: - /mock
-
Sync your changes with Kong Gateway:
deck gateway sync kong.yaml
-
Run a diff and note the response:
Whether you choose to define a subset of custom defaults or all available
options, the result is the same: the diff doesn't show any changes.
Find defaults for an object
Kong Gateway defines all the defaults it applies in object schema files. Check the schemas to find the most up-to-date default values for an object.
If you want to completely avoid differences between the configuration file and
the Kong Gateway, set all possible default values for an object in your
kong.yaml
file.