--- title: Back up and restore Kong Gateway description: Learn how to back up and restore your Kong Gateway data. url: "/gateway/upgrade/backup-and-restore/" canonical_url: "/gateway/upgrade/backup-and-restore/" content_type: reference products: - Kong Gateway tags: - upgrade - backup - restore canonical: true works_on: - on-prem --- # 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](#database-native-backup) and [declarative backup](#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](#declarative-tools-for-backup-and-restore) to load in entity data. When running Kong Gateway in Konnect, only [declarative backup is available](#back-up-a-konnect-control-plane), as Kong manages the database. [Keyring materials](#keyring-materials-backup-and-restore) and Kong Gateway [configuration files](#other-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. ## Declarative tools for backup and restore Kong ships two declarative backup tools: [decK](/deck/) and the [kong config CLI](/gateway/cli/reference/), 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`](/deck/gateway/sync/) or [`deck gateway diff`](/deck/gateway/diff/), or use decK’s [federated configuration](/deck/apiops/federated-configuration/) feature. * **Entities managed by decK**: decK does not manage Enterprise-only entities, like [RBAC roles](/gateway/entities/rbac/#default-kong-gateway-roles), credentials, [Keyring](/gateway/keyring/), [license](/gateway/entities/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](/deck/reference/entities/) for a full list. Due to these limitations, we recommend prioritizing the [database-native method](#database-native-backup) in deployments using a database. ## Back up and restore Gateway entities for a Konnect control plane 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](/deck/reference/entities/) to see what can be backed up using this method. > decK **does not** back up Dev Portal, Catalog, Observability, 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: ```sh 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: ```yaml _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: ```sh deck gateway diff my-backup.yaml \ --konnect-token $KONNECT_TOKEN \ --konnect-control-plane-name $CONTROL_PLANE_NAME ``` 2. If you're satisfied with the diff result, run `deck gateway sync` to sync your configuration to a control plane: ```sh deck gateway sync my-backup.yaml \ --konnect-token $KONNECT_TOKEN \ --konnect-control-plane-name $CONTROL_PLANE_NAME ``` Check your control plane in Konnect to make sure the sync worked. Open [**API Gateway**](https://cloud.konghq.com/gateway-manager/), select your control plane, and check through the configured entities. ## Back up and restore Gateway entities in a self-managed deployment 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`](/gateway/cli/reference/#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: ```sh 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 ##### Traditional or hybrid mode - decK For a database-backed deployment, we recommend using decK as a secondary backup method. > Never use this method as your primary backup, as it doesn't back up all Kong Gateway entities. 1. To back up data with decK, first make sure it successfully connects to Kong Gateway: ```sh deck gateway ping ``` If you have [RBAC enabled](/how-to/enable-rbac-with-admin-api/), use the CLI option `--headers` to specify the admin token. You can specify this token with any decK command: ```sh deck gateway ping --headers “Kong-Admin-Token: $PASSWORD” ``` 2. Use decK to dump the configuration. You can back up a particular Workspace or all Workspaces at once: ```sh deck gateway dump --all-workspaces -o ./kong_backup.yaml ``` or ```sh deck gateway dump --workspace it_dept -o ./kong_backup.yaml ``` 3. Store the resulting file or files in a secure location. ##### Traditional or hybrid mode - kong config CLI As a final fail-safe for a database-backed deployment, you can also back up the database using the [`kong config`](/gateway/cli/reference/#kong-config) CLI. > Never use this method as your primary backup, as it might not accurately represent the final state of your database. ```sh kong config db_export ./kong_backup.yaml ``` ##### DB-less mode To back up a DB-less deployment, make a copy of your declarative configuration file (`kong.yml` by default) and store it in a safe place. You can find your declarative config file at the path set via the [`declarative_config`](/gateway/configuration/#declarative-config) setting. ### 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 ``` 2. In `kong.conf`, set a database name using the `pg_database` parameter: ``` pg_database = kong ``` 3. Bootstrap database entities using the `migrations` command. Refer to the [`kong migrations` CLI reference](/gateway/cli/reference/#kong-migrations) for more information. ```sh kong migrations bootstrap ``` 4. You can now restore the data using the utility `pg_restore`: ```sh pg_restore -U kong -C -d postgres --if-exists --clean kongdb_backup_20230816/ ``` #### 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. ##### Traditional or hybrid mode - decK In traditional or hybrid mode, use decK to restore your configuration from a backup state file. 1. Check that Kong Gateway is online: ```sh deck gateway ping ``` 2. Validate the declarative config: ```sh deck gateway validate ./kong_backup.yaml [--online] ``` 3. Once verified, restore a particular workspace or all workspaces at once: ```sh deck gateway sync ./kong_backup.yaml --all-workspaces ``` or ```sh deck gateway sync ./kong_backup.yaml --workspace it_dept ``` ##### Traditional or hybrid mode - kong config CLI If you backed up Kong Gateway database using [`kong config db_export`](/gateway/cli/reference/#kong-config), use the kong config CLI to restore your configuration from the backup declarative config file. 1. Validate the backup configuration file before restoring it: ```sh kong config parse ./kong_backup.yaml ``` 2. Import entities into your database: ```sh kong config db_import ./kong_backup.yaml ``` 2. Restart or reload your Kong Gateway instance: ```sh kong restart ``` or ```sh kong reload ``` ##### DB-less mode In DB-less mode, use the kong config CLI to restore your configuration from a declarative config file. 1. Validate the backup configuration file before restoring it: ```sh kong config parse ./kong_backup.yaml ``` 2. Restart or reload your Kong Gateway instance using the backup configuration file: ```sh export KONG_DECLARATIVE_CONFIG=./kong_backup.yaml; kong restart -c ./kong.conf ``` or ``` export KONG_DECLARATIVE_CONFIG=./kong_backup.yaml; kong reload -c ./kong.conf ``` Alternatively, post the declarative backup file to the `:8001/config` endpoint: ```sh curl -sS http://localhost:8001/config?check_hash=1 \ -F 'config=@./kong_backup.yaml' ; echo ``` ## Keyring materials backup and restore If you have enabled [Keyring](/gateway/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](/gateway/keyring/#disaster-recovery). ## Other files to back up Manually back up the following files: * Kong Gateway configuration file `kong.conf`. * Files in the Kong Gateway prefix, such as [Keys](/gateway/entities/key/), [Certificates](/gateway/entities/certificate/), `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. ## Related Resources - [Upgrade and migrate Kong Gateway](/gateway/upgrade/) - [Migrate from Kong Gateway OSS to Kong Gateway Enterprise](/gateway/upgrade/migrate-oss-to-ee/) - [Rolling upgrade](/gateway/upgrade/rolling/) - [Dual-cluster upgrade](/gateway/upgrade/dual-cluster/) - [In-place upgrade](/gateway/upgrade/in-place/) - [Kong Gateway breaking changes](/gateway/breaking-changes/) - [3.10 to 3.14 LTS upgrade](/gateway/upgrade/lts-upgrade-310-314/) - [3.4 to 3.10 LTS upgrade](/gateway/upgrade/lts-upgrade-34-310/) - [2.8 to 3.4 LTS upgrade](/gateway/upgrade/lts-upgrade-28-34/)