Skip to content
Kong Logo | Kong Docs Logo
search
  • We're Hiring!
  • Docs
    • Kong Gateway
    • Kong Konnect
    • Kong Mesh
    • Plugin Hub
    • decK
    • Kubernetes Ingress Controller
    • Insomnia
    • Kuma

    • Docs contribution guidelines
  • Plugin Hub
  • Support
  • Community
  • Kong Academy
Get a Demo Start Free Trial
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Plugin Hub
  • decK
  • Kubernetes Ingress Controller
  • Insomnia
  • Kuma

  • Docs contribution guidelines
  • 1.19.x (latest)
  • 1.18.x
  • 1.17.x
  • 1.16.x
  • 1.15.x
  • 1.14.x
  • 1.13.x
  • 1.12.x
  • 1.11.x
  • 1.10.x
  • 1.9.x
  • 1.8.x
  • 1.7.x
  • pre-1.7
    • Terminology
    • Architecture
    • Compatibility Promise
    • Getting Started with decK
    • Backup and Restore
    • Upgrade to Kong Gateway 3.x
    • Configuration as Code and GitOps
    • Distributed Configuration
    • Best Practices
    • Using decK with Kong Gateway (Enterprise)
    • Using decK with Konnect
    • Run decK with Docker
    • Using Multiple Files to Store Configuration
    • De-duplicate Plugin Configuration
    • Set Up Object Defaults
      • Overview
      • Secret Management with decK
      • Using Environment Variables with decK
    • Entities Managed by decK
      • deck completion
      • deck convert
      • deck diff
      • deck dump
      • deck ping
      • deck reset
      • deck sync
      • deck validate
      • deck version

github-edit-pageEdit this page

report-issueReport an issue

enterprise-switcher-iconSwitch to OSS

On this page
  • Konnect flags
  • Authenticate with Konnect
    • Authenticate using a plaintext password
    • Authenticate using a password file
    • Authenticate using a decK config file
    • Authenticate using a personal access token
  • Target a Konnect API
  • Runtime groups
  • Konnect service tags
  • Troubleshoot
    • Authentication with a Konnect password or token file is not working
    • Workspace connection refused
    • ACL, Key Auth, or OpenID Connect plugins and app registration
    • decK targets Kong Gateway instead of Konnect
  • See also
decK
1.16.x
  • Home
  • decK
  • Guides
  • Konnect
  • Using decK with Kong Konnect
You are browsing documentation for an outdated version. See the latest documentation here.

Using decK with Kong Konnect

You can manage Kong Gateway core entity configuration in your Konnect organization using decK.

decK can only target one runtime group at a time. Managing multiple runtime groups requires a separate state file per group.

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-email
Email address associated with your Konnect account.
--konnect-password
Password associated with your Konnect account. This takes precedence over the --konnect-password-file flag.
--konnect-password-file
File containing the password to your Konnect account.
--konnect-runtime-group-name
Konnect runtime group name.
--konnect-token
Personal access token associated with your Konnect account, this takes precedence over the --konnect-token-file flag.
--konnect-token-file
File containing the personal access token to your Konnect 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:

  1. Credentials set with a flag, either --konnect-password or --konnect-token
  2. decK configuration file, if one exists (default lookup path: $HOME/.deck.yaml)
  3. Credential file passed with a flag, either --konnect-password-file or --konnect-token-file

For example, if you have both a decK config file and a Konnect password file, decK uses the password in the config file.

Authenticate using a plaintext password

You can use the --konnect-password flag to provide the password directly in the command:

deck ping \
  --konnect-email example@example.com \
  --konnect-password YOUR_PASSWORD

Authenticate using a password file

You can save your Konnect password to a file, then pass the filename to decK with --konnect-password-file:

deck ping \
  --konnect-email example@example.com \
  --konnect-password-file /PATH/TO/FILE

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 Konnect credentials in the file, decK uses the credentials for every command. Set either konnect-password or konnect-password-file in the decK config file.

  • Use konnect-password to store Konnect credentials directly in the configuration file:

      konnect-email: example@email.com
      konnect-password: YOUR_PASSWORD
    
  • Store your password in a separate file, then specify the path to konnect-password-file instead of a literal password:

      konnect-email: example@example.com
      konnect-password-file: PATH/TO/FILENAME
    

decK automatically uses the credentials from $HOME/.deck.yaml in any subsequent calls:

deck ping

Successfully Konnected to the Example-Name organization!

Authenticate using a personal access token

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.

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.

To generate a PAT for a user account in Konnect, select your name to open the context menu and click Personal access tokens, then click Generate token.

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 PAT 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 US and EU geographic regions. To target the EU region, set konnect-addr to "https://eu.api.konghq.com".

Runtime groups

Each state file targets one runtime group. If you don’t provide a group, decK targets the default runtime group.

If you have a custom runtime group, you can specify the group in the state file, or use a flag when running any decK command.

  • Target a runtime group in your state file with the konnect_runtime_group parameter:

      _format_version: "3.0"
      _konnect:
        runtime_group_name: staging
    
  • Set a group using the --konnect-runtime-group-name flag:

      deck sync --konnect-runtime-group-name staging
    

Konnect service tags

In Konnect, there are two types of services:

  • Gateway services: Managed through Runtime Manager
  • Konnect services: Managed through Service Hub

Each Konnect service may contain one or more service versions. A service version represents an implementation of a Gateway service.

decK manages Gateway services, which contain configurations for the Gateway proxy.

Although decK doesn’t directly manage Konnect services or service versions, you can use tags to associate a Gateway service to a service version in a Konnect service:

services:
- name: SERVICE_NAME
  tags:
  - _KonnectService:KONNECT_SERVICE_NAME

Where:

  • KONNECT_SERVICE_NAME: Identifies which Konnect service to associate the Gateway service to.
  • SERVICE_NAME: The name of the Gateway service. Identifies which Konnect service version to associate the Gateway service to.

If the Konnect service doesn’t exist, setting a _Konnect tag creates a Konnect service.

For example, see the following configuration snippet, where the Gateway service named example_service is attached to the Konnect service example:

_format_version: "3.0"
_konnect:
  runtime_group_name: default
services:
- name: example_service
  host: mockbin.org
  tags:
  - _KonnectService:example

If the Konnect service doesn’t exist, this configuration snippet creates a Konnect service named example with a version named example_service in the Service Hub.

Troubleshoot

Authentication with a Konnect password or token file is not working

If you have verified that your password or 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 password or token file. A decK config file is likely conflicting with the password or 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 runtime group, or add a key to apply the configuration to a specific runtime group.

To apply the configuration to custom runtime groups, replace _workspace with runtime_group_name: GroupName.

For example, to export the configuration from workspace staging to runtime group 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 Service Hub UI, but don’t appear in the output from a deck dump or deck diff.
  • When trying to set up one of the plugins on a Konnect service version 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 the service version. They are managed entirely by Konnect, so you can’t manage these plugins directly.

Manage application registration through the Service Hub to avoid any issues.

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 Konnect credentials are 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.

See also

  • Import Kong Gateway entities into Konnect
  • Manage runtime groups with decK
Thank you for your feedback.
Was this page useful?
  • Kong
    THE CLOUD CONNECTIVITY COMPANY

    Kong powers reliable digital connections across APIs, hybrid and multi-cloud environments.

    • Company
    • Customers
    • Events
    • Investors
    • Careers Hiring!
    • Partners
    • Press
    • Contact
  • Products
    • Kong Konnect
    • Kong Gateway
    • Kong Mesh
    • Get Started
    • Pricing
  • Resources
    • eBooks
    • Webinars
    • Briefs
    • Blog
    • API Gateway
    • Microservices
  • Open Source
    • Install Kong Gateway
    • Kong Community
    • Kubernetes Ingress
    • Kuma
    • Insomnia
  • Solutions
    • Decentralize
    • Secure & Govern
    • Create a Dev Platform
    • API Gateway
    • Kubernetes
    • Service Mesh
Star
  • Terms•Privacy
© Kong Inc. 2023