Configuring built-in listeners with MeshGateway

To configure built-in gateway listeners, use the MeshGateway resource.

The MeshGateway resource specifies what network ports the gateway should listen on and how network traffic should be accepted. A built-in gateway data plane can have exactly one MeshGateway resource bound to it.

This binding uses standard, tag-based Kong Mesh matching semantics:

apiVersion: kuma.io/v1alpha1
kind: MeshGateway
mesh: default
metadata:
  name: edge-gateway
spec:
  selectors:
    - match:
        kuma.io/service: edge-gateway_default_svc

type: MeshGateway
mesh: default
name: edge-gateway
selectors:
  - match:
      kuma.io/service: edge-gateway

A MeshGateway can have any number of listeners, where each listener represents an endpoint that can accept network traffic. The MeshGateway doesn’t specify which IP addresses are listened on; the Dataplane resource specifies that.

To configure a listener, you need to specify at least the port number and network protocol. Each listener may also have its own set of Kong Mesh tags so that Kong Mesh policy configuration can target specific listeners.

apiVersion: kuma.io/v1alpha1
kind: MeshGateway
mesh: default
metadata:
  name: edge-gateway
spec:
  selectors:
    - match:
        kuma.io/service: edge-gateway_default_svc
  conf:
    listeners:
      - port: 8080
        protocol: HTTP
        tags:
          port: http-8080

type: MeshGateway
mesh: default
name: edge-gateway
selectors:
  - match:
      kuma.io/service: edge-gateway
conf:
  listeners:
    - port: 8080
      protocol: HTTP
      tags:
        port: http-8080

An HTTP or HTTPS listener can also specify a hostname.

Note that listeners can share both port and protocol but differ on hostname. This way, routes can be attached to requests to specific hostnames, but share the port/protocol with other routes attached to other hostnames.

apiVersion: kuma.io/v1alpha1
kind: MeshGateway
mesh: default
metadata:
  name: edge-gateway
spec:
  selectors:
    - match:
        kuma.io/service: edge-gateway_default_svc
  conf:
    listeners:
      - port: 8080
        protocol: HTTP
        hostname: foo.example.com
        tags:
          port: http-8080

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

In the above example, the gateway proxy listens for HTTP protocol connections on TCP port 8080 but restricts the Host header to foo.example.com.

apiVersion: kuma.io/v1alpha1
kind: MeshGateway
mesh: default
metadata:
  name: edge-gateway
spec:
  selectors:
    - match:
        kuma.io/service: edge-gateway_default_svc
  conf:
    listeners:
      - port: 8080
        protocol: HTTP
        hostname: foo.example.com
        tags:
          vhost: foo.example.com
      - port: 8080
        protocol: HTTP
        hostname: bar.example.com
        tags:
          vhost: bar.example.com

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:
        vhost: foo.example.com
    - port: 8080
      protocol: HTTP
      hostname: bar.example.com
      tags:
        vhost: bar.example.com

The example above shows a MeshGateway resource with two HTTP listeners on the same port. In this case, the gateway proxy will be configured to listen on port 8080, and accept HTTP requests for both hostnames.

Because each listener entry has its own Kong Mesh tags, policies can still be targeted to a specific listener. Kong Mesh generates a set of tags for each listener by combining the tags from the listener, the MeshGateway and the Dataplane. Kong Mesh matches policies against this set of combined tags.

TLS sessions are terminated on a gateway by specifying the HTTPS protocol, and providing a server certificate configuration. Below, the gateway listens on port 8443 and terminates TLS sessions:

apiVersion: kuma.io/v1alpha1
kind: MeshGateway
mesh: default
metadata:
  name: edge-gateway
spec:
  selectors:
    - match:
        kuma.io/service: edge-gateway_default_svc
  conf:
    listeners:
      - port: 8443
        protocol: HTTPS
        hostname: foo.example.com
        tls:
          mode: TERMINATE
          certificates:
            - secret: foo-example-com-certificate
        tags:
          name: foo.example.com

type: MeshGateway
mesh: default
name: edge-gateway
selectors:
  - match:
      kuma.io/service: edge-gateway
conf:
  listeners:
    - port: 8443
      protocol: HTTPS
      hostname: foo.example.com
      tls:
        mode: TERMINATE
        certificates:
          - secret: foo-example-com-certificate
      tags:
        name: foo.example.com

The server certificate is provided through a Kong Mesh data source reference, in this case naming a secret that must contain both the server certificate and the corresponding private key.

Server certificate secrets

A TLS server certificate secret is a collection of PEM objects in a Kong Mesh data source (which may be a file, a Kong Mesh secret, or inline data).

There must be at least a private key and the corresponding TLS server certificate. The CA certificate chain may also be present, but if it is, the server certificate must be the first certificate in the secret.

Kong Mesh gateway supports serving both RSA and ECDSA server certificates. To enable this support, generate two server certificate secrets and provide them both to the listener TLS configuration. The kumactl tool supports generating simple, self-signed TLS server certificates:

apiVersion: v1
kind: Secret
metadata:
  name: foo-example-com-certificate
  namespace: kong-mesh-system
  labels:
    kuma.io/mesh: default
data:
  value: "$(kumactl generate tls-certificate --type=server --hostname=foo.example.com --key-file=- --cert-file=- | base64 -w0)"
type: system.kuma.io/secret

type: Secret
mesh: default
name: foo-example-com-certificate
data: $(kumactl generate tls-certificate --type=server --hostname=foo.example.com --key-file=- --cert-file=- | base64 -w0)

Cross-mesh

The Mesh abstraction allows users to encapsulate and isolate services inside a kind of sub-mesh 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 MeshHTTPRoute resources. 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:

apiVersion: kuma.io/v1alpha1
kind: MeshGateway
mesh: default
metadata:
  name: cross-mesh-gateway
  labels:
    kuma.io/mesh: default
spec:
  selectors:
    - match:
        kuma.io/service: cross-mesh-gateway_default_svc
  conf:
    listeners:
      - port: 8080
        protocol: HTTP
        crossMesh: true
        hostname: default.mesh

type: MeshGateway
mesh: default
name: cross-mesh-gateway
selectors:
  - match:
      kuma.io/service: cross-mesh-gateway
conf:
  listeners:
    - port: 8080
      protocol: HTTP
      crossMesh: true
      hostname: default.mesh

Cross-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 the example above, the URL is http://default.mesh:8080.

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

Outbound

If transparent proxy isn’t set up, you must 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

• 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.

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

In a multi-zone deployment, MeshGateway resources must be created on the global control plane. For more information, see Built-in gateways.