Migrate from Kong Gateway DB-less format to decK state file format

decK uses its own state file format, which differs from the declarative configuration format built into Kong Gateway for DB-less mode. Both formats use YAML and share some metadata fields, but they represent certain entities differently and aren’t directly compatible. This page explains the differences between the two formats and what to consider when migrating from DB-less config to decK.

The following table summarizes when to use each format:

decK has several advantages over the kong config db_import and db_export commands:

• decK applies changes through the Admin API, so all nodes receive updates automatically.
• In addition to creating and updating entities, decK can also delete entities that exist in the database but are absent from your config file.
• decK uses the Admin API, so it works in production networking environments where a direct database connection isn’t available.
• decK can compare the configuration in Kong Gateway’s database against your config file and report differences. This is useful for CI pipelines or scheduled drift checks.
• deck gateway dump produces a more human-readable file than db_export.

Note: Before migrating to decK, consider the following limitations:

• For very large installations, decK sync can be slow. Mitigate this with distributed configuration and the --parallelism flag. db_import is typically faster by orders of magnitude.
• decK can’t correctly export and re-import fields that are hashed in the database. For example, the password of a basic-auth credential will be rehashed during sync, corrupting the value.

Both formats use metadata fields prefixed with an underscore (_). Support for each field varies by format and target environment:

Note: Neither format includes a field to identify itself as a decK or DB-less file. You can’t reliably detect the file type from its contents alone.

The formats represent some entities differently, making them explicitly incompatible in certain areas. Use deck file format to convert between the two.

For example, to convert a DB-less file to decK format:

deck file format deck dbless.yaml

Or, convert a decK file to DB-less format:

deck file format dbless deck.yaml

Consumer Group plugins

In decK format, Consumer Group plugins are nested under each Consumer Group entry. In DB-less format, they are stored in a top-level consumer_group_plugins array where each entry references its Consumer Group by name.

decK requires the Consumer Group to be defined in the same file, because the plugin is nested inside the group entry. In DB-less format, consumer_group_plugins entries can exist independently.

To convert Consumer Groups from DB-less format to decK:

1. Rename consumer_groups[*].consumer_group_plugins to consumer_groups[*].plugins (merge if the key already exists).
2. Iterate over consumer_group_plugins.
3. For each entry, find the matching Consumer Group entry.
4. Append the plugin entry to the plugins array in that Consumer Group (create the array if it doesn’t exist).

Consumer Group membership

In decK format, Consumer Group membership is nested under each Consumer entry as an array of objects with a single name key. In DB-less format, memberships are stored in a top-level consumer_group_consumers array where each entry references both a Consumer and a Consumer Group.

decK requires the Consumer to be defined in the same file, because membership is nested inside the Consumer entry.

To convert Consumers and their Consumer Groups from DB-less to decK:

1. Iterate over consumer_group_consumers.
2. For each entry, find the matching Consumer entry.
3. Create a groups array in the Consumer object if it doesn’t exist.
4. Insert a new object with a single key name and the value set to consumer_group_consumer.consumer_group.
5. Add appropriate tags as needed.

Plugin partials

In decK format, plugin Partial links are nested under each plugin entry as an array of objects with name, id, and optional path keys. In DB-less format, they are stored in a top-level plugins_partials array where each entry references both a plugin and a Partial.

To convert Partials from DB-less to decK:

1. Iterate over plugins_partials.
2. For each entry, find the matching plugin entry.
3. Create a partials array in the plugin object if it doesn’t exist.
4. Insert a new object with name or id set to the Partial reference, and include path if specified. If no path is provided, Kong Gateway uses the default path from the Partial’s schema.

The following examples show the same Kong Gateway entity configuration expressed in each format.

_transform: false
_format_version: '3.0'

consumer_groups:
- name: A-team

consumer_group_plugins:
- name: rate-limiting-advanced
  consumer_group: A-team
  config:
    limit:
    - 1000
    retry_after_jitter_max: 0
    window_size:
    - 3600
    window_type: sliding

consumers:
- username: example-user1
  custom_id: user1
- username: example-user2
  custom_id: user2

consumer_group_consumers:
- consumer: example-user1
  consumer_group: A-team
- consumer: example-user2
  consumer_group: A-team

partials:
- id: c4ff03ed-478a-4b86-bdcf-811c45c00737
  name: my-redis-instance
  type: redis-ee
  config:
    port: 6379
    host: 127.0.0.1

plugins:
- id: 017320fe-ba14-4e14-8bac-3a7d1d3cd1e0
  name: rate-limiting-advanced
  config:
    strategy: redis
    sync_rate: -1
    limit:
    - 1000
    retry_after_jitter_max: 0
    window_size:
    - 3600
    window_type: sliding

plugins_partials:
- plugin: 017320fe-ba14-4e14-8bac-3a7d1d3cd1e0
  partial: c4ff03ed-478a-4b86-bdcf-811c45c00737
  path: config.redis

_format_version: "3.0"

consumer_groups:
- name: A-team
  plugins:
  - config:
      limit:
      - 1000
      retry_after_jitter_max: 0
      window_size:
      - 3600
      window_type: sliding
    name: rate-limiting-advanced

consumers:
- custom_id: user1
  groups:
  - name: A-team
  username: example-user1
- custom_id: user2
  groups:
  - name: A-team
  username: example-user2

partials:
- config:
    host: 127.0.0.1
    port: 6379
  id: c4ff03ed-478a-4b86-bdcf-811c45c00737
  name: my-redis-instance
  type: redis-ee

plugins:
- id: 017320fe-ba14-4e14-8bac-3a7d1d3cd1e0
  name: rate-limiting-advanced
  config:
    strategy: redis
    sync_rate: -1
    limit:
    - 1000
    retry_after_jitter_max: 0
    window_size:
    - 3600
    window_type: sliding
  partials:
  - id: c4ff03ed-478a-4b86-bdcf-811c45c00737
    name: my-redis-instance
    path: config.redis