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
Get a Demo Start Free Trial
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Plugin Hub
  • decK
  • Kubernetes Ingress Controller
  • Insomnia
  • Kuma

  • Docs contribution guidelines
  • 2.1.x (latest)
  • 2.0.x
  • 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
    • Understanding TargetRef policies
    • 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
  • TLS Termination
    • Server Certificate Secrets
Kong Mesh
2.0.x
  • Home
  • Kong Mesh
  • Policies
  • MeshGateway
You are browsing documentation for an outdated version. See the latest documentation here.

MeshGateway

MeshGateway is a policy used to configure Kong Mesh’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 Kong Mesh 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 Kong Mesh tags so that Kong Mesh 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 Kong Mesh tags, policy can still be targeted to a specific listener. Kong Mesh 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 Kong Mesh 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=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.

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 Kong Mesh 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 Kong Mesh datasource (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. 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: 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
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
)
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