Skip to content
Kong Logo | Kong Docs Logo
search
  • We're Hiring!
  • Docs
    • Kong Gateway
    • Kong Konnect
    • Kong Mesh
    • Plugin Hub
    • decK
    • Kubernetes Ingress Controller
    • Insomnia
    • Kuma

    • Docs contribution guidelines
  • Plugin Hub
  • Support
  • Community
  • Kong Academy
Early Access
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Plugin Hub
  • decK
  • Kubernetes Ingress Controller
  • Insomnia
  • Kuma

  • Docs contribution guidelines
  • 2.0.x (latest)
  • 1.9.x
  • 1.8.x
  • 1.7.x
  • 1.6.x
  • 1.5.x
  • 1.4.x
  • 1.3.x
  • 1.2.x
  • 1.1.x
  • 1.0.x
    • Introduction to Kong Mesh
    • What is Service Mesh?
    • How Kong Mesh works
    • Deployments
    • Version support policy
    • Stability
    • Release notes
    • Installation Options
    • Kubernetes
    • Helm
    • OpenShift
    • Docker
    • Amazon ECS
    • Amazon Linux
    • Red Hat
    • CentOS
    • Debian
    • Ubuntu
    • macOS
    • Windows
    • Explore Kong Mesh with the Kubernetes demo app
    • Explore Kong Mesh with the Universal demo app
    • Standalone deployment
    • Multi-zone deployment
    • License
    • Overview
    • Data plane proxy
    • Data plane on Kubernetes
    • Data plane on Universal
    • Gateway
    • Zone Ingress
    • Zone Egress
    • CLI
    • GUI
    • Observability
    • Inspect API
    • Kubernetes Gateway API
    • Networking
    • Service Discovery
    • DNS
    • Kong Mesh CNI
    • Transparent Proxying
    • IPv6 support
    • Secure access across Kong Mesh components
    • Secrets
    • Kong Mesh API Access Control
    • API server authentication
    • Data plane proxy authentication
    • Zone proxy authentication
    • Data plane proxy membership
    • Dataplane Health
    • Fine-tuning
    • Control Plane Configuration
    • Upgrades
    • Requirements
    • Introduction
    • General notes about Kong Mesh policies
    • Applying Policies
    • How Kong Mesh chooses the right policy to apply
    • Policy matching
    • Protocol support in Kong Mesh
    • Mesh
    • Mutual TLS
    • Traffic Permissions
    • Traffic Route
    • Traffic Metrics
    • Traffic Trace
    • Traffic Log
    • Locality-aware Load Balancing
    • Fault Injection
    • Health Check
    • Circuit Breaker
    • Proxy Template
    • External Service
    • Retry
    • Timeout
    • Rate Limit
    • Virtual Outbound
    • MeshGateway
    • MeshGatewayRoute
    • Service Health Probes
    • MeshTrace (Beta)
    • MeshAccessLog (Beta)
    • MeshTrafficPermission (Beta)
    • Overview
    • HashiCorp Vault CA
    • Amazon ACM Private CA
    • cert-manager Private CA
    • OPA policy support
    • Multi-zone authentication
    • FIPS support
    • Certificate Authority rotation
    • Role-Based Access Control
    • UBI Images
    • Windows Support
    • Auditing
    • HTTP API
    • Annotations and labels in Kubernetes mode
    • Kong Mesh data collection
      • Mesh
      • CircuitBreaker
      • ExternalService
      • FaultInjection
      • HealthCheck
      • MeshGateway
      • MeshGatewayRoute
      • ProxyTemplate
      • RateLimit
      • Retry
      • Timeout
      • TrafficLog
      • TrafficPermission
      • TrafficRoute
      • TrafficTrace
      • VirtualOutbound
      • Dataplane
      • ZoneEgress
      • ZoneIngress
      • kuma-cp
      • kuma-dp
      • kumactl
    • Kuma-cp configuration reference

github-edit-pageEdit this page

report-issueReport an issue

enterprise-switcher-iconSwitch to OSS

On this page
  • Delegated
    • Usage
  • Builtin
    • Usage
    • TCP
    • Multi-zone
    • Cross-mesh
    • Policy support
Kong Mesh
2.0.x (latest)
  • Home
  • Kong Mesh
  • Explore
  • Gateway

Gateway

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

Kong Mesh Gateway deploys as a Kong Mesh Dataplane, that’s an instance of the kuma-dp process. Like all Kong Mesh Dataplanes, the Kong Mesh 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.
  • 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 Kong Mesh, which needs configuring in the Gateway.

Delegated

The Dataplane entity can operate in gateway mode. This way you can integrate Kong Mesh with existing API Gateways like Kong.

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

Kubernetes
Universal

Kong Mesh supports most of the ingress controllers. However, the recommended gateway in Kubernetes is Kong. You can use Kong ingress controller for Kubernetes to implement authentication, transformations, and other functionalities across Kubernetes clusters with zero downtime. Most ingress controllers require an annotation ingress.kubernetes.io/service-upstream=true on every Kubernetes Service to work with Kong Mesh. Kong Mesh automatically injects the annotation for every Service in a namespace in a mesh that has kuma.io/sidecar-injection: enabled label.

To use the delegated gateway feature, mark your API Gateway’s Pod with the kuma.io/gateway: enabled annotation. Control plane automatically generates Dataplane objects.

For example:

apiVersion: apps/v1
kind: Deployment
metadata:
  ...
spec:
  template:
    metadata:
      annotations:
        kuma.io/gateway: enabled
      ...

API Gateway receives Services from:

  • one specific zone
  • multi-zone

Multi-zone requires exposing a dedicated Kubernetes Service object with type ExternalName. Control plane creates a DNS entry externalName with suffix .mesh, which Kong Mesh resolves in internal service discovery.

Example setting up Kong Ingress Controller

Follow instructions to setup an echo service reachable through Kong. These instructions are mostly taken from the Kong docs.

  1. Install Kong Mesh on your cluster and have the default namespace labelled with sidecar-injection.

  2. Install Kong using helm.

  3. Start an echo-service:

    kubectl apply -f https://bit.ly/echo-service
    
  4. Add an ingress:

    echo "
    apiVersion: networking.k8s.io/v1
    kind: Ingress
    metadata:
      name: demo
    spec:
      ingressClassName: kong
      rules:
      - http:
          paths:
          - path: /foo
            pathType: ImplementationSpecific
            backend:
              service:
                name: echo
                port:
                  number: 80
    " | kubectl apply -f -
    

You can access your ingress with curl -i $PROXY_IP/foo where $PROXY_IP you can retrieve from the service that exposes Kong outside your cluster.

You can check that the sidecar is running by checking the number of containers in each pod:

kubectl get pods
NAME                                    READY   STATUS    RESTARTS   AGE
echo-5fc5b5bc84-zr9kl                   2/2     Running   0          41m
kong-1645186528-kong-648b9596c7-f2xfv   3/3     Running   2          40m

Example Gateway in Multi-Zone

In the previous example, you setup an echo, that’s running on port 80, and deployed in the default namespace.

Now make sure that this service works correctly with multi-zone. In order to do so, create Service manually:

echo "
apiVersion: v1
kind: Service
metadata:
  name: echo-multizone
  namespace: default
spec:
  type: ExternalName
  externalName: echo.default.svc.80.mesh
" | kubectl apply -f -

Finally, you need to create a corresponding Kubernetes Ingress that routes /bar to the multi-zone service:

echo "
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: demo-multizone
  namespace: default
spec:
  ingressClassName: kong
  rules:
    - http:
        paths:
          - path: /bar
            pathType: ImplementationSpecific
            backend:
              service:
                name: echo-multizone
                port:
                  number: 80
" | kubectl apply -f -

Note that since you are addressing the service by its domain name echo.default.svc.8080.mesh, you should always refer to port 80. This port is only a placeholder and is automatically replaced with the actual port of the service.

If you want to expose a Service in one zone only, as opposed to multi-zone, you can just use the service name in the Ingress definition without having to create an externalName entry, this is what you did in your first example.

For an in-depth example on deploying Kong Mesh with Kong for Kubernetes, please follow this demo application guide.

On Universal, you can define the Dataplane entity like this:

type: Dataplane
mesh: default
name: kong-01
networking:
  address: 10.0.0.1
  gateway:
    type: DELEGATED
    tags:
      kuma.io/service: kong
  outbound:
    - port: 33033
      tags:
        kuma.io/service: backend

When configuring your API Gateway to pass traffic to backend set the url to http://localhost:33033

Builtin

The builtin gateway is integrated into the core Kong Mesh control plane. You can configure gateway listeners and routes to service directly using Kong Mesh 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

A builtin gateway Dataplane does not have either inbound or outbound configuration.

To configure your gateway Kong Mesh 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.

Kong Mesh gateways are configured with the Envoy best practices for edge proxies.

Usage

You can create and configure a gateway that listens for traffic from outside of your mesh and forwards it to the demo app frontend.

Kubernetes
Universal

To ease starting gateways on Kubernetes, Kong Mesh comes with a builtin type MeshGatewayInstance.

This resource launches kuma-dp in your cluster. If you are running a multi-zone Kuma, MeshGatewayInstance needs to be created in a specific zone, not the global cluster. See the dedicated section for using builtin gateways on multi-zone.

This type requests that the control plane create and manage a Kubernetes Deployment and Service suitable for providing service capacity for the MeshGateway with the matching kuma.io/service tag.

echo "
apiVersion: kuma.io/v1alpha1
kind: MeshGatewayInstance
metadata:
  name: edge-gateway
  namespace: default
spec:
  replicas: 1
  serviceType: LoadBalancer
  tags:
    kuma.io/service: edge-gateway
" | kubectl apply -f -

Once a MeshGateway exists that matches the kuma.io/service tag, the control plane creates a new Deployment in the default namespace. This Deployment has the requested number of builtin gateway Dataplane pod replicas running as the service named in the MeshGatewayInstance tags. The control plane also creates a new Service to send network traffic to the builtin Dataplane pods. The Service is of the type requested in the MeshGatewayInstance, and its ports are automatically adjusted to match the listeners on the corresponding MeshGateway.

Customization

Additional customization of the generated Service or Deployment is possible via MeshGatewayInstance.spec. For example, you can add annotations to the generated Service:

spec:
  replicas: 1
  serviceType: LoadBalancer
  tags:
    kuma.io/service: edge-gateway
  resources:
    limits: ...
    requests: ...
  serviceTemplate:
    metadata:
      annotations:
        service.beta.kubernetes.io/aws-load-balancer-internal: "true"
        ...
    spec:
      loadBalancerIP: ...
" | kubectl apply -f -

The first thing you’ll need is to create a Dataplane object for your gateway:

type: Dataplane
mesh: default
name: gateway-instance-1
networking:
  address: 127.0.0.1
  gateway:
    type: BUILTIN
    tags:
      kuma.io/service: edge-gateway

Note that this gateway has a kuma.io/service tag. Use this to bind policies to configure this gateway.

As you’re in universal you now need to run kuma-dp:

kuma-dp run \
  --cp-address=https://localhost:5678/ \
  --dns-enabled=false \
  --dataplane-token-file=kuma-token-gateway \ # this needs to be generated like for regular Dataplane
  --dataplane-file=my-gateway.yaml # the Dataplane resource described above

Now let’s create a MeshGateway to configure the listeners:

Kubernetes
Universal
echo "
apiVersion: kuma.io/v1alpha1
kind: MeshGateway
mesh: default
metadata:
  name: edge-gateway
spec:
  selectors:
  - match:
      kuma.io/service: edge-gateway
  conf:
    listeners:
      - port: 8080
        protocol: HTTP
        hostname: foo.example.com
        tags:
          port: http/8080
" | kubectl apply -f -
type: MeshGateway
mesh: default
name: edge-gateway
selectors:
  - match:
      kuma.io/service: edge-gateway
conf:
  listeners:
    - port: 8080
      protocol: HTTP
      hostname: foo.example.com
      tags:
        port: http/8080

The MeshGateway creates a listener on port 8080 and will accept 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 Kong Mesh policies so if you are running on multi-zone they need to be created on the Global CP. See the dedicated section for using builtin gateways on multi-zone.

Now, you can define a MeshGatewayRoute to forward your traffic based on the matched URL path.

Kubernetes
Universal
echo "
apiVersion: kuma.io/v1alpha1
kind: MeshGatewayRoute
mesh: default
metadata:
  name: edge-gateway-route
spec:
  selectors:
    - match:
        kuma.io/service: edge-gateway
        port: http/8080
  conf:
    http:
      rules:
        - matches:
            - path:
                match: PREFIX
                value: /
          backends:
            - destination:
                kuma.io/service: demo-app_kuma-demo_svc_5000
" | kubectl apply -f -
type: MeshGatewayRoute
mesh: default
name: edge-gateway-route
selectors:
  - match:
      kuma.io/service: edge-gateway
      port: http/8080
conf:
  http:
    rules:
      - matches:
          - path:
              match: PREFIX
              value: /
        backends:
          - destination:
              kuma.io/service: demo-app_kuma-demo_svc_5000

TCP

The builtin gateway also supports TCP MeshGatewayRoutes:

type: MeshGateway
mesh: default
name: edge-gateway
selectors:
  - match:
      kuma.io/service: edge-gateway
conf:
  listeners:
    - port: 8080
      protocol: TCP
      tags:
        port: tcp/8080
---
type: MeshGatewayRoute
mesh: default
name: edge-gateway-route
selectors:
  - match:
      kuma.io/service: edge-gateway
      port: tcp/8080
conf:
  tcp:
    rules:
      - backends:
          - destination:
              kuma.io/service: redis_kuma-demo_svc_6379

The TCP configuration only supports the backends key (no matches or filters). There are no TCP-generic ways to filter or match traffic so it can only load balance.

Multi-zone

The Kong Mesh Gateway resource types, MeshGateway and MeshGatewayRoute, are synced across zones by the Kong Mesh control plane. If you have a multi-zone deployment, follow existing Kong Mesh practice and create any Kong Mesh 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).

See the multi-zone docs for a refresher.

Cross-mesh

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 Kong Mesh 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

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

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 Kong Mesh policies are applicable to Kong Mesh Gateway (see table below). Kong Mesh connection policies are selected by matching the source and destination expressions against sets of Kong Mesh tags. In the case of Kong Mesh 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, Kong Mesh can only configure the route with one connection policy. In this case, Kong Mesh employs some simple heuristics to choose the policy. If all the backend destinations refer to the same service, Kong Mesh will choose the oldest connection policy that has a matching destination service. However, if the backend destinations refer to different services, Kong Mesh will prefer a connection policy with a wildcard destination (i.e. where the destination service is *).

Kong Mesh may select different connection policies of the same type depending on the context. For example, when Kong Mesh configures an Envoy route, there may be multiple candidate policies (due to the traffic splitting across destination services), but when Kong Mesh 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.

Thank you for your feedback.
Was this page useful?
  • Kong
    THE CLOUD CONNECTIVITY COMPANY

    Kong powers reliable digital connections across APIs, hybrid and multi-cloud environments.

    • Company
    • Customers
    • Events
    • Investors
    • Careers Hiring!
    • Partners
    • Press
    • Contact
  • Products
    • Kong Konnect
    • Kong Gateway
    • Kong Mesh
    • Get Started
    • Pricing
  • Resources
    • eBooks
    • Webinars
    • Briefs
    • Blog
    • API Gateway
    • Microservices
  • Open Source
    • Install Kong Gateway
    • Kong Community
    • Kubernetes Ingress
    • Kuma
    • Insomnia
  • Solutions
    • Decentralize
    • Secure & Govern
    • Create a Dev Platform
    • API Gateway
    • Kubernetes
    • Service Mesh
Star
  • Terms•Privacy
© Kong Inc. 2023