Repository navigation
Conversation
There was a problem hiding this comment.
🟡 Changes recommended
Missing ownership and service-sharing checks can modify or delete other routes’ Kong entities, while prefix removal can leave old routes and plugins active.
4 open issues
2 files not reviewed
gateway/api/v1/zz_generated.deepcopy.go: Generated filegateway/internal/features/mock/mock_FeaturesBuilder.go: Generated file
What changed in this PR
This PR adds realm-prefixed Kong entity names to isolate environments sharing one Kong instance. Building on #805, it adds in-place legacy migration and route-ID-based plugin adoption.
Changes:
- Add Gateway name prefixes, admin assignment, validation, and reconciliation on prefix changes.
- Introduce legacy discovery, ownership and conflict checks, plugin slot adoption, and coordinated circuit-breaker updates.
- Preserve status IDs, decode untyped success responses, and expand tests and migration documentation.
| File | Description |
|---|---|
| tools/snapshotter/go.sum | Update dependency checksums. |
| tools/snapshotter/go.mod | Update indirect dependencies. |
| gateway/pkg/kongutil/migrator_test.go | Test migrator cache invalidation. |
| gateway/pkg/kongutil/client_factory.go | Inject migrators into cached clients. |
| gateway/pkg/kong/naming/suite_test.go | Register naming test suite. |
| gateway/pkg/kong/naming/naming.go | Derive desired and legacy names. |
| gateway/pkg/kong/naming/naming_test.go | Test naming and candidate deduplication. |
| gateway/pkg/kong/legacy/testdata/legacy-naming.yaml | Supply migration test configuration. |
| gateway/pkg/kong/legacy/testdata/java-routes/default-api.yaml | Add default-realm API fixture. |
| gateway/pkg/kong/legacy/testdata/java-routes/default-ai.yaml | Add default-realm AI fixture. |
| gateway/pkg/kong/legacy/testdata/java-routes/bond-voyager.yaml | Add Voyager migration fixture. |
| gateway/pkg/kong/legacy/testdata/java-routes/bond-sse.yaml | Add SSE migration fixture. |
| gateway/pkg/kong/legacy/testdata/java-routes/bond-publish.yaml | Add event-publishing migration fixture. |
| gateway/pkg/kong/legacy/testdata/java-routes/bond-callback.yaml | Add callback migration fixture. |
| gateway/pkg/kong/legacy/testdata/java-routes/bond-api.yaml | Add prefixed API migration fixture. |
| gateway/pkg/kong/legacy/suite_test.go | Register legacy test suite. |
| gateway/pkg/kong/legacy/migrator.go | Load rules and generate legacy candidates. |
| gateway/pkg/kong/legacy/migrator_test.go | Test migration rules and validation. |
| gateway/pkg/kong/client/upstream.go | Separate upstream discovery from writes. |
| gateway/pkg/kong/client/upstream_test.go | Test raw target-response decoding. |
| gateway/pkg/kong/client/types.go | Define realm and upstream interfaces. |
| gateway/pkg/kong/client/route.go | Coordinate discovery, migration, and deletion. |
| gateway/pkg/kong/client/response.go | Decode untyped successful responses. |
| gateway/pkg/kong/client/realm_route_errors_test.go | Test discovery and API failures. |
| gateway/pkg/kong/client/plugin/util.go | Add route-binding helpers. |
| gateway/pkg/kong/client/plugin/rtp.go | Expose transformer route ID and prefix. |
| gateway/pkg/kong/client/plugin/route_binding_test.go | Test plugin route bindings. |
| gateway/pkg/kong/client/plugin/request_termination.go | Expose termination-plugin binding. |
| gateway/pkg/kong/client/plugin/ratelimit.go | Bind rate limits to route IDs. |
| gateway/pkg/kong/client/plugin/jwt.go | Expose JWT-plugin binding. |
| gateway/pkg/kong/client/plugin/acl.go | Expose ACL-plugin binding. |
| gateway/pkg/kong/client/plugin.go | Write plugins using route IDs. |
| gateway/pkg/kong/client/plugin_helpers_test.go | Add slot-lookup test helpers. |
| gateway/pkg/kong/client/plugin_discovery.go | Adopt legacy plugins by route slot. |
| gateway/pkg/kong/client/plugin_discovery_test.go | Test slot adoption and ownership. |
| gateway/pkg/kong/client/plugin_cleanup.go | Resolve cleanup routes by ID. |
| gateway/pkg/kong/client/plugin_cleanup_test.go | Test ID-based cleanup scope. |
| gateway/pkg/kong/client/ownership.go | Define entity ownership predicates. |
| gateway/pkg/kong/client/located_entity.go | Update discovered entities by ID. |
| gateway/pkg/kong/client/legacy_roundtrip_test.go | Test slot adoption over HTTP. |
| gateway/pkg/kong/client/kongclient.go | Add migrator options and lookup APIs. |
| gateway/pkg/kong/client/kinds.go | Adapt entity types and paginate lists. |
| gateway/pkg/kong/client/helpers_test.go | Add blocked-error assertion helper. |
| gateway/pkg/kong/client/fake_kong_test.go | Provide in-memory Kong test server. |
| gateway/pkg/kong/client/discovery.go | Implement discovery and conflict policies. |
| gateway/Makefile | Include naming and migration coverage. |
| gateway/internal/handler/route/handler.go | Apply Gateway prefixes to Routes. |
| gateway/internal/handler/route/handler_test.go | Test prefix propagation. |
| gateway/internal/features/mock/mock_FeaturesBuilder.go | Update generated upstream accessor mock. |
| gateway/internal/features/feature/ratelimit_test.go | Update rate-limit construction tests. |
| gateway/internal/features/feature/circuit_breaker.go | Defer upstream changes to Kong client. |
| gateway/internal/features/feature/circuit_breaker_test.go | Test deferred upstream operations. |
| gateway/internal/features/builder.go | Rebuild properties while retaining IDs. |
| gateway/internal/features/builder_test.go | Test status and circuit-breaker handling. |
| gateway/internal/controller/suite_test.go | Record reconciled Kong names. |
| gateway/internal/controller/route_controller.go | Watch Gateway prefix changes. |
| gateway/internal/controller/index.go | Index Routes by Gateway reference. |
| gateway/internal/controller/controller_test.go | Test prefix reconciliation and validation. |
| gateway/go.mod | Declare direct YAML dependency. |
| gateway/config/samples/legacy_naming_configmap.yaml | Provide sample migration configuration. |
| gateway/config/crd/bases/gateway.cp.ei.telekom.de_gateways.yaml | Add prefix schema and transition validation. |
| gateway/cmd/main.go | Load optional migration configuration. |
| gateway/api/v1/zz_generated.deepcopy.go | Generate runtime-state deep copies. |
| gateway/api/v1/route_types.go | Add runtime naming and property rebuilding. |
| gateway/api/v1/gateway_types.go | Define validated Gateway name prefix. |
| docs/docs/architecture/sftp.mdx | Reposition heading around SPDX comment. |
| docs/docs/architecture/gateway.mdx | Document naming, status, and plugin adoption. |
| docs/docs/architecture/gateway-realm-migration.mdx | Explain migration rules and limitations. |
| docs/docs/architecture/file.mdx | Reposition heading around SPDX comment. |
| docs/docs/architecture/agentic.mdx | Move SPDX comment below front matter. |
| docs/docs/architecture/admin.mdx | Document admin-assigned prefixes. |
| admin/internal/handler/zone/handler_test.go | Test realm-derived Gateway prefixes. |
| admin/internal/handler/zone/gateway.go | Assign and preserve Gateway prefixes. |
Review effort: Balanced
| return nil, ctrlerrors.BlockedErrorf("gateway %q is not ready", route.Spec.GatewayRef.Name) | ||
| } | ||
| // The Kong names of the Route use the prefix of its Gateway. | ||
| route.SetNamePrefix(gateway.Spec.NamePrefix) |
There was a problem hiding this comment.
🤖 AI-generated reply (Copilot), on behalf of @rgummich.
Valid, fixed in f021e14. The Route records the prefix it was built with in the status property namePrefix.
- Reconcile: if the Route has a recorded prefix and its Gateway has none,
newFeatureBuilderreturns aBlockedErrorand writes nothing. That covers the line-116 path too. - Delete: if the Gateway has no prefix, the recorded one is used. Discovery then still finds
P--Rby its stored IDs, so its route, service and plugins are removed.
Tests: handler_test.go (blocked reconcile; delete table entries for the recorded prefix and for the Gateway prefix taking precedence).
| if d.kind.entName(current) == d.names.Desired { | ||
| return current, origin, nil | ||
| } | ||
| if err := d.checkConflicts(ctx, current, named); err != nil { | ||
| return nil, origin, err | ||
| } | ||
| return d.checkShared(ctx, current, origin) | ||
| } | ||
|
|
||
| // checkShared asks the policy what to do with an entity found through its parent or a legacy | ||
| // name that another Kong entity uses as well. Skipping it means nothing was found. | ||
| func (d *discovery[Req, Resp]) checkShared(ctx context.Context, current *Resp, origin Origin) (*Resp, Origin, error) { | ||
| if d.sharedWith == nil || (origin != OriginParent && origin != OriginPreMigration && origin != OriginLegacy) { |
There was a problem hiding this comment.
🤖 AI-generated reply (Copilot), on behalf of @rgummich.
Valid, fixed in f021e14. The sharing guard no longer depends on how the service was found:
- Reconcile: a service that is about to be renamed is checked whichever step found it (stored ID, CP tags, parent, pre-migration or legacy). That closes the first-migration gap for pre-PR stored IDs.
- Delete: the check always runs, including a service already named
P--R(deletePolicy.checksSharingAlways()), so a shared service is skipped instead of hitting Kong's foreign-key error. - Not changed: a normal reconcile of a service already under its desired name still skips the check, so steady-state reconciles make no extra
GET /services/{id}/routes. Updating a service by name behaves as it did before this PR.
Tests: realm_route_test.go (blocked rename of a shared service found by stored ID; delete skipping a shared service under its new name).
| if err != nil { | ||
| return nil, OriginNone, fmt.Errorf("looking up %s by id: %w", d.kind.name, err) | ||
| } | ||
| return current, origin, nil |
There was a problem hiding this comment.
🤖 AI-generated reply (Copilot), on behalf of @rgummich.
Valid, fixed in f021e14. lookupID, used for stored and parent IDs, now applies notClaimedElsewhere(env, route). An ID hit whose env-- or route-- tag names another environment or route is logged and skipped, in both reconcile and delete. Entities without CP tags, such as legacy ones, are still accepted.
I chose skip-and-continue over blocking: a stale shared ID would otherwise block the Route permanently. With skipping, discovery continues; if the other environment hasn't migrated yet, the pre-migration name lookup reports a foreign owner and blocks. Once it has migrated, this Route creates its own P--R.
Tests: realm_route_test.go (reconcile ignores an ID claimed by env--cit2 and creates its own route; delete leaves that entity untouched).
| IssuerUrl: issuerURL, | ||
| Url: config.Admin.Url, | ||
| }, | ||
| NamePrefix: gatewayNamePrefix(gateway.Spec.NamePrefix, hc.Zone.Status.RealmName), |
There was a problem hiding this comment.
🤖 AI-generated reply (Copilot), on behalf of @rgummich.
Valid, fixed in f021e14, with a compatibility path rather than an admission change:
gatewayv1.IsValidNamePrefixmatches the CRD pattern and the 63-character limit.- If the effective realm name isn't a valid prefix (for example
qa--blue), the admin operator keeps the Gateway's current prefix (usually none) and logs it, instead of failing every Gateway update. Such environments keep their pre-PR unprefixed Kong names. - I didn't add webhook validation for new Environments. A CEL rule on
metadata.namewould also run on updates and could break existing Environments, and the fallback already keeps them working. The docs (environments-and-zones.md,admin.mdx) describe the limitation.
Tests: gatewayNamePrefix table entries for a double hyphen, too long a name, and keeping an existing prefix.
The merge-base changed after approval.
f59cfd6 to
8c6db1d
Compare
a7c5f56 to
2963b0c
Compare
The comment above or before the front matter kept Docusaurus from reading it, so agentic, file and sftp rendered with the file name as title.
Several virtual environments can share one Kong, so naming Kong entities after Route.metadata.name lets them overwrite each other. Gateway.spec.namePrefix now names the route, service and circuit-breaker upstream of every Route on that Gateway "<namePrefix>--<metadata.name>" and adds a realm--<namePrefix> tag. A set prefix can be changed but not removed (CEL). Existing entities are adopted and renamed in place by ID. Discovery runs stored ID, new name, CP tags, pre-migration name and Java candidates from the optional --legacy-naming-config file. Name lookups check ownership; foreign entities, taken target names and owned duplicates block the reconcile before any write and are skipped on delete. Legacy ei__telekom__de--* tags are kept. Plugins bind to their route by Kong route ID. Legacy plugins are adopted by their slot on the route, replacing the fixed legacy realm tag lookup. The builder rebuilds status properties instead of resetting them midway, so circuit-breaker IDs persist, and records routeName, namePrefix and legacyName. The circuit breaker hands its upstream to the Kong client, which writes it after all lookups succeeded and updates the service before deleting an upstream. Kong 201 responses are decoded from the raw body.
The zone handler writes zone.Status.RealmName to Gateway.spec.namePrefix, so all Routes on the Gateway get realm-prefixed Kong names. An existing prefix is kept when the realm name is empty, because a set prefix cannot be removed.
Use legacy-compatible horizon names for event Routes. Remove name rewriting rules and label selectors from the gateway migrator. Update tests, configuration examples, and migration documentation.
…d-mock check Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Scope route watch lookups to their source environment and correct the backend description. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Block Route deletion while the Gateway is not ready instead of dereferencing the nil Gateway returned by GetGatewayByRef. Check Route and Consumer for nil before Build and BuildForConsumer read their names, so they return ErrNoRoute and ErrNoConsumer. Skip the initial list on the Gateway watch of the Route controller. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2963b0c to
c7ea2da
Compare
| // makePublishEventsRoutePath returns the main downstream path of the publish route. | ||
| func makePublishEventsRoutePath() string { | ||
| return eventv1.HorizonPublishEventPathSuffix | ||
| return horizonPrefix("") + "/events/v1" |
There was a problem hiding this comment.
Why is this horizonPrefix("") and rest horizon
There was a problem hiding this comment.
🤖 AI-generated reply (Copilot), on behalf of @rgummich.
The split is intentional: horizonPrefix("") builds a path prefix (/horizon, or /horizon-<zone> for mesh routes), while the bare horizon constant is used for Route names (horizon-events, horizon-sse--…), which must match the legacy Kong base names.
However, makePublishEventsRoutePath() had duplicated the shared constant eventv1.HorizonPublishEventPathSuffix (/horizon/events/v1, also used by rover-server). Fixed in 17c0f92: it returns the shared constant again.
|
|
||
| // gatewayNamePrefix returns the Kong name prefix of a Gateway: the zone's realm name, or the | ||
| // current prefix if the realm name is empty, because a set prefix cannot be removed. | ||
| func gatewayNamePrefix(current, realmName string) string { |
There was a problem hiding this comment.
I want a new feature-flag called LEGACY_GATEWAY_NAMING. If its true then we will omit the namePrefix if realmName=="default". Otherwise, we will use the use the (e *Environment) GetRealmName().
There was a problem hiding this comment.
🤖 AI-generated reply (Copilot), on behalf of @rgummich.
Done in 17c0f92:
- New feature flag
FeatureLegacyGatewayNamingincommon/pkg/config/feature.go. It follows the existing flag convention, so the env var isFEATURE_LEGACY_GATEWAY_NAMING_ENABLED(defaultfalse). gatewayNamePrefixnow useshc.Environment.GetRealmName(). If the flag is on and the realm isdefault, no prefix is set.- Edge case: if a
defaultGateway already has a prefix when the flag is turned on, the prefix is kept. The CRD rejects removing a set prefix, so clearing it would fail every Gateway update. - The old "empty realm keeps the current prefix" fallback is gone, because
GetRealmName()falls back to the environment name and is never empty. - Table test extended;
gateway.mdx,gateway-realm-migration.mdxand the design doc describe the flag.
|
|
||
| // GatewaySpec defines the desired state of Gateway | ||
| // | ||
| // +kubebuilder:validation:XValidation:rule="!has(oldSelf.namePrefix) || size(oldSelf.namePrefix) == 0 || (has(self.namePrefix) && size(self.namePrefix) != 0)",message="namePrefix cannot be removed once set" |
There was a problem hiding this comment.
has this been verified to work?
There was a problem hiding this comment.
🤖 AI-generated reply (Copilot), on behalf of @rgummich.
Yes. gateway/internal/controller/controller_test.go (Describe("validation")) runs the rule against a real kube-apiserver via envtest: it sets a prefix, changes it (allowed), then empties it and asserts IsInvalid with namePrefix cannot be removed once set. A DescribeTable also covers the pattern and length constraints. It passes in CI and locally with make test. No change needed.
|
|
||
| // KongName returns the name of the Kong entities of this Route: "<namePrefix>--<metadata.name>" | ||
| // if the prefix is set, otherwise metadata.name. | ||
| func (g *Route) KongName() string { |
There was a problem hiding this comment.
Can we rename this to FullName or ID. So decouple it from the Kong product
There was a problem hiding this comment.
🤖 AI-generated reply (Copilot), on behalf of @rgummich.
Renamed to GetFullName() in 17c0f92, decoupling it from Kong. It returns <namePrefix>--<metadata.name>, or metadata.name without a prefix. I chose FullName over ID because ID would clash with the Kong IDs (routeId/serviceId/upstreamId) that the Route also tracks. The RealmRoute interface, all callers and the design doc are updated.
| } | ||
|
|
||
| // GetKongName implements the RealmRoute interface for Route. | ||
| func (g *Route) GetKongName() string { |
There was a problem hiding this comment.
Why is that and the KongName needed? Seems like a dupe
There was a problem hiding this comment.
🤖 AI-generated reply (Copilot), on behalf of @rgummich.
Agreed, it was a duplicate. KongName() and GetKongName() are replaced by a single GetFullName() in 17c0f92, which also satisfies the RealmRoute interface.
- admin: add FEATURE_LEGACY_GATEWAY_NAMING_ENABLED; when enabled, Gateways of the "default" realm get no namePrefix. Otherwise the prefix is the environment's realm name (Environment.GetRealmName()). - gateway: replace Route.KongName()/GetKongName() with GetFullName() to decouple the API from Kong. - event: reuse eventv1.HorizonPublishEventPathSuffix for the publish path. - docs: describe the legacy gateway naming flag and the rename. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- gateway: block a Route built with a name prefix whose Gateway has none; a delete uses the recorded prefix instead. - gateway: ignore Kong entities found by stored or parent ID whose env-- or route-- tag names another environment or route. - gateway: check service sharing before every rename and every delete, whichever discovery step found the service. - gateway: sort RouteListeners by name before building. - admin: keep the current Gateway namePrefix if the realm name is no valid prefix (for example with "--" or longer than 63 characters). - docs: describe the new behavior. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>


Builds on #805 (merged). The branch is rebased onto
mainand contains only this PR's commits.Summary
Gateway.spec.namePrefixnames the route, service and circuit-breaker upstream of every Route on the Gateway<namePrefix>--<metadata.name>and adds arealm--<namePrefix>tag. This keeps virtual environments that share one Kong apart. The prefix can be changed but not removed (CEL rule). Gateways without a prefix keep the old behaviour.zone.Status.RealmNameto the Gateway. API and AI routes on one Gateway share the prefix; agentic names (ai-gateway--…) keep them apart. No changes are needed in the api, agentic or event operators.env--,route--) → pre-migration name → Java operator names from the optional--legacy-naming-configfile (<realm>.<name>, the-airealm, event base-name mapping). They are renamed with aPUTby ID, and legacyei__telekom__de--*tags are kept.GET /routes/{id}/plugins). This replaces the fixedLegacyPluginTaglookup from fix(gateway): discover and reuse legacy Kong plugins #805.upstreamId/targetsIdnow persist.routeName,namePrefixandlegacyNameare recorded.201responses (target create) are decoded from the raw body.architecture/gateway.mdxand the newarchitecture/gateway-realm-migration.mdx(diagrams),admin.mdx, the design docdocs/design/gateway-realm.md, and SPDX placement fixes on agentic/file/sftp pages.Tests
make verify MODULES="gateway admin"passed: REUSE, gitleaks, tidy, build, lint (0 issues).make testpasses ingateway/(12 packages) andadmin/.gateway/pkg/kong/legacy/testdata/java-routes.Notes
config/samples/legacy_naming_configmap.yamlis a sample only. The admin-journey docs are a follow-up.hack/boilerplate.yaml.txthas CRLF line endings, somake buildregenerates CRD headers with CRLF (normalized by git). This is pre-existing and unchanged here.