Moving Services from Kong Gateway OSS to Konnect
Michael Heap

By on June 2, 2021

Migrating from Kong Gateway OSS to Konnect

Konnect is a hybrid cloud control plane managed by Kong that launched in May. Konnect provides an easy way to create and configure service configurations through a UI, rather than using the admin API and HTTP requests to configure your Kong Gateway. On top of that, it provides usage analytics, a developer portal and role-based access control for service configuration.

If you have a Kong Gateway OSS installation, you may be wondering how you can move your instance over to Konnect. In this tutorial, I’ll go through the process of converting a Kong Gateway OSS installation to a Konnect-compatible install step-by-step. It’ll take about 20 minutes if you want to work through it too.

Konnect depends on the non-OSS version of the Kong data plane. The non-OSS version is available free of charge, and we’ll be replacing our OSS installation with that version in this post.

The Kong Gateway instance that I have running and ready to migrate is a proxy for, built by following the Getting Started guide and configuring API key authentication.

1. Install decK

The first step of the migration process is to install decK, the Kong Gateway declarative configuration CLI. decK will enable you to export the configuration from your running Kong Gateway instance so that you can import it into Konnect.

decK is available on Windows, macOS and Linux, and provides installation instructions for Homebrew, deb/rpm and a Docker image. 

decK works by talking to Kong’s admin port, which (hopefully!) isn’t available on the internet, which means that we need to install decK alongside our running Kong instance. As I’m running the Kong Gateway on an Ubuntu machine, I’ve chosen to install the deb package:

$ wget
$ sudo dpkg -i deck_v1.7.0_amd64.deb

2. Export Your Kong Gateway Config

Once you install decK, you can export your existing configuration by running deck dump. This may take a few minutes if you’ve got a complex configuration.

$ deck dump --output-file kong.yaml

deck dump will create a kong.yml file in the current folder that contains all the configuration for your Kong instance. Here’s my configuration, created by following the getting started guide in the Kong Gateway documentation:

_format_version: "1.1"
- connect_timeout: 60000
  name: example-service
  port: 80
  protocol: http
  read_timeout: 60000
  retries: 5
  write_timeout: 60000
  - hosts:
	id: 47fff0e8-b263-4c63-8c8a-3197a3c0823c
	path_handling: v0
	preserve_host: false
	- http
	- https
	regex_priority: 0
	strip_path: true
	https_redirect_status_code: 426
	request_buffering: true
	response_buffering: true
  - name: key-auth
  	anonymous: null
  	hide_credentials: false
  	key_in_body: false
  	key_in_header: true
  	key_in_query: true
  	- apikey
  	run_on_preflight: true
	enabled: true
	- grpc
	- grpcs
	- http
	- https
- username: Jason

3. Sign Up for Konnect

Now that you’ve got your config, it’s time to sign up for Konnect and import this configuration. If you have a Konnect account already, you can skip this step.

Konnect’s signup process is self-service and provides you with a 30-day free trial of Konnect Plus. After 30 days, your account will revert to Konnect Free, which includes 2 million API requests per month.

4. Convert Your Kong Gateway Configuration

Once you have a Konnect account, it’s time to convert your Kong Gateway configuration to a Konnect configuration file. We can use decK’s convert command to do this:

$ deck convert --from kong-gateway --to konnect --input-file kong.yaml --output-file konnect.yaml

Once this command completes, you should see a konnect.yaml file in the current directory. This yaml file contains the Konnect version of your service configuration, including routes, plugins, consumers and more.

5. Import Your Config

You can use the konnect.yaml file to update your Konnect account with the service configuration you’re currently using. It works by creating a diff between what’s currently in your Konnect account and what’s in the config file before making API requests to synchronize the configuration. This means that it will delete existing service configuration that does not exist in your Kong Gateway export.

Once you’re ready to go ahead and sync your services, run the following command, replacing the placeholders with your Konnect credentials:

$ deck konnect sync --konnect-email YOUR_EMAIL --konnect-password YOUR_PASSWORD --state konnect.yaml

You will see your service configuration in Konnect once this command has finished executing. This is what the example service looks like. You can see the defined route when the Host header matches


Kong Konnect ServiceHub Header

6. Update Kong Gateway on Your Server

Once you import your configuration into Konnect, it’s time to register your existing API Gateway as a runtime. Konnect allows you to seamlessly use additional features—both paid and free—that are not bundled into the OSS distribution of the Kong Gateway. For that reason, we’ll need to replace our existing installation with a Konnect-compatible one. Don’t worry, though, the Konnect-compatible gateway is API-compatible with the one you’re used to: it just has some extra stuff (additional plugins and a free-to-use management UI) bundled in.

Kong Gateway OSS will continue to serve requests until you run kong restart at the end, so any downtime caused by following the instructions here will be minimal. Here’s how I installed Kong EE on Ubuntu (your instructions may be slightly different):

$ wget
$ sudo apt-get remove kong
$ sudo dpkg -i kong-enterprise-edition_2.3.3.2_all.deb

Now that your API gateway is Konnect-compatible, let’s register it as a runtime so that it reads its configuration from Konnect rather than its local database. Log in to Konnect and go to the runtime configuration page and click Configure Runtime in the top right. This will take you to a page that contains instructions on how to register a runtime. As I’m using Ubuntu without Docker, I chose the Linux instructions.

After generating the certificates, I created three files in /etc/kong and pasted the certificates into them:

  • Cluster certificate: /etc/kong/tls.crt 
  • Cluster key: /etc/kong/tls.key 
  • Root CA certificate: /etc/kong/ca.crt 

I then copied the configuration parameters provided on the page into my Kong configuration file (located at /etc/kong/kong.conf), replacing the existing file and making sure I set the paths for the last three configuration entries as required.

After saving the new config and running sudo kong restart, I clicked Done at the bottom of the page. Konnect Runtime Manager then displayed my new runtime.

Go Forth and Configure

After migrating to Konnect, you’ll be able to make requests to your API gateway on port 8000 and watch as it uses your existing routes and plugins. If you make any changes in Konnect, the system will synchronize them immediately with all of your existing runtimes.

To test this, I visited the configuration section of Konnect and changed the authentication key for one of my consumers. I then made a request with the old key and received an error message. When I tried the new key, the request was successful.


Kong Konnect Key Authentication Plugin Setup

If you’re not sure what to try first in Konnect, try
choosing a service and taking a look at the traffic flowing through it. Or explore the plugins that are available for use with Konnect.

Start a free trial, or contact us if you have any questions as you’re getting set up.

Once you’re on Konnect, you may find these other tutorials helpful:


Share Post