(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 thekonnect-password
option. See thedeck 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 adocument
section in theservice_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 Serviceversion
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.