Migrating from self-managed Kong Gateway to Konnect

As a Kong Gateway user, you can directly migrate to Konnect, as Konnect uses Kong Gateway in its foundation.

As organizations grow and scale, they need more advanced capabilities while lowering operational complexity. This includes features such as:

• Multi-tenancy
• Federated API management
• Advanced security integrations

At its core, migration to Konnect is mostly a straightforward export and migration of proxy configuration. Depending on your environment, you may also need to move over:

• Convert RBAC roles and permissions into Konnect teams
• Certificates
• Custom plugins

This guide provides key details for completing a successful migration from a self-managed Kong Gateway to Konnect. It focuses on migrating a hybrid or traditional Kong Gateway deployment to Konnect.

 
flowchart TD
A{Which deployment
topology are you
starting with?}
B(Traditional)
C(Hybrid)
D(Kong Ingress Controller)
E(DB-less)

A-->B & C & D & E

B & C --> F["Migrate to Konnect
(use this guide)"]
E --> H["Migrate to hybrid mode
(reach out to support for help)"] --> F
D --> G[Link your Kong Ingress Controller deployment to a
Kong Ingress Controller-based control plane]
  

Figure 1: For traditional and hybrid deployments, you can migrate directly to Konnect. DB-less deployments must migrate to hybrid first. For Kong Ingress Controller deployments, migrate to a Kong Ingress Controller-based control plane.

Kong Gateway’s RBAC system does not map directly to the IAM system provided by Konnect. When migrating from a self-managed Kong Gateway to Konnect, we recommend using Konnect’s IdP integrations. You can take advantage of your existing IdP solution and Konnect’s team-based mappings instead of migrating your self-managed Kong Gateway RBAC configuration directly.

The following are the general steps for setting up IAM in Konnect for your migration:

1. Sign up for Konnect (if necessary), and use the Org Switcher to create or select the organization you are going to migrate your self-managed deployment to.
2. Set up single sign-on (SSO) access to Konnect using an existing IdP provider.
3. Create teams in Konnect or use predefined teams to create your desired organizational structure.
4. For any custom teams, assign the appropriate roles from the predefined list of available roles in Konnect.
5. Use the Konnect IdP Team Mappings feature to map the Konnect teams to your IdP provider groups.

Kong Gateway supports configuration isolation using Workspaces. Konnect also supports Workspaces within a control plane, so you can preserve your existing Workspace structure when migrating.

Konnect supports the majority of plugins available to Kong Gateway. Since Konnect runs in hybrid mode, this limits support for plugins that require direct access to a database. See the plugins page for those that are supported on Konnect.

Konnect also provides Dedicated Cloud Gateways, which further limit plugins that require specialized software agents running on the Data Plane hosts.

To migrate plugins from a self-managed deployment to Konnect, review Konnect Compatibility page to check for supported and unsupported plugins. Also review any plugin configuration values, as certain values are unsupported in Konnect and may require additional changes to your configuration.

Konnect supports custom plugins with similar restrictions to pre-built plugins. Since Konnect runs in a hybrid deployment mode, custom plugins can’t access a database directly and can’t provide custom Admin API endpoints. See the Konnect documentation for more details on custom plugin support requirements.

Migrating custom plugins to Konnect requires uploading and associating your custom plugin’s schema.lua file to the desired control plane. This can be done using the Konnect UI or the Konnect control planes Config API.

Just like in self-managed deployments, the custom plugin code must be distributed to the Data Plane instances.

Note: Konnect’s Dedicated Cloud Gateways can support custom plugins, but they require a manual deployment process involving Kong Gateway’s support team. Contact your Kong representative for more information.

We recommend migrating Kong Gateway configuration to Konnect using decK, the declarative management tool for Kong Gateway configurations.

The general process for migrating the configuration involves “dumping” your existing self-managed configuration to a local file, and then synchronizing the configuration to your desired control plane in Konnect. The following provides an example of migrating a multi-Workspace self-managed setup to Konnect. These steps illustrate the general approach rather than a complete step-by-step guide.

1. Query the Admin API of your self-managed installation to get a list of Workspaces using the /workspaces endpoint. The response includes a name field for each Workspace.

   The default Workspace in your self-managed deployment maps to the default Workspace in your Konnect control plane. Neither can be deleted.

2. Dump your self-managed configuration into per-Workspace files:

   deck gateway dump --all-workspaces

   Copied!

   This produces one YAML file per Workspace, each with a _workspace: header.

3. Set your decK environment variables:

   export DECK_KONNECT_TOKEN="kpat_..."
   export DECK_KONNECT_ADDR="https://us.api.konghq.com"

   Copied!

4. Sync each file to your Konnect control plane. If a Workspace doesn’t exist yet, decK creates it automatically:

   deck gateway sync default.yaml \
     --konnect-control-plane-name my-control-plane \
     --workspace default

   Copied!

   Repeat for each Workspace.

5. Log in to the Konnect UI and validate that your Workspaces and entities migrated correctly.

In addition to decK, Konnect provides other tools that could be used for migrating your configuration. Each tool requires a different process. See their documentation for more information:

• Konnect control planes Config API
• Konnect Terraform Provider

The recommended approach for migrating your Data Plane instances to Konnect is to create new Data Plane instances connected to your control plane, validate their configuration and connectivity, and then decommission the self-managed Data Plane instances.

See the Data Plane hosting options for more information. The easiest way to deploy new Data Planes is using the Konnect UI, which provides integrated launchers for popular operating systems and compute platforms.

If you are interested in assistance with migrating from a self-managed Kong Gateway to Konnect, contact a Kong field representative.