Konnect Cloud

(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

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

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.

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

Log in to your Konnect Cloud account.
From the left navigation menu, select Services to open ServiceHub.
Look through your Service catalog to check that all of your Services and related entities were migrated successfully.
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.

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.

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.

Follow the runtime setup guide for your preferred deployment type.
Once you have created or converted the data plane nodes, kong stop your old Gateway runtimes, then shut them down.
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.