Select tags and lookup tags

decK can operate on a subset of configuration instead of managing a complete Kong Gateway configuration. To do this, decK tags each entity with a value, and ignores any resources that don’t have that tag when running deck gateway dump or deck gateway sync.

Common use cases for splitting your configuration across multiple files include:

• Managing Consumers separately from your Service, Route, and Plugin configuration
• Allowing each Service owner to manage their own configuration
• Splitting large configuration files to reduce the time it takes to run deck gateway sync

When multiple tags are specified in decK, decK ANDs those tags together, meaning only entities containing all the tags will be managed by decK. You can specify a combination of up to 5 tags, but we recommend using fewer for performance reasons.

To specify a tag to manage, you can use the --select-tag command line flag. This flag may be provided multiple times to specify multiple tags:

deck gateway dump --select-tag foo-tag --select-tag bar-tag -o kong.yaml

This will dump all resources that have the foo-tag tag and the bar-tag tag.

Make some changes to this file, then push them to Kong Gateway using:

deck gateway diff kong.yaml

# Then if the changes are expected, apply the changes
deck gateway sync kong.yaml

Notice how the --select-tag flags are not required for deck gateway diff/sync. This is because deck gateway dump added an _info section to the declarative configuration file that automatically adds the tags to the sync request:

_info:
  select_tags:
    - foo-tag
    - bar-tag

The --select-tag flag can be used with deck gateway sync for situations where the state file doesn’t contain the above information. It is strongly advised that you do not supply select-tags to sync and diff commands via flags.

Important: You can’t sync a subset of content from a single file using select_tags. --select-tag must be provided when running deck gateway dump and the same file must be synced to the Admin API using the exact same select_tags.

decK lets you specify entity relationships using foreign keys. For example, look at the following files that manage Consumers and Consumer Groups:

# consumers.yaml
_format_version: "3.0"
_info:
  select_tags:
    - billing-consumers
consumers:
  - username: alice
    groups:
      - name: finance
    keyauth_credentials:
      - key: hello_world

# consumer-groups.yaml
_format_version: "3.0"
_info:
  select_tags:
    - billing-groups
consumer_groups:
  - name: finance
    plugins:
      - name: rate-limiting
        config:
          minute: 5
          limit_by: consumer
          policy: local

The consumer-groups.yaml file syncs as expected as it doesn’t contain any foreign key references. However, you will get an error when syncing consumers.yaml as the finance Consumer Group won’t be available:

deck gateway sync consumers.yaml
Error: building state: consumer-group 'finance' not found for consumer '093645f9-e189-47ba-bc9e-f4e9b09325eb'

You have two options to resolve this issue:

1. Ensure that all resources use the same select_tags.
2. Use default_lookup_tags to load additional resources without including them in your state file. Default lookup tags can be used on Services, Routes, Partials, Consumers, and Consumer Groups.

Update consumers.yaml now to specify default_lookup_tags.consumer_groups:

# consumers.yaml
_format_version: "3.0"
_info:
  select_tags:
    - billing-consumers
  default_lookup_tags:
    consumer_groups:
      - billing-groups
consumers:
  - username: alice
    groups:
      - name: finance
    keyauth_credentials:
      - key: hello_world

This loads all consumer_groups with the tag billing-groups in to memory and decK can successfully resolve the foreign keys used in consumers.yaml.

If the entity has multiple tags, all tags must be added to default_lookup_tags. For example, if the finance Consumer Group had tags for billing-groups and demo, then consumer.yaml would need both tags listed:

# consumers.yaml
_format_version: "3.0"
_info:
  select_tags:
    - billing-consumers
  default_lookup_tags:
    consumer_groups:
      - billing-groups
      - demo
consumers:
  - username: alice
    groups:
      - name: finance
    keyauth_credentials:
      - key: hello_world