Upgrade to Kong Gateway 3.x

With the release of Kong Gateway 3.0, route paths that use regular expressions are no longer automatically detected. For Kong Gateway to parse a path that contains a regular expression, the path must be prefixed with a ~.

For example, in 2.x, a route path that was expressed like this:

/status/\d+

Would need to be rewritten in the new 3.0 format:

~/status/\d+

If you migrated your Kong Gateway database from 2.8.x to 3.0, the ~ prefix is automatically added to the route paths in the database. This causes configuration drift between the formats of the routes that exist in the database and the routes in your configuration file.

Before using your state files to update the database, convert them into the 3.0 format using deck convert.

Important: Don’t use deck sync with Kong Gateway 3.x before converting paths into the 3.0 format. This will break all regex routing in 3.x.

Convert declarative configuration files

1. Run deck-convert against your 2.x state file to turn it into a 3.x file:

    deck convert \
    --from kong-gateway-2.x \
    --to kong-gateway-3.x \
    --input-file kong.yaml \
    --output-file new-kong.yaml
   

   This command upgrades the _format_version setting to 3.0 and adds the ~ prefix to all route paths containing a regex pattern.

   You can leave input-file out to convert all declarative configuration files in your working directory. We recommend specifying both input and output files.

2. Look over all the changes carefully and validate the converted file in a test environment.

   Make sure to manually audit the generated file before applying the configuration in production. These changes may not be fully correct or exhaustive, so manual validation is strongly recommended.

   Incorrect changes will result in unintended traffic routing by Kong Gateway.

FAQ

What happens if I set the format version to 3.0 but don’t update regex paths?

You should avoid setting the format version manually. When you sync the file without updating regex paths, the incorrect values will be pushed to the database and Kong Gateway will route traffic incorrectly.

decK will issue a warning stating that an invalid regex pattern was detected and that it must be updated with a ~ to distinguish it from a standard prefix match.

I ran decK convert but there are still errors or warnings, what do I do?

Manually validate the file, then make any necessary updates to your state file.

Can I still apply configuration if there are warnings?

If you have validated the configuration and found no issues but are still getting a warning, the warning may be a false positive. You can still apply the configuration, but do so at your own risk.

If you run into false positives, file an issue to let us know.

Changes to decK commands in 3.x

When running decK commands against Kong Gateway 3.x, keep the following behavior in mind:

deck dump

Explicitly sets the format version to 3.0. It assumes that the paths have been correctly transformed, either via Kong migrations, manually, or through a deck convert.

deck diff, deck validate (with --online flag only), or deck sync

decK performs a check to ensure all regex routes are correctly prefixed. The behavior of the command depends on the format version in the declarative configuration file:

• _format_version: 1.1 or earlier: Prints an error and stops the operation.
• _format_version: 3.0 with incorrectly prefixed routes: Prints a warning and goes ahead with the diff, sync, or validate operation as usual.
• _format_version: 3.0 with correctly prefixed routes: Goes ahead with the diff, sync, or validate operation as usual.

deck convert

Includes --from and --to flags for converting state files between major versions. Converts all relevant files in the present working directory:

• Upgrades the _format_version setting to 3.0
• Adds the ~ prefix to all route paths containing a regex pattern

You can optionally provide --input-file and --output-file flags to limit conversion to a subset of files.

Using decK with Konnect data plane nodes

Konnect supports 3.x and 2.x data plane nodes, but the Konnect control plane version is 3.x. Since decK can’t tell if a control plane is intended for 2.x or 3.x data plane nodes, it will always dump configuration with _format_version: 3.0.

To avoid compatibility errors, make sure that all data plane nodes in a single control plane are of the same major version (all 2.x or all 3.x).

For all diff, sync, or validate (with --online flag) operations against Konnect, decK issues warnings when it detects incorrect regex path configurations.