このページは、まだ日本語ではご利用いただけません。翻訳中です。
Manage Control Plane Configuration with decK
You can manage control planes in your Kong Konnect org using configuration files instead of the GUI or admin API commands. With decK, Kong’s declarative configuration management tool, you can create, update, compare, and synchronize configuration as part of an automation pipeline.
In Kong Konnect, decK can manage control planes and all of their configurations:
- Create state files for different control planes and manage each one separately.
- Manage Gateway entities for each control plane.
- Migrate configuration from one control plane to another.
One way to learn decK or write a decK file is to view the YAML generated files in Konnect. Konnect autogenerates a YAML configuration file that reflects the current Gateway Manager configuration. You can view and copy the current configuration on the Configuration tab of each entity in Gateway Manager.
Use a --konnect
-prefixed CLI flag or pass Konnect
parameters using a decK configuration file (~/.deck.yaml
by default) to target
https://cloud.konghq.com
. If you don’t pass any Konnect parameters to decK,
decK looks for a local Kong Gateway instance instead.
Run deck help
to see all available flags, or see the decK CLI reference.
You cannot use decK to publish content to the Dev Portal, manage application registration, or configure custom plugins.
Prerequisites
- decK v1.12.0 or later installed.
- Optional: To test your configuration, set up a simple data plane node.
Generate a personal access token
To test your connection, we recommend that you use a personal access token (PAT).
You can generate a personal access token (PAT) in Konnect for authentication with decK commands. This is more secure than basic authentication, and can be useful for organizations with CI pipelines that can’t use the standard username and password authentication.
There are two types of PATs available for Konnect:
- Personal access tokens associated with user accounts
- System account access tokens associated with system accounts
Learn more about system accounts in the Konnect System Accounts documentation.
Before you generate a PAT, keep the following in mind:
- A PAT is granted all of the permissions that the user has access to via their most up-to-date role assignment.
- The PAT 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.
Test your connection
Check that you can log in to Konnect and that decK recognizes your account credentials:
deck gateway ping \
--konnect-control-plane-name default \
--konnect-token {YOUR_PERSONAL_ACCESS_TOKEN}
If the connection is successful, the terminal displays the full name of the user associated with the account:
Successfully Konnected to the Example-Name organization!
You can also use decK with Konnect more securely by storing
your personal access token in a file, then either calling it with
--konnect-token-file /path/{FILENAME}.txt
, or adding it to your decK configuration
file under the konnect-token
option:
konnect-token: {YOUR_PERSONAL_ACCESS_TOKEN}
The default location for this file is $HOME/.deck.yaml
. You can target a
different configuration file with the --config /path/{FILENAME}.yaml
flag, if
needed.
The following steps all use a .deck.yaml
file to store the
Konnect credentials instead of flags.
Create a configuration file
Capture a snapshot of the current configuration in a file:
deck gateway dump --konnect-control-plane-name default -o konnect.yaml
If you don’t specify the --konnect-control-plane-name
flag, decK will target the
default
control plane. If you have more than one control plane in your
organization, we recommend always setting this flag to avoid accidentally
pushing configuration to the wrong group.
The command creates a file named konnect.yaml
. If you have nothing
configured, decK creates the file with only the format version and control plane
name:
_format_version: "1.1"
_konnect:
control_plane_name: default
You can specify a different filename or location, or export the configuration in JSON format:
deck gateway dump --konnect-control-plane-name default \
--format json \
--output-file examples/konnect.json
Make changes to configuration
Make any changes you like using YAML or JSON format. For this example, let’s add a new service.
-
Add the following snippet to your
konnect.yaml
file:_format_version: "1.1" _konnect: control_plane_name: default services: - name: MyService host: httpbin.konghq.com port: 80 protocol: http routes: - methods: - GET - POST name: mockpath paths: - /mock plugins: - name: key-auth config: key_names: - apikey
This snippet defines a service named
MyService
pointing tohttpbin.konghq.com
. The service has one version, and the version gets implemented with the route/mock
, which means that you can access the service by appending this route to your proxy URL.Because you’re also enabling the
key-auth
plugin on the route, you need a consumer key to access it, so you can’t test the route yet. -
Compare your local file with the configuration currently in Kong Konnect:
deck gateway diff konnect.yaml --konnect-control-plane-name default
If the format and schema is correct, decK gives you a preview of what would be added to the Kong Konnect configuration:
creating service MyService creating route mockpath creating plugin key-auth for route mockpath Summary: Created: 3 Updated: 0 Deleted: 0
-
If you’re satisfied with the preview, sync the changes to Kong Konnect:
deck gateway sync konnect.yaml --konnect-control-plane-name default
You should see the same output again:
creating service MyService creating route mockpath creating plugin key-auth for route mockpath Summary: Created: 3 Updated: 0 Deleted: 0
-
Check Kong Konnect to make sure the sync worked. Open Gateway Manager, select your control plane, and select Gateway Services.
You should see a new service named
MyService
in the control plane.
Manage consumers and global plugins
You can also use decK to manage objects not tied to a specific service or route. For this example, create a consumer and a global proxy caching plugin:
-
Consumers represent users of a service, and are most often used for authentication. They provide a way to divide access to your services, and make it easy to revoke that access without disturbing a service’s function.
-
Global plugins are plugins that apply to all services, routes, and consumers in the control plane, as applicable. For example, you can configure proxy caching on all your services at once with one
proxy-cache
plugin entry.
-
In the previous section, you created a route with key authentication. To access this route, add a consumer to the
konnect.yaml
file and configure a key:consumers: - custom_id: consumer username: consumer keyauth_credentials: - key: apikey
-
Enable proxy caching so that your upstream service is not bogged down with repeated requests. Add a global proxy cache plugin:
plugins: - name: proxy-cache config: content_type: - "application/json; charset=utf-8" cache_ttl: 30 strategy: memory
-
Run a diff to test your changes:
deck gateway diff konnect.yaml --konnect-control-plane-name default
-
If everything looks good, run another sync, then check Kong Konnect to see your changes:
deck gateway sync konnect.yaml --konnect-control-plane-name default
Test the service
If you have already have a data plane node deployed, you can test this configuration now. Or, you can start a new data plane node using the Docker quick setup script.
The default proxy URL is localhost:8000
.
Make a call to the proxy URL and append the route path /mock
with an apikey
header:
curl -i -X GET http://localhost:8000/mock \
-H 'apikey: {API_KEY}'
If successful, you should see the homepage for httpbin.konghq.com
. On the Service
Version overview page, you’ll see a record for status code 200
.
If you try to access the route without a key, you’ll get an authorization error:
Kong Error
No API key found in request.
Migrate configuration between control planes
You can also use decK to migrate or duplicate configuration between control planes.
-
Export configuration from the original control plane with
deck gateway dump
into a state file:deck gateway dump \ --konnect-control-plane-name default \ --output-file default.yaml
-
In the file, change the control plane name to the new group:
_format_version: "1.1" _konnect: control_plane_name: staging
-
Using the state file you just edited, preview the import with the
deck gateway diff
command, pointing to the control plane that you want to target:deck gateway diff default.yaml \ --konnect-control-plane-name staging
-
If everything looks good,
deck gateway sync
the configuration to the new control plane:deck gateway sync default.yaml \ --konnect-control-plane-name staging
You should now have two control planes in Konnect with the same configuration.