You are browsing documentation for an outdated version. See the latest documentation here.
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:
Would need to be rewritten in the new 3.0 format:
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
Important: Don’t use
deck syncwith 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
deck-convertagainst 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
3.0and adds the
~prefix to all route paths containing a regex pattern.
You can leave
input-fileout to convert all declarative configuration files in your working directory. We recommend specifying both input and output files.
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.
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:
- 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
--onlineflag only), or
- 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.1or earlier: Prints an error and stops the operation.
_format_version: 3.0with incorrectly prefixed routes: Prints a warning and goes ahead with the
validateoperation as usual.
_format_version: 3.0with correctly prefixed routes: Goes ahead with the
validateoperation as usual.
--toflags for converting state files between major versions. Converts all relevant files in the present working directory:
- Upgrades the
- Adds the
~prefix to all route paths containing a regex pattern
- Upgrades the
You can optionally provide
--output-fileflags to limit conversion to a subset of files.
Using decK with Konnect runtime instances
Konnect supports 3.x and 2.x runtime instances, but the Konnect control plane version is 3.x.
Since decK can’t tell if a runtime group is intended for 2.x or 3.x runtime instances, it will always dump configuration with
To avoid compatibility errors, make sure that all runtime instances in a single runtime group are of the same major version (all 2.x or all 3.x).
--online flag) operations against Konnect, decK issues warnings when it detects incorrect regex path configurations.