Gateway Domain
The Gateway domain configures the API Gateway at runtime. It manages routes, consumers, and their access relationships. While the architecture is designed to be gateway-agnostic, the current implementation uses Kong as the underlying gateway technology.
Custom Resources
Consumer
Consumer is the Schema for the consumers API
Group: gateway.cp.ei.telekom.de · Version: v1 · Scope: Namespaced
ConsumerSpec
Appears in: Consumer
ConsumerSpec defines the desired state of Consumer
| Field | Type | Default | Validation |
|---|---|---|---|
gateway | ObjectRef | — | Required |
name | string | — | Required |
security | Security | — | Optional |
ObjectRef
Appears in: ConsumerSpec, ConsumeRouteSpec, RouteSpec
ObjectRef is a reference to a Kubernetes object It is similar to types.NamespacedName but has the required json tags for serialization
| Field | Type | Default | Validation |
|---|---|---|---|
name | string | — | Required |
namespace | string | — | Required |
uid | string | — | Optional |
Security
Appears in: ConsumerSpec
Security defines the security configuration for the Rover Security is optional, but if provided, exactly one of m2m or h2m must be set
| Field | Type | Default | Validation |
|---|---|---|---|
ipRestrictions | IpRestrictions | — | Optional |
IpRestrictions
Appears in: Security
| Field | Type | Default | Validation |
|---|---|---|---|
allow | string[] | — | Optional |
deny | string[] | — | Optional |
ConsumerStatus
Appears in: Consumer, ConsumeRoute
ConsumerStatus defines the observed state of Consumer
| Field | Type | Default | Validation |
|---|---|---|---|
conditions | Condition[] | — | Optional |
properties | map<string, string> | — | Optional |
Condition
Appears in: ConsumerStatus, GatewayStatus, RouteStatus
| Field | Type | Default | Validation |
|---|---|---|---|
lastTransitionTime | string | — | Required, Format: date-time |
message | string | — | Required, maxLength: 32768 |
observedGeneration | integer | — | Optional, Format: int64, minimum: 0 |
reason | string | — | Required, minLength: 1, maxLength: 1024, pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$ |
status | string | — | Required, Enum: True \| False \| Unknown |
type | string | — | Required, maxLength: 316, pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$ |
ConsumeRoute
ConsumeRoute is the Schema for the consumeroutes API
Group: gateway.cp.ei.telekom.de · Version: v1 · Scope: Namespaced
ConsumeRouteSpec
Appears in: ConsumeRoute
ConsumeRouteSpec defines the desired state of ConsumeRoute
| Field | Type | Default | Validation |
|---|---|---|---|
consumerName | string | — | Required |
route | ObjectRef | — | Required |
security | ConsumeRouteSecurity | — | Optional |
traffic | Traffic | — | Optional |
ConsumeRouteSecurity
Appears in: ConsumeRouteSpec
| Field | Type | Default | Validation |
|---|---|---|---|
m2m | M2M | — | Optional |
M2M
Appears in: ConsumeRouteSecurity
M2M defines machine-to-machine authentication configuration
| Field | Type | Default | Validation |
|---|---|---|---|
basic | Basic | — | Optional |
client | Client | — | Optional |
scopes | string[] | — | Optional, maxItems: 100 |
Basic
Appears in: M2M, RouteM2M, ExternalIDP
Basic defines basic authentication configuration
| Field | Type | Default | Validation |
|---|---|---|---|
password | string | — | Required, minLength: 1 |
username | string | — | Required, minLength: 1 |
Client
Appears in: M2M, ExternalIDP
Client defines client credentials for OAuth2
| Field | Type | Default | Validation |
|---|---|---|---|
clientId | string | — | Required, minLength: 1 |
clientKey | string | — | Optional |
clientSecret | string | — | Optional |
refreshToken | string | — | Optional |
Traffic
Appears in: ConsumeRouteSpec
| Field | Type | Default | Validation |
|---|---|---|---|
rateLimit | RateLimit | — | Optional |
RateLimit
Appears in: Traffic
RateLimit defines the rate limit configuration for the ConsumeRoute
| Field | Type | Default | Validation |
|---|---|---|---|
limits | Limits | — | Required |
Limits
Appears in: RateLimit, RouteRateLimit
Limits defines the actual rate limit values for different time windows
| Field | Type | Default | Validation |
|---|---|---|---|
hour | integer | — | Optional, minimum: 0 |
minute | integer | — | Optional, minimum: 0 |
second | integer | — | Optional, minimum: 0 |
Gateway
Gateway is the Schema for the gateways API
Group: gateway.cp.ei.telekom.de · Version: v1 · Scope: Namespaced
GatewaySpec
Appears in: Gateway
GatewaySpec defines the desired state of Gateway
| Field | Type | Default | Validation |
|---|---|---|---|
admin | Admin | — | Required |
features | string[] | — | Optional |
redis | Redis | — | Optional |
Admin
Appears in: GatewaySpec
| Field | Type | Default | Validation |
|---|---|---|---|
clientId | string | — | Required |
clientSecret | string | — | Required |
issuerUrl | string | — | Required |
url | string | — | Required |
Redis
Appears in: GatewaySpec
| Field | Type | Default | Validation |
|---|---|---|---|
enableTLS | boolean | — | Required |
host | string | — | Required |
password | string | — | Required |
port | integer | — | Required |
GatewayStatus
Appears in: Gateway
GatewayStatus defines the observed state of Gateway
| Field | Type | Default | Validation |
|---|---|---|---|
conditions | Condition[] | — | Optional |
Route
Route is the Schema for the routes API
Group: gateway.cp.ei.telekom.de · Version: v1 · Scope: Namespaced
RouteSpec
Appears in: Route
spec defines the desired state of Route
| Field | Type | Default | Validation |
|---|---|---|---|
additionalTags | string[] | — | Optional |
backend | Backend | — | Required |
buffering | Buffering | — | Optional |
gatewayRef | ObjectRef | — | Required |
hostnames | string[] | — | Optional, minItems: 0, maxItems: 20 |
passThrough | boolean | false | Required |
paths | string[] | / | Optional, minItems: 1, maxItems: 10 |
security | RouteSecurity | — | Optional |
traffic | RouteTraffic | — | Required |
transformation | Transformation | — | Optional |
type | string | primary | Required, Enum: primary \| secondary \| proxy |
Backend
Appears in: RouteSpec
Backend defines the backend for this route. Only one of Backend or Traffic can be set.
| Field | Type | Default | Validation |
|---|---|---|---|
upstreams | Upstreams[] | — | Required, minItems: 1, maxItems: 10 |
Upstreams
Appears in: Backend
Upstreams defines the upstream targets for this route. If multiple targets are defined, they will be load balanced according to their weight.
| Field | Type | Default | Validation |
|---|---|---|---|
hostname | string | — | Required |
path | string | — | Required |
port | integer | — | Required, Format: int32 |
scheme | string | — | Required |
weight | integer | — | Optional, Format: int32 |
Buffering
Appears in: RouteSpec
Buffering configures Kong request/response body buffering for this route
| Field | Type | Default | Validation |
|---|---|---|---|
disableRequestBuffering | boolean | false | Optional |
disableResponseBuffering | boolean | false | Optional |
RouteSecurity
Appears in: RouteSpec, Failover
Security is the security configuration for the route
| Field | Type | Default | Validation |
|---|---|---|---|
defaultConsumers | string[] | — | Optional |
disableAccessControl | boolean | false | Optional |
m2m | RouteM2M | — | Optional |
realmName | string | — | Required |
trustedIssuers | string[] | — | Optional, minItems: 0 |
RouteM2M
Appears in: RouteSecurity
M2M defines machine-to-machine authentication configuration
| Field | Type | Default | Validation |
|---|---|---|---|
basic | Basic | — | Optional |
claims | Claims[] | — | Optional |
externalIDP | ExternalIDP | — | Optional |
scopes | string[] | — | Optional, maxItems: 100 |
Claims
Appears in: RouteM2M
Claims defines token claims applied to all consumers (the "default" bucket)
| Field | Type | Default | Validation |
|---|---|---|---|
key | string | — | Required, Enum: aud |
value | string | — | Optional, minLength: 1, maxLength: 256 |
valueFrom | string | — | Optional, Enum: ConsumerClientId |
ExternalIDP
Appears in: RouteM2M
ExternalIDP defines external identity provider configuration
| Field | Type | Default | Validation |
|---|---|---|---|
basic | Basic | — | Optional |
client | Client | — | Optional |
grantType | string | — | Required, Enum: client_credentials \| authorization_code \| password \| refresh_token |
tokenEndpoint | string | — | Required, Format: uri |
tokenRequest | string | — | Required, Enum: client_secret_basic \| client_secret_post |
RouteTraffic
Appears in: RouteSpec
Traffic defines the traffic configuration for this route.
| Field | Type | Default | Validation |
|---|---|---|---|
circuitBreaker | CircuitBreaker | — | Optional |
dynamicUpstream | DynamicUpstream | — | Optional |
failover | Failover | — | Optional |
healthProbe | boolean | — | Optional |
rateLimit | RouteRateLimit | — | Optional |
CircuitBreaker
Appears in: RouteTraffic
| Field | Type | Default | Validation |
|---|---|---|---|
enabled | boolean | — | Optional |
DynamicUpstream
Appears in: RouteTraffic
DynamicUpstream configures runtime upstream URL resolution. When set, the gateway resolves the actual upstream target from a request query parameter instead of using the static upstream.
| Field | Type | Default | Validation |
|---|---|---|---|
queryParameter | string | — | Required, minLength: 1, pattern: ^[a-zA-Z0-9_-]+$ |
Failover
Appears in: RouteTraffic
| Field | Type | Default | Validation |
|---|---|---|---|
security | RouteSecurity | — | Optional |
targetZoneName | string | — | Required |
targets | Target[] | — | Required |
Target
Appears in: Failover
| Field | Type | Default | Validation |
|---|---|---|---|
hostname | string | — | Required |
path | string | — | Required |
port | integer | — | Required, Format: int32 |
scheme | string | — | Required |
weight | integer | — | Optional, Format: int32 |
zoneName | string | — | Optional |
RouteRateLimit
Appears in: RouteTraffic
RateLimit defines rate limits for different time windows
| Field | Type | Default | Validation |
|---|---|---|---|
limits | Limits | — | Required |
options | Options | — | Optional |
Options
Appears in: RouteRateLimit
Options defines additional configuration options for rate limiting
| Field | Type | Default | Validation |
|---|---|---|---|
faultTolerant | boolean | true | Optional |
hideClientHeaders | boolean | false | Optional |
Transformation
Appears in: RouteSpec
Transformation defines optional request/response transformations for this API
| Field | Type | Default | Validation |
|---|---|---|---|
request | Request | — | Optional |
Request
Appears in: Transformation
Request defines transformations applied to incoming API requests
| Field | Type | Default | Validation |
|---|---|---|---|
headers | Headers | — | Optional |
Headers
Appears in: Request
Headers defines HTTP header modifications for requests
| Field | Type | Default | Validation |
|---|---|---|---|
add | string[] | — | Optional, minItems: 1, maxItems: 5 |
remove | string[] | — | Optional, minItems: 1, maxItems: 5 |
RouteStatus
Appears in: Route
status defines the observed state of Route
| Field | Type | Default | Validation |
|---|---|---|---|
conditions | Condition[] | — | Optional |
consumers | string[] | — | Optional |
properties | map<string, string> | — | Optional |
Feature Architecture
The Gateway operator uses a plugin-based feature system for configuring route behavior. Each feature is implemented as a separate plugin that can be enabled or disabled per route, allowing fine-grained control over how requests are processed.
Host Preservation
A Route's spec.passThrough also sets Kong's preserve_host. Passthrough routes forward the incoming Host header to the upstream. All other routes keep Kong's default, false, so the upstream gets its own hostname. There is no separate setting for this. Reconciliation fixes drift in either direction. Upstreams behind passthrough routes, such as managed Proxy routes, must accept the public Host.
Health Probes
Admin creates a passthrough Route per gateway with spec.traffic.healthProbe: true and placeholder upstream http://localhost:8081/api/v1/zone-health. The Kong client restricts flagged routes to HEAD, and the builder attaches the request-termination plugin with status 200. The service is required by Kong, but never called. This checks gateway reachability and route configuration, not backend health.
healthProbe is an optional boolean, false when omitted. Unflagged routes keep normal behavior even with the same upstream path. Reconciliation corrects method drift, and disabling the flag clears the restriction and cleans up the plugin. Other HTTP methods do not match the health route, although another overlapping route can match them. No separate methods field is needed. Deploy the updated Route CRD and Gateway controller before Admin.
Audience Claim Resolution
An API provider can require that every token reaching its backend carries an audience claim (aud), so the backend can confirm the token was meant for it. The provider declares this once on the API exposure, and the platform makes sure the claim is present on all traffic to that API.
The interesting part is who decides the actual value. Some sources are known when the API is configured, while one can only be known at the moment of each request. The Control Plane resolves as much as possible up front and leaves the rest to the request-time token service.
| Source | Known at configuration time? | Resolved by | Result |
|---|---|---|---|
| Fixed value | Yes | The user | The literal value is used as-is. |
| Provider identifier | Yes — always the exposing application | Control Plane | Filled in as a literal value. |
| Base path | Yes | Control Plane | Filled in as a literal value. |
| Consumer identifier | No — differs for every consumer | Request-time token service | Left as a symbolic reference and filled in per request. |
The consumer identifier cannot be decided in advance: a single exposed API is shared by many consumers, so one fixed value could never represent all of them. Instead, the platform records the source symbolically, and the token service reads the calling consumer's identity from the incoming request and stamps it onto the outgoing token.
The resolved claims are grouped into a default bucket that applies to all consumers of the API. The audience claim is declared only on the API exposure by the provider; consumers do not configure it.
The audience claim is configured by API teams on their Rover file. See Security: Audience Claims for the user-facing configuration.
Route Types & Cross-Zone Meshing
Every gateway Route has a type that determines where it sends traffic. Together, these three types let consumers and providers live in different zones while still reaching each other — a pattern we call meshing.
| Type | Lives in | Sends traffic to | Purpose |
|---|---|---|---|
| Primary | The provider's zone | The provider's backend upstreams directly | The single egress point for an API. Every other route ultimately targets it. |
| Proxy | A subscriber's zone (when different from the provider's) | The provider zone's gateway (the primary route) | Forwards cross-zone requests. It never talks to the backend itself. |
| Secondary | A provider failover zone | The provider's backend upstreams (as a backup) | Stand-in for the primary route when the provider's primary zone is unhealthy. |
Why proxy routes exist
A consumer always sends its request to the gateway in its own zone. If the API it wants is exposed in a different zone, that local gateway has no backend to call — so the Control Plane creates a proxy route there. The proxy route accepts the consumer's request, validates its token, and forwards the call across the zone boundary to the provider zone's primary route, which finally reaches the backend.
This keeps every consumer talking to a local gateway while the platform handles the cross-zone hop transparently.
If the consumer lives in the same zone as the provider, no proxy route is needed — the consumer reaches the primary route directly.
Secondary routes and failover
When a provider declares a failover zone, the Control Plane creates a secondary route there carrying a copy of the provider's upstreams. The proxy routes are configured with the failover zone as a fallback target. A health-check service watches the provider's primary zone; if it becomes unhealthy, proxy routes redirect to the secondary route instead of the primary one, and traffic is served from the backup zone.
Route types are created by the API domain, not configured by hand. See API Domain: Route Provisioning for which resource creates which route, and Failover for the operator-facing setup.
Additional route tags
Route.spec.additionalTags is an optional list of strings. The Gateway operator merges these values unchanged with its built-in Kong Route tags. They do not apply to Kong Services.
API and Agentic controllers use this field for traffic classification, with tags such as variant--default and variant--mcp.
Domain Interactions
- Admin domain — Zones define which gateway instance to use.
- API domain — Creates Routes for exposed APIs and ConsumeRoutes for subscriptions.
- Application domain — Creates Consumers for applications.
- Organization domain — Creates Consumers for teams.
- Event domain — Creates Routes for event publishing and SSE delivery.
- Rover domain — Configures rate limiting and load balancing via traffic management settings.