Skip to content
Open
Show file tree
Hide file tree
Changes from 8 commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .agents/auditignore
Original file line number Diff line number Diff line change
Expand Up @@ -8,3 +8,5 @@
#
# Audit ignores expire by construction: the item id contains the snippet, so
# changing the code retires the audit ignore automatically. Only a human adds a line here.

8fe17c6fb41aa522: Accepted temporarily: immutability is enforced by the Environment webhook; CEL enforcement and comment alignment are deferred. (ron96g, 2026-11-13)
12 changes: 11 additions & 1 deletion admin/internal/handler/zone/gateway.go
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,8 @@ func createGateway(ctx context.Context, hc *HandlingContext, config *adminapi.Ga
IssuerUrl: issuerURL,
Url: config.Admin.Url,
},
TLS: hc.managedTLS(),
NamePrefix: gatewayNamePrefix(gateway.Spec.NamePrefix, hc.Zone.Status.RealmName),

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 AI-generated reply (Copilot), on behalf of @rgummich.

Valid, fixed in f021e14, with a compatibility path rather than an admission change:

  • gatewayv1.IsValidNamePrefix matches 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.name would 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.

TLS: hc.managedTLS(),
}

if hc.Zone.Spec.Redis != nil {
Expand All @@ -108,6 +109,15 @@ func createGateway(ctx context.Context, hc *HandlingContext, config *adminapi.Ga
return gateway, nil
}

// 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 {

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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().

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 AI-generated reply (Copilot), on behalf of @rgummich.

Done in 17c0f92:

  • New feature flag FeatureLegacyGatewayNaming in common/pkg/config/feature.go. It follows the existing flag convention, so the env var is FEATURE_LEGACY_GATEWAY_NAMING_ENABLED (default false).
  • gatewayNamePrefix now uses hc.Environment.GetRealmName(). If the flag is on and the realm is default, no prefix is set.
  • Edge case: if a default Gateway 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.mdx and the design doc describe the flag.

if realmName == "" {
return current
}
return realmName
}

// createGatewayConsumer creates the default gateway consumer for the zone.
func createGatewayConsumer(ctx context.Context, hc *HandlingContext, gatewayName string, gateway *gatewayapi.Gateway) (*gatewayapi.Consumer, error) {
c := cclient.ClientFromContextOrDie(ctx)
Expand Down
12 changes: 12 additions & 0 deletions admin/internal/handler/zone/handler_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,16 @@ import (
. "github.com/onsi/gomega"
)

var _ = DescribeTable("gatewayNamePrefix",
func(current, realmName, expected string) {
Expect(gatewayNamePrefix(current, realmName)).To(Equal(expected))
},
Entry("set from the realm", "", "bond", "bond"),
Entry("realm replaces an existing prefix", "old", "bond", "bond"),
Entry("empty realm keeps the existing prefix", "bond", "", "bond"),
Entry("empty realm without existing prefix stays unset", "", "", ""),
)

var _ = Describe("Zone Handler", func() {
var zone *adminv1.Zone
var zoneIdx int
Expand Down Expand Up @@ -89,7 +99,9 @@ var _ = Describe("Zone Handler", func() {
Expect(clients.Items[0].Name).To(Equal(naming.ForGatewayAdminClient(naming.ForIdentityProvider(zone, "primary"))))
Expect(clients.Items[0].Spec.ClientId).To(Equal("rover"))
Expect(clients.Items[0].Spec.ClientSecret).NotTo(BeEmpty())
Expect(zone.Status.RealmName).NotTo(BeEmpty())
for i := range gateways.Items {
Expect(gateways.Items[i].Spec.NamePrefix).To(Equal(zone.Status.RealmName))
Expect(gateways.Items[i].Spec.Admin.ClientId).To(Equal("rover"))
Expect(gateways.Items[i].Spec.Admin.ClientSecret).To(Equal(clients.Items[0].Spec.ClientSecret))
}
Expand Down
426 changes: 426 additions & 0 deletions docs/design/gateway-realm.md

Large diffs are not rendered by default.

2 changes: 2 additions & 0 deletions docs/docs/architecture/admin.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,8 @@ Zone deletion deliberately retains the client and its stored secret; deleting th

Every named gateway exposes issuer, certificate, and OpenID discovery routes for the default realm and the internal `rover` realm, plus the team-api realm when configured. These routes cover the hostnames and base paths of all presets using that gateway. World-visible zones add `/spacegate` after the preset base path.

Every Gateway gets `spec.namePrefix` set to the zone's realm name (`zone.status.realmName`, which falls back to the environment name). The Gateway operator prefixes the Kong names of all Routes on that Gateway with it, so virtual environments sharing one Kong stay apart (see [Kong entity naming and realms](./gateway.mdx#kong-entity-naming-and-realms)). An existing prefix is kept if the realm name is ever empty, since a set prefix cannot be removed.

Admin also creates an owned `<gateway>--zone-health` passthrough route for every gateway, independent of managed routes and DTC. It covers every preset hostname and base path without `/spacegate`. Its `spec.traffic.healthProbe: true` flag tells Gateway to answer HEAD probes with 200 without contacting an upstream. The Route CRD gains this optional boolean; the Zone CRD is unchanged. Shared preflight validation checks the 20-hostname and 10-distinct-path Route limits before creating identity or health routes. Stale-route cleanup removes health routes when their gateway is removed.

Zone admission and reconciliation share aggregation, normalized path construction, and cardinality validation in `admin/internal/routeinputs`. Create/update admission rejects excessive inputs with field-specific errors; the controller retains a defensive blocked-error check for existing invalid Zones. Fixed identity and health suffixes preserve the number of distinct normalized base paths, so validation does not depend on provisioned realm names or visibility.
Expand Down
14 changes: 7 additions & 7 deletions docs/docs/architecture/agentic.mdx
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
<!--
SPDX-FileCopyrightText: 2026 Deutsche Telekom AG

SPDX-License-Identifier: CC0-1.0
-->

---
sidebar_position: 16
---

# Agentic Domain

<!--
SPDX-FileCopyrightText: 2026 Deutsche Telekom AG

SPDX-License-Identifier: CC0-1.0
-->

The Agentic domain manages the lifecycle of MCP (Model Context Protocol) servers within the Control Plane — from server registration through exposure to subscription. It acts as an abstraction layer above the Gateway domain, handling business logic for who can access which MCP servers and under what conditions.

## Custom Resources
Expand Down Expand Up @@ -132,7 +132,7 @@ Subscribers in other zones keep their own proxy routes, which only allow the sub

If the Telecontext Application does not exist, is not ready, or has no client ID, the exposure is blocked. The operator does not change the existing routes and keeps them in the exposure status, so subscriptions keep their route reference. The exposure controller does not watch Applications, so a Telecontext Application that becomes ready later is picked up at the next periodic reconcile.

This mirrors how the legacy Java controlplane handled Telecontext integration: iterating all zones and creating proxy routes where the Telecontext Application is located, plus granting access via a dedicated RoutePermission (now replaced by the `DefaultConsumers` mechanism).
This preserves legacy-compatible Telecontext integration behavior: iterating all zones and creating proxy routes where the Telecontext Application is located. Access is now granted through `DefaultConsumers` rather than a dedicated RoutePermission.

**Why not a ConsumeRoute?** A `ConsumeRoute` is namespace-scoped and goes through the approval flow. `DefaultConsumers` is a gateway-level bypass that is more appropriate for a trusted platform component that needs seamless, always-on access to TeleMCP servers across the whole platform.

Expand Down
6 changes: 3 additions & 3 deletions docs/docs/architecture/event.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -95,7 +95,7 @@ The publish route is the front door for sending events. A publishing service sim

When the publisher sits in the same zone as the event backend, the local publish route hands the events straight to the backend. When the publisher sits in a *proxy* zone that runs no backend of its own, the publish route there forwards the events to the target zone, whose own publish route then delivers them to the backend. Either way, the publisher uses the exact same kind of address.

The Route resource is named `publish`; its public paths are **`/horizon/events/v1`** and the alias **`/horizon/publish/v1`**, not `/publish`. Gateway preset base paths may prefix these paths. The proxy forwards to the backend gateway's `/horizon/events/v1` path.
The Route resource is named `horizon-events`; its public paths are **`/horizon/events/v1`** and the alias **`/horizon/publish/v1`**, not `/publish`. Gateway preset base paths may prefix these paths. The proxy forwards to the backend gateway's `/horizon/events/v1` path. Event Route names (`horizon-events`, `horizon-callback-<zone>`, `horizon-voyager-<zone>`, `horizon-sse--<eventType>`) equal the legacy-compatible Kong base names, so the Gateway can adopt existing entities that use them.

```mermaid
sequenceDiagram
Expand Down Expand Up @@ -126,10 +126,10 @@ sequenceDiagram
autonumber
box dataplane1 — backend zone
participant H1 as Horizon H1
participant G1 as G1<br/>callback--dataplane3<br/>PROXY
participant G1 as G1<br/>horizon-callback-dataplane3<br/>PROXY
end
box dataplane3 — subscriber zone, even if proxy
participant G3 as G3<br/>callback--dataplane3<br/>PRIMARY
participant G3 as G3<br/>horizon-callback-dataplane3<br/>PRIMARY
participant S as Subscriber URL U
end
Note over H1,G1: Configured first hop is G1, never exposure gateway G2
Expand Down
4 changes: 2 additions & 2 deletions docs/docs/architecture/file.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -2,14 +2,14 @@
sidebar_position: 12
---

# File Domain

<!--
SPDX-FileCopyrightText: 2025 Deutsche Telekom AG

SPDX-License-Identifier: CC0-1.0
-->

# File Domain

The File domain manages file-type exposure and subscription resources. It acts as the business-logic layer between Rover-style file declarations and runtime solutions such as SFTP.

## Custom Resources
Expand Down
Loading
Loading