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’s model is more advanced and uses Control Planes which are managed, virtual, and lightweight components used to isolate configuration.

When migrating to Konnect, you will create a Control Plane design that best fits your goals, which may or may not mirror the number of Workspaces you use in your self-managed deployment. Here’s an example Workspace to Control Plane mapping strategy:

• Single Workspace: Create a matching Control Plane with the same name as your Workspace. Alternatively, you can re-organize your single Workspace configuration into multiple Control Planes if there is a clear separation of concerns in your gateway configuration.
• Multiple Workspaces: The most straightforward approach is to create a Control Plane for each Workspace, but you may choose to reorganize your design during the migration.

Example Workspace migration

The following provides an example set of steps for migrating a small multi-Workspace setup to Konnect. Instructions on this page are not step-by-step guides. They are meant to illustrate the general steps you can perform to migrate Workspaces. The examples use decK and some well-known command line tools for querying APIs and manipulating text output. See the jq and yq tool pages for more information.

1. Query the Admin API of your self-managed installation to get a list of Workspaces for a particular Kong Gateway deployment by using the /workspace endpoint: You will receive a response with a name for each Workspace in the name field.

   Note: Kong Gateway provides a default Workspace, and similarly Konnect provides a default Control Plane. Neither of these can be deleted, so migrating the default Workspace to the default Control Plane is a logical choice.

2. Create a new Control Plane for each non-default Workspace using the Konnect Control Plane API /control-planes endpoint. To use the Konnect APIs, you must create a new personal access token by opening the Konnect PAT page and selecting Generate Token.

3. Log in into the Konnect UI and validate the new Control Planes.

Kong Gateway Workspaces provide a way to share runtime infrastructure across isolated configurations. With Konnect, this is achieved using Control Plane groups. Control Planes can be added to and removed from Control Plane groups, and you can set them up to mirror your existing multi-tenant Workspace configuration.

With Control Plane groups set up, you can connect Data Plane instances to each group, creating a shared Data Plane infrastructure among the constituent Control Planes.

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 in Gateway Manager 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 currently 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, modifying the configuration slightly to remove any Workspace-specific metadata, and then synchronizing the configuration to your desired Control Plane in Konnect.

For example, if you have three Workspaces (default, inventory, and sales), use decK to dump the configuration of each Workspace to a local file:

deck gateway dump --workspace default --output-file default.yaml
deck gateway dump --workspace inventory --output-file inventory.yaml
deck gateway dump --workspace sales --output-file sales.yaml

When using deck to dump the configuration, the output file will include the Workspace name in the configuration.

Synchronize the configuration to the Control Planes using decK configured with the proper Control Plane name and the Konnect access token:

deck gateway sync --konnect-token "$KONNECT_PAT" --konnect-control-plane-name default default.yaml
deck gateway sync --konnect-token "$KONNECT_PAT" --konnect-control-plane-name inventory inventory.yaml
deck gateway sync --konnect-token "$KONNECT_PAT" --konnect-control-plane-name sales sales.yaml

In this example, replace $KONNECT_PAT with your Konnect PAT or specify your PAT as an environment variable.

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 Gateway Manager, 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.