このページは、まだ日本語ではご利用いただけません。翻訳中です。
旧バージョンのドキュメントを参照しています。 最新のドキュメントはこちらをご参照ください。
Using decK with Kong Konnect
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.
You cannot use decK to publish content to the Dev Portal, manage application registration, or configure custom plugins.
Konnect flags
You can use decK commands such as ping
, diff
, or sync
with --konnect-*
flags to interact with Konnect.
If you don’t pass a Konnect flag to decK, decK looks for a local Kong Gateway instance instead.
--konnect-addr
- Address of the Konnect endpoint. (Default:
"https://us.api.konghq.com"
) --konnect-runtime-group-name
- Konnect runtime group name.
--konnect-token
- Personal access token associated with your Konnect account (
kpat_*
), or with a system account (spat_*
). This takes precedence over the--konnect-token-file
flag. --konnect-token-file
- File containing the personal access token to your Konnect account, or to a system account.
Note: Prior to decK 1.12, decK provided
deck konnect
commands. Those commands are deprecated and have been replaced with the flags in this guide.
Authenticate with Konnect
decK looks for Konnect credentials in the following order of precedence:
- Credential set with the
--konnect-token
flag - decK configuration file, if one exists (default lookup path:
$HOME/.deck.yaml
) - Credential file passed with the
--konnect-token-file
flag
For example, if you have both a decK config file and a Konnect token file, decK uses the token in the config file.
Note: decK also includes flags to authenticate to Konnect via email and password. This is no longer supported by Konnect; instead, use a token as described below.
Authenticate using a decK config file
By default, decK looks for a configuration file named .deck.yaml
in the $HOME
directory.
This file lets you specify flags to include with every decK command.
You can create the file at the default location, or set a custom filename and path with --config
.
If you store a Konnect token in the file, decK uses the token for every command.
Set either konnect-token
or konnect-token-file
in the decK config file.
-
Use
konnect-token
to store Konnect credentials directly in the configuration file:konnect-token: YOUR_TOKEN
-
Store your token in a separate file, then specify the path to
konnect-token-file
instead of a literal token:konnect-token-file: PATH/TO/FILENAME
decK automatically uses the token from $HOME/.deck.yaml
in any subsequent calls:
deck ping
Successfully Konnected to the Example-Name organization!
Authenticate using a token
You can generate a token in Konnect for authentication with decK commands.
There are two types of tokens available for Konnect:
- Personal access tokens associated with user accounts (PATs)
- System account access tokens associated with system accounts (SPATs)
Learn more about system accounts in the Konnect System Accounts documentation.
Before you generate a token, keep the following in mind:
- A token is granted all of the permissions that the user or system account has access to via their most up-to-date role assignment.
- The token has a maximum duration of 12 months.
- There is a limit of 10 personal access tokens per user.
- Unused tokens are deleted and revoked after 12 months of inactivity.
Important: The access token is only displayed once, so make sure you save it securely.
You can use the --konnect-token
flag to pass the PAT directly in the command:
deck ping \
--konnect-token YOUR_KONNECT_TOKEN
You can save your Konnect
token to a file, then pass the filename to decK with --konnect-token-file
:
deck ping \
--konnect-token-file /PATH/TO/FILE
Target a Konnect API
Use --konnect-addr
to select the API to connect to.
The default API decK uses is https://us.api.konghq.com
, which targets the cloud.konghq.com
environment.
Kong Gateway supports AU, EU, 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"
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.runtime_group_name
parameter:_format_version: "3.0" _konnect: runtime_group_name: staging
-
Set a control plane using the
--konnect-runtime-group-name
flag:deck sync --konnect-runtime-group-name staging
Troubleshoot
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:
runtime_group_name: staging
ACL, Key Auth, or OpenID Connect plugins and app registration
You may encounter one of the following scenarios with the ACL, Key Authentication, or OpenID Connect (OIDC) plugins:
- The plugins are visible in the Gateway Manager, but don’t appear in the output from a decK
dump
ordiff
. -
When trying to set up one of the plugins with app registration enabled, you see the following error:
{Create} plugin key-auth for service example_service failed: HTTP status 400
This is intentional. When you have application registration enabled, decK doesn’t manage these plugins, and doesn’t let you create duplicates of the plugin entries.
When setting up app registration, Konnect enables two plugins automatically: ACL, and either Key Authentication or OIDC, depending on your choice of authentication. These plugins run in the background to support application registration for an API product. They are managed entirely by Konnect, so you can’t manage these plugins directly.
Read Manage application registration for more information.