You are browsing documentation for a version of Kuma that is not the latest release.
Looking for even older versions? Learn more.
Kuma Gateway is a Kuma component that routes network traffic from outside a Kuma mesh to services inside the mesh. The gateway can be thought of as having one foot outside the mesh to receive traffic and one foot inside the mesh to route this external traffic to services inside the mesh.
When you use a data plane proxy with a service, both inbound traffic to a service and outbound traffic from the service flows through the proxy. Gateway should be deployed as any other service within the mesh. However, in this case we want inbound traffic to go directly to the gateway, otherwise clients would have to be provided with certificates that are generated dynamically for communication between services within the mesh. Security for an entrance to the mesh should be handled by Gateway itself.
Kuma Gateway is deployed as a Kuma Dataplane, i.e. an instance of the
Like all Kuma Dataplanes, the Kuma Gateway Dataplane manages an Envoy proxy process that does the actual network traffic proxying.
There exists two types of gateways:
- Delegated: Which enables users to use any existing gateway like Kong.
- Builtin: configures the data plane proxy to expose external listeners to drive traffic inside the mesh.
Gateways exist within a mesh. If you have multiple meshes, each mesh will need its own gateway.
Dataplane entity can operate in
gateway mode. This way you can integrate Kuma with existing API Gateways like Kong.
Gateway mode lets you skip exposing inbound listeners so it won’t be intercepting ingress traffic.
On Universal, you can define the
Dataplane entity like this:
- port: 33033
When configuring your API Gateway to pass traffic to backend set the url to
The builtin gateway is currently experimental and is enabled with the kuma-cp flag
--experimental-meshgateway or the environment variable
The builtin type of gateway is integrated into the core Kuma control plane. You can therefore configure gateway listeners and routes to service directly using Kuma policies.
As with provided gateway, the builtin gateway is configured with a dataplane:
A builtin gateway Dataplane does not have either inbound or outbound configuration.
To configure your gateway Kuma has these resources:
- MeshGateway is used to configure listeners exposed by the gateway
- MeshGatewayRoute is used to configure route to route traffic from listeners to other services.
We will set up a simple gateway that exposes a http listener and 2 routes to imaginary services: “frontend” and “api”.
The first thing you’ll need is to create a dataplane object for your gateway:
Note that this gateway has a
kuma.io/service tag. We will use this to bind policies to configure this gateway.
As we’re in universal you now need to run kuma-dp:
kuma-dp run \
--dataplane-token-file=kuma-token-gateway \ # this needs to be generated like for regular Data plane
--dataplane-file=my-gateway.yaml # the dataplane resource described above
Now that the dataplane is running we can describe the gateway listener:
- port: 8080
This policy creates a listener on port 8080 and will receive any traffic which has the
Host header set to
Notice that listeners have tags like dataplanes. This will be useful when binding routes to listeners.
These are Kuma policies so if you are running on multi-zone they need to be created on the Global CP. See the dedicated section for detailed information.
We will now define our routes which will take traffic and route it either to our
api or our
frontend depending on the path of the http request:
Because routes are applied in order of specificity the first route will take precedence over the second one.
/api/foo will go to the
api service whereas
/asset will go to the
The Kuma Gateway resource types,
MeshGatewayRoute, are synced across zones by the Kuma control plane.
If you have a multi-zone deployment, follow existing Kuma practice and create any Kuma Gateway resources in the global control plane.
Once these resources exist, you can provision serving capacity in the zones where it is needed by deploying builtin gateway Dataplanes (in Universal zones) or
MeshGatewayInstances (Kubernetes zones).
Not all Kuma policies are applicable to Kuma Gateway (see table below). Kuma connection policies are selected by matching the source and destination expressions against sets of Kuma tags. In the case of Kuma Gateway the source selector is always matched against the Gateway listener tags, and the destination expression is matched against the backend destination tags configured on a Gateway Route.
When a Gateway Route forwards traffic, it may weight the traffic across multiple services.
In this case, matching the destination for a connection policy becomes ambiguous.
Although the traffic is proxied to more than one distinct service, Kuma can only configure the route with one connection policy.
In this case, Kuma employs some simple heuristics to choose the policy.
If all the backend destinations refer to the same service, Kuma will choose the oldest connection policy that has a matching destination service.
However, if the backend destinations refer to different services, Kuma will prefer a connection policy with a wildcard destination (i.e. where the destination service is
Kuma may select different connection policies of the same type depending on the context. For example, when Kuma configures an Envoy route, there may be multiple candidate policies (due to the traffic splitting across destination services), but when Kuma configures an Envoy cluster there is usually only a single candidate (because clusters are defined to be a single service). This can result in situations where different policies (of the same type) are used for different parts of the Envoy configuration.
You can find in each policy’s dedicated information with regard to builtin gateway support.