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.

Kong Gateway deployments come in a wide variety of environments and topologies. Konnect runs in a topology very similar to hybrid mode, so migration from a self-managed Gateway hybrid deployment is the most straightforward. For this reason, this guide focuses on migrating a hybrid or traditional deployment to Konnect.

Why migrate to Konnect?

As organizations grow and scale, they gain the need for more advanced capabilities while lowering operational complexity. This includes features such as strong multi-tenancy, federated API management, advanced security integrations, and others. With Konnect, you gain access to a full featured API management platform which provides managed components and builds on the lessons learned from deep customer usage of Kong Gateway and API management best practices.

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:

Dev Portal files, developer accounts, and applications
Application registrations
Convert RBAC roles and permissions into Konnect teams
Certificates
Custom plugins

Migration guide

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 deployment to Konnect.

 
flowchart TD
A{Which deployment 
topology are you 
starting with?}
B(Traditional)
C(Hybrid)
D(KIC)
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 KIC deployment to a
KIC-based control plane]

Figure 1: For traditional and hybrid deployments, you can migrate directly to Konnect by following this guide. For DB-less deployments, migrate to hybrid first, then follow this guide. For KIC deployments, migrate to a KIC-based control plane.

Role Based Access Controls (RBAC)

Both Kong Gateway and Kong Konnect provide frameworks for controlling security and data access.

Kong Gateway provides a traditional Role Based Access Control (RBAC) system to manage administrators and users of the API gateway system. Kong Konnect provides a robust multi-layer Identity and Access Management (IAM) system including organizations, teams, and roles. Kong Konnect also provides integrations with IdP providers via OIDC, allowing you to map centrally managed teams to Kong Konnect-based roles.

Kong Gateway’s RBAC system does not map directly to the IAM system provided by Kong 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 Kong Konnect for your migration:

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.
Set up single sign-on (SSO) access to Konnect using an existing IdP provider
Create teams in Konnect or use predefined teams to create your desired organizational structure.
For any custom teams, assign the appropriate roles from the predefined list of available roles in Konnect.
Use the Konnect IdP Team Mappings feature to map the Konnect teams to your IdP provider groups.

Migrating from workspaces to control planes

Kong Gateway supports configuration isolation using workspaces. Kong Konnect’s model is more advanced and uses control planes which are managed, virtual, and lightweight components used to isolate configuration.

When migrating to Kong 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.

Control plane design

If you currently use a single workspace in your self-managed installation, you can simply create a matching control plane with the same name. Alternatively, you can choose to take the opportunity to re-organize your single workspace configuration into multiple control planes if there is a clear separation of concerns in your gateway configuration.

If you’re using multiple workspaces in your self-managed installation, the most straightforward approach is to create a control plane for each workspace, but you may choose to reorganize your design during the migration.

Multi-tenancy

Kong Gateway workspaces provide a way to share runtime infrastructure across isolated configurations. With Kong 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.

Control plane management

You can manage control planes and control plane groups in Kong Konnect by using the Konnect UI, the Konnect Control Planes API, or the Kong Konnect Terraform Provider.

Example workspace migration

The following provides an example set of steps for migrating a small multi-workspace setup to Kong Konnect.

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

Query the Admin API of your self-managed installation to get a list of workspaces for a particular Kong Gateway deployment:

curl -s localhost:8001/workspaces | jq -r '.data.[].name'

You will receive a response with a name for each workspace:

default
inventory
sales

In this example, the self-managed installation has three total workspaces: the default workspace, inventory, and sales.

Note: Kong Gateway provides a default workspace, and similarly Kong 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.

Create a new control plane for each non-default workspace:

curl -s -H "Authorization: Bearer ${KONNECT_PAT}" \
  --request POST \
  --url https://us.api.konghq.com/v2/control-planes \
  --header 'Content-Type: application/json' \
  --header 'accept: application/json' \
  --data '{"name":"inventory","description":"CP for the Inventory team.","cluster_type":"CLUSTER_TYPE_CONTROL_PLANE"}'

curl -s -H "Authorization: Bearer ${KONNECT_PAT}" \
  --request POST \
  --url https://us.api.konghq.com/v2/control-planes \
  --header 'Content-Type: application/json' \
  --header 'accept: application/json' \
  --data '{"name":"sales","description":"CP for the Sales team.","cluster_type":"CLUSTER_TYPE_CONTROL_PLANE"}'

Plugin migration

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.

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

Custom plugins

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 currently require a manual deployment process involving Kong Gateway’s support team. Contact your Kong representative for more information.

Kong Gateway configuration

We recommend migrating Kong Gateway configuration to Kong 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.

Continuing the example from earlier, 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. To remove the _workspace key from the configuration, you can use the yq tool:

yq -i 'del(._workspace)' default.yaml
yq -i 'del(._workspace)' inventory.yaml
yq -i 'del(._workspace)' sales.yaml 

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

Data planes

The recommended approach for migrating your data plane instances to Kong 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.

The Kong Konnect documentation provides details on Kong Gateway installation options. 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.

APIOps

In Konnect, there are additional options for managing the API deployment lifecycle, as compared to Kong Gateway.

decK: If you’re using deck to manage your Kong Gateway configuration, you can continue to use the tool to managing your Kong Konnect configuration. The decK CLI supports Konnect control plane configuration by providing additional flags that configure the tool to connect to a particular control plane using access tokens.
Terraform: Kong provides a Terraform provider for managing a full Konnect deployment, including control planes, control plane groups, data plane configuration, and more. The Konnect Terraform Provider can be used independently or in conjunction with decK to manage your API deployment lifecycle.
Kong Gateway Operator: The Kong Gateway Operator (KGO) is available for teams that want to use standardized Kubernetes APIs to manage their Konnect deployments.