THE CLOUD

CONNECTIVITY COMPANY

Kong Gateway Operations

Upgrading Kong Gateway

THE CLOUD CONNECTIVITY COMPANY

Kong Confidential 1
 Course Agenda
1. Kong Gateway Installation 6. Advanced Plugins Review
2. Upgrading Kong Gateway 7. Troubleshooting
3. Securing Kong 8. Monitoring / Observability
4. Securing Services on Kong 9. Administering Kong Gateway
using Deck
5. OIDC Plugin

THE CLOUD CONNECTIVITY COMPANY

Kong Confidential 2
Learning Objectives
1. Kong Gateway Versioning Pattern
2. Upgrade Path
3. Upgrade Model
4. Kong Migration Commands
5. Version Specific Upgrade Considerations

THE CLOUD CONNECTIVITY COMPANY

Kong Confidential 3
 Upgrading Kong Gateway

THE CLOUD CONNECTIVITY COMPANY

Kong Confidential 4
 Versioning
Kong adheres to semantic versioning, making a distinction between the following versions:

● major (making breaking changes)

● minor (add backwards compatible functionality)
● patch (making backwards compatible bug fixes)

Kong Gateway additionally has one more decimal point on the right which identifies a
sub-patch based on the Kong Community Gateway.

THE CLOUD CONNECTIVITY COMPANY

Kong Confidential 5
 Upgrade Path

The upgrade path for major and minor versions differs depending on the version from which
you are migrating.

For example:

● Upgrading from 2.5.x to 2.6.x is a minor upgrade (same major version)

● Upgrading from 1.x to 2.x is a major upgrade (different major version)

Always consult release notes for any additional, release specific, migration steps

● Database migration instructions should be reviewed

● Suggested incremental upgrading as per version prerequisites should be followed, and
breaking changes accounted for.

THE CLOUD CONNECTIVITY COMPANY

Kong Confidential 6
 Kong Upgrade Model

Kong Gateway can be upgraded in-place and also supports a zero downtime migration model.

This means that while the migration is in process, you have two Kong clusters with different
versions running that are sharing the same database. This is sometimes referred to as the
blue-green migration model.

THE CLOUD CONNECTIVITY COMPANY

Kong Confidential 7
 Upgrading Kong

Use the 'kong migrations' command to :

● Upgrade major, minor, and patch releases of Kong Gateway (Enterprise), or

● Upgrade Kong Gateway (OSS) to Kong Gateway Enterprise.

The migrations are designed so that there is no need to fully copy the data:

● The new version of Kong Gateway is able to use the data as it is migrated, and
● The old Kong cluster keeps working until it is finally time to decommission it.

For this reason, the full migration is split into two stages:

1. kong migrations up - performs only non-destructive operations

2. kong migrations finish - puts the database in the final expected state

THE CLOUD CONNECTIVITY COMPANY

Kong Confidential 8
 Kong Migration Commands
Kong Migrations command Meaning

bootstrap Bootstrap the database and run all migrations.

up Run any new migrations

finish Finish running any pending migrations after ‘up’

list List executed migrations

reset Reset the database

migrate-community-to-enterprise Migrates CE entities to EE on the default workspace

upgrade-workspace-table Outputs a script to be run on the db to upgrade the entity for

2.x workspaces implementation

reinitialize-workspace-entity-counters Resets the entity counters from the database entities

THE CLOUD CONNECTIVITY COMPANY

Kong Confidential 9
 Lab: Upgrading Kong Gateway

To set up your lab environment for this lesson, run the 'setup' command, then select option '2'

$ setup
1) Kong Gateway Installation
2) Upgrading Kong Gateway
3) Securing Kong Gateway
4) Securing Services on Kong
5) OIDC Plugin
6) Kong Vitals
7) Advanced Plugins Review
8) Troubleshooting
9) Reset Virtual Machine
10) Quit
Please select the lesson you wish to set up: 2

Setting up for lesson '2 Upgrading Kong Gateway'

...
THE CLOUD CONNECTIVITY COMPANY
Kong Confidential 10
 Kong Upgrade Lab

In the following lab we will upgrade Kong API Gateway on Docker from Kong 2.5 to 2.6.

This is a minor upgrade, and the exercise will incur a brief downtime.

We will offer the lab exercise for both Docker CLI and Docker compose

● Docker Compose allows you to try more complex scenarios more easily, such as
incremental and/or hybrid upgrades with start/upgrade releases of your choice.

THE CLOUD CONNECTIVITY COMPANY

Kong Confidential 11
 Task: Upgrade Using Docker CLI

THE CLOUD CONNECTIVITY COMPANY

Kong Confidential 12
 Upgrade Using Docker CLI

In this lab we will perform the following steps:

1. Create a dedicated docker network

2. Create a database container
3. Bootstrap the Database for the 2.5.1.2 initial installation
4. Run Kong GW 2.5.1.2 and create a simple service/route
5. Run the 2.6 migrations
6. Complete the 2.6 migrations
7. Remove the old 2.5 container
8. Start the new 2.6 container
9. Confirm previous data is still available and the GW was upgraded

THE CLOUD CONNECTIVITY COMPANY

Kong Confidential 13
Task: Create a docker network and a database container

Create a dedicated docker network:

$ docker network create kong-edu-net

Create the Database Container:

$ docker run -d --name kong-ee-database --network kong-edu-net \

-p 5432:5432 \
-e "POSTGRES_USER=kong" \
-e "POSTGRES_DB=kong-edu" \
-e "POSTGRES_PASSWORD=kong" \
postgres:13.1

THE CLOUD CONNECTIVITY COMPANY

Kong Confidential 14
 Task: Bootstrap the Database for Kong 2.5.1.2
We will set the license using an environment variable for upgrade examples:

$ export KONG_LICENSE_DATA=$(cat "/etc/kong/license.json")

Bootstrap the Database for the 2.5.1.2 initial installation:

$ docker run --rm --network kong-edu-net \
-e "KONG_DATABASE=postgres" \
-e "KONG_PG_HOST=kong-ee-database" \
-e "KONG_PG_PORT=5432" \
-e "KONG_LICENSE_DATA=$KONG_LICENSE_DATA" \
-e "KONG_PG_PASSWORD=kong" \
-e "KONG_PG_USER=kong" \
-e "KONG_PG_PASSWORD=kong" \
-e "KONG_PASSWORD=admin" \
-e "KONG_PG_DATABASE=kong-edu" \
kong/kong-gateway:2.5.1.2-alpine kong migrations bootstrap

THE CLOUD CONNECTIVITY COMPANY

Kong Confidential 15
 Task: Start Kong Gateway 2.5.1.2
Run Kong GW 2.5.1.2:
$ docker run -d --name kong-ee-edu --network kong-edu-net \
-e "KONG_DATABASE=postgres" \
-e "KONG_PG_HOST=kong-ee-database" \
-e "KONG_PG_PORT=5432" \
-e "KONG_PG_PASSWORD=kong" \
-e "KONG_PASSWORD=admin" \
-e "KONG_PG_DATABASE=kong-edu" \
-e "KONG_PROXY_ACCESS_LOG=/dev/stdout" \
-e "KONG_ADMIN_ACCESS_LOG=/dev/stdout" \
-e "KONG_PROXY_ERROR_LOG=/dev/stderr" \
-e "KONG_ADMIN_ERROR_LOG=/dev/stderr" \
-e "KONG_LICENSE_DATA=$KONG_LICENSE_DATA" \
-e "KONG_PASSWORD=admin" \
-e "KONG_ADMIN_API_URI=$KONG_ADMIN_API_URI" \
-e "KONG_ADMIN_GUI_URL=$KONG_MANAGER_URI" \
-e "KONG_ADMIN_LISTEN=0.0.0.0:8001, 0.0.0.0:8444 http2 ssl" \
-p 8000-8004:8000-8004 \
-p 8443-8445:8443-8445 \
kong/kong-gateway:2.5.1.2-alpine

THE CLOUD CONNECTIVITY COMPANY

Kong Confidential 16
 Task: Check Version & create a simple service/route
Check version of Kong:

$ http GET localhost:8001 | jq .version

Create a sample service/route:

$ docker run -d --name mockbin \
--network kong-edu-net \
-p 8888:8080 mashape/mockbin

$ http POST localhost:8001/services \

name=mockbin_service \
url=http://mockbin:8080/request

$ http -f POST localhost:8001/services/mockbin_service/routes \

name=mockbin_route \
paths=/mockbin
THE CLOUD CONNECTIVITY COMPANY
Kong Confidential 17
 Task: Run the 2.6 migrations
Run the 2.6 migrations:
$ docker run --rm --network kong-edu-net \
-e "KONG_DATABASE=postgres" \
-e "KONG_PG_HOST=kong-ee-database" \
-e "KONG_PG_PORT=5432" \
-e "KONG_PG_DATABASE=kong-edu" \
-e "KONG_LICENSE_DATA=$KONG_LICENSE_DATA" \
-e "KONG_PG_PASSWORD=kong" \
-e "KONG_PASSWORD=admin" \
kong/kong-gateway:2.6.0.1-alpine \
kong migrations up

2 migrations processed
1 executed
1 pending

THE CLOUD CONNECTIVITY COMPANY

Kong Confidential 18
 Task: Complete the 2.6 migrations
Complete the 2.6 migrations:
$ docker run --rm --network kong-edu-net \
-e "KONG_DATABASE=postgres" \
-e "KONG_PG_HOST=kong-ee-database" \
-e "KONG_PG_DATABASE=kong-edu" \
-e "KONG_PG_PORT=5432" \
-e "KONG_LICENSE_DATA=$KONG_LICENSE_DATA" \
-e "KONG_PG_PASSWORD=kong" \
-e "KONG_PASSWORD=admin" \
kong/kong-gateway:2.6.0.1-alpine kong migrations finish

1 migration processed
1 executed
No pending migrations to finish

Stop and remove the old 2.5 container:

$ docker container rm $(docker container stop kong-ee-edu)

THE CLOUD CONNECTIVITY COMPANY

Kong Confidential 19
 Task: Start the new 2.6 container:
Start the new 2.6 container:
$ docker run -d --name kong-ee-edu --network kong-edu-net \
-e "KONG_DATABASE=postgres" \
-e "KONG_PG_HOST=kong-ee-database" \
-e "KONG_PG_PORT=5432" \
-e "KONG_PG_PASSWORD=kong" \
-e "KONG_PASSWORD=admin" \
-e "KONG_PG_DATABASE=kong-edu" \
-e "KONG_PROXY_ACCESS_LOG=/dev/stdout" \
-e "KONG_ADMIN_ACCESS_LOG=/dev/stdout" \
-e "KONG_PROXY_ERROR_LOG=/dev/stderr" \
-e "KONG_ADMIN_ERROR_LOG=/dev/stderr" \
-e "KONG_ADMIN_LISTEN=0.0.0.0:8001, 0.0.0.0:8444 http2 ssl" \
-e "KONG_LICENSE_DATA=$KONG_LICENSE_DATA" \
-e "KONG_PASSWORD=admin" \
-e "KONG_ADMIN_API_URI=$KONG_ADMIN_API_URI" \
-e "KONG_ADMIN_GUI_URL=$KONG_MANAGER_URI" \
-p 8000-8004:8000-8004 \
-p 8443-8445:8443-8445 \
kong/kong-gateway:2.6.0.1-alpine
THE CLOUD CONNECTIVITY COMPANY
Kong Confidential 20
 Task: Confirm upgrade and persistence of data
Confirm previous data is still available and Gateway was upgraded:
$ http --headers GET localhost:8000/mockbin

HTTP/1.1 200 OK
Access-Control-Allow-Credentials: true
Access-Control-Allow-Origin: *
Connection: keep-alive
Content-Length: 515
Content-Type: application/json
Date: Mon, 17 Apr 2023 10:39:15 GMT
Server: gunicorn/19.9.0
Via: kong/2.6.0.1-enterprise-edition
X-Kong-Proxy-Latency: 81
X-Kong-Upstream-Latency: 83

Once done with this lab, please clean up the environment:

$ docker rm -f $(docker ps -a -q)
$ docker volume rm $(docker volume ls -q)
$ docker network rm -f kong-edu-net

THE CLOUD CONNECTIVITY COMPANY

Kong Confidential 21
Task: Upgrade Using Docker Compose

THE CLOUD CONNECTIVITY COMPANY

Kong Confidential 22
 Task: Upgrade Using Docker Compose

Using compose greatly simplifies the process. An additional service can be added to
the compose file to handle the migrations up and migrations finish like this:

kong-migrations-up:
image: "${KONG_DOCKER_TAG:-kong:latest}"
command: kong migrations up && kong migrations finish
depends_on:
- db
networks:
- kong-net

THE CLOUD CONNECTIVITY COMPANY

Kong Confidential 23
 Task: Upgrade Using Docker Compose

Here is an example of upgrading an instance of Kong GW 2.5.1.2 to 2.6.0.1 using

Docker compose.

- Setup license and bring up an instance of Kong GW 2.5.1.2:

$ export KONG_LICENSE_DATA=$(cat "/etc/kong/license.json")

$ export KONG_VERSION="2.5.1.2-alpine"
$ docker-compose -f kongupgdemo.yaml up -d
$ http GET localhost:8001 | jq '.hostname + " : " + .version'

"kong-ee : 2.5.1.2-enterprise-edition"

THE CLOUD CONNECTIVITY COMPANY

Kong Confidential 24
 Task: Upgrade Using Docker Compose

Create a sample service/route:

$ docker run -d --name mockbin \

--network kong-edu-net \
-p 8888:8080 mashape/mockbin

$ http POST localhost:8001/services \

name=mockbin_service \
url=http://mockbin:8080/request

$ http -f POST localhost:8001/services/mockbin_service/routes \

name=mockbin_route \
paths=/mockbin
THE CLOUD CONNECTIVITY COMPANY
Kong Confidential 25
 Task: Upgrade Using Docker Compose

Setup license and bring up an instance of Kong GW 2.6.0.1:

$ export KONG_VERSION="2.6.0.1-alpine"
$ docker-compose -f kongupgdemo.yaml up -d

Confirm previous data is still available and GW was upgraded:

$ http --headers GET localhost:8000/mockbin

HTTP/1.1 200 OK
Via: kong/2.6.0.1-enterprise-edition

Clean up the lab, once testing is done:

$ docker-compose -f kongupgdemo.yaml down -v

THE CLOUD CONNECTIVITY COMPANY

Kong Confidential 26
 Task: Upgrade Using Docker Compose
The same compose file kongupgdemo.yaml can be used to demonstrate
minor/major/incremental upgrades for 1.x/2.x versions

For example, you can start with KONG_VERSION="2.4.1.3-alpine", then

incrementally upgrade to first KONG_VERSION="2.5.1.2-alpine" and then
KONG_VERSION="2.6.0.1-alpine".

However please note that this compose file was put together for hybrid mode, which
was introduced in 2.1, so that compose file will not work with anything earlier than 2.1
as starting point.

If you use a compose file for a traditional mode install, you will not have that
limitation, and can start the upgrade from earlier versions of the Kong Gateway.

THE CLOUD CONNECTIVITY COMPANY

Kong Confidential 27
 Some Version Specific Upgrade Considerations

● If currently using the Developer Portal in 1.5.x, manual migration of its files to version
2.1.x is required.

● Pre-2.7, Upgrades should be performed incrementally. If you are upgrading from

Gateway 2.4 to 2.6 the following path should be followed: 2.4 -> 2.5 -> 2.6.
● If you are migrating from 2.x.x, upgrading to 2.7.x is a minor upgrade, which can be
done directly.
● If you are migrating from 1.x.x, upgrading to 2.7.x is a major upgrade. While you can
upgrade directly to the latest version, be aware of any breaking changes between the
1.x and 2.x series noted in documentation.
● Consult documentation for consideration when upgrading Hybrid mode and K8s

THE CLOUD CONNECTIVITY COMPANY

Kong Confidential 28
 Summary

In this lesson we

● Described the versioning scheme for Kong Gateway

● Explained upgrade Path for minor and major upgrades

● Described Kong Gateway's upgrade Model

● Presented Kong Migration Commands

● Presented Version Specific Upgrade Considerations

THE CLOUD CONNECTIVITY COMPANY

Kong Confidential 29
 Questions?

THE CLOUD CONNECTIVITY COMPANY

Kong Confidential 30
 What's next?

In the next lesson we will look at how to secure Kong Gateway.

THE CLOUD CONNECTIVITY COMPANY

Kong Confidential 31
 THE CLOUD
CONNECTIVITY COMPANY

THE CLOUD CONNECTIVITY COMPANY

Kong Confidential 32