Kuma Star

Careful!

You are browsing documentation for the next version of Kuma. Use this version at your own risk.

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

targetRef Allowed kinds
targetRef.kind Mesh, Dataplane

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

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'

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

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

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:
                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:
                  1. "Sidecar"
                  2. "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:
            1. "Sidecar"
            2. "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:
                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:
                  1. "Sidecar"
                  2. "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 Thu Apr 03 2025 20:28:50 GMT+0000 (Coordinated Universal Time)