旧バージョンのドキュメントを参照しています。最新のドキュメントはこちらをご参照ください。

MeshTCPRoute

This policy uses new policy matching algorithm. It’s recommended to migrate from TrafficRoute. See “Interactions with TrafficRoute” section for more information.

The MeshTCPRoute policy allows you to alter and redirect TCP requests depending on where the request is coming from and where it’s going to.

TargetRef support matrix

Sidecar

Builtin Gateway

Delegated Gateway

`targetRef`	Allowed kinds
`targetRef.kind`	`Mesh`, `MeshSubset`
`to[].targetRef.kind`	`MeshService`

`targetRef`	Allowed kinds
`targetRef.kind`	`Mesh`, `MeshGateway`, `MeshGateway` with listener `tags`
`to[].targetRef.kind`	`Mesh`

For more information, see the matching docs.

Configuration

Unlike other outbound policies, MeshTCPRoute doesn’t contain default directly in the to array. The default section is nested inside rules, so the policy structure looks like the following:

spec:
  targetRef: # top-level targetRef selects a group of proxies to configure
    kind: Mesh|MeshSubset 
  to:
    - targetRef: # targetRef selects a destination (outbound listener)
        kind: MeshService
        name: backend
      rules:
        - default: # configuration applied for the matched TCP traffic
            backendRefs: [...]

Default configuration

The following describes the default configuration settings of the MeshTCPRoute policy:

backendRefs: (Optional) List of destinations for the request to be redirected to
- kind: One of MeshService, MeshServiceSubset, MeshExtenalService
- name: The service name
- tags: Service tags. These must be specified if the kind is MeshServiceSubset.
- weight: When a request matches the route, the choice of an upstream cluster is determined by its weight. Total weight is a sum of all weights in the backendRefs list.

Gateways

In order to route TCP traffic for a MeshGateway, you need to target the MeshGateway in spec.targetRef and set spec.to[].targetRef.kind: Mesh.

Interactions with `MeshHTTPRoute`

MeshHTTPRoute takes priority over MeshTCPRoute when both are defined for the same service, and the matching MeshTCPRoute is ignored.

Interactions with `TrafficRoute`

MeshTCPRoute takes priority over TrafficRoute when a proxy is targeted by both policies.

All legacy policies like Retry, TrafficLog, Timeout etc. only match on routes defined by TrafficRoute. All new recommended policies like MeshRetry, MeshAccessLog, MeshTimeout etc. match on routes defined by MeshTCPRoute and TrafficRoute.

If you don’t use legacy policies, it’s recommended to remove any existing TrafficRoute. Otherwise, it’s recommended to migrate to new policies and then removing TrafficRoute.

Examples

Traffic split

We can use MeshTCPRoute to split an TCP traffic between different MeshServices implementing A/B testing or canary deployments. If we want to split traffic between v1 and v2 versions of the same service, first we have to create MeshServices backend-v1 and backend-v2 that select backend application instances according to the version.

Kubernetes

Universal

I am using MeshService

apiVersion: kuma.io/v1alpha1
kind: MeshTCPRoute
metadata:
  name: tcp-route-1
  namespace: kuma-demo
  labels:
    kuma.io/mesh: default
spec:
  targetRef:
    kind: MeshSubset
    tags:
      app: frontend
  to:
  - targetRef:
      kind: MeshService
      name: backend_kuma-demo_svc_3001
    rules:
    - default:
        backendRefs:
        - kind: MeshServiceSubset
          name: backend_kuma-demo_svc_3001
          weight: 90
          tags:
            version: v0
        - kind: MeshServiceSubset
          name: backend_kuma-demo_svc_3001
          weight: 10
          tags:
            version: v1

apiVersion: kuma.io/v1alpha1
kind: MeshTCPRoute
metadata:
  name: tcp-route-1
  namespace: kuma-demo
  labels:
    kuma.io/mesh: default
spec:
  targetRef:
    kind: MeshSubset
    tags:
      app: frontend
  to:
  - targetRef:
      kind: MeshService
      name: backend
      namespace: kuma-demo
      sectionName: http
    rules:
    - default:
        backendRefs:
        - kind: MeshService
          name: backend-v0
          namespace: kuma-demo
          port: 3001
          weight: 90
        - kind: MeshService
          name: backend-v1
          namespace: kuma-demo
          port: 3001
          weight: 10

I am using MeshService

type: MeshTCPRoute
name: tcp-route-1
mesh: default
spec:
  targetRef:
    kind: MeshSubset
    tags:
      app: frontend
  to:
  - targetRef:
      kind: MeshService
      name: backend
    rules:
    - default:
        backendRefs:
        - kind: MeshServiceSubset
          name: backend
          weight: 90
          tags:
            version: v0
        - kind: MeshServiceSubset
          name: backend
          weight: 10
          tags:
            version: v1

type: MeshTCPRoute
name: tcp-route-1
mesh: default
spec:
  targetRef:
    kind: MeshSubset
    tags:
      app: frontend
  to:
  - targetRef:
      kind: MeshService
      name: backend
      sectionName: http
    rules:
    - default:
        backendRefs:
        - kind: MeshService
          name: backend-v0
          port: 3001
          weight: 90
        - kind: MeshService
          name: backend-v1
          port: 3001
          weight: 10

Traffic redirection

You can use MeshTCPRoute to redirect outgoing traffic from one service to another.

Here’s an example of a MeshTCPRoute that redirects outgoing traffic originating at frontend_kuma-demo_svc_8080 from backend_kuma-demo_svc_3001 to external-backend:

Kubernetes

Universal

I am using MeshService

apiVersion: kuma.io/v1alpha1
kind: MeshTCPRoute
metadata:
  name: tcp-route-1
  namespace: kuma-demo
  labels:
    kuma.io/mesh: default
spec:
  targetRef:
    kind: MeshSubset
    tags:
      app: frontend
  to:
  - targetRef:
      kind: MeshService
      name: backend_kuma-demo_svc_3001
    rules:
    - default:
        backendRefs:
        - kind: MeshService
          name: external-backend_kuma-demo_svc_8080

apiVersion: kuma.io/v1alpha1
kind: MeshTCPRoute
metadata:
  name: tcp-route-1
  namespace: kuma-demo
  labels:
    kuma.io/mesh: default
spec:
  targetRef:
    kind: MeshSubset
    tags:
      app: frontend
  to:
  - targetRef:
      kind: MeshService
      name: backend
      namespace: kuma-demo
      sectionName: http
    rules:
    - default:
        backendRefs:
        - kind: MeshService
          name: external-backend
          namespace: kuma-demo
          port: 8080

I am using MeshService

type: MeshTCPRoute
name: tcp-route-1
mesh: default
spec:
  targetRef:
    kind: MeshSubset
    tags:
      app: frontend
  to:
  - targetRef:
      kind: MeshService
      name: backend
    rules:
    - default:
        backendRefs:
        - kind: MeshService
          name: external-backend

type: MeshTCPRoute
name: tcp-route-1
mesh: default
spec:
  targetRef:
    kind: MeshSubset
    tags:
      app: frontend
  to:
  - targetRef:
      kind: MeshService
      name: backend
      sectionName: http
    rules:
    - default:
        backendRefs:
        - kind: MeshService
          name: external-backend
          port: 8080

Route policies with different types targeting the same destination

If multiple route policies with different types (MeshTCPRoute and MeshHTTPRoute for example) target the same destination, only a single route type with the highest specificity will be applied.

In this example, both MeshTCPRoute and MeshHTTPRoute target the same destination:

Kubernetes

Universal

I am using MeshService

apiVersion: kuma.io/v1alpha1
kind: MeshHTTPRoute
metadata:
  name: simple-http
  namespace: kuma-demo
  labels:
    kuma.io/mesh: default
spec:
  targetRef:
    kind: MeshSubset
    tags:
      app: frontend
  to:
  - targetRef:
      kind: MeshService
      name: backend_kuma-demo_svc_3001
    rules:
    - default:
        backendRefs:
        - kind: MeshService
          name: other-tcp-backend_kuma-demo_svc_8080

apiVersion: kuma.io/v1alpha1
kind: MeshHTTPRoute
metadata:
  name: simple-http
  namespace: kuma-demo
  labels:
    kuma.io/mesh: default
spec:
  targetRef:
    kind: MeshSubset
    tags:
      app: frontend
  to:
  - targetRef:
      kind: MeshService
      name: backend
      namespace: kuma-demo
      sectionName: http
    rules:
    - default:
        backendRefs:
        - kind: MeshService
          name: other-tcp-backend
          namespace: kuma-demo
          port: 8080

I am using MeshService

type: MeshHTTPRoute
name: simple-http
mesh: default
spec:
  targetRef:
    kind: MeshSubset
    tags:
      app: frontend
  to:
  - targetRef:
      kind: MeshService
      name: backend
    rules:
    - default:
        backendRefs:
        - kind: MeshService
          name: other-tcp-backend

type: MeshHTTPRoute
name: simple-http
mesh: default
spec:
  targetRef:
    kind: MeshSubset
    tags:
      app: frontend
  to:
  - targetRef:
      kind: MeshService
      name: backend
      sectionName: http
    rules:
    - default:
        backendRefs:
        - kind: MeshService
          name: other-tcp-backend
          port: 8080

Kubernetes

Universal

I am using MeshService

apiVersion: kuma.io/v1alpha1
kind: MeshHTTPRoute
metadata:
  name: simple-http
  namespace: kuma-demo
  labels:
    kuma.io/mesh: default
spec:
  targetRef:
    kind: MeshSubset
    tags:
      app: frontend
  to:
  - targetRef:
      kind: MeshService
      name: backend_kuma-demo_svc_3001
    rules:
    - matches: 
      path:
        type: PathPrefix
        value: "/"
      default:
        backendRefs:
        - kind: MeshService
          name: other-http-backend_kuma-demo_svc_8080

apiVersion: kuma.io/v1alpha1
kind: MeshHTTPRoute
metadata:
  name: simple-http
  namespace: kuma-demo
  labels:
    kuma.io/mesh: default
spec:
  targetRef:
    kind: MeshSubset
    tags:
      app: frontend
  to:
  - targetRef:
      kind: MeshService
      name: backend
      namespace: kuma-demo
      sectionName: http
    rules:
    - matches: 
      path:
        type: PathPrefix
        value: "/"
      default:
        backendRefs:
        - kind: MeshService
          name: other-http-backend
          namespace: kuma-demo
          port: 8080

I am using MeshService

type: MeshHTTPRoute
name: simple-http
mesh: default
spec:
  targetRef:
    kind: MeshSubset
    tags:
      app: frontend
  to:
  - targetRef:
      kind: MeshService
      name: backend
    rules:
    - matches: 
      path:
        type: PathPrefix
        value: "/"
      default:
        backendRefs:
        - kind: MeshService
          name: other-http-backend

type: MeshHTTPRoute
name: simple-http
mesh: default
spec:
  targetRef:
    kind: MeshSubset
    tags:
      app: frontend
  to:
  - targetRef:
      kind: MeshService
      name: backend
      sectionName: http
    rules:
    - matches: 
      path:
        type: PathPrefix
        value: "/"
      default:
        backendRefs:
        - kind: MeshService
          name: other-http-backend
          port: 8080

Depending on the backend’s protocol:

MeshHTTPRoute will be applied if http, http2, or grpc are specified
MeshTCPRoute will be applied if tcp or kafka is specified, or when nothing is specified

All policy configuration settings

Spec is the specification of the Kuma MeshTCPRoute resource.

Type: object

Properties

targetRef
- TargetRef is a reference to the resource the policy takes an effect on.The resource could be either a real store object or virtual resourcedefined in-place.
- Type: object
- Properties
  - kind
    - Kind of the referenced resource
    - Type: string
    - The value is restricted to the following:
      1. "Mesh"
      2. "MeshSubset"
      3. "MeshGateway"
      4. "MeshService"
      5. "MeshExternalService"
      6. "MeshMultiZoneService"
      7. "MeshServiceSubset"
      8. "MeshHTTPRoute"
  - labels
    - Labels are used to select group of MeshServices that match labels. Either Labels orName and Namespace can be used.
    - Type: object
    - This schema accepts additional properties.
    - Properties
  - mesh
    - Mesh is reserved for future use to identify cross mesh resources.
    - Type: string
  - name
    - Name of the referenced resource. Can only be used with kinds: MeshService,MeshServiceSubset and MeshGatewayRoute
    - Type: string
  - namespace
    - Namespace specifies the namespace of target resource. If empty only resources in policy namespacewill be targeted.
    - Type: string
  - proxyTypes
    - ProxyTypes specifies the data plane types that are subject to the policy. When not specified,all data plane types are targeted by the policy.
    - Type: array
    - Item Count: ≥ 1
      - Items
      - Type: string
      - The value is restricted to the following:
        
        "Sidecar"
        
        "Gateway"
  - sectionName
    - SectionName is used to target specific section of resource.For example, you can target port from MeshService.ports[] by its name. Only traffic to this port will be affected.
    - Type: string
  - tags
    - Tags used to select a subset of proxies by tags. Can only be used with kindsMeshSubset and MeshServiceSubset
    - Type: object
    - This schema accepts additional properties.
    - Properties
to
- To list makes a match between the consumed services and correspondingconfigurations
- Type: array
- Item Count: ≥ 1
  - Items
  - Type: object
  - Properties
    - rules
      - Rules contains the routing rules applies to a combination of top-leveltargetRef and the targetRef in this entry.
      - Type: array
      - Item Count: ≤ 1
        
        Items
        
        Type: object
        
        Properties
        
        default required
        
        Default holds routing rules that can be merged with rules from otherpolicies.
        
        Type: object
        
        Properties
        
        backendRefs required
        
        Type: array
        
        Item Count: ≥ 1
        
        Items
        
        BackendRef defines where to forward traffic.
        
        Type: object
        
        Properties
        
        kind
        
        Kind of the referenced resource
        
        Type: string
        
        The value is restricted to the following:
        
        "Mesh"
        
        "MeshSubset"
        
        "MeshGateway"
        
        "MeshService"
        
        "MeshExternalService"
        
        "MeshMultiZoneService"
        
        "MeshServiceSubset"
        
        "MeshHTTPRoute"
        
        labels
        
        Labels are used to select group of MeshServices that match labels. Either Labels orName and Namespace can be used.
        
        Type: object
        
        This schema accepts additional properties.
        
        Properties
        
        mesh
        
        Mesh is reserved for future use to identify cross mesh resources.
        
        Type: string
        
        name
        
        Name of the referenced resource. Can only be used with kinds: MeshService,MeshServiceSubset and MeshGatewayRoute
        
        Type: string
        
        namespace
        
        Namespace specifies the namespace of target resource. If empty only resources in policy namespacewill be targeted.
        
        Type: string
        
        port
        
        Port is only supported when this ref refers to a real MeshService object
        
        Type: integer
        
        proxyTypes
        
        ProxyTypes specifies the data plane types that are subject to the policy. When not specified,all data plane types are targeted by the policy.
        
        Type: array
        
        Item Count: ≥ 1
        
        Items
        
        Type: string
        
        The value is restricted to the following:
        
        "Sidecar"
        
        "Gateway"
        
        sectionName
        
        SectionName is used to target specific section of resource.For example, you can target port from MeshService.ports[] by its name. Only traffic to this port will be affected.
        
        Type: string
        
        tags
        
        Tags used to select a subset of proxies by tags. Can only be used with kindsMeshSubset and MeshServiceSubset
        
        Type: object
        
        This schema accepts additional properties.
        
        Properties
        
        weight
        
        Type: integer
        
        Default: 1
        
        Range: ≥ 0
    - targetRef required
      - TargetRef is a reference to the resource that represents a group ofdestinations.
      - Type: object
      - Properties
        
        kind
        
        Kind of the referenced resource
        
        Type: string
        
        The value is restricted to the following:
        
        "Mesh"
        
        "MeshSubset"
        
        "MeshGateway"
        
        "MeshService"
        
        "MeshExternalService"
        
        "MeshMultiZoneService"
        
        "MeshServiceSubset"
        
        "MeshHTTPRoute"
        
        labels
        
        Labels are used to select group of MeshServices that match labels. Either Labels orName and Namespace can be used.
        
        Type: object
        
        This schema accepts additional properties.
        
        Properties
        
        mesh
        
        Mesh is reserved for future use to identify cross mesh resources.
        
        Type: string
        
        name
        
        Name of the referenced resource. Can only be used with kinds: MeshService,MeshServiceSubset and MeshGatewayRoute
        
        Type: string
        
        namespace
        
        Namespace specifies the namespace of target resource. If empty only resources in policy namespacewill be targeted.
        
        Type: string
        
        proxyTypes
        
        ProxyTypes specifies the data plane types that are subject to the policy. When not specified,all data plane types are targeted by the policy.
        
        Type: array
        
        Item Count: ≥ 1
        
        Items
        
        Type: string
        
        The value is restricted to the following:
        
        "Sidecar"
        
        "Gateway"
        
        sectionName
        
        SectionName is used to target specific section of resource.For example, you can target port from MeshService.ports[] by its name. Only traffic to this port will be affected.
        
        Type: string
        
        tags
        
        Tags used to select a subset of proxies by tags. Can only be used with kindsMeshSubset and MeshServiceSubset
        
        Type: object
        
        This schema accepts additional properties.
        
        Properties

Generated with json-schema-md-doc Wed May 14 2025 13:05:36 GMT+0000 (Coordinated Universal Time)