Skip to content
Kong Logo | Kong Docs Logo
search
  • We're Hiring!
  • Docs
    • Kong Gateway
    • Kong Konnect
    • Kong Mesh
    • Plugin Hub
    • decK
    • Kubernetes Ingress Controller
    • Insomnia
    • Kuma

    • Docs contribution guidelines
  • Plugin Hub
  • Support
  • Community
  • Kong Academy
Early Access
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Plugin Hub
  • decK
  • Kubernetes Ingress Controller
  • Insomnia
  • Kuma

  • Docs contribution guidelines
  • 1.17.x (latest)
  • 1.16.x
  • 1.15.x
  • 1.14.x
  • 1.13.x
  • 1.12.x
  • 1.11.x
  • 1.10.x
  • 1.9.x
  • 1.8.x
  • 1.7.x
  • pre-1.7
    • Terminology
    • Architecture
    • Compatibility Promise
    • Getting Started with decK
    • Backup and Restore
    • Configuration as Code and GitOps
    • Distributed Configuration
    • Best Practices
    • Using decK with Kong Gateway (Enterprise)
    • Run decK with Docker
    • Using Multiple Files to Store Configuration
    • De-duplicate Plugin Configuration
    • Set Up Object Defaults
    • Using environment variables with decK
    • deck completion
    • deck convert
    • deck diff
    • deck dump
    • deck ping
    • deck reset
    • deck sync
    • deck validate
    • deck version
    • deck konnect
    • deck konnect diff
    • deck konnect dump
    • deck konnect ping
    • deck konnect sync

github-edit-pageEdit this page

report-issueReport an issue

enterprise-switcher-iconSwitch to OSS

On this page
  • Object defaults behavior
  • Configure object defaults
    • Create a file and test without defaults
    • Set defaults
  • Defaults reference
    • Find default values for your Gateway version
  • See also
decK
1.10.x
  • Home
  • decK
  • Guides
  • Defaults
  • Set Up Object Defaults
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:

  • 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 deck 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

  1. Create a kong.yaml configuration file.

  2. 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
    
  3. Compare this file with the object configuration in Kong Gateway:

    Command
    Response
    deck diff
    
    creating service example_service
     creating route mockpath
     Summary:
       Created: 2
       Updated: 0
       Deleted: 0
    

    If you’re using a completely empty instance, you should only see the service and route creation messages with no extra JSON data.

  4. Sync your changes with Kong Gateway:

     deck sync
    
  5. Now, run another diff and note the difference in the response:

    Command
    Response
    deck diff
    
    updating service example_service  {
        "connect_timeout": 60000,
        "host": "mockbin.org",
        "id": "1c088e59-b5fb-4c14-8d3a-401c02fc50b7",
        "name": "example_service",
        "port": 80,
        "protocol": "http",
        "read_timeout": 60000,
     -  "retries": 5,
        "write_timeout": 60000
      }
        
     updating route mockpath  {
     -  "https_redirect_status_code": 426,
        "id": "1f900445-1957-4c79-aa16-1c86ea41df7f",
        "name": "mockpath",
     -  "path_handling": "v0",
        "paths": [
          "/mock"
        ],
        "preserve_host": false,
        "protocols": [
          "http",
          "https"
        ],
        "regex_priority": 0,
     -  "request_buffering": true,
     -  "response_buffering": true,
        "service": {
          "id": "1c088e59-b5fb-4c14-8d3a-401c02fc50b7"
        },
        "strip_path": false
      }
        
     Summary:
       Created: 0
       Updated: 2
       Deleted: 0
    

    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

  1. In your kong.yaml configuration file, add an _info section with defaults:

     _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.yaml file or use tags to apply the defaults wherever they are needed.

  2. Define the properties you want to set for core Kong Gateway objects.

    You can define defaults for service, route, upstream, and target 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: mockbin.org
         name: example_service
         routes:
           - name: mockpath
             paths:
               - /mock
    
  3. Save the file and run a diff:

    Command
    Response
    deck diff
    
    Summary:
       Created: 0
       Updated: 0
       Deleted: 0
    

    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.

Route
Service
Upstream
Target

Set the following properties to the values you want to use across all Routes:

_info:
  defaults:
    route:
      https_redirect_status_code: 426
      path_handling: v0
      preserve_host: false
      protocols:
      - http
      - https
      regex_priority: 0
      request_buffering: true
      response_buffering: true
      strip_path: true

For all available properties, see the Route object documentation.

Set the following properties to the values you want to use across all Services:

_info:
  defaults:
    service:
      port: 80
      protocol: http
      connect_timeout: 60000
      write_timeout: 60000
      read_timeout: 60000
      retries: 5

For all available properties, see the Service object documentation.

Set the following properties to the values you want to use across all Upstreams:

_info:
  defaults:
    upstream:
      slots: 10000
      algorithm: round-robin
      hash_fallback: none
      hash_on: none
      hash_on_cookie_path: /
      healthchecks:
        active:
          concurrency: 10
          healthy:
            http_statuses:
            - 200
            - 302
            interval: 0
            successes: 0
          http_path: /
          https_verify_certificate: true
          timeout: 1
          type: http
          unhealthy:
            http_failures: 0
            http_statuses:
            - 429
            - 404
            - 500
            - 501
            - 502
            - 503
            - 504
            - 505
            interval: 0
            tcp_failures: 0
            timeouts: 0
        passive:
          healthy:
            http_statuses:
            - 200
            - 201
            - 202
            - 203
            - 204
            - 205
            - 206
            - 207
            - 208
            - 226
            - 300
            - 301
            - 302
            - 303
            - 304
            - 305
            - 306
            - 307
            - 308
            successes: 0
          type: http
          unhealthy:
            http_failures: 0
            http_statuses:
              - 429
              - 500
              - 503
            tcp_failures: 0
            timeouts: 0
        threshold: 0

For all available properties, see the Upstream object documentation.

Set the following property to the value you want to use across all Targets:

_info:
  defaults:
    target:
      weight: 100

For all available properties, see the Target object documentation.

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
HTTPie
curl -i -X GET http://localhost:8001/schemas/targets
http :8001/schemas/targets

See also

  • Deduplicate plugin configuration
  • Distributed configuration for Kong Gateway using decK
  • Using multiple files to store configuration
  • Kong Gateway admin API: /schemas endpoint
Thank you for your feedback.
Was this page useful?
  • Kong
    THE CLOUD CONNECTIVITY COMPANY

    Kong powers reliable digital connections across APIs, hybrid and multi-cloud environments.

    • Company
    • Customers
    • Events
    • Investors
    • Careers Hiring!
    • Partners
    • Press
    • Contact
  • Products
    • Kong Konnect
    • Kong Gateway
    • Kong Mesh
    • Get Started
    • Pricing
  • Resources
    • eBooks
    • Webinars
    • Briefs
    • Blog
    • API Gateway
    • Microservices
  • Open Source
    • Install Kong Gateway
    • Kong Community
    • Kubernetes Ingress
    • Kuma
    • Insomnia
  • Solutions
    • Decentralize
    • Secure & Govern
    • Create a Dev Platform
    • API Gateway
    • Kubernetes
    • Service Mesh
Star
  • Terms•Privacy
© Kong Inc. 2023