Careful!

You are browsing documentation for a version of Kuma that is not the latest release.

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.

Universal
Kubernetes

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 

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 

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.

Universal
Kubernetes

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

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:
        vhost: foo.example.com
    - port: 8080
      protocol: HTTP
      hostname: bar.example.com
      tags:
        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` tags	Listener tags	Final Tags
kuma.io/service=edge-gateway	vhost=foo.example.com	kuma.io/service=edge-gateway,vhost=foo.example.com
kuma.io/service=edge-gateway	kuma.io/service=example,domain=example.com	kuma.io/service=example,domain=example.com
kuma.io/service=edge,location=us	version=2	kuma.io/service=edge,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.

Universal
Kubernetes

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

apiVersion: kuma.io/v1alpha1
kind: MeshGateway
mesh: default
metadata:
  name: edge-gateway
spec:
  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 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.

Kubernetes
Universal

kubectl apply -f <(
cat<<EOF
apiVersion: v1
kind: Secret
metadata:
  name: foo-example-com-certificate
  namespace: kuma-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
EOF
)

kumactl apply -f <(
cat<<EOF
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)
EOF
)

All options

$schema: http://json-schema.org/draft-04/schema#

$ref: #/definitions/MeshGateway

definitions

MeshGateway

## Mesh Gateway
MeshGateway is a virtual proxy. Each MeshGateway is bound to a set of builtin gateway dataplanes. Each builtin dataplane instance can host exactly one Gateway proxy configuration. Gateway aligns with the Kubernetes Gateway API. See that spec for detailed documentation.
Type: object
This schema accepts additional properties.
Properties
- selectors
  - Selectors is a list of selectors that are used to match builtin gateway dataplanes that will receive this MeshGateway configuration.
  - Type: array
    - Items
    - $ref: #/definitions/kuma.mesh.v1alpha1.Selector
- tags
  - Tags is the set of tags common to all of the gateway's listeners. This field must not include a kuma.io/service tag (the service is always defined on the dataplanes).
  - Type: object
  - This schema accepts additional properties.
  - Properties
- conf
  - The desired configuration of the MeshGateway.
  - Type: object
  - $ref: #/definitions/kuma.mesh.v1alpha1.MeshGateway.Conf
  - This schema accepts additional properties.
  - Properties kuma.mesh.v1alpha1.MeshGateway.Conf
## Conf
Conf defines the desired state of MeshGateway. Aligns with MeshGatewaySpec.
Type: object
This schema accepts additional properties.
Properties
- listeners
  - Listeners define logical endpoints that are bound on this MeshGateway's address(es).
  - Type: array
    - Items
    - $ref: #/definitions/kuma.mesh.v1alpha1.MeshGateway.Listener kuma.mesh.v1alpha1.MeshGateway.Listener
## Listener
Type: object
This schema accepts additional properties.
Properties
- hostname
  - Hostname specifies the virtual hostname to match for protocol types that define this concept. When unspecified, "", or *, all hostnames are matched. This field can be omitted for protocols that don't require hostname based matching.
  - Type: string
- port
  - Port is the network port. Multiple listeners may use the same port, subject to the Listener compatibility rules.
  - Type: integer
- protocol
  - #### Protocol
  - The value is restricted to the following:
    1. "NONE"
    2. 0
    3. "TCP"
    4. 1
    5. "HTTP"
    6. 4
    7. "HTTPS"
    8. 5
- tls
  - TLS is the TLS configuration for the Listener. This field is required if the Protocol field is "HTTPS" or "TLS" and ignored otherwise.
  - Type: object
  - $ref: #/definitions/kuma.mesh.v1alpha1.MeshGateway.TLS.Conf
  - This schema accepts additional properties.
  - Properties
- tags
  - Tags specifies a unique combination of tags that routes can use to match themselves to this listener. When matching routes to listeners, the control plane constructs a set of matching tags for each listener by forming the union of the gateway tags and the listener tags. A route will be attached to the listener if all of the route's tags are preset in the matching tags
  - Type: object
  - This schema accepts additional properties.
  - Properties
- crossMesh
  - CrossMesh enables traffic to flow to this listener only from other meshes.
  - Type: boolean
- resources
  - Resources is used to specify listener-specific resource settings.
  - Type: object
  - $ref: #/definitions/kuma.mesh.v1alpha1.MeshGateway.Listener.Resources
  - This schema accepts additional properties.
  - Properties kuma.mesh.v1alpha1.MeshGateway.Listener.Resources
## Resources
Type: object
This schema accepts additional properties.
Properties
- connection_limit
  - Type: integer kuma.mesh.v1alpha1.MeshGateway.TLS.Conf
## Conf
Aligns with MeshGatewayTLSConfig.
Type: object
This schema accepts additional properties.
Properties
- mode
  - #### Mode
  - The value is restricted to the following:
    1. "NONE"
    2. 0
    3. "TERMINATE"
    4. 1
- certificates
  - Certificates is an array of datasources that contain TLS certificates and private keys. Each datasource must contain a sequence of PEM-encoded objects. The server certificate and private key are required, but additional certificates are allowed and will be added to the certificate chain. The server certificate must be the first certificate in the datasource. When multiple certificate datasources are configured, they must have different key types. In practice, this means that one datasource should contain an RSA key and certificate, and the other an ECDSA key and certificate.
  - Type: array
    - Items
    - $ref: #/definitions/kuma.system.v1alpha1.DataSource
- options
  - Options should eventually configure how TLS is configured. This is where cipher suite and version configuration can be specified, client certificates enforced, and so on.
  - Type: object
  - $ref: #/definitions/kuma.mesh.v1alpha1.MeshGateway.TLS.Options
  - This schema accepts additional properties.
  - Properties kuma.mesh.v1alpha1.MeshGateway.TLS.Options
## Options
TODO(jpeach)
Type: object
This schema accepts additional properties.
Properties kuma.mesh.v1alpha1.Selector
## Selector
Selector defines structure for selecting tags for given dataplane
Type: object
This schema accepts additional properties.
Properties
- match
  - Tags to match, can be used for both source and destinations
  - Type: object
  - This schema accepts additional properties.
  - Properties kuma.system.v1alpha1.DataSource
## Data Source
DataSource defines the source of bytes to use.
Type: object
This schema accepts additional properties.
Properties
- secret
  - Data source is a secret with given Secret key.
  - Type: string
- file
  - Data source is a path to a file. Deprecated, use other sources of a data.
  - Type: string
- inline
  - Data source is inline bytes.
  - Type: string
- inlineString
  - Data source is inline string
  - Type: string

Generated with json-schema-md-doc Mon Jul 28 2025 21:17:43 GMT+0000 (Coordinated Universal Time)