justeat / kongverge

A desired state configuration tool for Kong

Kongverge

A Desired State Configuration tool for Kong.

A command-line tool written in cross-platform .NET Core 2.2.

See the tutorial for examples of how to use Kongverge.

Installation

Kongverge is built as a .NET core global tool.

You can install kongverge as a global tool as follows:

• First, have .NET Core SDK 2.1 or later installed. At a commandline, dotnet --list-sdks should succeed and show an item for 2.1.0 or later.
• Install with dotnet tool install kongverge --global.
• You should then be able to run kongverge from the commandline e.g. kongverge --help

Other operations:

• Update to latest: dotnet tool update kongverge --global
• Uninstall: dotnet tool uninstall kongverge --global

This should all work on development and build machines, on Windows, Mac and Linux, as long as the .NET Core 2.1 SDK is installed. Alternatively, this can be built as a standard .NET Core application which only requires the .NET Core runtime rather than the SDK (technically you only need the SDK to install/update/uninstall a .NET core global tool - running it only requires the runtime).

Kong DTOs

Kongverge uses several DTOs to read from files and write to Kong (and vice versa). For simplicity, the field names on these objects generally match what is present in Kong. See KongConfiguration, KongRoute, KongService, KongPlugin which are used to serialize these kong concepts.

These objects also handle matching - i.e. reconciling the state described by files with the state in Kong, and performing actions in Kong as needed to make them the same. The possible cases for these objects are:

• Unchanged; The object in Kong is identical to the object in config, so no action is required.
• Changed; the object in Kong is matched with an object in config, but not all of the properties are the same. Action is required to update the object in place.
• New; the object needs to be added to Kong.
• Deleted; the object needs to be removed from Kong.

Kongverge is smart enough to perform some basic normalization when comparing object graphs to find differences: It does some basic sorting of arrays and sorting of object properties during comparison.

Kong's plugin model is more complex, as each plugin has its own set of properties used to configure it. We model this as a JObject and the equality comparison checks a normalized version of this object graph.

Kongverge is smart enough to validate these configuration objects when reading from files, taking into account that some properties have default values if omitted (in the case of plugins, it does this by inspecting the associated schema object), and thus will not show an omitted default value as changed.

Testing

Integration tests exist to test Kongverge against a real instance of Kong running in Docker. In order to build the integration tests project, you will need to have Docker installed locally. For development and CI-build purposes, the following steps are required:

• Before running the integration tests, start the docker services by running docker-compose start from within the integration tests project folder.
• After running the integration tests (or when required), stop the docker services by running docker-compose stop from within the integration tests project folder.

kongverge's Issues

Route ToString method breaks when Hosts, Paths, Methods or Protocols are null

The ToString() method override for Route fails when any of the following properties are null:

• Hosts
• Paths
• Methods
• Protocols

Routes should always start with "/"

Kongverge will allow regex patterns that don't match this requirement.

Kongverge could easily reject routes configured without a "/" as the initial character.

The only documentation around this doesn't appear to call this out as a specific requirement - however it does call out that the routes are anchored on matching the first character anyway, so it makes no sense for a route that doesn't start with a "/" character.

Configuration validation fails on route paths and hosts

Validation of route configuration fails in the following cases:

• When paths contain regexes
• When hosts contain leading or trailing wildcards

Automatically rollback if Kong responds with 400 when applying configuration changes

If Kong responds with a 400 status code (Bad Request) while we are applying configuration changes via the Admin API, this indicates that something about our target configuration is invalid. In this case, we should attempt to rollback to the previous configuration that was in place before beginning the configuration changes, so that we leave Kong in a known working state.

Validate configuration objects more thoroughly when parsing

Currently, we perform some rudimentary validation of configuration objects when reading files from disk. We'd like to perform this validation more thoroughly, so that any potential errors are found before we begin the workflow to synchronize the configuration to Kong. This will help to make sure that the workflow doesn't fail halfway through and leave Kong in a broken/undefined state.

Things we'd like to validate are:

• Properties of Service are set to valid values
• Properties of Route are set to valid values
• Properties of Plugin are set to valid values
• Only plugins which are installed are valid for use (the list of installed plugins can be queried from Kong)
• Plugin configuration is valid according to that plugin's schema (which we can query from Kong)

Can not access host with basic auth

We enabled basic auth on our Kong node. However, Kongverge does not support such a form of authentication, yet. In addition, the error code does not provide an appropiate error code. Am I doing something wrong, or isn't it supported, yet?

C:\Users\p.wessels>kongverge --host localhost --port 7001 --output C:\Users\p.wessels\Desktop --verbose
[16:50:25 INF] ************** Kongverge 1.2.0.150 **************
[16:50:25 INF] Exporting configuration from Kong
[16:50:25 ERR] Specified host unreachable

Add schema validation for KongService to ensure "name" is required

We require that KongService files declare the "name" property, which is optional for Kong, but required for Kongverge to perform matching for determining if there any changes.