Skip to content
2023 API Summit Hackathon: Experiment with AI for APIs (August 28 - September 27) Learn More →
Kong Logo | Kong Docs Logo
search
  • We're Hiring!
  • Docs
    • Kong Gateway
      Lightweight, fast, and flexible cloud-native API gateway
      Kong Konnect
      Single platform for SaaS end-to-end connectivity
      Kong Mesh
      Enterprise service mesh based on Kuma and Envoy
      decK
      Helps manage Kong’s configuration in a declarative fashion
      Kong Ingress Controller
      Works inside a Kubernetes cluster and configures Kong to proxy traffic
      Insomnia
      Collaborative API development platform
      Kuma
      Open-source distributed control plane with a bundled Envoy Proxy integration
      Docs Contribution Guidelines
      Want to help out, or found an issue in the docs and want to let us know?
  • API Specs
  • Plugin Hub
    • Explore the Plugin Hub
      View all plugins View all plugins View all plugins arrow image
    • Functionality View all View all arrow image
      View all plugins
      Authentication's icon
      Authentication
      Protect your services with an authentication layer
      Security's icon
      Security
      Protect your services with additional security layer
      Traffic Control's icon
      Traffic Control
      Manage, throttle and restrict inbound and outbound API traffic
      Serverless's icon
      Serverless
      Invoke serverless functions in combination with other plugins
      Analytics & Monitoring's icon
      Analytics & Monitoring
      Visualize, inspect and monitor APIs and microservices traffic
      Transformations's icon
      Transformations
      Transform request and responses on the fly on Kong
      Logging's icon
      Logging
      Log request and response data using the best transport for your infrastructure
  • Support
  • Community
  • Kong Academy
Get a Demo Start Free Trial
decK
1.12.x
  • Home icon
  • decK
  • Guides
  • Konnect
  • Using decK with Kong Konnect
github-edit-pageEdit this page
report-issueReport an issue
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Plugin Hub
  • decK
  • Kong Ingress Controller
  • Insomnia
  • Kuma

  • Docs contribution guidelines
  • 1.27.x (latest)
  • 1.26.x
  • 1.25.x
  • 1.24.x
  • 1.23.x
  • 1.22.x
  • 1.21.x
  • 1.20.x
  • 1.19.x
  • 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
enterprise-switcher-icon Switch to OSS
On this pageOn this page
  • Konnect flags
  • Authenticate with Konnect
    • Authenticate using a plaintext password
    • Authenticate using a password file
    • Authenticate using a decK config file
  • Target a Konnect API
  • Control planes
  • Troubleshoot
    • Authentication with a Konnect password file is not working
    • Workspace connection refused
    • ACL, Key Auth, or OpenID Connect plugins and app registration
  • See also
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 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-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.

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. Password set with the --konnect-password flag
  2. decK configuration file, if one exists (default lookup path: $HOME/.deck.yaml)
  3. File passed with the --konnect-password-file flag

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!

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.

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 password file is not working

If you have verified that your password 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 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 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 or deck diff.
  • 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.

See also

  • Import Kong Gateway entities into Konnect
  • Manage control planes with decK
Thank you for your feedback.
Was this page useful?
Too much on your plate? close cta icon
More features, less infrastructure with Kong Konnect. 1M requests per month for free.
Try it for Free
  • 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