Back up and restore Kong Gateway

Before you start any upgrade, back up your Kong Gateway data.

Kong supports two back up methods for Kong Gateway entities: database-native backup and declarative backup. A database-native backup backs up the entire Kong Gateway database, while a declarative backup works by managing declarative configuration files.

We recommend backing up data using both methods when possible, as this offers recovery flexibility:

• The database-native tools are robust and can restore data instantly, compared to the declarative tools.
• In case of data corruption, try to do a database-level restore first, otherwise bootstrap a new database and use declarative tools to load in entity data.

When running Kong Gateway in Konnect, only declarative backup is available, as Kong manages the database.

Keyring materials and Kong Gateway configuration files must be backed up separately. See their respective sections below for details.

The backup and restore methods described in this guide serve as general instructions. Revise the methods as necessary to fit your infrastructure, deployment, and business requirements.

Kong ships two declarative backup tools: decK and the kong config CLI, which support managing Kong Gateway entities in the declarative format.

• For database-backed deployments (traditional and hybrid mode), backups taken with either of these tools serve as an extra safeguard layer. If the database-native backup or restore corrupts the database, you can fall back to declarative files for restoring data.

  Both tools require the database to be ready for data export and import. To import or export data using these tools, ensure the user and password are initialized, and the database is bootstrapped.

• For DB-less deployments, no special tools are needed, so there is no declarative tool support. Back up your declarative files manually.

decK is generally more powerful than the kong config CLI. It has more features, invalidates the cache automatically, and fetches entities from the database instead of the LRU cache. Additionally, it overwrites entities instead of patching, so that the database has the exact copy of the config that you provide.

However, decK also has its limitations:

• Availability: decK requires Kong Gateway to be online, while the kong config CLI doesn’t.

• Performance: decK uses the Admin API to read and write entities and might take longer than expected, especially when the number of entities is very large.

  You can resolve this by increasing the number of threads by passing the flag --parallelism to deck gateway sync or deck gateway diff, or use decK’s federated configuration feature.

• Entities managed by decK: decK does not manage Enterprise-only entities, like RBAC roles, credentials, Keyring, license, and so on. Configure these security related entities separately using the Admin API or Kong Manager. See the reference for Entities managed by decK for a full list.

Due to these limitations, we recommend prioritizing the database-native method in deployments using a database.

If you’re running Kong Gateway as a Control Plane in Konnect, use decK for backup and restore. Review the list of entities managed by decK to see what can be backed up using this method.

Note: This method only backs up Control Plane configurations in Gateway Manager. It does not back up Dev Portal, API Products, Service Catalog, and so on. Data stored in these applications, such as API specs and documents, must be manually backed up.

Back up a Konnect Control Plane

Use deck gateway dump to back up your configuration:

deck gateway dump -o my-backup.yaml \
  --konnect-token $KONNECT_TOKEN \
  --konnect-control-plane-name $CONTROL_PLANE_NAME

This command generates a state file for the Control Plane’s entity configuration, for example:

_format_version: "3.0"
_konnect:
    control_plane_name: us-west
consumers:
- username: example-user1
- username: example-user2
services:
- connect_timeout: 60000
    host: httpbin.konghq.com
    name: MyService
    tags:
    - _KonnectService:example_service
    ...

Restore a Konnect Control Plane

You can restore entity configuration for a Control Plane using a declarative configuration file. You must do this for one group at a time.

Assuming you have a backup file, for example, my-backup.yaml:

1. Run a diff between your backup file and the Control Plane in Konnect to make sure you’re applying the configuration you want:

   deck gateway diff my-backup.yaml \
     --konnect-token $KONNECT_TOKEN \
     --konnect-control-plane-name $CONTROL_PLANE_NAME
   

   Copied to clipboard!

2. If you’re satisfied with the diff result, run deck gateway sync to sync your configuration to a Control Plane:

   deck gateway sync my-backup.yaml \
     --konnect-token $KONNECT_TOKEN \
     --konnect-control-plane-name $CONTROL_PLANE_NAME
   

   Copied to clipboard!

Check your Control Plane in Konnect to make sure the sync worked. Open Gateway Manager, select your Control Plane, and check through the configured entities.

The following sections explain the different backup methods.

Back up a self-managed deployment

Use a combination of database-native and declarative backups to safely preserve your data.

Database-native backup

When upgrading your Kong Gateway to a newer version, you have to perform a database migration using the kong migrations utility. The kong migrations commands are not reversible. We recommend backing up data before any starting any upgrade in case of any migration issues.

If you are running Kong Gateway with a database, run a database dump of raw data so that you can recover the database quickly in a database-native way. This is the recommended way to back up Kong Gateway.

With PostgreSQL, you can dump data in text format, tar format (no compression), or directory format (with compression) using the utility pg_dump. For example:

pg_dump -U kong -d kong -F d -f kongdb_backup_20230816

Use the CLI option -d to specify the database (for example, kong) to export, especially when the PostgreSQL instance also serves applications other than Kong Gateway.

Declarative backup

kong config db_export ./kong_backup.yaml

Restore a self-managed deployment

Restore Kong Gateway entity configuration from database-native and declarative backups.

Database-native restore

To recover Kong Gateway configuration data from a database-native backup, make sure the database is prepared first.

For PostgreSQL:

1. In kong.conf, set a database user using the pg_user parameter:

    pg_user = kong
   

   Copied to clipboard!

2. In kong.conf, set a database name using the pg_database parameter:

    pg_database = kong
   

   Copied to clipboard!

3. Bootstrap database entities using the migrations command. Refer to the kong migrations CLI reference for more information.

    kong migrations bootstrap
   

   Copied to clipboard!

4. You can now restore the data using the utility pg_restore:

    pg_restore -U kong -C -d postgres --if-exists --clean kongdb_backup_20230816/
   

   Copied to clipboard!

Declarative restore

If you need to roll back, change the Kong Gateway instance back to the original version, validate the declarative config, then apply it to your Kong Gateway instance.

If you have enabled Keyring and data encryption, you must separately back up and restore Keyring materials.

Caution: Make sure to store the encryption key in a safe place. If the encryption key is lost, you will permanently lose access to the encrypted Kong Gateway configuration data and there is no other way to recover it.

For technical details, refer to the disaster recovery documentation.

Manually back up the following files:

• Kong Gateway configuration file kong.conf.
• Files in the Kong Gateway prefix, such as Keys, Certificates, nginx-kong.conf, and any others you may have.
• Any other files you have created for your Kong Gateway deployment.

Although these files don’t contain Kong Gateway entities, without them, you won’t be able to launch Kong Gateway.

Note: If you have built a commercial offering where Kong Gateway is stateless – that is, where everything that gets configured on either the AMI or the Docker container is defined in version control and pushed into the platform that it’s running on – back up Kong Gateway’s configuration parameters in your own operational or secure way.