Skip to content
Kong Logo | Kong Docs Logo
  • Docs
    • Explore the API Specs
      View all API Specs View all API Specs View all API Specs arrow image
    • Documentation
      API Specs
      Kong Gateway
      Lightweight, fast, and flexible cloud-native API gateway
      Kong Konnect
      Single platform for SaaS end-to-end connectivity
      Kong AI Gateway
      Multi-LLM AI Gateway for GenAI infrastructure
      Kong Mesh
      Enterprise service mesh based on Kuma and Envoy
      decK
      Helps manage Kong’s configuration in a declarative fashion
      Kong Ingress Controller
      Works inside a Kubernetes cluster and configures Kong to proxy traffic
      Kong Gateway Operator
      Manage your Kong deployments on Kubernetes using YAML Manifests
      Insomnia
      Collaborative API development platform
  • Plugin Hub
    • Explore the Plugin Hub
      View all plugins View all plugins View all plugins arrow image
    • Functionality View all View all arrow image
      View all plugins
      AI's icon
      AI
      Govern, secure, and control AI traffic with multi-LLM AI Gateway plugins
      Authentication's icon
      Authentication
      Protect your services with an authentication layer
      Security's icon
      Security
      Protect your services with additional security layer
      Traffic Control's icon
      Traffic Control
      Manage, throttle and restrict inbound and outbound API traffic
      Serverless's icon
      Serverless
      Invoke serverless functions in combination with other plugins
      Analytics & Monitoring's icon
      Analytics & Monitoring
      Visualize, inspect and monitor APIs and microservices traffic
      Transformations's icon
      Transformations
      Transform request and responses on the fly on Kong
      Logging's icon
      Logging
      Log request and response data using the best transport for your infrastructure
  • Support
  • Community
  • Kong Academy
Get a Demo Start Free Trial
Kong Mesh
2.10.x (latest)
  • Home icon
  • Kong Mesh
  • Using Mesh
  • Managing Ingress Traffic
  • Configuring built-in listeners
github-edit-pageEdit this page
report-issueReport an issue
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Kong AI Gateway
  • Plugin Hub
  • decK
  • Kong Ingress Controller
  • Kong Gateway Operator
  • Insomnia
  • Kuma

  • Docs contribution guidelines
  • dev
  • 2.10.x (latest)
  • 2.9.x
  • 2.8.x
  • 2.7.x (LTS)
  • 2.6.x
  • 2.5.x
  • 2.4.x
  • 2.3.x
  • 2.2.x
  • Introduction
    • About service meshes
    • Overview of Kong Mesh
    • How Kong Mesh works
    • Architecture
    • Install
    • Concepts
    • Stages of software availability
    • Version support policy
    • Software Bill of Materials
    • Vulnerability patching process
    • Mesh requirements
    • Release notes
  • Quickstart
    • Deploy Kong Mesh on Kubernetes
    • Deploy Kong Mesh on Universal
  • Kong Mesh in Production
    • Overview
    • Deployment topologies
      • Overview
      • Single-zone deployment
      • Multi-zone deployment
    • Use Kong Mesh
    • Control plane deployment
      • Kong Mesh license
      • Deploy a single-zone control plane
      • Deploy a multi-zone global control plane
      • Zone Ingress
      • Zone Egress
      • Configure zone proxy authentication
      • Control plane configuration reference
      • Systemd
      • Kubernetes
      • kumactl
      • Deploy Kong Mesh in Production with Helm
    • Configuring your Mesh and multi-tenancy
    • Data plane configuration
      • Data plane proxy
      • Configure the data plane on Kubernetes
      • Configure the data plane on Universal
      • Configure the Kong Mesh CNI
      • Configure transparent proxying
      • IPv6 support
    • Secure your deployment
      • Manage secrets
      • Authentication with the API server
      • Authentication with the data plane proxy
      • Configure data plane proxy membership
      • Secure access across services
      • Kong Mesh RBAC
      • FIPS support
    • Kong Mesh user interface
    • Inspect API
      • Matched policies
      • Affected data plane proxies
      • Envoy proxy configuration
    • Upgrades and tuning
      • Upgrade Kong Mesh
      • Performance fine-tuning
      • Version specific upgrade notes
    • Control Plane Configuration
      • Modifying the configuration
      • Inspecting the configuration
      • Store
  • Using Kong Mesh
    • Zero Trust & Application Security
      • Mutual TLS
      • External Service
    • Resiliency & Failover
      • Dataplane Health
      • Service Health Probes
    • Managing incoming traffic with gateways
      • How ingress works in Kuma
      • Delegated gateways
      • Built-in gateways
      • Running built-in gateway pods on Kubernetes
      • Configuring built-in listeners
      • Configuring built-in routes
      • Using the Kubernetes Gateway API
    • Observability
      • Demo setup
      • Control plane metrics
      • Configuring Prometheus
      • Configuring Grafana
      • Configuring Datadog
      • Observability in multi-zone
    • Route & Traffic shaping
      • Protocol support in Kong Mesh
    • Service Discovery & Networking
      • Service Discovery
      • MeshService
      • MeshMultiZoneService
      • HostnameGenerator
      • DNS
      • Non-mesh traffic
      • MeshExternalService
      • Transparent Proxying
  • Policies
    • Introduction
      • What is a policy?
      • What do policies look like?
      • Writing a targetRef
      • Merging configuration
      • Using policies with MeshService
      • Examples
      • Applying policies in shadow mode
    • MeshAccessLog
      • TargetRef support matrix
      • Configuration
      • Examples
    • MeshCircuitBreaker
      • TargetRef support matrix
      • Configuration
      • Examples
    • MeshFaultInjection
      • TargetRef support matrix
      • Configuration
      • Examples
    • MeshHealthCheck
      • TargetRef support matrix
      • Configuration
      • Examples
    • MeshHTTPRoute
      • TargetRef support matrix
      • Configuration
      • Examples
      • Merging
    • MeshLoadBalancingStrategy
      • TargetRef support matrix
      • Configuration
      • Examples
    • MeshMetric
      • TargetRef support matrix
      • Configuration
      • Prometheus
      • OpenTelemetry
      • Examples
    • MeshPassthrough
      • TargetRef support matrix
      • Configuration
      • Examples
    • MeshProxyPatch
      • TargetRef support matrix
      • Configuration
      • Examples
      • Merging
    • MeshRateLimit
      • TargetRef support matrix
      • Configuration
      • Examples
    • MeshRetry
      • TargetRef support matrix
      • Configuration
      • Examples
    • MeshTCPRoute
      • TargetRef support matrix
      • Configuration
      • Examples
      • Route policies with different types targeting the same destination
    • MeshTimeout
      • TargetRef support matrix
      • Configuration
      • Examples
    • MeshTLS
      • TargetRef support matrix
      • Configuration
      • Examples
    • MeshTrace
      • TargetRef support matrix
      • Configuration
      • Examples
    • MeshTrafficPermission
      • TargetRef support matrix
      • Configuration
      • Examples
    • MeshOPA
    • MeshGlobalRateLimit (beta)
    • Previous Policies
      • General notes about Kong Mesh policies
      • How Kong Mesh chooses the right policy to apply
      • Traffic Permissions
      • Traffic Route
      • Traffic Metrics
      • Traffic Trace
      • Traffic Log
      • Locality-aware Load Balancing
      • Fault Injection
      • Health Check
      • Circuit Breaker
      • Retry
      • Timeout
      • Rate Limit
      • Virtual Outbound
      • MeshGatewayRoute
      • OPA policy
  • Guides
    • Federate zone control plane
    • Add a builtin Gateway
    • Add Kong as a delegated Gateway
    • Kubernetes Gateway API
    • Collect Metrics with OpenTelemetry
    • Migration to the new policies
    • Progressively rolling in strict mTLS
    • Producer and consumer policies
    • Configuring inbound traffic with Rules API
    • Upgrading Transparent Proxy
    • Deploy Kong Mesh using Terraform and Konnect
    • Import existing Konnect Kong Mesh deployment to Terraform
  • Enterprise Features
    • Overview
    • HashiCorp Vault CA
    • Amazon ACM Private CA
    • cert-manager Private CA
    • OPA policy support
    • MeshOPA
    • Multi-zone authentication
    • FIPS support
    • Certificate Authority rotation
    • Role-Based Access Control
    • Red Hat
      • UBI Images
      • Red Hat OpenShift Quickstart
    • Windows Support
    • ECS Support
    • Auditing
    • MeshGlobalRateLimit (beta)
    • Verify signatures for signed Kong Mesh images
    • Build provenance
      • Verify build provenance for signed Kong Mesh images
      • Verify build provenance for signed Kong Mesh binaries
  • Reference
    • HTTP API
    • Kubernetes annotations and labels
    • Kuma data collection
    • Control plane configuration reference
    • Envoy proxy template
  • Community
    • Contribute to Kuma
enterprise-switcher-icon Switch to OSS
On this pageOn this page
  • TLS Termination
    • Server Certificate Secrets
    • Cross-mesh
  • All options

Configuring built-in listeners

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

These are Kong Mesh 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 Kong Mesh matching semantics:

Kubernetes
Universal
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. 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 Kong Mesh tags so that Kong Mesh policy configuration can be targeted to specific listeners.

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

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.

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

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

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 Kong Mesh tags, policy 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.

Dataplane tags Listener tags Final Tags
kuma.io/service=edge-gateway_default_svc vhost=foo.example.com kuma.io/service=edge-gateway_default_svc,vhost=foo.example.com
kuma.io/service=edge-gateway_default_svc kuma.io/service=example,domain=example.com kuma.io/service=example,domain=example.com
kuma.io/service=edge_default_svc,location=us version=2 kuma.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.

Kubernetes
Universal
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 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
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 MeshHTTPRoutes. 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.

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

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:

...
  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. In the future, this limitation may be relaxed.

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

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. "TLS"
        6. 3
        7. "HTTP"
        8. 4
        9. "HTTPS"
        10. 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
        5. "PASSTHROUGH"
        6. 2
    • 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 Sat May 10 2025 10:38:38 GMT+0000 (Coordinated Universal Time)

Thank you for your feedback.
Was this page useful?
Too much on your plate? close cta icon
More features, less infrastructure with Kong Konnect. 1M requests per month for free.
Try it for Free
  • Kong
    Powering the API world

    Increase developer productivity, security, and performance at scale with the unified platform for API management, service mesh, and ingress controller.

    • Products
      • Kong Konnect
      • Kong Gateway Enterprise
      • Kong Gateway
      • Kong Mesh
      • Kong Ingress Controller
      • Kong Insomnia
      • Product Updates
      • Get Started
    • Documentation
      • Kong Konnect Docs
      • Kong Gateway Docs
      • Kong Mesh Docs
      • Kong Insomnia Docs
      • Kong Konnect Plugin Hub
    • Open Source
      • Kong Gateway
      • Kuma
      • Insomnia
      • Kong Community
    • Company
      • About Kong
      • Customers
      • Careers
      • Press
      • Events
      • Contact
  • Terms• Privacy• Trust and Compliance
© Kong Inc. 2025