Konnect Configuration
Konnect requires decK v1.40.0 or above. Versions below this will see inconsistent
deck gateway diff
results.
You can manage Kong Gateway core entity configuration in your Konnect organization using decK.
decK can only target one control plane at a time.
Managing multiple control planes requires a separate state file per control plane.
decK does not support publishing content to the Dev Portal or managing application registrations. Custom plugins can only be configured if the plugin schema has been uploaded to Konnect. Please note that creating or managing schemas via decK is not supported.
Using decK with Konnect
To use decK with Konnect, you must provide a Konnect authentication method and the name of a control plane to target.
# This is missing an authentication method
# See below for token/OIDC authentication examples
deck gateway ping --konnect-addr https://us.api.konghq.com --konnect-control-plane-name default
--konnect-addr
is optional. If any --konnect
flag is set, the Admin API URL will default to https://us.api.konghq.com
.
deck gateway ping --konnect-control-plane-name default
Token authentication
If you are using personal access tokens or system access tokens, you can provide them using the --konnect-token
flag:
deck gateway ping --konnect-token $KONNECT_TOKEN --konnect-addr https://us.api.konghq.com --konnect-control-plane-name default
You can provide the Konnect token in a file on disk rather than as an environment variable using the --konnect-token-file
flag:
deck gateway ping --konnect-token-file /path/to/file --konnect-addr https://us.api.konghq.com --konnect-control-plane-name default
Region selection
Use --konnect-addr
to select the API to connect to.
The default API decK uses is https://us.api.konghq.com
.
Kong Gateway supports AU, EU, IN, ME, and US geographic regions.
To target a specific geo, set konnect-addr
to one of the following:
- AU geo:
"https://au.api.konghq.com"
- EU geo:
"https://eu.api.konghq.com"
- US geo:
"https://us.api.konghq.com"
- IN geo:
"https://in.api.konghq.com"
- ME geo:
"https://me.api.konghq.com"
Control planes
Each state file targets one control plane.
If you don’t provide a control plane, decK targets the default
control plane.
If you have a custom control plane, you can specify it in the state file, or use a flag when running any decK command.
-
Target a control plane in your state file with the
_konnect.control_plane_name
parameter:_format_version: "3.0" _konnect: control_plane_name: staging
-
Set a control plane using the
--konnect-control-plane-name
flag:deck gateway sync konnect.yaml --konnect-control-plane-name staging
Troubleshooting
Authentication with a Konnect token file is not working
If you have verified that your token is correct but decK can’t connect to your account, check for conflicts with the decK config file ($HOME/.deck.yaml
) and the Konnect token file.
A decK config file is likely conflicting with the token file and passing another set of credentials.
To resolve, remove one of the duplicate sets of credentials.
Workspace connection refused
When migrating from Kong Gateway to Konnect, make sure to remove any _workspace
tags. If you leave _workspace
in, you get the following error:
Error: checking if workspace exists
Remove the _workspace
key to resolve this error.
You can now sync the file as-is to apply it to the default control plane or add a key to apply the configuration to a specific control plane.
To apply the configuration to custom control planes, replace _workspace
with control_plane_name: ExampleName
.
For example, to export the configuration from workspace staging
to control plane staging
, you would change:
_workspace: staging
To:
_konnect:
control_plane_name: staging
decK targets Kong Gateway instead of Konnect
decK can run against Kong Gateway or Konnect. By default, it targets Kong Gateway, unless a setting tells decK to point to Konnect instead.
decK determines the environment using the following order of precedence:
-
If the declarative configuration file contains the
_konnect
entry, decK runs against Konnect. -
If the
--kong-addr
flag is set to a non-default value, decK runs against Kong Gateway. -
If Konnect token is set in any way (flag, file, or decK config), decK runs against Konnect.
-
If none of the above are present, decK runs against Kong Gateway.