Skip to content

feat(gateway): add migration mode for the Kong takeover - #876

Open
ron96g wants to merge 1 commit into
feat/gateway-realm-namingfrom
feat/gateway-migration-mode
Open

ron96g wants to merge 1 commit into
feat/gateway-realm-namingfrom
feat/gateway-migration-mode

Conversation

@ron96g

@ron96g ron96g commented Nov 20, 2026

Copy link
Copy Markdown
Member

🤖 PR description generated by Copilot.

Stacked on #816 (feat/gateway-realm-naming). Merge that first; GitHub then retargets this PR to main.

What

Adds Migration Mode to the Gateway operator. While the legacy Java operator still manages Kong, it checks the operator's Kong changes before writing them. An unexpected change is blocked, and a human can review it and approve it.

  • --migration-mode=off|on|strict (default off)
    • on: the changes are written only if every diff is on the ignore list, or if they are approved.
    • strict: every change needs an approval, even if all diffs are ignored.
  • One bundle per Route or Consumer. Each reconcile first runs a plan. It records every create, update and delete across the upstream and targets, service, route, plugins, consumer, consumer-group membership and deletes, and writes nothing. The bundle is then decided on once, and only an allowed or approved bundle is applied. Entities that don't exist yet get planned-- placeholder IDs, so the entities that depend on them can be planned too.
  • Diff: normalized JSON, compared the same way the operator compares a normal reconcile. Diffs are reported by JSON path ($.tags, $.config.minute, …).
  • Ignore list: --migration-ignore-config, a YAML file with kind, an optional name regex and paths (.* and [*] are wildcards). A sample is in gateway/config/samples/migration_ignore_configmap.yaml.
  • Review: a blocked object gets the temporary field status.migration, which lists every change with its desired and current values and the hash.
  • Approval: set the annotation gateway.cp.ei.telekom.de/migration-approved-hash=<status.migration.hash>. The next reconcile plans again and writes only if the hash is unchanged. Any other change (to the Route, to Kong or to the ignore list) is blocked again.
  • Metrics: gateway_kong_migration_checks_total and gateway_kong_migration_diffs_total.

Docs

Testing

  • Gateway make test: unit tests for the plan, hash, decision, modes and ignore rules. Fake-Kong tests plan the adoption of a real Java route snapshot without writing and then apply it, plan a delete, and plan a new service, route and plugin as one bundle. Handler tests cover a blocked change with the status set, then its approval with the status removed, for both create and delete.
  • make lint: no new findings.
  • Snapshotter still builds.
  • Code auditor: staged and full-range audits have no findings at or above HIGH.

Known limits

  • In Migration Mode, every reconcile reads Kong twice (plan and apply). Kong could change in the short window between them.
  • Only entities the Go operator writes are compared. Configuration managed only by Java isn't reported.

Compare the Kong changes of a Route or Consumer with the current Kong
state before writing them, so the switch from the legacy operator
cannot change Kong unnoticed.

- --migration-mode=off|on|strict: on blocks unexpected diffs, strict
  requires an approval for every change.
- Plan the whole bundle (upstream, targets, service, route, plugins,
  consumer, group, deletes) without writing, decide once, then apply.
- Diff normalized JSON by path; expected diffs come from an ignore list
  (--migration-ignore-config) with kind, name pattern and JSON paths.
- Show blocked changes in the temporary status.migration field and
  approve them with gateway.cp.ei.telekom.de/migration-approved-hash.
- Metrics gateway_kong_migration_checks_total and
  gateway_kong_migration_diffs_total.
- Docs and ADRs 0001-0011 under docs/adrs.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant