Kong Konnect is a powerful SaaS-based API lifecycle management platform that provides a fast path for people looking to get started with Kong API Gateway. For existing users of Kong’s open-source gateway, it offers a way to rapidly take advantage of a scalable, highly-available architecture while upgrading to an Enterprise-class feature set and support options. Today we will drill down the benefits of Konnect as well as provide a step-by-step example of migrating an open-source Kong gateway configuration onto Konnect.

Benefits of Konnect

Konnect was designed to provide three primary benefits to complement the existing capabilities of the Kong Gateway:

1. Simplify the operation of running Kong Gateway instances – By providing SaaS hosted Control planes through the concept of a Runtime Group. A Runtime Group is effectively a virtual Kong Gateway control plane provided as a service with 99.99% SLA. Konnect Runtime Groups can be provisioned in seconds via a single UI click or API call.
2. Enable governance of multiple Kong Gateway deployments across different teams, geographies, clouds, or environments at scale – The Konnect Runtime Manager combined with Konnect’s powerful Authorization capabilities enable multiple teams within an organization to access their Kong Gateway environments with just the right level of access, while central teams can have a full view of all deployments for governance purposes.
3. Provide a Services Catalog (called Service Hub), API Portal, and API Analytics capabilities as a service. With Konnect, all of these capabilities are available for all Kong Gateway deployments with zero additional operational complexity.

There are many reasons users of Kong’s open source gateway should consider migrating to Konnect to achieve a production-ready, highly-available, distributed API gateway in a very rapid time frame.

Migrating from Kong Open Source to Konnect

At Kong, we’ve made migrating from Kong’s OSS Gateway to Konnect very straightforward. All it takes is three (3) steps:

1. Extract the configuration from the existing OSS Gateway
2. Sync the configuration to a Konnect Runtime group
3. Register your gateway with Konnect

The remainder of this blog post walks you through an example. Follow along!

Extract Kong Configuration

If you do not have an existing installation of Kong OSS to follow along, begin with an install of Kong OSS and configure an example route and service to proxy. If you already have a Kong Gateway OSS installation, you’re ready for the next step. To set up a Kong installation, you can follow the quick start and to set up a sample service and route, follow this guide.

Kong provides decK, a command line tool that can manage gateway configuration declaratively using simple YAML files. Gateway configuration can be exported from, or imported to the gateway and diff and sync options are available. For more information on decK, see the documentation.

To utilize decK, download and install it using the steps documented here.

With decK downloaded and installed, let’s export the current running configuration of the gateway into a yaml file using the following command. In our case, both decK and the Kong Admin API are running on the same system.

deck dump --output-file kong.yaml --kong-addr http://127.0.0.1:8001

This generates a kong.yaml file of the Kong Gateway configuration in our current working directory.

_format_version: "3.0"
services:
- connect_timeout: 60000
  enabled: true
  host: mockbin.org
  name: example_service
  port: 80
  protocol: http
  read_timeout: 60000
  retries: 5
  routes:
  - https_redirect_status_code: 426
    name: example_route
    path_handling: v0
    paths:
    - /mock
    preserve_host: false
    protocols:
    - http
    - https
    regex_priority: 0
    request_buffering: true
    response_buffering: true
    strip_path: true
  write_timeout: 60000

Sync Kong Configuration to Konnect

Log on to your Konnect Organization. If you do not have a Konnect Organization, get started by following this link and clicking on “Start for Free”. In this section, we will follow the process described here for the migration.

Once in Konnect, select Runtime Manager and identify or create a new Runtime Group for the migration. For example, the “default” Runtime Group.

Next, let’s generate a Personal Access Token (PAT) that we can use with decK for the migration. Click your account name in the lower left corner of the Konnect portal, select “Personal Access Tokens” and click generate token. For our example, we have placed the generated token in a file called “kpat.txt” to more securely reference it.

Let’s go ahead and validate decK can communicate with Konnect using the generated PAT:

deck ping --konnect-runtime-group-name default --konnect-token-file kpat.txt

Next, let’s run the decK diff command to preview the changes that will be migrated and then run a decK sync to apply the changes. The output from these two commands will generally look the same, the difference is the sync command applies the changes to the Runtime Group.

deck diff  --konnect-runtime-group-name default --konnect-token-file kpat.txt
deck sync  --konnect-runtime-group-name default --konnect-token-file kpat.txt

creating service example_service
creating route example_route
Summary:
  Created: 2
  Updated: 0
  Deleted: 0

You can verify the creation of the entities by checking the GUI in the Konnect SaaS portal, selecting the Runtime Group in Runtime Manager and selecting Gateway Services and Routes.

At this point, we have successfully migrated the configuration from our Kong OSS Gateway instance to Konnect.

Let’s now get a runtime instance registered with Konnect.

Create a Runtime Instance

Within the Konnect Runtime Manager, choose Runtime Instances and then the "+ New Runtime Instance" button to see instructions to add a new runtime.

For this example, we will use a basic Ubuntu Linux instance. The links in Konnect first direct us to install Kong software for Ubuntu using the instructions here. To install Kong Gateway on a new Ubuntu 20.04 instance in AWS, we execute the following commands:

First we updated the Ubuntu OS:

sudo apt update

sudo apt upgrade -y

Then run the following command to resolve a Kong dependency in newer versions of Ubuntu:

sudo apt install zlib1g-dev

Then download and run the dpkg install as described in documentation:

curl -Lo kong-enterprise-edition-3.1.1.1.all.deb "https://download.konghq.com/gateway-3.x-ubuntu-$(lsb_release -sc)/pool/all/k/kong-enterprise-edition/kong-enterprise-edition_3.1.1.1_amd64.deb"

sudo dpkg -i kong-enterprise-edition-3.1.1.1.all.deb

The Konnect “Create Runtime Instance” page includes a button to automatically generate a certificate and key for the new instance to establish a TLS connection to Konnect. You can also upload a certificate you’ve generated. Executing this, we used the contents to create two separate text files with the certificate and key, and placed them in the /etc/kong directory. Then we create a minimal kong.conf file to use for the instance using the example provided by Konnect with our two filenames substituted for the cluster_cert and cluster_cert_key. Our kong.conf file looks like below. Make sure to make the necessary updates to your kong.conf file based on your environment.

role = data_plane
database = off
cluster_mtls = pki
cluster_control_plane = 2f4xxxxxxx.us.cp0.konghq.com:443
cluster_server_name = 2f4xxxxxxx.us.cp0.konghq.com
cluster_telemetry_endpoint = 2f4xxxxxxx.us.tp0.konghq.com:443
cluster_telemetry_server_name = 2f4xxxxxxx.us.tp0.konghq.com
cluster_cert = /etc/kong/cluster.crt
cluster_cert_key = /etc/kong/cluster.key
lua_ssl_trusted_certificate = system
konnect_mode = on
vitals = off

Then we started the Kong Runtime:

sudo kong restart

As the runtime registers, you will see the new Kong Runtime instance in Runtime Manager with a status of Connected and Compatible at which point the runtime is ready.

Let’s verify the runtime can successfully proxy requests to the migrated services, in our case the mock route and mocking service.

curl -I -X GET http://localhost:8000/mock

HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Date: Tue, 24 Jan 2023 18:07:49 GMT
Vary: Accept-Encoding
Via: kong/3.1.1.1-enterprise-edition
CF-Cache-Status: DYNAMIC
Report-To: {"endpoints":[{"url":"https:\/\/a.nel.cloudflare.com\/report\/v3?s=3bECDuAxR4uVvyfH0Od2WXHoIAuKEc0OO2u%2BS0Bwjh3gSc39tyinuN424jVA1MaipDrDUMu9YMXhDAL7ULzbF%2BpWVExTDMGVBubTkrrc%2FON83uKy%2BmWw8tjB05d0TA%3D%3D"}],"group":"cf-nel","max_age":604800}
NEL: {"success_fraction":0,"report_to":"cf-nel","max_age":604800}
Server: cloudflare
CF-RAY: 78eab5ffaa0ae1e7-ORD
alt-svc: h3=":443"; ma=86400, h3-29=":443"; ma=86400
X-Kong-Upstream-Latency: 112
X-Kong-Proxy-Latency: 217

Success! Our Konnect runtime instance is now up and serving the same gateway services as our Kong OSS gateway. Any updates to the configuration in Konnect will be automatically pushed down to the runtimes. As new runtimes are deployed, Konnect will deploy the configuration.

In Closing

Konnect provides the benefits of simplified operations, enhanced governance and additional capabilities like a service catalog, analytics and more. In this article we’ve outlined how straight forward it is for OSS users to migrate to Konnect in three (3) simple steps:

1. Extract the existing configuration from Kong OSS via deck dump
2. Select or create a Runtime Group and sync the exported configuration to Konnect via deck sync
3. Register the runtime instance with Konnect via Runtime Manager

Once leveraging Konnect you can now deploy runtime instances to any environment or regions, on-prem or cloud and centrally manage them. Additionally, you can create different Runtime Groups, runtime instances and apply different sets of configuration to support multiple teams or departments.

Get Started Today!

Kong Konnect offers a generous free tier specifically to support our Open Source community who are looking for an efficient way to run Kong Gateway. Start using Kong Konnect for free today as the fastest & easiest way to deploy, secure, and manage your APIs.