Policies · Gateway

MeshGateway

Built-in gateway listeners (ports, protocols, hostnames, TLS) selected by a kuma.io/service tag.

Kuma

Behaviour per target

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

Output: Gateway

Converted to a Gateway API Gateway named after the MeshGateway:

  • conf.listeners[] → spec.listeners[] (name is <protocol>-<port>, with a -2, -3, … suffix when two listeners share protocol and port; hostname, tls.mode recased, certificates[].secret → certificateRefs[]).
  • metadata.namespace is the namespace of the companion MeshGatewayInstance, matched on the shared kuma.io/service tag. MeshGateway is cluster-scoped, the gateway pods run in the instance's namespace, and Kuma creates a Gateway's instance in the Gateway's own namespace. Instances in several namespaces pick the first and warn; none omits the field and warns (apply with -n). An empty namespace is never emitted.
  • spec.gatewayClassName is the name of the GatewayClass generated from the same instance. An instance without spec.tags["kuma.io/service"] matches on the <name>_<namespace>_svc tag Kuma gives it. Several matches pick the first and warn; none leaves REPLACE-WITH-YOUR-GATEWAYCLASS and warns.
  • spec.selectors has no Gateway API equivalent and is reported.

Universal input is copied unchanged, with an advisory that 3.0 removes the built-in gateway: Universal has no Gateway API, so a Gateway could not be applied (kumactl apply: invalid resource type).

--to-latest v3 (3.0) converted

Output: Gateway

Universal input is rejected by the target and written to _manual/ unchanged, with the delegated-gateway steps for Universal: run your gateway on a Dataplane without kuma.io/gateway and start kuma-dp with --exclude-inbound-ports covering its listen ports. Kubernetes input:

The listener block and metadata.namespace are converted as on v2, but gatewayClassName is always REPLACE-WITH-YOUR-GATEWAYCLASS: 3.0 has no Gateway or GatewayClass reconciler. Set it to the class of the gateway implementation you adopt, and rejoin the workload as a delegated gateway (traffic.kuma.io/exclude-inbound-ports on the pod, kuma.io/ignore: "true" on its Service).

Delete the source MeshGateway before upgrading: the 3.0 chart deletes its CRD and every object stored under it.

Timeline

VersionChange
2.10Policies no longer attach to built-in gateway listeners through a top-level targetRef.kind: MeshGateway.
3.0Built-in gateway API removed (types, CRDs, KDS sync); MeshGateway is no longer a valid targetRef.kind.

Source files