Skip to content
Kong Summit 2022: Where API Innovation Runs Wild  —Learn More →
Kong Logo | Kong Docs Logo
search
  • We're Hiring!
  • Docs
    • Kong Gateway
    • Konnect Cloud
    • Kong Mesh
    • Plugin Hub
    • decK
    • Kubernetes Ingress Controller
    • Insomnia
    • Kuma

    • Kong Konnect Platform

    • Docs contribution guidelines
  • Plugin Hub
  • Support
  • Community
  • Kong Academy
Request Demo
  • Kong Gateway
  • Konnect Cloud
  • Kong Mesh
  • Plugin Hub
  • decK
  • Kubernetes Ingress Controller
  • Insomnia
  • Kuma

  • Kong Konnect Platform

  • Docs contribution guidelines
    • Overview of Konnect
    • Architecture
    • Network Resiliency and Availability
    • Port and Network Requirements
    • Compatibility
    • Release Notes
    • 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 Cloud
    • Overview
      • Konnect Services
      • Service Versions
      • Service Implementations
      • Manage Service Documentation
      • Overview
      • Configure a Plugin on a Service
      • Configure a Plugin on a Route
    • Overview
      • Overview
      • Manage Runtime Groups with UI
      • Manage Runtime Groups with decK
      • Install with Docker
      • Install on Kubernetes
      • Install on Linux
      • Upgrade a Runtime Instance to a New Version
      • Renew Certificates
      • Runtime Parameter Reference
      • Overview
      • Runtime Configuration
    • Troubleshoot
    • 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
      • Application Overview
      • Enable and Disable App Registration
      • Create, Edit, and Delete an Application
      • Register an Application with a Service
      • Generate Credentials for an Application
    • Customize Dev Portal
    • Troubleshoot
    • Introduction to Vitals
    • Overview Dashboard
    • Analyze Services and Routes
    • Generate Reports
      • Manage a Konnect Account or Plan
      • Change to a Different Plan
      • Manage Payment Methods and Invoices
      • Overview
        • Overview
        • Manage Teams and Roles
        • Teams Reference
        • Roles Reference
      • Manage Users
      • Set up SSO with Okta
    • Account and Org Deactivation
    • Troubleshoot
    • Overview of Konnect
      • Access a Konnect Account
        • Manage a Konnect Account or Plan
        • Change to a Different Plan
        • Manage Payment Methods and Invoices
        • Manage Users and Roles
        • Set up SSO with Okta
      • Account and Org Deactivation
      • License Management
      • Port and Network Requirements
      • Network Resiliency and Availability
      • Migrate from Kong Gateway to Konnect Cloud
        • Set up a Runtime
        • Configure a Service
        • Implement and Test the Service
      • Manage Konnect Cloud with decK
      • Manage Services
        • Manage Service Documentation
        • Publish a Service to Dev Portal
        • Docker
        • Kubernetes
        • Linux
        • Runtime Parameter Reference
      • Upgrade a Runtime to a New Version
      • Renew Certificates
        • Developer Registration
        • Manage Developer Access
        • Auto Approve Dev and App Registrations
        • Application Overview
        • Create, Edit, and Delete an Application
        • Enable App Registration
        • Disable App Registration
        • Manage Application Registration Requests
        • Manage Application Connections
        • Register an Application with a Service
        • Generate Credentials for an Application
        • Appearance
        • Public Portal
        • Add a Custom Domain
      • Generating Vitals Reports
      • Configure a Plugin on a Service
      • Configure a Plugin on a Route
      • Configure Global or Consumer Plugins
    • Shared Config
      • Proxy Traffic

github-edit-pageEdit this page

report-issueReport an issue

enterprise-switcher-iconSwitch to OSS

On this page
  • Prerequisites
  • Test your connection
  • Create a configuration file
  • Make changes to configuration
  • Manage consumers and global plugins
  • Test the service
  • See also
Konnect Cloud
  • Home
  • Konnect Cloud
  • Legacy
  • Getting started

(Legacy) Manage Konnect Cloud with decK

This documentation is for the legacy Konnect environment at konnect.konghq.com. For the cloud.konghq.com environment, see the current Konnect documentation.

You can manage entities in your Konnect Cloud 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 Konnect Cloud, decK can manage:

  • All parts of a service: Service versions, implementations, routes, and plugins.
  • Dev Portal documents: Specs and markdown files.
  • Consumers, upstreams, and global plugins.

To do this, you need decK v1.7.0 or later.

You cannot use decK to publish content to the Dev Portal, manage application registration, or configure custom plugins.

Prerequisites

  • Organization Admin permissions.
  • decK v1.7.0 or later installed.
  • Optional: To test your configuration, set up a simple runtime.

Test your connection

Check that you can log in to Konnect and that decK recognizes your account credentials:

deck konnect ping --konnect-email <email> --konnect-password <password>

If the connection is successful, the terminal displays the first and last name associated with the account:

Successfully Konnected as Some Name (Kong)!

You can also use decK with Konnect more securely by storing your password in a file, then either calling it with --konnect-password-file <pass>.txt, or adding it to your decK configuration under the konnect-password option.

The following steps all use --konnect-password-file.

Create a configuration file

Capture a snapshot of the current configuration in a file:

deck konnect dump --konnect-email <email> --konnect-password-file <pass>.txt

The command creates a file named konnect.yaml. If you have nothing configured, decK creates the file with only the format version:

_format_version: "0.1"

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

deck konnect dump --konnect-email <email> --konnect-password-file <pass>.txt \
--format json \
--output-file examples/konnect2.yaml

Make changes to configuration

Make any changes you like using YAML or JSON format. For this example, let’s add a new service.

  1. Generate a UUID. You can do this in any way you want; a common tool is the uuidgen utility.

  2. Add the following snippet to your konnect.yaml file, replacing the id in the example with your generated UUID:

     _format_version: "0.1"
     service_packages:
     - name: MyService
       versions:
       - implementation:
           type: kong-gateway
           kong:
             service:
               host: mockbin.org
               port: 80
               protocol: http
               id: {YOUR_GENERATED_UUID}
               routes:
               - methods:
                 - GET
                 - POST
                 name: mockpath
                 paths:
                 - /mock
                 plugins:
                 - name: key-auth
                   config:
                     key_names:
                     - apikey
         version: "1"
    

    This snippet defines a service named MyService pointing to mockbin.org. The service has one version, and the version gets implemented with the route /mockpath, 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.

  3. Compare your local file with the configuration currently in Konnect Cloud:

     deck konnect diff --konnect-email <email> --konnect-password-file <pass>.txt
    

    If the format and schema is correct, decK gives you a preview of what would be added to the Konnect Cloud configuration:

     creating service 9595B5F9-3B6A-4C48-BE93-9EC1B0EA487A
     creating route mockpath
     creating service-package MyService
     creating service-version 1
     Summary:
       Created: 4
       Updated: 0
       Deleted: 0
    
  4. If you’re satisfied with the preview, sync the changes to Konnect Cloud:

     deck konnect sync --konnect-email <email> --konnect-password-file <pass>.txt
    

    You should see the same output again:

     creating service 9595B5F9-3B6A-4C48-BE93-9EC1B0EA487A
     creating route mockpath
     creating service-package MyService
     creating service-version 1
     Summary:
       Created: 4
       Updated: 0
       Deleted: 0
    
  5. Check Konnect Cloud to make sure the sync worked. You should see a new service named MyService in the ServiceHub.

    ServiceHub tiles

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 cluster, 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 konnect diff --konnect-email <email> --konnect-password-file <pass>.txt
    
  4. If everything looks good, run another sync, then check Konnect Cloud to see your changes:

     deck konnect sync --konnect-email <email> --konnect-password-file <pass>.txt
    

    You can find consumers and global plugins under the icon Shared Config menu option.

    Shared Config overview page

    Note: If you add consumers to the konnect.yaml file and sync your local file to Konnect, it picks up consumers automatically. However, if you want to pull consumer configuration down from Konnect, use the --include-consumers flag in your command.

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.

Enter the proxy URL into your browser’s address bar and append the route path /mock with an apikey query:

http://localhost:8000/mock?apikey=apikey

If successful, you should see the homepage for mockbin.org. On your Service Version overview page, you’ll see a record for status code 200. This might take a few moments.

If you try to access the route without a key, you’ll get an authorization error:

Kong Error
No API key found in request.

See also

  • decK CLI reference: decK commands for 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. 2022