MeshGateway

MeshGateway is a policy used to configure Kuma’s builtin gateway. It is used in combination with MeshGatewayRoute.

A builtin gateway Dataplane with no additional configuration does nothing. It is simply an unconfigured unit of proxying capacity. To make use of it, we need to place a MeshGateway resource on it. 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 Kuma matching semantics.

The most important field in the MeshGateway resource is the listener field. A MeshGateway can have any number of listeners, where each listener represents an endpoint that can accept network traffic. To configure a listener, you need to specify the port number, the network protocol, and (optionally) the hostname to accept. Each listener has its own set of Kuma tags so that Kuma policy configuration can be targeted to specific listeners.

  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
  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
  10.   conf:
  11.     listeners:
  12.     - port: 8080
  13.       protocol: HTTP
  14.       hostname: foo.example.com
  15.       tags:
  16.         port: http/8080

The selectors field matches Dataplane tags to determine which Dataplanes will be configured with this MeshGateway. The listeners field is an array of listeners for the Gateway. In this example, the Gateway will listen for HTTP protocol connections on TCP port 8080. The MeshGateway doesn’t specify which IP addresses will be listened on; that is done in the Dataplane resource. Since HTTP has a protocol-specific concept of hostname, this listener can specify a hostname that it is willing to accept requests for.

It is common to configure HTTP proxies to accept requests for more than one hostname. The Gateway resource supports this by merging listeners that have a common port. Whether merging listeners is allowed depends on the semantics of the protocol field. It is allowed for the most common protocols, HTTP and HTTPS.

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

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 both for 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 overlaying the tags from the listener onto the tags from the Dataplane to which the Gateway is matched. This set of listener tags is what Kuma will match policies against.

Dataplane tagsListener tagsFinal Tags
kuma.io/service=edge-gatewayvhost=foo.example.comkuma.io/service=edge-gateway,vhost=foo.example.com
kuma.io/service=edge-gatewaykuma.io/service=example,domain=example.comkuma.io/service=example,domain=example.com
kuma.io/service=edge,location=usversion=2kuma.io/service=edit,location=us,version=2

The reference doc contains all options on MeshGateway.

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

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