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
in the future.
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 AND
s 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 or only one tag for performance reasons.
Select tags
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: It is not possible to 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
.
Default 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:
- Ensure that all resources use the same
select_tags
- Use
default_lookup_tags
to load additional resources without including them in your state file.
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
.
Default lookup tags can be used on Services, Routes, Consumers and Consumer Groups.