MeshRateLimit

This policy uses new policy matching algorithm. Do not combine with Rate Limit.

This policy enables per-instance service request limiting. Policy supports rate limiting of HTTP/HTTP2 requests and TCP connections.

The MeshRateLimit policy leverages Envoy’s local rate limiting for HTTP/HTTP2 and local rate limit filter for TCP connections.

You can configure:

how many HTTP requests are allowed in a specified time period
how the HTTP service responds when the limit is reached
how many TCP connections are allowed in a specified time period

The policy is applied per service instance. This means that if a service backend has 3 instances rate limited to 100 requests per second, the overall service rate limit is 300 requests per second.

Rate limiting supports an ExternalService only when ZoneEgress is enabled.

TargetRef support matrix

Sidecar

Builtin Gateway

Delegated Gateway

`targetRef`	Allowed kinds
`targetRef.kind`	`Mesh`, `Dataplane`, `MeshSubset(deprecated)`
`from[].targetRef.kind`	`Mesh`

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

To learn more about the information in this table, see the matching docs.

Configuration

The MeshRateLimit policy supports both L4/TCP and L7/HTTP limiting. Envoy implements Token Bucket algorithm for rate limiting.

HTTP Rate limiting

disabled - (optional) - should rate limiting policy be disabled
requestRate - configuration of the number of requests in the specific time window
- num - the number of requests to limit
- interval - the interval for which requests will be limited
onRateLimit (optional) - actions to take on RateLimit event
- status (optional) - the status code to return, defaults to 429
- headers - (optional) headers which should be added to every rate limited response

Headers

set - (optional) - list of headers to set. Overrides value if the header exists.
- name - header’s name
- value - header’s value
add - (optional) - list of headers to add. Appends value if the header exists.
- name - header’s name
- value - header’s value

TCP Rate limiting

TCP rate limiting allows the configuration of a number of connections in the specific time window

disabled - (optional) - should rate limiting policy be disabled
connectionRate - configuration of the number of connections in the specific time window
- num - the number of requests to limit
- interval - the interval for which connections will be limited

Examples

HTTP Rate limit configured for service `backend` from all services in the Mesh

        
          Kubernetes
        
      

        
          Universal
        
      

        
          Terraform
        
      

    
      apiVersion: kuma.io/v1alpha1
kind: MeshRateLimit
metadata:
  name: backend-rate-limit
  namespace: kuma-demo
  labels:
    kuma.io/mesh: default
spec:
  targetRef:
    kind: Dataplane
    labels:
      app: backend
  rules:
  - default:
      local:
        http:
          requestRate:
            num: 5
            interval: 10s
          onRateLimit:
            status: 423
            headers:
              set:
              - name: x-kuma-rate-limited
                value: 'true'

    
      type: MeshRateLimit
mesh: default
name: backend-rate-limit
spec:
  targetRef:
    kind: Dataplane
    labels:
      app: backend
  rules:
  - default:
      local:
        http:
          requestRate:
            num: 5
            interval: 10s
          onRateLimit:
            status: 423
            headers:
              set:
              - name: x-kuma-rate-limited
                value: 'true'

    
      
Please adjust konnect_mesh_control_plane.my_meshcontrolplane.id and konnect_mesh.my_mesh.name according to your current configuration
resource "konnect_mesh_rate_limit" "backend_rate_limit" {
  provider = konnect-beta
  type = "MeshRateLimit"
  name = "backend-rate-limit"
  spec = {
    target_ref = {
      kind = "Dataplane"
      labels = {
        app = "backend"
      }
    }
    rules = [
      {
        default = {
          local = {
            http = {
              request_rate = {
                num = "5"
                interval = "10s"
              }
              on_rate_limit = {
                status = "423"
                headers = {
                  set = [
                    {
                      name = "x-kuma-rate-limited"
                      value = "true"
                    }
                  ]
                }
              }
            }
          }
        }
      }
    ]
  }
  labels   = {
    "kuma.io/mesh" = konnect_mesh.my_mesh.name
  }
  cp_id    = konnect_mesh_control_plane.my_meshcontrolplane.id
  mesh     = konnect_mesh.my_mesh.name
}


    
  

TCP rate limit for service backend from all services in the Mesh

        
          Kubernetes
        
      

        
          Universal
        
      

        
          Terraform
        
      

    
      apiVersion: kuma.io/v1alpha1
kind: MeshRateLimit
metadata:
  name: backend-rate-limit
  namespace: kuma-demo
  labels:
    kuma.io/mesh: default
spec:
  targetRef:
    kind: Dataplane
    labels:
      app: backend
  rules:
  - default:
      local:
        tcp:
          connectionRate:
            num: 5
            interval: 10s

    
      type: MeshRateLimit
name: backend-rate-limit
mesh: default
spec:
  targetRef:
    kind: Dataplane
    labels:
      app: backend
  rules:
  - default:
      local:
        tcp:
          connectionRate:
            num: 5
            interval: 10s

    
      
Please adjust konnect_mesh_control_plane.my_meshcontrolplane.id and konnect_mesh.my_mesh.name according to your current configuration
resource "konnect_mesh_rate_limit" "backend_rate_limit" {
  provider = konnect-beta
  type = "MeshRateLimit"
  name = "backend-rate-limit"
  spec = {
    target_ref = {
      kind = "Dataplane"
      labels = {
        app = "backend"
      }
    }
    rules = [
      {
        default = {
          local = {
            tcp = {
              connection_rate = {
                num = "5"
                interval = "10s"
              }
            }
          }
        }
      }
    ]
  }
  labels   = {
    "kuma.io/mesh" = konnect_mesh.my_mesh.name
  }
  cp_id    = konnect_mesh_control_plane.my_meshcontrolplane.id
  mesh     = konnect_mesh.my_mesh.name
}


    
  

All policy options

Spec is the specification of the Kuma MeshRateLimit resource.

Type: object

Properties

from
- From list makes a match between clients and corresponding configurations
- Type: array
  - Items
  - Type: object
  - Properties
    - default
      - Default is a configuration specific to the group of clients referenced in'targetRef'
      - Type: object
      - Properties
        
        local
        
        LocalConf defines local http or/and tcp rate limit configuration
        
        Type: object
        
        Properties
        
        http
        
        LocalHTTP defines configuration of local HTTP rate limitinghttps://www.envoyproxy.io/docs/envoy/latest/configuration/http/httpfilters/localratelimitfilter
        
        Type: object
        
        Properties
        
        disabled
        
        Define if rate limiting should be disabled.
        
        Type: boolean
        
        onRateLimit
        
        Describes the actions to take on a rate limit event
        
        Type: object
        
        Properties
        
        headers
        
        The Headers to be added to the HTTP response on a rate limit event
        
        Type: object
        
        Properties
        
        add
        
        Type: array
        
        Item Count: ≤ 16
        
        Items
        
        Type: object
        
        Properties
        
        name required
        
        Type: string
        
        The value must match this pattern: ^[a-z0-9!#$%&'*+\-.^_\x60|~]+$
        
        Length: between 1 and 256
        
        value required
        
        Type: string
        
        set
        
        Type: array
        
        Item Count: ≤ 16
        
        Items
        
        Type: object
        
        Properties
        
        name required
        
        Type: string
        
        The value must match this pattern: ^[a-z0-9!#$%&'*+\-.^_\x60|~]+$
        
        Length: between 1 and 256
        
        value required
        
        Type: string
        
        status
        
        The HTTP status code to be set on a rate limit event
        
        Type: integer
        
        requestRate
        
        Defines how many requests are allowed per interval.
        
        Type: object
        
        Properties
        
        interval required
        
        The interval the number of units is accounted for.
        
        Type: string
        
        num required
        
        Number of units per interval (depending on usage it can be a number of requests,or a number of connections).
        
        Type: integer
        
        tcp
        
        LocalTCP defines confguration of local TCP rate limitinghttps://www.envoyproxy.io/docs/envoy/latest/configuration/listeners/networkfilters/localratelimitfilter
        
        Type: object
        
        Properties
        
        connectionRate
        
        Defines how many connections are allowed per interval.
        
        Type: object
        
        Properties
        
        interval required
        
        The interval the number of units is accounted for.
        
        Type: string
        
        num required
        
        Number of units per interval (depending on usage it can be a number of requests,or a number of connections).
        
        Type: integer
        
        disabled
        
        Define if rate limiting should be disabled.Default: false
        
        Type: boolean
    - targetRef required
      - TargetRef is a reference to the resource that represents a group ofclients.
      - Type: object
      - Properties
        
        kind required
        
        Kind of the referenced resource
        
        Type: string
        
        The value is restricted to the following:
        
        "Mesh"
        
        "MeshSubset"
        
        "MeshGateway"
        
        "MeshService"
        
        "MeshExternalService"
        
        "MeshMultiZoneService"
        
        "MeshServiceSubset"
        
        "MeshHTTPRoute"
        
        "Dataplane"
        
        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
        
        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
rules
- Rules defines inbound rate limiting configurations. Currently limited toselecting all inbound traffic, as L7 matching is not yet implemented.
- Type: array
  - Items
  - Type: object
  - Properties
    - default
      - Default contains configuration of the inbound rate limits
      - Type: object
      - Properties
        
        local
        
        LocalConf defines local http or/and tcp rate limit configuration
        
        Type: object
        
        Properties
        
        http
        
        LocalHTTP defines configuration of local HTTP rate limitinghttps://www.envoyproxy.io/docs/envoy/latest/configuration/http/httpfilters/localratelimitfilter
        
        Type: object
        
        Properties
        
        disabled
        
        Define if rate limiting should be disabled.
        
        Type: boolean
        
        onRateLimit
        
        Describes the actions to take on a rate limit event
        
        Type: object
        
        Properties
        
        headers
        
        The Headers to be added to the HTTP response on a rate limit event
        
        Type: object
        
        Properties
        
        add
        
        Type: array
        
        Item Count: ≤ 16
        
        Items
        
        Type: object
        
        Properties
        
        name required
        
        Type: string
        
        The value must match this pattern: ^[a-z0-9!#$%&'*+\-.^_\x60|~]+$
        
        Length: between 1 and 256
        
        value required
        
        Type: string
        
        set
        
        Type: array
        
        Item Count: ≤ 16
        
        Items
        
        Type: object
        
        Properties
        
        name required
        
        Type: string
        
        The value must match this pattern: ^[a-z0-9!#$%&'*+\-.^_\x60|~]+$
        
        Length: between 1 and 256
        
        value required
        
        Type: string
        
        status
        
        The HTTP status code to be set on a rate limit event
        
        Type: integer
        
        requestRate
        
        Defines how many requests are allowed per interval.
        
        Type: object
        
        Properties
        
        interval required
        
        The interval the number of units is accounted for.
        
        Type: string
        
        num required
        
        Number of units per interval (depending on usage it can be a number of requests,or a number of connections).
        
        Type: integer
        
        tcp
        
        LocalTCP defines confguration of local TCP rate limitinghttps://www.envoyproxy.io/docs/envoy/latest/configuration/listeners/networkfilters/localratelimitfilter
        
        Type: object
        
        Properties
        
        connectionRate
        
        Defines how many connections are allowed per interval.
        
        Type: object
        
        Properties
        
        interval required
        
        The interval the number of units is accounted for.
        
        Type: string
        
        num required
        
        Number of units per interval (depending on usage it can be a number of requests,or a number of connections).
        
        Type: integer
        
        disabled
        
        Define if rate limiting should be disabled.Default: false
        
        Type: boolean
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 inplace.
- Type: object
- Properties
  - kind required
    - 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"
      9. "Dataplane"
  - 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
      - 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 clients and corresponding configurations
- Type: array
  - Items
  - Type: object
  - Properties
    - default
      - Default is a configuration specific to the group of clients referenced in'targetRef'
      - Type: object
      - Properties
        
        local
        
        LocalConf defines local http or/and tcp rate limit configuration
        
        Type: object
        
        Properties
        
        http
        
        LocalHTTP defines configuration of local HTTP rate limitinghttps://www.envoyproxy.io/docs/envoy/latest/configuration/http/httpfilters/localratelimitfilter
        
        Type: object
        
        Properties
        
        disabled
        
        Define if rate limiting should be disabled.
        
        Type: boolean
        
        onRateLimit
        
        Describes the actions to take on a rate limit event
        
        Type: object
        
        Properties
        
        headers
        
        The Headers to be added to the HTTP response on a rate limit event
        
        Type: object
        
        Properties
        
        add
        
        Type: array
        
        Item Count: ≤ 16
        
        Items
        
        Type: object
        
        Properties
        
        name required
        
        Type: string
        
        The value must match this pattern: ^[a-z0-9!#$%&'*+\-.^_\x60|~]+$
        
        Length: between 1 and 256
        
        value required
        
        Type: string
        
        set
        
        Type: array
        
        Item Count: ≤ 16
        
        Items
        
        Type: object
        
        Properties
        
        name required
        
        Type: string
        
        The value must match this pattern: ^[a-z0-9!#$%&'*+\-.^_\x60|~]+$
        
        Length: between 1 and 256
        
        value required
        
        Type: string
        
        status
        
        The HTTP status code to be set on a rate limit event
        
        Type: integer
        
        requestRate
        
        Defines how many requests are allowed per interval.
        
        Type: object
        
        Properties
        
        interval required
        
        The interval the number of units is accounted for.
        
        Type: string
        
        num required
        
        Number of units per interval (depending on usage it can be a number of requests,or a number of connections).
        
        Type: integer
        
        tcp
        
        LocalTCP defines confguration of local TCP rate limitinghttps://www.envoyproxy.io/docs/envoy/latest/configuration/listeners/networkfilters/localratelimitfilter
        
        Type: object
        
        Properties
        
        connectionRate
        
        Defines how many connections are allowed per interval.
        
        Type: object
        
        Properties
        
        interval required
        
        The interval the number of units is accounted for.
        
        Type: string
        
        num required
        
        Number of units per interval (depending on usage it can be a number of requests,or a number of connections).
        
        Type: integer
        
        disabled
        
        Define if rate limiting should be disabled.Default: false
        
        Type: boolean
    - targetRef required
      - TargetRef is a reference to the resource that represents a group ofclients.
      - Type: object
      - Properties
        
        kind required
        
        Kind of the referenced resource
        
        Type: string
        
        The value is restricted to the following:
        
        "Mesh"
        
        "MeshSubset"
        
        "MeshGateway"
        
        "MeshService"
        
        "MeshExternalService"
        
        "MeshMultiZoneService"
        
        "MeshServiceSubset"
        
        "MeshHTTPRoute"
        
        "Dataplane"
        
        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
        
        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 Sat May 24 2025 21:42:07 GMT+0000 (Coordinated Universal Time)