Configuring Konnect

Note: Konnect requires decK v1.40.0 or above. Versions below this will see inconsistent deck gateway diff results.

To use decK with Konnect, you need:

• A Konnect authentication token
• The name of a control plane to target
• (Optional, if your organization isn’t in the us region) The Konnect API address

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. Note that creating or managing schemas via decK is not supported.

To use decK with Konnect, you must provide a Konnect authentication method and the name of a control plane to target.

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-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-control-plane-name default

Region selection

Use --konnect-addr to select the API to connect to.

deck gateway ping \
  --konnect-token $KONNECT_TOKEN \
  --konnect-addr https://us.api.konghq.com \
  --konnect-control-plane-name default

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

  Copied!

• Set a control plane using the --konnect-control-plane-name flag:

  deck gateway sync konnect.yaml --konnect-control-plane-name staging

  Copied!

Setting default connection values

If you need to connect to one organization and control plane consistently, you can use environment variables prefixed with DECK_* instead of passing connection flags with every command. For example:

export DECK_KONNECT_TOKEN='YOUR-KONNECT-TOKEN'
export DECK_KONNECT_ADDR='https://eu.api.konghq.com'
export DECK_KONNECT_CONTROL_PLANE_NAME='YOUR-CONTROL-PLANE'

For more on how decK uses environment variables and configuration files, see decK configuration.

You can make Admin API calls for control plane configuration using decK with a private connection through AWS PrivateLink to stay compliant and save data transfer costs. Once you set up AWS PrivateLink for your environment, you can make decK calls by using the domain region.svc.konghq.com/api/.

The following sections explain how to resolve common issues you may encounter when using decK with Konnect.

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:

1. If the declarative configuration file contains the _konnect entry, decK runs against Konnect.

2. If the --kong-addr flag is set to a non-default value, decK runs against Kong Gateway.

3. If a Konnect token is set in any way (flag, file, or decK config), decK runs against Konnect.

4. If none of the above are present, decK runs against Kong Gateway.