# Gateway

When services need to receive traffic from the outside, commonly called North/South, the Kuma Gateway enables routing network traffic from outside a Kuma mesh to services inside the mesh. The gateway is also responsible for security at the entrance of the Mesh.

Kuma Gateway deploys as a Kuma Dataplane, that's an instance of the kuma-dp process. Like all Kuma Dataplanes, the Kuma Gateway Dataplane manages an Envoy proxy process that does the actual network traffic proxying.

You can distinguish two types of gateways:

  • delegated: Allows users to use any existing gateway like Kong (opens new window).
  • 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 requires its own gateway. You can easily connect your meshes together using cross-mesh gateways.

Below visualization shows the difference between delegated and builtin gateways:

Builtin with Kong Gateway to handle the inbound traffic:

Delegated with Kong Gateway:

The blue lines represent traffic not managed by Kuma, which needs configuring in the Gateway.

# Delegated

The Dataplane entity can operate in gateway mode. This way you can integrate Kuma with existing API Gateways like Kong (opens new window).

The gateway mode lets you skip exposing inbound listeners so it won't be intercepting ingress traffic. 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. In the gateway mode, you want inbound traffic to go directly to the gateway, otherwise, clients require dynamically generated certificates for communication between services within the mesh. The gateway itself should handle security at an entrance to the mesh.

# Usage

    # Builtin

    The builtin gateway is currently experimental.

    The builtin gateway is integrated into the core Kuma control plane. You can configure gateway listeners and routes to service directly using Kuma policies.

    The builtin gateway is configured on a Dataplane:

    type: Dataplane
    mesh: default
    name: gateway-instance-1
    networking:
      address: 127.0.0.1
      gateway:
        type: BUILTIN
        tags:
          kuma.io/service: edge-gateway
    
    1
    2
    3
    4
    5
    6
    7
    8
    9

    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.

    Kuma gateways are configured with the Envoy best practices for edge proxies (opens new window).

    # Usage

    Steps required to setup a simple gateway that exposes a http listener and 2 routes to imaginary services: "frontend" and "api".

      Now that the Dataplane is running you can describe the gateway listener:

        This policy creates a listener on port 8080 and will receive any traffic which has the Host header set to foo.example.com. 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.

        Now define your routes which take the traffic and route it either to your api or your 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. So /api/foo will go to the api service whereas /asset will go to the frontend service.

          # Multi-zone

          The Kuma Gateway resource types, MeshGateway and 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).

          # Cross-mesh

          Cross-mesh gateways are an experimental feature new in Kuma v1.7. The Mesh abstraction allows users to encapsulate and isolate services inside a kind of submesh with its own CA. With a cross-mesh MeshGateway, you can expose the services of one Mesh to other Meshes by defining an API with MeshGatewayRoutes. All traffic remains inside the Kuma data plane protected by mTLS.

          All meshes involved in cross-mesh communication must have mTLS enabled. To enable cross-mesh functionality for a MeshGateway listener, set the crossMesh property.

            ...
            mesh: default
            selectors:
              - match:
                  kuma.io/service: cross-mesh-gateway
            conf:
              listeners:
                - port: 8080
                  protocol: HTTP
                  crossMesh: true
                  hostname: default.mesh
          
          1
          2
          3
          4
          5
          6
          7
          8
          9
          10
          11

          # Hostname

          If the listener includes a hostname value, the cross-mesh listener will be reachable from all Meshes at this hostname and port. In this case, the URL http://default.mesh:8080.

          Otherwise it will be reachable at the host: internal.<gateway-name>.<mesh-of-gateway-name>.mesh.

          # Without transparent proxy

          If transparent proxy isn't set up, you'll have to add the listener explicitly as an outbound to your Dataplane objects if you want to access it:

            ...
            outbound
            - port: 8080
              tags:
                kuma.io/service: cross-mesh-gateway
                kuma.io/mesh: default
          
          1
          2
          3
          4
          5
          6

          # Limitations

          Cross-mesh functionality isn't supported across zones at the moment but will be in a future release.

          The only protocol supported is HTTP. Like service to service traffic, all traffic to the gateway is protected with mTLS but appears to be HTTP traffic to the applications inside the mesh. In the future, this limitation may be relaxed.

          There can be only one entry in selectors for a MeshGateway with crossMesh: true.

          # Policy support

          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.

          Policy GatewaySupport
          Circuit Breaker Full
          External Services Full
          Fault Injection Full
          Health Check Full
          Proxy Template Full
          Rate Limits Full
          Retries Full
          Traffic Permissions Full
          Traffic Routes None
          Traffic Log Partial
          Timeouts Full
          VirtualOutbounds None

          You can find in each policy's dedicated information with regard to builtin gateway support.

          Last Updated: 9/1/2022, 1:01:27 PM