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
      • Azure OIDC
      • 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
  • Migrate object configuration
    • Export and convert Kong Gateway object configuration
    • Import the configuration into Konnect Cloud
  • Upload Dev Portal content
    • Migrate specs and documents using the GUI
    • Migrate specs and documents using decK
  • Migrate data planes
  • Post-migration tasks
Konnect Cloud
  • Home
  • Konnect Cloud
  • Legacy

(Legacy) Migrate from Kong Gateway to Konnect Cloud

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 migrate any edition of self-managed Kong Gateway to Konnect Cloud.

Use decK to convert and migrate the configuration for most Kong Gateway objects, as well as Dev Portal specs and documents.

Afterward, you must manually migrate:

  • Dev Portal developer accounts and applications
  • RBAC roles and permissions
  • Certificates
  • Custom plugins

You cannot migrate unsupported plugins.

Prerequisites

  • Konnect Cloud account credentials.
  • Organization Admin permissions.
  • decK v1.7.0 or later installed.

Migrate object configuration

Migrate object configurations with decK.

Export and convert Kong Gateway object configuration

  1. Export configuration from Kong Gateway with deck dump:

     deck dump --output-file kong.yaml
    

    This command outputs Kong Gateway’s object configuration into the specified file.

  2. Convert the file into Konnect Cloud format with deck convert:

     deck convert \
       --from kong-gateway \
       --to konnect \
       --input-file kong.yaml \
       --output-file konnect.yaml
    

    This command uses the configuration you exported from Kong Gateway and transforms it into Konnect Cloud configuration.

  3. Carefully look over the exported file. Note that not all elements may be exported, such as certificates and incompatible plugins. decK does not print a warning if this occurs.

Import the configuration into Konnect Cloud

  1. Preview the import with the deck konnect diff command:

     deck konnect diff \
       --konnect-email {YOUR_EMAIL} \
       --konnect-password {YOUR_PASSWORD} \
       --state konnect.yaml
    

    Note: You can also use decK with Konnect Cloud 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. See the deck konnect reference for more information about the flag.

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

     deck konnect sync \
       --konnect-email {YOUR_EMAIL} \
       --konnect-password {YOUR_PASSWORD} \
       --state konnect.yaml
    
  3. Log in to your Konnect Cloud account.

  4. From the left navigation menu, select Services to open ServiceHub.

  5. Look through your Service catalog to check that all of your Services and related entities were migrated successfully.

  6. From the left navigation menu, select Shared Config, and check that your Consumers were migrated.

Upload Dev Portal content

You can migrate specs and markdown documents using decK or the Konnect Cloud GUI.

Migrate specs and documents using the GUI

If you prefer to use the GUI, see Dev Portal Service Documentation.

Migrate specs and documents using decK

If you have any Dev Portal documents you want to associate with your services, you can do so in the konnect.yaml configuration file.

Each Service can have one markdown description file associated with it, and each Service version can have one spec in YAML or JSON format.

  1. In the konnect.yaml file, create a document section in the service_package you want to edit and include a path to the document:

     service_packages:
     - name: MyService
       document:
         path: {PATH_TO_FILE}/description.md
         published: true
    

    You must set published: true, otherwise the file will not be uploaded to Konnect Cloud. This parameter does not control whether the Service itself is published to the Dev Portal.

    The same principle applies to Service version specs.

  2. To upload a spec, create a document section in the Service version and include a path to the spec:

     service_packages:
     - name: MyService
       document:
         path: {PATH_TO_FILE}/description.md
         published: true
       versions:
       - version: "1"
         document:
           path: {PATH_TO_FILE}/vitalsSpec.yaml
           published: true
    

Migrate data planes

You can keep any data plane nodes that are:

  • Running Kong Gateway (not the open-source package)
  • Are at least version 2.3 or higher

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

  1. Follow the runtime setup guide for your preferred deployment type.

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

  3. If any of the old nodes have connected PostgreSQL or Cassandra 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 applications and developers: If you have developers or applications registered through the Portal, those developers need to create new accounts in Konnect Cloud and register their applications in the new location.
    • Developer registration
    • Enable application registration: App registration in Konnect Cloud 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 Konnect Cloud org (Plus or Enterprise tier). Publish your services to the Dev Portal.
  • Prepare custom plugins for migration: Custom plugins are supported in Konnect Cloud, 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 roles and permissions: Konnect Cloud roles and permissions don’t map directly to Kong Gateway RBAC. You also can’t create custom roles, or adjust permissions on the existing roles. Instead, invite users to your org and assign one of the available roles to them on invite.
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