Skip to content
Kong Docs are moving soon! Our docs are migrating to a new home. You'll be automatically redirected to the new site in the future. In the meantime, view this page on the new site!
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.5.x
  • Home icon
  • Kong Mesh
  • Policies
  • MeshGatewayRoute
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
    • Stages of software availability
    • Version support policy
    • Mesh requirements
    • Release notes
  • Getting Started
  • Kong Mesh in Production
    • Overview
    • Deployment topologies
      • Overview
      • Standalone deployment
      • Multi-zone deployment
    • Install kumactl
    • Use Kong Mesh
    • Control plane deployment
      • Kong Mesh license
      • Deploy a standalone control plane
      • Deploy a multi-zone global control plane
      • Zone Ingress
      • Zone Egress
      • Configure zone proxy authentication
      • Control plane configuration reference
      • Systemd
      • Kubernetes
    • Create multiple service meshes in a cluster
    • 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
    • Upgrades and tuning
      • Upgrade Kong Mesh
      • Performance fine-tuning
  • Deploy
    • Explore Kong Mesh with the Kubernetes demo app
    • Explore Kong Mesh with the Universal demo app
  • Explore
    • Gateway
      • Delegated
      • Builtin
    • CLI
      • kumactl
    • Observability
      • Demo setup
      • Control plane metrics
      • Configuring Prometheus
      • Configuring Grafana
      • Configuring Datadog
      • Observability in multi-zone
    • Inspect API
      • Matched policies
      • Affected data plane proxies
      • Envoy proxy configuration
    • Kubernetes Gateway API
      • Installation
      • Gateways
      • TLS termination
      • Customization
      • Multi-mesh
      • Multi-zone
      • GAMMA
      • How it works
  • Networking
    • Service Discovery
    • DNS
      • How it works
      • Installation
      • Configuration
      • Usage
    • Non-mesh traffic
      • Incoming
      • Outgoing
    • Transparent Proxying
  • Monitor & manage
    • Dataplane Health
      • Circuit Breaker Policy
      • Kubernetes and Universal Service Probes
      • Health Check Policy
    • Control Plane Configuration
      • Modifying the configuration
      • Inspecting the configuration
      • Store
  • Policies
    • 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
    • Mutual TLS
      • Usage of "builtin" CA
      • Usage of "provided" CA
      • Permissive mTLS
      • Certificate Rotation
    • Traffic Permissions
      • Usage
      • Access to External Services
    • Traffic Route
      • Usage
    • Traffic Metrics
      • Expose metrics from data plane proxies
      • Expose metrics from applications
      • Override Prometheus settings per data plane proxy
      • Filter Envoy metrics
      • Secure data plane proxy metrics
    • Traffic Trace
      • Add a tracing backend to the mesh
      • Add TrafficTrace resource
    • Traffic Log
      • Add a logging backend
      • Add a TrafficLog resource
      • Logging external services
      • Builtin Gateway support
      • Access Log Format
    • Locality-aware Load Balancing
      • Enabling locality-aware load balancing
    • Fault Injection
      • Usage
      • Matching
    • Health Check
      • Usage
      • Matching
    • Circuit Breaker
      • Usage
      • Matching
      • Builtin Gateway support
      • Non-mesh traffic
    • External Service
      • Usage
      • Builtin Gateway support
    • Retry
      • Usage
      • Matching
      • Builtin Gateway support
    • Timeout
      • Usage
      • Configuration
      • Default general-purpose Timeout policy
      • Matching
      • Builtin Gateway support
      • Inbound timeouts
      • Non-mesh traffic
    • Rate Limit
      • Usage
      • Matching destinations
      • Builtin Gateway support
    • Virtual Outbound
      • Examples
    • MeshGateway
      • TLS Termination
    • MeshGatewayRoute
      • Listener tags
      • Matching
      • Filters
      • Reference
    • MeshGatewayInstance
    • Service Health Probes
      • Kubernetes
      • Universal probes
    • 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
    • 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
    • MeshTrace
      • TargetRef support matrix
      • Configuration
      • Examples
    • MeshTrafficPermission
      • TargetRef support matrix
      • Configuration
      • Examples
    • MeshLoadBalancingStrategy
      • TargetRef support matrix
      • Configuration
      • Examples
    • OPA policy
    • MeshOPA (beta)
    • MeshGlobalRateLimit (beta)
  • Enterprise Features
    • Overview
    • HashiCorp Vault CA
    • Amazon ACM Private CA
    • cert-manager Private CA
    • OPA policy support
    • MeshOPA (beta)
    • 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)
  • 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
  • Listener tags
  • Matching
  • Filters
  • Reference
You are browsing documentation for an older version. See the latest documentation here.

MeshGatewayRoute

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

MeshGatewayRoute is a Kong Mesh dataplane policy that replaces TrafficRoute for Kong Mesh Gateway. It configures how a gateway should process network traffic. At the moment, it targets HTTP routing use cases. MeshGatewayRoutes are attached to gateways by matching their selector to the MeshGateway listener tags. This requires the kuma.io/service tag and, optionally, additional tags to match specific MeshGateway listeners.

The following MeshGatewayRoute routes traffic to the backend service and attaches to any listeners tagged with vhost=foo.example.com that attach to builtin gateways with kuma.io/service: edge-gateway.

Universal
Kubernetes
type: MeshGatewayRoute
mesh: default
name: foo.example.com-backend 
selectors:
- match:
    kuma.io/service: edge-gateway
    vhost: foo.example.com
conf:
  http:
    rules:
      - matches:
          - path:
              match: PREFIX
              value: /
        backends:
          - destination:
              kuma.io/service: backend
apiVersion: kuma.io/v1alpha1
kind: MeshGatewayRoute
mesh: default
metadata:
  name: foo.example.com-backend
spec:
  selectors:
    - match:
        kuma.io/service: edge-gateway
        vhost: foo.example.com
  conf:
    http:
      rules:
        - matches:
            - path:
                match: PREFIX
                value: /
          backends:
            - destination:
                kuma.io/service: backend

Listener tags

When Kong Mesh binds a MeshGatewayRoute to a MeshGateway, careful specification of tags lets you control whether the MeshGatewayRoute will bind to one or more of the listeners declared on the MeshGateway.

Each listener stanza on a MeshGateway has a set of tags; Kong Mesh creates the listener tags by combining these tags with the tags from the underlying builtin gateway Dataplane. A selector that matches only on the kuma.io/service tag will bind to all listeners on the MeshGateway, but a selector that includes listener tags will only bind to matching listeners. One application of this mechanism is to inject standard routes into all virtual hosts, without the need to modify MeshGatewayRoutes that configure specific applications.

Matching

MeshGatewayRoute allows HTTP requests to be matched by various criteria (for example uri path, HTTP headers). When Kong Mesh generates the final Envoy configuration for a builtin gateway Dataplane, it combines all the matching MeshGatewayRoutes into a single set of routing tables, partitioned by the virtual hostname, which is specified either in the MeshGateway listener or in the MeshGatewayRoute.

Kong Mesh sorts the rules in each table by specificity, so that routes with more specific match criteria are always ordered first. For example, a rule that matches on a HTTP header and a path is more specific than one that matches only on path, and the longest match path will be considered more specific. This ordering allows Kong Mesh to combine routing rules from multiple MeshGatewayRoute resources and still produce predictable results.

Filters

Every rule can include filters that further modifies requests. For example, by modifying headers and mirroring, redirecting, or rewriting requests.

For example, the following filters match /prefix, trim it from the path and set the Host header:

...
        - matches:
          - path:
              match: PREFIX
              value: /prefix/
          backends:
          - destination:
              kuma.io/service: backend
          filters:
          - requestHeader:
              set:
              - name: Host
                value: test.com
          - rewrite:
              replacePrefixMatch: "/"

Reference

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