Policies · Gateway

MeshGatewayRoute

Built-in gateway HTTP or TCP routes attached to MeshGateway listeners.

Kuma

Behaviour per target

--to-latest v2 (2.x) converted

Output: HTTPRoute, TCPRoute, ReferenceGrant

conf.http → Gateway API HTTPRoute, conf.tcp → TCPRoute.

  • parentRefs[] come from spec.selectors[]. The kuma.io/service tag is matched against the MeshGateway documents in the input, so the parentRef names the converted Gateway (named after the MeshGateway, not after the tag) in the namespace that Gateway gets. The remaining tags select listeners by their tags, and each match becomes a parentRef whose sectionName is that listener's emitted name. A tag selected by several MeshGateways emits one parentRef per Gateway and warns. When no MeshGateway in the input selects the tag, the name is decoded from <name>_<ns>_svc (or the raw tag is used) and a warning asks you to verify it.
  • MeshGatewayRoute is cluster-scoped. When every parent Gateway resolves to one namespace, the route is placed there: a Gateway listener accepts routes only from its own namespace by default.
  • backends[].destination["kuma.io/service"] → backendRefs[] of kind: Service with the decoded name, namespace and port.
  • A backend in another namespace than the route gets a ReferenceGrant. A route whose namespace is still unknown is reported instead.

A warning states the alternative successor: if Kuma should keep routing this traffic, write a MeshHTTPRoute/MeshTCPRoute. Kuma never reconciles TCPRoute; only the gateway implementation you adopt does.

Universal input is copied unchanged with a 3.0 advisory: Universal has no Gateway API.

--to-latest v3 (3.0) converted

Output: HTTPRoute, TCPRoute, ReferenceGrant

Universal input is rejected by the target and written to _manual/ unchanged, with the same delegated-gateway guidance as MeshGateway. Kubernetes input:

Same conversion. Generated routes carry kuma.io/mesh as a label and integer backendRefs[].port. 3.0 ignores HTTPRoutes whose parentRef is a Gateway, so only your gateway implementation reconciles them. Delete the source MeshGatewayRoute before upgrading.

Timeline

VersionChange
3.0Built-in gateway API removed. Cross-namespace Gateway API backendRefs require a ReferenceGrant.

Source files