How to export your data from Kong Konnect starts with decK, not the console
A renewal, a pricing change or a residency requirement is forcing you off Konnect, and the first question is what you can take with you. Gateway configuration can be exported with decK's deck gateway dump -o kong.yaml command into a declarative YAML or JSON file covering services, routes, consumers and plugins. Analytics history, developer portal content and Konnect-only settings are not part of that file and need separate handling. decK is compatible with Konnect from version 1.40.0, so confirm your installed version with deck version before you run the export against your control plane.
Treat the export as an inventory, not a finished migration. Review the generated file for entities you expect and for ones you do not, because anything that depends on Konnect's control plane, its portal or its analytics will not carry over as configuration. Check each plugin in the dump against the open-source edition you plan to run. Plugins that rely on Enterprise features or on a database in traditional mode behave differently once they leave Konnect, so note them for a compatibility test rather than assuming they will work unchanged.
Plan the second half of the work before you export. Store the dump in version control, record which Konnect control plane it came from, and keep a dated copy because the Konnect environment may change or be retired on your renewal schedule. Ask Kong, in writing, which Konnect-only features your contract includes and whether any of them need a separate export path. Confirm your retention obligations for analytics and logs with your compliance team, since these will not appear in the gateway file.
What decK exports from Konnect and in which format
This table lists what the decK gateway dump brings out of Konnect, the file format it writes, and the points where you must check the output yourself. Read it as a checklist before you rely on the file as a complete backup or migration input. The main takeaway is that the dump covers the entities decK supports, so anything outside that set needs a manual export or a comparison in the Konnect console.
| Item | What the dump covers | What to check before relying on it |
|---|---|---|
| Command | deck gateway dump -o kong.yaml writes the exported configuration to one file | Run it with decK 1.40.0 or later, which the Kong documentation lists as compatible with Konnect |
| Output format | Declarative YAML or JSON, the same format decK uses to sync configuration back | Choose the file extension that matches your tooling, then validate the file before any sync |
| Services and routes | Gateway services and their routes are included in the file | Compare route counts and paths against the Konnect console |
| Consumers | Consumers are included in the file | Confirm that consumer credentials are present or regenerated, since the dump is not a secrets store |
| Plugins | Plugins attached to services, routes and consumers are included in the file | Confirm plugin scope (global, service or route) and any plugin that is not listed by decK |
| Other entities | Only the entities decK supports are written to the file | Check upstreams, certificates, vaults and Konnect-only objects such as portals and analytics settings in the console |
| Format limits | The file reflects the configuration decK can read at the time of the dump | Review the file for entities or fields decK skips before you treat it as a complete record |
What does not come out of Konnect in a decK file
A decK export carries gateway configuration, not the surrounding Konnect platform. The cards below list the Konnect components that stay behind, the workaround for each, and what to confirm against Konnect's current documentation before you cancel anything.
Konnect control plane state
The Konnect control plane, including its organization settings, control plane groups and the metadata Konnect stores about each gateway, sits outside the declarative file. The file captures services, routes, consumers and plugins, but not the Konnect console state around them. Rebuild that state in your own control plane, and check whether any Konnect-only objects in your organization have no equivalent in the open-source edition before you plan the cutover.
Developer portal content
Portal pages, custom content, API documentation rendered in the portal and developer-facing branding are not part of a gateway dump. Export the OpenAPI specifications and Markdown pages by hand from your source repositories or the portal itself, then publish them on the portal you will run. Confirm with Konnect which portal assets can be downloaded directly, because some may only be available through the console.
Application and credential records
Developer applications, their registrations and the API keys or OAuth client secrets that developers hold are managed through the portal and the Konnect console. Consumers exported by decK carry their credential configuration, but the human side of the relationship, such as who owns each application and which plan it is on, may not transfer. Plan a notification to each developer, reissue secrets where the old values cannot be carried over, and verify that every consumer maps to a real owner.
Analytics and usage history
Traffic metrics, request counts and usage reports that Konnect keeps for your gateways are not exported in the declarative file. For audit, capacity planning or chargeback, decide how much history you need before cancellation. Export what you can from the Konnect analytics views while the subscription is active, and send new gateway logs and metrics to your own observability stack from day one.
Team members and roles
User accounts, teams, role assignments and single sign-on links in Konnect are access-control records, not gateway configuration. Create the equivalent operators in your own identity system and map each Konnect role to the access your self-run gateway needs. Keep a written list of who had admin rights so you can confirm that none were dropped during the move, and remove access for people who leave the project.
Dedicated Cloud Gateway settings
If any data planes run as Dedicated Cloud Gateways on AWS, Azure or GCP, their network, sizing, region and provider settings are managed by Kong and are not in a decK file. Record those settings before you stop the service, then size and network your self-hosted data planes in your own accounts. Confirm the list of Dedicated Cloud Gateway settings against Kong's deployment documentation, since those settings depend on your plan.
Export sequence and verification for a complete Konnect dump
This sequence produces a version-controlled declarative file of your Konnect gateway configuration, checked against the console and validated before any other system relies on it. Each step ends with an artifact or check you can confirm yourself.
Confirm decK version 1.40.0 or later
The platform engineer running the export checks the installed decK binary with the version command on the workstation or jump host that will run the dump. decK must be at version 1.40.0 or later, because earlier releases are not compatible with Kong Konnect. If the version is older, upgrade decK from Kong's decK documentation before continuing. The step is done when the reported version is 1.40.0 or higher and the same version is recorded in the export notes.
Authenticate to the Konnect control plane
The engineer authenticates decK to the Konnect control plane with a Konnect access token scoped to the control plane being exported, supplied through an environment variable or a flag rather than typed into shared shell history. Use a read-only or least-privilege token where your Konnect role model allows it. The step is done when a read-only decK command such as listing the control plane's services returns results for the expected control plane and no authentication error. Confirm the control plane name against the Konnect console before proceeding.
Run the gateway dump command
From an empty working directory, the engineer runs deck gateway dump -o kong.yaml against the authenticated control plane. The command writes a declarative YAML file covering entities such as services, routes, consumers and plugins. Keep the output filename explicit so the file is easy to find later. The step is done when kong.yaml exists, is non-empty, and the command exits without errors. Record the command, decK version and timestamp in the migration log.
Store the export in Git
The engineer commits kong.yaml to a private Git repository inside your own infrastructure, in a branch or folder dedicated to the Konnect export, and tags the commit with the control plane name and export date. Restrict write access to the repository and treat the file as sensitive, because plugin configuration can reference secrets or credentials depending on how Konnect stored them. The step is done when the commit hash is recorded and the file can be read back from the repository.
Inspect entities against the Konnect console
A platform engineer compares the exported file with the Konnect console, walking through services, routes, consumers and plugins for a sample of each type and checking names, paths, hosts, methods, upstream targets and plugin settings. Pay particular attention to plugins attached at the global, service, route or consumer level, because scope errors are easy to miss. The step is done when every sampled entity matches the console and any gaps, such as items that the console shows but the dump does not, are written down with an owner.
Record captured plugins and consumers
The engineer builds an inventory from the file listing each plugin type in use and the consumers defined, with the number of instances of each. Plugins that depend on a database or on Konnect-specific features need separate review before any move to a self-hosted gateway, so flag them now. The output is a short inventory document stored beside kong.yaml. The step is done when the inventory and the file agree on plugin and consumer counts, and any plugin that is not expected to carry over is marked for follow-up.
Compare entity counts with the console
The engineer counts entities by type in kong.yaml and compares each count with the number shown in the Konnect console or retrieved through a read-only API call for the same control plane. Counts for services, routes, consumers, plugins and any other entity types in use should match. A mismatch means the export is incomplete or that some configuration sits outside the dump, and the export must be repeated and investigated before continuing. The step is done when every count matches and the comparison is saved with the commit.
Validate the file before further use
Before the file is used for a self-hosted Kong Gateway, a translation to Apache APISIX, or any other system, the engineer runs decK's validation on kong.yaml so the declarative file is checked for structural errors. Validation confirms the file is well formed and internally consistent, but it does not prove that a self-hosted gateway will behave the same, so it is a gate and not a sign-off. The step is done when validation passes with no errors and the result is attached to the migration record.
How the exported file feeds self-hosted Kong Gateway
The decK file can be loaded into a self-hosted Kong Gateway in two ways, and the choice depends on how your plugins behave. In DB-less mode, Kong Gateway needs no database and takes its configuration from declarative files, which you can keep in Git and review like any other code. The Admin API is read-only in this mode, so changes flow only from the file. In traditional mode, the gateway uses a database, and you use decK to sync the exported file into the running control plane. Both paths use the same kong.yaml structure that deck gateway dump produced, so the file itself does not need to be rewritten for either mode.
Before you pick a mode, check every plugin the Konnect configuration uses. Only traditional mode supports database-dependent plugins, such as cluster-strategy rate limiting and OAuth2. If your dump contains either, DB-less mode will not run those plugins as configured, and you will need a database-backed deployment. Plugin names in the exported file, under the plugins entries, are the fastest inventory. Also confirm the deployment version. The open-source Kong Gateway line you can run yourself is the 3.9 series, which is the current open-source release line, while Enterprise releases move ahead on their own schedule. Verify version compatibility against the Kong Gateway changelog before you install.
Plan a test run before any cutover. Load the exported file into a non-production gateway, then compare routes, services, consumers and plugins against the Konnect control plane with a sample of real requests. Keep the file under version control so each change is reviewed, and record which secrets, such as consumer credentials and plugin keys, were not included in the dump and must be supplied separately. Confirm with your Kong account team or in your own environment which Konnect-only entities, such as portal or analytics settings, sit outside the file and need manual reconstruction.
Translating the Kong export for Apache APISIX
Standalone mode is the closest fit when you want APISIX to run without etcd and keep its configuration in a single file that can be versioned in Git. In this model, the decK export is not loaded as is. You use it as the reference inventory of services, routes, consumers and plugins, then write the APISIX equivalent into conf/apisix.yaml or conf/apisix.json. APISIX checks that file for changes every second and hot-reloads it, so the file itself becomes the source of truth for the gateway.
- Reference inventory: Keep the decK YAML in a separate folder as the baseline, and record which Kong entity each APISIX object replaces.
- Single file target: Confirm the file location and format against the APISIX deployment modes documentation before you start writing.
- Hot reload behavior: Test that a malformed edit does not take a route offline, because the reload picks up the file as soon as it changes.
- Admin API scope: Check whether your team needs the Admin API at all in this mode, since configuration arrives through the file.
- Change control: Route every edit through a pull request so the file history doubles as your audit trail.
Confirm with your platform team that a file-based workflow matches how your organization deploys and approves gateway changes before you choose this path.
Traditional mode runs the data plane and control plane together, while decoupled mode separates them and has both share one etcd cluster. Both suit teams that want dynamic configuration through the Admin API and need routes and plugins to change without restarts. The decK export still matters here, but its role is to seed the objects you create through the Admin API rather than to act as a live file. Plan the etcd cluster as a stateful component with its own backup and recovery procedure.
- Admin API port: Traditional mode listens on port 9080 for client traffic and port 9180 for the Admin API, so network policy must reflect that split.
- Decoupled topology: Plan how data plane nodes reach the shared etcd cluster and how the control plane is secured.
- Object creation order: Create upstreams and routes before the plugins that reference them, and script the sequence so it can be rerun.
- etcd operations: Assign an owner for etcd backups, quorum health and upgrades, since losing it affects every route.
- Access control: Restrict the Admin API to the platform team and protect its credentials as you would any administrative interface.
Ask your APISIX support channel or implementation partner to confirm the etcd sizing and high availability design for your expected route count before you commit to this model.
Whichever deployment model you pick, the Kong entities do not map one to one onto APISIX objects. Kong services and routes become APISIX routes that point to upstreams, consumers become APISIX consumers with their own credentials, and Kong plugins become APISIX plugins with different names, fields and defaults. A manual translation works for a small inventory, while a script that reads the decK YAML and writes APISIX objects helps when the count grows. Either way, the translation is a planned step with testing, not a file conversion you run once and forget.
- Entity mapping: Document how each Kong service, route, consumer and plugin maps to its APISIX counterpart before writing any code.
- Plugin verification: Verify each plugin mapping individually against the APISIX plugin documentation, because names, options and behavior differ between the two gateways.
- Authentication flows: Test JWT, key authentication and OAuth or OpenID Connect flows with real client requests, and confirm the APISIX openid-connect plugin supports the flows your identity provider uses.
- Parallel testing: Send mirrored or staged traffic through the APISIX routes and compare responses, status codes and rate limit behavior with Kong.
- Rollback plan: Keep the Kong routes running until the APISIX configuration has passed agreed test cases, and record the cutover steps.
Before you rely on a translated plugin in production, have a named owner confirm its behavior with a documented test, since the decK export alone does not prove equivalence.
What to plan before the Konnect contract ends
Most of the export work is simple once the file exists. The risk sits in the contract terms around it: when notice is due, whether configuration can keep changing during the export, how long a parallel run lasts, and what Konnect data you can still reach after termination. Confirm each item in writing with Kong before you set a cutover date.
Notice period and renewal date
Find the notice period and the exact renewal or termination date in your order form, not in a sales summary. Missing a notice window can roll the subscription forward for another term while you still need Konnect for the parallel run. Ask Kong to confirm in writing whether a short extension is available if the export and testing take longer than planned. Record the date by which you must give notice, then work backward to set your export and cutover milestones.
Configuration freeze during export
Dump the configuration only after your teams agree on a change freeze for Konnect services, routes, consumers and plugins. A decK dump is a point-in-time snapshot, so any change made after it will be missing from the file you migrate. Ask Kong whether any Konnect-side changes, such as plugin updates or control plane maintenance, could alter what the dump returns. Schedule a second dump just before cutover and diff it against the first.
Parallel run timing
Plan a parallel run in which the self-hosted gateway serves test traffic while Konnect still serves production. Confirm with Kong that your Konnect subscription and data plane nodes remain fully active through that period, not just until the renewal date. Agree on which team owns rollback and how long the Konnect data plane must stay ready to take traffic back. Document the traffic percentage and the criteria that end the parallel run.
Konnect analytics and log retention
Request your analytics dashboards, usage reports and gateway logs before termination, since a self-hosted gateway will not carry Konnect's analytics history forward. Ask Kong what retention period applies to these records after the subscription ends and in what formats they can be exported. Decide whether you need this history for audit, capacity planning or incident review, and move it to your own logging stack if so.
Access to data after termination
Ask Kong in writing whether you can still log in, read configuration and download exports after the subscription ends, and for how long. Some vendors close the control plane at termination, so the decK dump and any local copies of your declarative files must be complete before that date. Store the exported YAML or JSON under version control in your own environment so a dump does not depend on Konnect remaining available.
Questions buyers ask before exporting from Konnect
Can I run decK alone to export everything from Konnect?
decK can export the gateway configuration on its own. The command deck gateway dump -o kong.yaml writes entities such as services, routes, consumers and plugins into a declarative YAML or JSON file. That file covers the gateway layer only. Developer portal content, analytics history, Konnect team and role settings and any Konnect-only features are outside it, so list them separately. Before you rely on the dump, run it against a copy of your configuration and compare the result with what the Konnect console shows, then confirm in your own environment which fields your Konnect version includes.
What makes an export and conversion take more effort?
The main drivers are the number of entities, the number and type of plugins, any custom code and the amount of portal content. Each service, route and consumer must be checked after the dump, so a configuration with many small services takes longer than one with a few large ones. Plugins that carry custom logic, or that depend on a database, need a decision about how they will run after the move. Portal pages, specs and applications are outside decK, so they add separate work. Ask any provider to break the quote down by these four drivers so you can see which one dominates.
How long does a parallel run of Kong Konnect and self-hosted Kong take?
The length of a parallel run depends on how much traffic you need to validate, how many consumers and credentials must be checked, and how much risk your change process allows. No researched duration is available for this, so ask for a timeline tied to your environments and cutover plan. decK syncs declarative files to self-hosted Kong Gateway, which lets you stage the same configuration in a non-production environment first. Keeping the file in Git makes each change reviewable and repeatable during the overlap period, and it gives you a clear record of what changed between runs.
What access and tools does my team need before the export?
You need a Konnect account with enough access to read the control plane configuration for the organization and region you are exporting. decK must be a version that supports Konnect, which is version 1.40.0 or later according to decK documentation. Your team also needs a Git repository for the exported file, one or more staging hosts for self-hosted Kong Gateway (Docker, Kubernetes or a supported Linux package), and an owner who can approve changes. Confirm your Konnect role permissions with your administrator before the work starts, because read access to some settings may be limited.
Do I need an outside partner to export from Konnect?
You do not need an outside partner to run decK, but the migration also involves plugin decisions, testing, hardening and operations. Whether to bring in help depends on your team's experience with Kong, your change process and how many environments are in scope. DeployOpen plans, implements, customizes, integrates, hardens, backs up, upgrades, documents and supports self-hosted open-source platforms in your own infrastructure. Most engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts, and DeployOpen does not publish a price list, so a quote follows from that written scope.
How does the open-source edition's support position affect planning?
Plan for the fact that Kong's published version support policy applies to Kong Gateway Enterprise only, so it gives no support window for the open-source edition. The open-source repository's newest release line is 3.9, while Enterprise has moved ahead to 3.16, according to the version support policy and GitHub releases. That means your team, or a retainer partner, must own patching, upgrade testing and vulnerability tracking. Ask who will make security fixes available for your chosen version, and write an upgrade path into the plan before cutover.
Will my plugins and Konnect features work in self-hosted Kong?
Most declarative gateway configuration carries over, but some plugins depend on a database. In DB-less mode, Kong Gateway needs no database and reads its configuration from declarative files, yet database-dependent plugins such as cluster-strategy rate limiting and OAuth2 need traditional mode. Check each plugin in your dump against the deployment topologies documentation before choosing a mode. Konnect-only capabilities, such as the hosted control plane, the portal and Dedicated Cloud Gateways, do not come across in the file, so each needs a replacement decision.
Is the exported file safe to store in Git?
Review the file before you commit it, because a configuration dump can include plugin settings and credential references that should not be stored in plain text. Confirm which fields your decK version writes, whether sensitive values are included or masked, and how consumer credentials are handled. Store secrets in a dedicated secrets manager and reference them from the declarative file, and restrict who can read the repository. Limit access to the staging hosts in the same way, and record who approved each sync so the change history is complete.
How DeployOpen works on this
DeployOpen plans and implements the export of your Kong Konnect configuration inside your own infrastructure, then supports the move to a self-hosted gateway. Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
How we scope
- Inventory every Konnect control plane, service, route, consumer and plugin that the export must cover.
- Record which plugins depend on Konnect-only features and which need a database-backed Kong deployment.
- Agree the target runtime, either self-run Kong Gateway OSS or Apache APISIX, in the written scope.
How we build
- Run decK gateway dump against your control plane and version the resulting declarative file in Git.
- Validate the exported file against a test Kong Gateway instance before any production traffic moves.
- Translate exported entities to APISIX routes, upstreams and plugins where APISIX is the chosen target.
How we hand over
- Deliver the exported files, mapping notes, test results and a runbook for your own platform team.
- Document every configuration item that did not translate and the decision taken for each one.
- Provide a cutover plan that lists rollback steps, owners and the checks to run after switching traffic.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer after handover.
- Confirm with your team which upgrade path and version line you will run once Konnect is retired.
- Quotes follow from the written scope, so ask for the scope items that drive effort before signing.
