View on GitHub

decK

Declarative configuration for Kong and Kong Enterprise

Distributed configuration for Kong using decK

decK can operate on a sub-set of configuration instead of taking care of managing the entire configuration of Kong.

This can be very useful in a variety of scenarios, some examples include:

In such case, you can use decK’s select-tag feature to export, sync, reset only a sub-set of configuration.

Tags

Tags, introduced in Kong 1.1, provide a way to associate metadata with entities in Kong. You can also filter entities by tags on the list endpoints in Kong.

Using this feature, decK associates tags with entities and can manage a group of entities which share a common tag(s).

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 it is recommended to use fewer or only on tag, for performance reasons in Kong’s codebase.

Dump

You can export a sub-set of entities in Kong by specifying common tags using --select-tag flag.

For example:

$ deck dump --select-tag foo-tag --select-tag bar-tag
# generates a kong.yaml file with all entities which have both the tags

If you observe the file generated by decK, you will see the following section:

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

This sub-section tells decK to filter out entities containing select-tags during a sync operation.

Sync

You don’t need to specify --select-tag in sync and diff commands. The commands will use the tags present in the state file and perform the diff accordingly.

Since the state files have the tagging information, different teams can make updates to the part of configuration in Kong, without worrying about configuration of other teams. You no longer need to maintain Kong’s configuration in a single repository, where multiple teams need to co-ordinate.

The --select-tag flag is present on those two commands for use-cases where the file cannot have select_tags defined inside it. It is strongly advised that you do not supply select-tags to sync and diff commands via flags. The reason being that the tag information should be part of the declarative configuration file itself in order to provide a practical declarative file. The tagging information and entity definitions should be present in one place, else an error in supplying the wrong tag via the CLI can break the configuration.

Reset

You can delete only a sub-set of entities sharing a tag using the --select-tag flag on the reset command.

Initial setup problem

When you initially get started with a distributed configuration management, you will likely run into a problem where the related entities you would like to manage don’t share a single database.

To get around this problem, you can use one of the following approaches: