Upgrade to Kong Gateway 3.x with decK

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.

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.

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.

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.