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
Kong Konnect
  • Home icon
  • Kong Konnect
  • Getting Started
  • Import Kong Gateway Entities into 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
enterprise-switcher-icon Switch to OSS
On this pageOn this page
  • Prerequisites
  • Generate a Personal Access Token
  • Import entity configuration
  • Migrate data planes
  • Post-migration tasks

Import Kong Gateway Entities into Konnect

If you are an existing Kong Gateway user looking to use Konnect as your cloud-hosted control plane, you can use decK to import your Kong Gateway entity configuration into a control plane in your Konnect organization.

You can also use this method to migrate between Konnect organizations.

Afterward, you must manually move over:

  • Dev Portal files, developer accounts, and applications
  • Application registrations
  • Convert roles and permissions into Konnect teams
  • Certificates
  • Custom plugins

You cannot import unsupported plugins.

Prerequisites

  • Kong Konnect account credentials.
  • decK v1.12 or later installed.

Generate a Personal Access Token

To use decK to import entity configurations, 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 user icon 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.

Import entity configuration

Use decK to import entity configurations into a control plane.

When you provide any Konnect flags, decK targets the cloud.konghq.com environment by default.

  1. Make sure that decK can connect to your Konnect account:

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

  2. Run deck dump to export configuration into a file:

     deck dump
    

    This command outputs Kong Gateway’s object configuration into kong.yaml by default. You can also set --output-file /path/{FILENAME}.yaml to set a custom filename or location.

  3. Open the file. If you have any of the following in your configuration, remove it:

    • Any _workspace entries: There are no workspaces in Konnect. For a similar concept, see control planes.

    • Configuration for the Portal App Registration plugin: App registration is supported in Konnect, but not through a plugin, and decK does not manage it.

    • Any other unsupported plugins:

      • OAuth2 Authentication
      • Apache OpenWhisk
      • Vault Auth
      • Key Authentication Encrypted
  4. Preview the import with the deck diff command, pointing to the control plane that you want to target:

     deck diff --konnect-control-plane-name default
    

    If you’re not using the default kong.yaml file, specify the filename and path with --state /path/{FILENAME}.yaml.

  5. If you’re satisfied with the preview, run deck sync:

     deck sync --konnect-control-plane-name default
    

    If you don’t specify the --konnect-control-plane-name flag, decK targets 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 control plane.

  6. Log in to your Kong Konnect account.

  7. From the left navigation menu, open Gateway Manager, then open the control plane you just updated.

  8. Look through the configuration details of any imported entities to make sure they were migrated successfully.

Migrate data planes

You can keep any data plane nodes that are:

  • Running Kong Gateway (Enterprise, include free mode)
  • Are at least version 2.5 or higher

Turn any self-managed nodes into cloud data plane nodes by registering them through the Gateway Manager and adjusting their configurations, or power down the old data plane nodes and deploy new nodes through Kong Konnect.

  1. Follow the data plane node setup guide for your preferred deployment type.

  2. Once you have created or converted the data plane nodes, kong stop your old Gateway data plane nodes, then shut them down.

  3. If any of the old nodes have connected database instances, you can shut them down now.

Post-migration tasks

See the following docs to set up any additional things you may need:

  • Dev Portal files: You can migrate API specs and markdown service descriptions into API Products using the Kong Konnect GUI. Each API product accepts one markdown description file, and each API product version accepts one API spec. See Dev Portal Service Documentation.

  • Dev Portal applications and developers: If you have developers or applications registered through the Portal, those developers need to create new accounts in Kong Konnect and register their applications in the new location.
    • Create Dev Portal accounts
    • Enable application registration: App registration in Kong Konnect works through a different mechanism than in self-managed Kong Gateway. Enable app registration on each service that requires it.
    • Publish services to the Dev Portal: The Dev Portal is automatically enabled on a Kong Konnect org (Plus or Enterprise tier). Publish your services to the Dev Portal.
  • Prepare custom plugins for migration: Custom plugins are supported in Kong Konnect, but with limitations. As long as your plugins fit the criteria, or if you can adjust them to do so, contact Kong Support to get the plugin manually added to your account.
  • Review and set up teams and roles: Kong Konnect groups and roles don’t map directly to Kong Gateway teams and roles. Set up teams to mirror your Kong Gateway groups, then invite users to your org and assign them to a team on invite.
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