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
Early Access
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Plugin Hub
  • decK
  • Kubernetes Ingress Controller
  • Insomnia
  • Kuma

  • Docs contribution guidelines
  • 2.0.x (latest)
  • 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
    • Policy matching
    • 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
  • Default TrafficRoute
  • L4 Traffic Split
  • L4 Traffic Rerouting
  • L7 Traffic Split
  • L7 Traffic Modification
  • L7 Traffic Rerouting
  • Load balancer types
Kong Mesh
2.0.x (latest)
  • Home
  • Kong Mesh
  • Policies
  • Traffic Route

Traffic Route

Traffic Route is an outbound policy. Dataplanes whose configuration is modified are in the sources matcher.

This policy lets you configure routing rules for the traffic in the mesh. It supports weighted routing and can be used to implement versioning across services or to support deployment strategies such as blue/green or canary.

Note the following:

  • The configuration must specify the data plane proxies for the routing rules.
  • The spec.destinations field supports only kuma.io/service.
  • All available tags are supported for spec.conf.
  • This is an outbound connection policy. Make sure that your data plane proxy configuration includes the appropriate tags.

Kong Mesh also supports locality aware load balancing.

Default TrafficRoute

The control plane creates a default TrafficRoute every time a new Mesh is created. The default TrafficRoute enables the traffic between all the services in the mesh.

Kubernetes
Universal
apiVersion: kuma.io/v1alpha1
kind: TrafficRoute
mesh: default
metadata:
  name: route-all-default
spec:
  sources:
    - match:
        kuma.io/service: '*'
  destinations:
    - match:
        kuma.io/service: '*'
  conf:
    loadBalancer:
      roundRobin: {}
    destination:
      kuma.io/service: '*'
type: TrafficRoute
name: route-all-default
mesh: default
sources:
  - match:
      kuma.io/service: '*'
destinations:
  - match:
      kuma.io/service: '*'
conf:
  loadBalancer:
    roundRobin: {}
  destination:
    kuma.io/service: '*'

Usage

Here is a full example of TrafficRoute policy

Kubernetes
Universal
apiVersion: kuma.io/v1alpha1
kind: TrafficRoute
mesh: default
metadata:
  name: full-example
spec:
  sources:
    - match:
        kuma.io/service: backend_default_svc_80
  destinations:
    - match:
        kuma.io/service: redis_default_svc_6379
  conf:
    http:
    - match:
        method: # one of either "prefix", "exact" or "regex" is allowed
          exact: GET
          regex: "^POST|PUT$"
        path: # one of either "prefix", "exact" or "regex" is allowed
          prefix: /users
          exact: /users/user-1
          regex: "^users$"
        headers:
          some-header: # one of either "prefix", "exact" or "regex" will be allowed
            exact: some-value
            prefix: some-
            regex: "^users$"
      modify: # optional section
        path: # one of "rewritePrefix" or "regex" is allowed
          rewritePrefix: /not-users # rewrites previously matched prefix
          regex: # (example to change the path from "/service/foo/v1/api" to "/v1/api/instance/foo")
            pattern: "^/service/([^/]+)(/.*)$"
            substitution: '\2/instance/\1'
        host: # one of "value" or "fromPath" is allowed
          value: "XYZ"
          fromPath: # (example to extract "envoyproxy.io" host header from "/envoyproxy.io/some/path" path)
            pattern: "^/(.+)/.+$"
            substitution: '\1'
        requestHeaders:
          add:
            - name: x-custom-header
              value: xyz
              append: true # if true then if there is x-custom-header already, it will append xyz to the value 
          remove:
            - name: x-something
        responseHeaders:
          add:
            - name: x-custom-header
              value: xyz
              append: true
          remove:
            - name: x-something
      destination: # one of "destination", "split" is allowed
        kuma.io/service: redis_default_svc_6379
      split:
        - weight: 100
          destination:
            kuma.io/service: redis_default_svc_6379
    destination: # one of "destination", "split" is allowed
      kuma.io/service: redis_default_svc_6379
    split:
      - weight: 100
        destination:
          kuma.io/service: redis_default_svc_6379
    loadBalancer: # one of "roundRobin", "leastRequest", "ringHash", "random", "maglev" is allowed    
      roundRobin: {}
      leastRequest:
        choiceCount: 8
      ringHash:
        hashFunction: "MURMUR_HASH_2"
        minRingSize: 64
        maxRingSize: 1024
      random: {}
      maglev: {}
type: TrafficRoute
name: full-example
mesh: default
sources:
  - match:
      kuma.io/service: backend
destinations:
  - match:
      kuma.io/service: redis
conf:
  http:
    - match:
        method: # one of either "prefix", "exact" or "regex" is allowed
          exact: GET
          regex: "^POST|PUT$"
        path: # one of either "prefix", "exact" or "regex" is allowed
          prefix: /users
          exact: /users/user-1
          regex: "^users$"
        headers:
          some-header: # one of either "prefix", "exact" or "regex" will be allowed
            exact: some-value
            prefix: some-
            regex: "^users$"
      modify: # optional section
        path: # one of "rewritePrefix" or "regex" is allowed
          rewritePrefix: /not-users # rewrites previously matched prefix
          regex: # (example to change the path from "/service/foo/v1/api" to "/v1/api/instance/foo")
            pattern: "^/service/([^/]+)(/.*)$"
            substitution: '\2/instance/\1'
        host: # one of "value" or "fromPath" is allowed
          value: "XYZ"
          fromPath: # (example to extract "envoyproxy.io" host header from "/envoyproxy.io/some/path" path)
            pattern: "^/(.+)/.+$"
            substitution: '\1'
        requestHeaders:
          add:
            - name: x-custom-header
              value: xyz
              append: true # if true then if there is x-custom-header already, it will append xyz to the value 
          remove:
            - name: x-something
        responseHeaders:
          add:
            - name: x-custom-header
              value: xyz
              append: true
          remove:
            - name: x-something
      destination: # one of "destination", "split" is allowed
        kuma.io/service: redis
      split:
        - weight: 100
          destination:
            kuma.io/service: redis
  destination: # one of "destination", "split" is allowed
    kuma.io/service: redis
  split:
    - weight: 100
      destination:
        kuma.io/service: redis
  loadBalancer: # one of "roundRobin", "leastRequest", "ringHash", "random", "maglev" is allowed    
    roundRobin: {}
    leastRequest:
      choiceCount: 8
    ringHash:
      hashFunction: "MURMUR_HASH_2"
      minRingSize: 64
      maxRingSize: 1024
    random: {}
    maglev: {}

Kong Mesh utilizes positive weights in the TrafficRoute policy and not percentages, therefore Kong Mesh does not check if the total adds up to 100. If we want to stop sending traffic to a destination service we change the weight for that service to 0.

L4 Traffic Split

We can use TrafficRoute to split a TCP traffic between services with different tags implementing A/B testing or canary deployments.

Here is an example of a TrafficRoute that splits the traffic over the two different versions of the application. 90% of the connections from backend_default_svc_80 service will be initiated to redis_default_svc_6379 with tag version: 1.0 and 10% of the connections will be initiated to version: 2.0

Kubernetes
Universal
apiVersion: kuma.io/v1alpha1
kind: TrafficRoute
mesh: default
metadata:
  name: split-traffic
spec:
  sources:
    - match:
        kuma.io/service: backend_default_svc_80
  destinations:
    - match:
        kuma.io/service: redis_default_svc_6379
  conf:
    split:
      - weight: 90
        destination:
          kuma.io/service: redis_default_svc_6379
          version: '1.0'
      - weight: 10
        destination:
          kuma.io/service: redis_default_svc_6379
          version: '2.0'
type: TrafficRoute
name: split-traffic
mesh: default
sources:
  - match:
      kuma.io/service: backend
destinations:
  - match:
      kuma.io/service: redis
conf:
  split:
    - weight: 90
      destination:
        kuma.io/service: redis
        version: '1.0'
    - weight: 10
      destination:
        kuma.io/service: redis
        version: '2.0'

L4 Traffic Rerouting

We can use TrafficRoute to fully reroute a TCP traffic to different version of a service or even completely different service.

Here is an example of a TrafficRoute that redirects the traffic to another-redis_default_svc_6379 when backend_default_svc_80 is trying to consume redis_default_svc_6379.

Kubernetes
Universal
apiVersion: kuma.io/v1alpha1
kind: TrafficRoute
mesh: default
metadata:
  name: reroute-traffic
spec:
  sources:
    - match:
        kuma.io/service: backend_default_svc_80
  destinations:
    - match:
        kuma.io/service: redis_default_svc_6379
  conf:
    destination:
      kuma.io/service: another-redis_default_svc_6379
type: TrafficRoute
name: reroute-traffic
mesh: default
sources:
  - match:
      kuma.io/service: backend_default_svc_80
destinations:
  - match:
      kuma.io/service: redis_default_svc_6379
conf:
  destination:
    kuma.io/service: another-redis_default_svc_6379

L7 Traffic Split

We can use TrafficRoute to split an HTTP traffic between services with different tags implementing A/B testing or canary deployments.

Here is an example of a TrafficRoute that splits the traffic from frontend_default_svc_80 to backend_default_svc_80 between versions, but only on endpoints starting with /api. All other endpoints will go to version: 1.0

Kubernetes
Universal
apiVersion: kuma.io/v1alpha1
kind: TrafficRoute
mesh: default
metadata:
  name: api-split
spec:
  sources:
    - match:
        kuma.io/service: frontend_default_svc_80
  destinations:
    - match:
        kuma.io/service: backend_default_svc_80
  conf:
    http:
    - match:
        path:
          prefix: "/api"
      split:
      - weight: 90
        destination:
          kuma.io/service: backend_default_svc_80
          version: '1.0'
      - weight: 10
        destination:
          kuma.io/service: backend_default_svc_80
          version: '2.0'
    destination: # default rule is applied when endpoint does not match any rules in http section
      kuma.io/service: backend_default_svc_80
      version: '1.0'
type: TrafficRoute
name: api-split
mesh: default
sources:
  - match:
      kuma.io/service: frontend_default_svc_80
destinations:
  - match:
      kuma.io/service: backend_default_svc_80
conf:
  http:
    - match:
        path:
          prefix: "/api"
      split:
        - weight: 90
          destination:
            kuma.io/service: backend_default_svc_80
            version: '1.0'
        - weight: 10
          destination:
            kuma.io/service: backend_default_svc_80
            version: '2.0'
  destination: # default rule is applied when endpoint does not match any rules in http section
    kuma.io/service: backend_default_svc_80
    version: '1.0'

In order to use L7 Traffic Split, we need to mark the destination service with kuma.io/protocol: http.

L7 Traffic Modification

We can use TrafficRoute to modify outgoing requests, by setting new path or changing request and response headers.

Here is an example of a TrafficRoute that adds x-custom-header with value xyz when frontend_default_svc_80 tries to consume backend_default_svc_80.

Kubernetes
Universal
apiVersion: kuma.io/v1alpha1
kind: TrafficRoute
mesh: default
metadata:
  name: add-header
spec:
  sources:
    - match:
        kuma.io/service: frontend_default_svc_80
  destinations:
    - match:
        kuma.io/service: backend_default_svc_80
  conf:
    http:
    - match:
        path:
          prefix: "/"
      modify:
        requestHeader:
          add:
            - name: x-custom-header
              value: xyz
      destination:
        kuma.io/service: backend_default_svc_80
    destination:
      kuma.io/service: backend_default_svc_80
type: TrafficRoute
name: add-header
mesh: default
sources:
  - match:
      kuma.io/service: frontend_default_svc_80
destinations:
  - match:
      kuma.io/service: backend_default_svc_80
conf:
  http:
    - match:
        path:
          prefix: "/"
      modify:
        requestHeader:
          add:
            - name: x-custom-header
              value: xyz
      destination:
        kuma.io/service: backend_default_svc_80
  destination:
    kuma.io/service: backend_default_svc_80

In order to use L7 Traffic Modification, we need to mark the destination service with kuma.io/protocol: http.

L7 Traffic Rerouting

We can use TrafficRoute to modify outgoing requests, by setting new path or changing request and response headers.

Here is an example of a TrafficRoute that redirect traffic to offers_default_svc_80 when frontend_default_svc_80 is trying to consume backend_default_svc_80 on /offers endpoint.

Kubernetes
Universal
apiVersion: kuma.io/v1alpha1
kind: TrafficRoute
mesh: default
metadata:
  name: http-reroute
spec:
  sources:
    - match:
        kuma.io/service: frontend_default_svc_80
  destinations:
    - match:
        kuma.io/service: backend_default_svc_80
  conf:
    http:
    - match:
        path:
          prefix: "/offers"
      destination:
        kuma.io/service: offers_default_svc_80
    destination:
      kuma.io/service: backend_default_svc_80
type: TrafficRoute
name: http-reroute
mesh: default
sources:
  - match:
      kuma.io/service: frontend_default_svc_80
destinations:
  - match:
      kuma.io/service: backend_default_svc_80
conf:
  http:
    - match:
        path:
          prefix: "/offers"
      destination:
        kuma.io/service: offers_default_svc_80
  destination:
    kuma.io/service: backend_default_svc_80

In order to use L7 Traffic Rerouting, we need to mark the destination service with kuma.io/protocol: http.

Load balancer types

There are different load balancing algorithms that can be used to determine how traffic is routed to the destinations. By default TrafficRoute uses the roundRobin load balancer, but more options are available:

  • roundRobin is a simple algorithm in which each available upstream host is selected in round robin order.

    Example:

    loadBalancer:
      roundRobin: {}
    
  • leastRequest uses different algorithms depending on whether the hosts have the same or different weights. It has a single configuration field choiceCount, which denotes the number of random healthy hosts from which the host with the fewer active requests will be chosen.

    Example:

    loadBalancer:
      leastRequest:
        choiceCount: 8
    
  • ringHash implements consistent hashing to the upstream hosts. It has the following fields:
    • hashFunction the hash function used to hash the hosts onto the ketama ring. Can be XX_HASH or MURMUR_HASH_2.
    • minRingSize minimum hash ring size.
    • maxRingSize maximum hash ring size.

    Example:

    loadBalancer:
      ringHash:
        hashFunction: "MURMUR_HASH_2"
        minRingSize: 64
        maxRingSize: 1024
    
  • random selects a random available host.

    Example:

    loadBalancer:
      random: {}
    
  • maglev implements consistent hashing to upstream hosts

    Example:

    loadBalancer:
      maglev: {}
    
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