Configuring built-in listeners

For configuring built-in gateway listeners, use the MeshGateway resource.

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 using builtin gateways on multi-zone.

The MeshGateway resource specifies what network ports the gateway should listen on and how network traffic should be accepted. A builtin gateway Dataplane can have exactly one MeshGateway resource bound to it. This binding uses standard, tag-based Kuma matching semantics:

Heads up! In previous versions of Kuma, setting the kuma.io/service tag directly within a MeshGatewayInstance resource was used to identify the service. However, this practice is deprecated and no longer recommended for security reasons since Kuma version 2.7.0.

We’ve automatically switched to generating the service name for you based on your MeshGatewayInstance resource name and namespace (format: {name}_{namespace}_svc).

  1. apiVersion: kuma.io/v1alpha1
  2. kind: MeshGateway
  3. mesh: default
  4. metadata:
  5.   name: edge-gateway
  6. spec:
  7.   selectors:
  8.     - match:
  9.         kuma.io/service: edge-gateway_default_svc
  1. type: MeshGateway
  2. mesh: default
  3. name: edge-gateway
  4. selectors:
  5.   - match:
  6.       kuma.io/service: edge-gateway

A MeshGateway can have any number of listeners, where each listener represents an endpoint that can accept network traffic. Note that 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 Kuma tags so that Kuma policy configuration can be targeted to specific listeners.

  1. apiVersion: kuma.io/v1alpha1
  2. kind: MeshGateway
  3. mesh: default
  4. metadata:
  5.   name: edge-gateway
  6. spec:
  7.   selectors:
  8.     - match:
  9.         kuma.io/service: edge-gateway_default_svc
  10.   conf:
  11.     listeners:
  12.       - port: 8080
  13.         protocol: HTTP
  14.         tags:
  15.           port: http-8080
  1. type: MeshGateway
  2. mesh: default
  3. name: edge-gateway
  4. selectors:
  5.   - match:
  6.       kuma.io/service: edge-gateway
  7. conf:
  8.   listeners:
  9.     - port: 8080
  10.       protocol: HTTP
  11.       tags:
  12.         port: http-8080

Hostname

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.

  1. apiVersion: kuma.io/v1alpha1
  2. kind: MeshGateway
  3. mesh: default
  4. metadata:
  5.   name: edge-gateway
  6. spec:
  7.   selectors:
  8.     - match:
  9.         kuma.io/service: edge-gateway_default_svc
  10.   conf:
  11.     listeners:
  12.       - port: 8080
  13.         protocol: HTTP
  14.         hostname: foo.example.com
  15.         tags:
  16.           port: http-8080
  1. type: MeshGateway
  2. mesh: default
  3. name: edge-gateway
  4. selectors:
  5.   - match:
  6.       kuma.io/service: edge-gateway
  7. conf:
  8.   listeners:
  9.     - port: 8080
  10.       protocol: HTTP
  11.       hostname: foo.example.com
  12.       tags:
  13.         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.

  1. apiVersion: kuma.io/v1alpha1
  2. kind: MeshGateway
  3. mesh: default
  4. metadata:
  5.   name: edge-gateway
  6. spec:
  7.   selectors:
  8.     - match:
  9.         kuma.io/service: edge-gateway_default_svc
  10.   conf:
  11.     listeners:
  12.       - port: 8080
  13.         protocol: HTTP
  14.         hostname: foo.example.com
  15.         tags:
  16.           vhost: foo.example.com
  17.       - port: 8080
  18.         protocol: HTTP
  19.         hostname: bar.example.com
  20.         tags:
  21.           vhost: bar.example.com
  1. type: MeshGateway
  2. mesh: default
  3. name: edge-gateway
  4. selectors:
  5.   - match:
  6.       kuma.io/service: edge-gateway
  7. conf:
  8.   listeners:
  9.     - port: 8080
  10.       protocol: HTTP
  11.       hostname: foo.example.com
  12.       tags:
  13.         vhost: foo.example.com
  14.     - port: 8080
  15.       protocol: HTTP
  16.       hostname: bar.example.com
  17.       tags:
  18.         vhost: bar.example.com

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

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

Dataplane tagsListener tagsFinal Tags
kuma.io/service=edge-gateway_default_svcvhost=foo.example.comkuma.io/service=edge-gateway_default_svc,vhost=foo.example.com
kuma.io/service=edge-gateway_default_svckuma.io/service=example,domain=example.comkuma.io/service=example,domain=example.com
kuma.io/service=edge_default_svc,location=usversion=2kuma.io/service=edge_default_svc,location=us,version=2

TLS Termination

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.

  1. apiVersion: kuma.io/v1alpha1
  2. kind: MeshGateway
  3. mesh: default
  4. metadata:
  5.   name: edge-gateway
  6. spec:
  7.   selectors:
  8.     - match:
  9.         kuma.io/service: edge-gateway_default_svc
  10.   conf:
  11.     listeners:
  12.       - port: 8443
  13.         protocol: HTTPS
  14.         hostname: foo.example.com
  15.         tls:
  16.           mode: TERMINATE
  17.           certificates:
  18.             - secret: foo-example-com-certificate
  19.         tags:
  20.           name: foo.example.com
  1. type: MeshGateway
  2. mesh: default
  3. name: edge-gateway
  4. selectors:
  5.   - match:
  6.       kuma.io/service: edge-gateway
  7. conf:
  8.   listeners:
  9.     - port: 8443
  10.       protocol: HTTPS
  11.       hostname: foo.example.com
  12.       tls:
  13.         mode: TERMINATE
  14.         certificates:
  15.           - secret: foo-example-com-certificate
  16.       tags:
  17.         name: foo.example.com

The server certificate is provided through a Kuma datasource 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 Kuma datasource (which may be a file, a Kuma 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.

Kuma 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. The script below shows how to do this.

  1. apiVersion: v1
  2. kind: Secret
  3. metadata:
  4.   name: foo-example-com-certificate
  5.   namespace: kuma-system
  6.   labels:
  7.     kuma.io/mesh: default
  8. data:
  9.   value: "$(kumactl generate tls-certificate --type=server --hostname=foo.example.com --key-file=- --cert-file=- | base64 -w0)"
  10. type: system.kuma.io/secret
  1. type: Secret
  2. mesh: default
  3. name: foo-example-com-certificate
  4. 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 MeshHTTPRoutes. 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.

  1. apiVersion: kuma.io/v1alpha1
  2. kind: MeshGateway
  3. mesh: default
  4. metadata:
  5.   name: cross-mesh-gateway
  6.   labels:
  7.     kuma.io/mesh: default
  8. spec:
  9.   selectors:
  10.     - match:
  11.         kuma.io/service: cross-mesh-gateway_default_svc
  12.   conf:
  13.     listeners:
  14.       - port: 8080
  15.         protocol: HTTP
  16.         crossMesh: true
  17.         hostname: default.mesh
  1. type: MeshGateway
  2. mesh: default
  3. name: cross-mesh-gateway
  4. selectors:
  5.   - match:
  6.       kuma.io/service: cross-mesh-gateway
  7. conf:
  8.   listeners:
  9.     - port: 8080
  10.       protocol: HTTP
  11.       crossMesh: true
  12.       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:

  1. ...
  2.   outbound:
  3.     - port: 8080
  4.       tags:
  5.         kuma.io/service: cross-mesh-gateway
  6.         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. In the future, this limitation may be relaxed.

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

All options