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.
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 https://github.com/Kong/deck/releases/download/v1.7.0/deck_v1.7.0_amd64.deb
$ 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:
- connect_timeout: 60000
- name: key-auth
- username: Jason
- key: ENTER_KEY_HERE
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 example.com:
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 https://download.konghq.com/gateway-2.x-ubuntu-xenial/pool/all/k/kong-enterprise-edition/kong-enterprise-edition_188.8.131.52_all.deb
$ sudo apt-get remove kong
$ sudo dpkg -i kong-enterprise-edition_184.108.40.206_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.
Once you’re on Konnect, you may find these other tutorials helpful:
- Getting Started With Kong Konnect in 10 Minutes
- Implementing Client Credentials With Kong and Okta
- 3 Ways Kong Helps With API Gateway Governance