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
    • Overview of Konnect
    • Architecture
    • Network Resiliency and Availability
    • Port and Network Requirements
    • Compatibility
    • Stages of Software Availability
    • Release Notes
      • Control Plane Upgrades FAQ
      • Supported Installation Options
    • Overview
    • Access a Konnect Account
    • Set up a Runtime
    • Configure a Service
    • Implement and Test the Service
      • Publish and Consume Services
      • Register Applications
    • Import Kong Gateway Entities into Konnect
    • Overview
      • Overview
      • Dashboard
      • Manage Runtime Groups with UI
      • Manage Runtime Groups with decK
      • Installation Options
      • Install with Docker
      • Install on Kubernetes
      • Install on Linux
      • Install on AWS
      • Install on Azure
      • Upgrade a Runtime Instance to a New Version
      • Renew Certificates
      • Runtime Parameter Reference
    • Create Consumer Groups
      • Overview
      • Set Up and Use a Vault in Konnect
    • Kong Gateway Configuration in Konnect
    • Plugin Ordering Reference
    • Troubleshoot
    • Overview
    • Manage Service Documentation
      • Overview
      • Configure a Plugin on a Service
      • Configure a Plugin on a Route
    • Overview
    • Access the Dev Portal
    • Sign Up for a Dev Portal Account
      • Manage Developer Access
      • Manage Application Registration Requests
      • Manage Application Connections
      • Auto Approve Dev and App Registrations
      • Azure OIDC
      • Application Overview
      • Enable and Disable App Registration
        • Overview
        • Okta
        • Curity
        • Auth0
      • Create, Edit, and Delete an Application
      • Register an Application with a Service
      • Generate Credentials for an Application
    • Customize Dev Portal
    • Troubleshoot
    • Introduction to Analytics
    • Summary Dashboard
    • Analyze Services and Routes
    • Generate Reports
    • Troubleshoot
      • Manage a Konnect Account or Plan
      • Change to a Different Plan
      • Manage Payment Methods and Invoices
      • Overview
        • Overview
        • Manage Teams
        • Teams Reference
        • Roles Reference
      • Manage Users
      • Manage System Accounts
      • Set up SSO with OIDC
      • Set up SSO with Okta
      • Login Sessions Reference
    • Account and Org Deactivation
    • Troubleshoot
    • Overview
      • API Documentation
      • Identity Integration Guide
      • API Documentation
      • API Documentation
      • Portal RBAC Guide
      • Overview
      • Nodes
      • Data Plane Certificiates
        • Services
        • Routes
        • Consumers
        • Plugins
        • Upstreams
        • Certificates
        • CA Certificates
        • SNIs
        • Targets
        • Vaults
      • API Spec
      • Filtering
    • Labels

github-edit-pageEdit this page

report-issueReport an issue

enterprise-switcher-iconSwitch to OSS

On this page
  • Prerequisites
  • Generate a Personal Access Token
  • Test your connection
  • Create a configuration file
  • Make changes to configuration
  • Manage consumers and global plugins
  • Test the service
  • Migrate configuration between runtime groups
  • See also
Kong Konnect
  • Home
  • Kong Konnect
  • Runtime Manager
  • Runtime Groups
  • Manage Runtime Groups with decK

Manage Runtime Groups with decK

You can manage runtime groups 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 runtime groups and all of their configurations:

  • Create state files for different runtime groups and manage each group separately.
  • Manage Gateway services, routes, consumers, plugins, and upstreams for each group.
  • Migrate configuration from one group to another.

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 runtime.

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.
User Account Token
System Account Token

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.

Create a system account token through the Konnect API.

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 ping \
  --konnect-runtime-group-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 dump --konnect-runtime-group-name default

If you don’t specify the --konnect-runtime-group-name flag, decK will target the default runtime group. If you have more than one runtime group in your organization, we recommend always setting this flag to avoid accidentally pushing configuration to the wrong group.

The command creates a file named kong.yaml. If you have nothing configured, decK creates the file with only the format version and runtime group name:

_format_version: "1.1"
_konnect:
  runtime_group_name: default

You can specify a different filename or location, or export the configuration in JSON format:

deck dump --konnect-runtime-group-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.

  1. Add the following snippet to your kong.yaml file:

     _format_version: "1.1"
     _konnect:
       runtime_group_name: default
     services:
     - name: MyService
       host: mockbin.org
       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 to mockbin.org. 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.

  2. Compare your local file with the configuration currently in Kong Konnect:

     deck diff --konnect-runtime-group-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
    
  3. If you’re satisfied with the preview, sync the changes to Kong Konnect:

     deck sync --konnect-runtime-group-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
    
  4. Check Kong Konnect to make sure the sync worked. Open Runtime Manager, select your runtime group, and select Gateway Services.

    You should see a new service named MyService in the runtime group.

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 runtime group, as applicable. For example, you can configure proxy caching on all your services at once with one proxy-cache plugin entry.

  1. 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
    
  2. 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
    
  3. Run a diff to test your changes:

     deck diff --konnect-runtime-group-name default
    
  4. If everything looks good, run another sync, then check Kong Konnect to see your changes:

     deck sync --konnect-runtime-group-name default
    

Test the service

If you have already have a runtime set up, you can test this configuration now. Or, you can start a simple runtime 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 mockbin.org. 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 runtime groups

You can also use decK to migrate or duplicate configuration between runtime groups.

  1. Export configuration from the original runtime group with deck dump into a state file:

     deck dump \
       --konnect-runtime-group-name default \
       --output-file default.yaml
    
  2. In the file, change the runtime group name to the new group:

     _format_version: "1.1"
     _konnect:
       runtime_group_name: staging
    
  3. Using the state file you just edited, preview the import with the deck diff command, pointing to the runtime group that you want to target:

     deck diff \
       --konnect-runtime-group-name staging \
       --state default.yaml
    
  4. If everything looks good, deck sync the configuration to the new runtime group:

     deck sync \
       --konnect-runtime-group-name staging \
       --state default.yaml
    

You should now have two runtime groups in Konnect with the same configuration.

See also

  • decK CLI reference
  • Import Kong Gateway configuration into Konnect
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