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: 10

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
backend	Backend	—	Required
buffering	Buffering	—	Optional
gatewayRef	ObjectRef	—	Required
hostnames	string[]	—	Optional, minItems: 0, maxItems: 20
passThrough	boolean	false	Required
paths	string[]	—	Optional, minItems: 0, 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: 10

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

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.

info

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.

info

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.

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.

Related Pages

• Architecture: API Domain
• Architecture: Identity Domain