You are browsing documentation for an outdated version.
See the latest documentation here.
Backup and restore
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, 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.
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
deck diff, or use decK’s
distributed configuration feature.
Entities managed by decK: decK does not manage Enterprise-only entities, like RBAC roles, credentials, keyring, licence, etc. Configure these security related entities separately using 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.
Back up Gateway entities
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.
Restore Gateway entities
To recover Kong Gateway configuration data from a database-native backup, make sure the database is prepared first.
kong.conf, set a database user using the
kong.conf, set a database name using the
Bootstrap database entities using the
Refer to the
kong migrations CLI reference
for more information.
kong migrations bootstrap
You can now restore the data using the utility
pg_restore -U kong -C -d postgres --if-exists --clean kongdb_backup_20230816/
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.
Keyring materials backup and restore
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 manual backup method and the automatic backup method.
Manually back up the following files:
- Kong Gateway configuration file
- 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.