> For the complete documentation index, see [llms.txt](https://docs.kangal.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kangal.dev/migration/kong.md). # Migrate from Kong This guide describes a controlled migration from Kong to Kangal. Kangal uses familiar gateway entities, but it is not a drop-in Kong Admin API or decK replacement. Plan an explicit model conversion, plugin review, security review, and traffic cutover. ## Migration principles 1. Inventory before translating. 2. Map behavior, not only entity names. 3. Move secret references, never exported plaintext values. 4. Validate and diff before every write. 5. Run both gateways against representative traffic before cutover. 6. Keep source configuration unchanged until Kangal acceptance is complete. 7. Define rollback around traffic ownership and data changes, not only deployments. ## Resource mapping | Kong concept | Kangal destination | Migration note | | -------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------ | | Workspace/control-plane boundary | Tenant, workspace, and gateway | Decide tenancy and ownership before importing entities | | Service | Service | Reconfirm protocol, destination URL or upstream reference, timeouts, retries, and gateway scope | | Route | Route | Re-test host, path, method, header, query, SNI, strip-path, preserve-host, and priority behavior | | Upstream | Upstream | Recreate load-balancing and health policy explicitly | | Target | Target | Preserve host/port and weight intent; re-establish health state from live probes | | Consumer | Consumer | Resolve duplicate usernames and tenant ownership before credential creation | | Credential | Consumer credential | Supported Kangal types include API key, HMAC, basic, and JWT; rotate during migration | | Plugin | Built-in or packaged plugin | Plugin names and schemas are not assumed to be identical | | Certificate and SNI | Certificate, CA certificate, and SNI | Import through the approved secret/certificate path; verify the served chain | | Vault reference | Tenant-scoped vault reference | Rewrite to an approved Kangal `vault://` provider path | | Declarative state | Kangal config bundle | Convert to Kangal YAML/JSON; do not submit a decK file unchanged | Custom Lua, external plugin servers, proprietary plugins, and side effects require a separate implementation and performance review. A matching label in a feature matrix does not prove equivalent request ordering, failure mode, or configuration semantics. ## Compatibility endpoints Kangal exposes the following Kong-style nested Admin API aliases to reduce client changes during migration: ``` GET|POST /api/v1/admin/gateways/{gateway_id}/services/{service_id_or_name}/routes GET|POST /api/v1/admin/gateways/{gateway_id}/upstreams/{upstream_id}/targets GET|POST /api/v1/admin/gateways/{gateway_id}/certificates/{certificate_id}/snis GET|POST /api/v1/admin/consumers/{consumer_id}/credentials ``` Unversioned `/admin/...` forms are also registered for compatibility. The aliases require Kangal admin authentication and enforce Kangal tenant scoping. The service route alias accepts a service ID or name; target creation accepts `target` as an alias for the target name. Use these aliases only for the listed nested resource operations. Convert declarative state and every other administration workflow to the Kangal configuration bundle, CLI, or versioned Admin API before cutover. ## Phase 1: inventory Export the source declarative configuration with the approved Kong/decK workflow and store it as restricted migration evidence. Record: * Kong and decK versions, deployment topology, workspaces, and data planes; * services, routes, upstreams, targets, consumers, credentials, certificates, SNIs, vaults, and plugin instances at every scope; * route match rules, path handling, protocol, timeout, retry, buffering, and header behavior; * plugin ordering, custom code, external calls, fail-open/fail-closed behavior, and secret fields; * current request volume, latency, errors, 4xx/5xx distribution, upstream health, connection behavior, and rate-limit state; * DNS TTL, load-balancer weights, client certificate expectations, and rollback path. Do not place credential values from the export in the transformed Kangal file. Create new credentials or vault references and rotate clients during the migration. ## Phase 2: transform Create a tenant-scoped Kangal bundle. Stable IDs can be supplied when relationships need them; otherwise use deterministic names and verify the resulting IDs before adding dependent records. ```yaml tenant_id: acme gateways: - id: gw-edge tenant_id: acme name: edge services: - id: svc-orders tenant_id: acme gateway_id: gw-edge name: orders url: https://orders.internal.example routes: - tenant_id: acme gateway_id: gw-edge service_id: svc-orders service_name: orders path: /orders methods: [GET, POST] strip_path: true preserve_host: false upstreams: [] targets: [] consumers: [] consumer_credentials: [] certificates: [] snis: [] vaults: [] ``` Set a direct service destination with `url`. For a managed backend pool, omit `url`, set the service's `upstream_id` or `upstream_name`, and include the referenced upstream and targets in the bundle. `upstream_url` is not a gateway or service bundle field. Transform one gateway at a time. Preserve an explicit mapping file containing source ID, Kangal ID/name, owner, conversion status, validation result, and exception reason. Do not embed source exports or secrets in that mapping. ## Phase 3: validate and preview Store an admin context, then run the public CLI: ```bash python scripts/kangalctl.py login \ --api-url "$KANGAL_API" \ --token "$KANGAL_ADMIN_TOKEN" \ --tenant-id acme \ --context-name migration python scripts/kangalctl.py validate kangal-acme.yaml --strict python scripts/kangalctl.py diff kangal-acme.yaml --tenant-id acme --strict python scripts/kangalctl.py sync kangal-acme.yaml \ --tenant-id acme \ --snapshot-note "pre-migration preview" \ --created-by migration-operator ``` `sync` is dry-run unless `--apply` is supplied. Review validation errors, warnings, fingerprint, insert/update/skip counts, removed resources, and every changed secret reference. Strict validation turns missing route-to-service and route/service-to-upstream references within the bundle into errors. It does not validate every resource field, resolve references from live state, prove upstream reachability, or prove plugin equivalence. ## Phase 4: apply in staging ```bash python scripts/kangalctl.py sync kangal-acme.yaml \ --tenant-id acme \ --apply \ --snapshot-note "before Kong migration staging apply" \ --created-by migration-operator ``` The apply flow validates, diffs, previews, creates a pre-apply Kangal configuration snapshot, and imports. The snapshot is not a MongoDB backup and does not include external systems. After apply: 1. Create or rotate credentials through approved secret channels. 2. Verify service, route, upstream, target, consumer, certificate, and plugin counts. 3. Test positive and negative authentication cases. 4. Compare route matching, path/header transformations, retries, timeouts, load balancing, health checks, rate limits, and error responses. 5. Run WebSocket, gRPC, TCP, TLS/mTLS, streaming, and large-body tests when used. 6. Compare logs, metrics, traces, latency, upstream error rate, and consumer identity. 7. Confirm tenant isolation and admin RBAC with cross-tenant negative tests. ## Phase 5: shadow and canary traffic Prefer replay or shadow traffic that cannot duplicate writes. For state-changing requests, use synthetic tenants, idempotency keys, or read-only test paths. Redact captured payloads and authorization material. Move a small, observable client or load-balancer weight first. Hold each step long enough to cover normal cache, connection, retry, and rate-limit windows. Compare: * success and error rate by route and status code; * p50, p95, and p99 latency; * upstream selection and health behavior; * authentication decisions and consumer attribution; * plugin side effects, headers, and body transformations; * connection reuse, WebSocket/gRPC lifecycle, and timeout behavior. Stop on tenant leakage, authentication divergence, unexpected mutation, material SLO regression, unmatched routes, duplicated side effects, or loss of rollback evidence. ## Phase 6: cutover 1. Freeze source configuration changes or establish a final change reconciliation. 2. Export final Kong state and rerun the mapping diff. 3. Take a verified Kangal database backup and configuration snapshot. 4. Re-run Kangal strict validate, live diff, and acceptance tests. 5. Lower DNS TTL in advance if DNS participates in cutover. 6. Shift traffic in approved increments while watching both platforms. 7. Keep Kong available but read-only/unchanged for the rollback window. 8. Rotate any migration-only credentials and remove temporary compatibility access. ## Rollback and decommission Traffic rollback returns ownership to Kong; it does not automatically remove writes already accepted through Kangal. Define reconciliation for each state-changing API before cutover. If Kangal configuration itself must be reverted, use the recorded pre-apply snapshot only after reviewing its strict diff; use database restore only under the recovery runbook. Decommission Kong only after the rollback window closes, client DNS/config has converged, no traffic or admin automation reaches it, audit and compliance evidence is retained, secrets and certificates are rotated or revoked, and the final migration report is approved. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.kangal.dev/migration/kong.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.