ASMLocalRateLimiter CRD field reference - Alibaba Cloud Service Mesh

Service Mesh (ASM) provides the ASMLocalRateLimiter CustomResourceDefinition (CRD) for declarative local rate limiting.

ASMLocalRateLimiter uses a token bucket algorithm: tokens are added to a bucket at a fixed interval (fill_interval), each request consumes one token, and requests are throttled when the bucket is empty. This page describes the CRD fields and provides configuration examples.

Important

The limit.quota applies to a single workload instance. For example, if a gateway has _n_ instances, the effective rate limiting threshold is _n_ x quota. Adjust the quota when you scale instances.

Version compatibility

Not all fields are available in every ASM version. The following table lists the minimum version required for each feature.

Feature	Minimum ASM version
`apiVersion: istio.alibabacloud.com/v1`	1.15.3.105
`per_downstream_connection`, `custom_response_body`, `response_header_to_add`	1.13.4
`limit_overrides` (`RateLimitOverrideConfig`)	1.19.0
`header_match` in `RouteMatch` (deprecated)	1.19.0
`status` in `LimitConfig`	1.24.6.64
`applyToTraffic`, `target_services`, `distinct`	1.25
Client-side, server-side, and waypoint rate limiting	1.25.6.74

`apiVersion`

ASM 1.15.3.105 or later: use apiVersion: istio.alibabacloud.com/v1. If existing configurations in a Container Service for Kubernetes (ACK) cluster use v1beta1, change them to v1 and redeploy.
Earlier than ASM 1.15.3.105: use apiVersion: istio.alibabacloud.com/v1beta1.

Configuration examples

Gateway rate limiting

The following configuration enforces rate limiting on the gateway to prevent downstream services from being overwhelmed. In the second config block, seconds: 1 and quota: 100 mean the gateway adds 100 tokens per second, allowing up to 100 requests per second for that route.

Note

The limit.quota applies to a single gateway instance. If the gateway has _n_ instances, the effective threshold is _n_ x quota. Adjust the quota when you scale gateway instances.

Expand to view the YAML content

apiVersion: istio.alibabacloud.com/v1beta1
kind: ASMLocalRateLimiter
metadata:
  name: for-api-test
  namespace: default
spec:
  workloadSelector:
    labels:
      app: istio-ingressgateway
  isGateway: true
  configs:
    - match:
        vhost:
          name: "www.example1.com"   # When multiple hosts are configured, enter the last one.
          port: 80
          route:
            name_match: "test1"   # Must match a route name in the VirtualService. If no match exists, this config has no effect.
      limit:
         fill_interval:
            seconds: 1
         quota: 10
    - match:
        vhost:
          name: "www.example2.com"
          port: 80
          route:
            name_match: "test1"
      limit:
         fill_interval:
            seconds: 1
         quota: 100

Client-side rate limiting

Note

This example requires an ASM instance of version 1.25.6.74 or later.

The following configuration limits the sleep application to one request to the httpbin service every 10 seconds. Because applyToTraffic is set to sidecar_outbound, the rate limit is enforced on the client's outbound sidecar proxy.

Expand to view the YAML content

apiVersion: istio.alibabacloud.com/v1
kind: ASMLocalRateLimiter
metadata:
  name: client-limit
spec:
  configs:
    - limit:
        custom_response_body: '{"ret_code": xxx, "message": "Your request be limited" }'
        fill_interval:
          seconds: 10
        quota: 1
      target_services:
      - name: httpbin
        port: 8000
  applyToTraffic: sidecar_outbound
  workloadSelector:
    labels:
      app: sleep

Server-side rate limiting

Note

This example requires an ASM instance of version 1.25.6.74 or later.

The following configuration limits access to the httpbin application to one request every 10 seconds. Because applyToTraffic is set to sidecar_inbound, the rate limit is enforced on the server's inbound sidecar proxy.

Expand to view the YAML content

apiVersion: istio.alibabacloud.com/v1
kind: ASMLocalRateLimiter
metadata:
  name: server-limit
spec:
  configs:
    - limit:
        custom_response_body: '{"ret_code": xxx, "message": "Your request be limited" }'
        fill_interval:
          seconds: 10
        quota: 1
      target_services:
      - name: httpbin
        port: 8000
  applyToTraffic: sidecar_inbound
  workloadSelector:
    labels:
      app: httpbin

Waypoint rate limiting

Applies only to Ambient mode. Requires ASM 1.25.6.74 or later.

The following configuration limits the waypoint named default to forward one request to the httpbin service every 10 seconds.

Expand to view the YAML content

apiVersion: istio.alibabacloud.com/v1
kind: ASMLocalRateLimiter
metadata:
  name: waypoint-limit
spec:
  configs:
    - limit:
        custom_response_body: '{"ret_code": xxx, "message": "Your request be limited" }'
        fill_interval:
          seconds: 10
        quota: 1
      target_services:
      - name: httpbin
        port: 8000
  applyToTraffic: waypoint
  workloadSelector:
    labels:
      gateway.networking.k8s.io/gateway-name: default

Field descriptions

`spec`

For usage examples, see Configure local rate limiting for an ingress gateway.

Field	Type	Required	Description
`workloadSelector`	map<string, string>	Yes	Labels that select the pods where rate limiting takes effect. Scoped to the namespace of this resource. See Workload Selector.
`isGateway`	bool	No	Whether the configuration applies to a gateway. Default: `false`.
`configs`	LocalRateLimiterConfig[]	Yes	One or more rate limiting configurations.
`applyToTraffic`	string	No	Traffic direction for rate limiting. Valid values: `sidecar_inbound` (default) -- inbound traffic to an application with a sidecar proxy. `sidecar_outbound` -- outbound traffic from an application with a sidecar proxy. `waypoint` -- traffic processed by a Waypoint in Ambient mode. `gateway` -- gateway traffic. Note ASM 1.25 or later.

LocalRateLimiterConfig

Field	Type	Required	Description
`name`	string	Yes	Name of this rate limiting configuration.
`match`	RatelimitMatch	Yes	Request matching conditions.
`limit`	LimitConfig	Yes	Rate limiting threshold.
`limit_overrides`	RateLimitOverrideConfig[]	No	Override thresholds for specific requests. Multiple overrides are supported. Note ASM 1.19.0 or later.
`target_services`	TargetServiceRef[]	No	Services to which this rate limiting policy applies. Note ASM 1.25 or later.

TargetServiceRef

Note

ASM 1.25 or later.

Field	Type	Required	Description
`kind`	string	No	The kind of service. Valid values: `Service` (default), `ServiceEntry`, `VirtualService`.
`name`	string	Yes	Service name.
`namespace`	string	No	Namespace of the service. Default: the namespace where the rate limiting policy is defined.
`port`	int32	No	Service port.
`section_name`	string	No	Additional property of the service. Valid only for `VirtualService`, where the value is the route name defined in the VirtualService.

TargetServiceRef examples

Target a Service on a specific port:

target_services:
- kind: Service
  namespace: default
  name: httpbin
  port: 8000

Target a ServiceEntry:

Given the following ServiceEntry:

apiVersion: networking.istio.io/v1
kind: ServiceEntry
metadata:
  name: se-httpbin-external
spec:
  hosts:
  - httpbin.test.com
  location: MESH_EXTERNAL
  ports:
  - name: http
    number: 80
    protocol: HTTP
  - name: https
    number: 443
    protocol: HTTPS
  resolution: DNS

Apply rate limiting to port 80 of this ServiceEntry:

target_services:
- kind: ServiceEntry
  namespace: default
  name: se-httpbin-external
  port: 80

Target a specific route in a VirtualService:

Given the following VirtualService:

apiVersion: networking.istio.io/v1
kind: VirtualService
metadata:
  name: vs-httpbin
spec:
  hosts:
  - httpbin.test.com
  http:
  - name: default
    route:
    - destination:
        host: httpbin
        port:
          number: 8000

Apply rate limiting to the route named default:

target_services:
- kind: VirtualService
  namespace: default
  name: vs-httpbin
  section_name: default

RatelimitMatch

Field	Type	Required	Description
`vhost`	VirtualHostMatch	No	VirtualHost matching conditions.

VirtualHostMatch

Field	Type	Required	Description
`name`	string	Yes	Name of the VirtualHost to match.
`port`	int	No	Request port to match.
`route`	RouteMatch	No	Route matching conditions.

RouteMatch

Field	Type	Required	Description
`name_match`	string	No	Name of the route to match. Corresponds to a route name in a VirtualService.
`header_match`	HeaderMatcher[]	No	Request headers to match. Multiple headers are supported. Important Deprecated in ASM 1.19.0 and later. Use `RateLimitOverrideConfig` instead.

LimitConfig

Field	Type	Required	Description
`status`	int	No	Custom HTTP response status code returned when a request is throttled. Must be >= 400. Default: `429`. Note ASM 1.24.6.64 or later.
`fill_interval`	Duration	No	Time interval for adding tokens. Example: `seconds: 1` or `nanos: 1000` (nanoseconds).
`quota`	int	No	Number of tokens added per interval. Must be an integer. Example: `1000`.
`per_downstream_connection`	bool	No	Token bucket scope. `false` (default): shared among all worker threads in an Envoy process. `true`: one bucket per connection. Note ASM 1.13.4 or later.
`custom_response_body`	string	No	Custom response body returned when a request is throttled. Note ASM 1.13.4 or later.
`response_header_to_add`	map[string]string	No	Custom response headers added when a request is throttled. Note ASM 1.13.4 or later.

RateLimitOverrideConfig

Field	Type	Required	Description
`request_match`	RequestMatcher	Yes	Matching conditions. Only requests that match these conditions use the override threshold.
`limit`	LimitConfig	Yes	Override threshold. Only `fill_interval` and `quota` take effect here. Other fields (`per_downstream_connection`, `custom_response_body`, `response_header_to_add`) inherit from `LocalRateLimiterConfig.limit`.

RequestMatcher

When multiple fields are specified, a request must match all conditions (AND logic).

Field	Type	Required	Description
`header_match`	HeaderMatcher[]	No	Request headers to match. Multiple headers are supported.
`query_match`	QueryParameterMatcher[]	No	Query parameters to match. Multiple parameters are supported.

RemoteAddressMatcher

Field	Type	Required	Description
`distinct`	bool	No	Whether to apply separate rate limiting per source IP. When set to `true`, the `address` field cannot be specified. Note ASM 1.25 or later.

HeaderMatcher

Field	Type	Required	Description
`name`	string	No	Header name.
`regex_match`	string	No	Match by regular expression. Select one match type.
`exact_match`	string	No	Match by exact value. Select one match type.
`prefix_match`	string	No	Match by prefix. Select one match type.
`suffix_match`	string	No	Match by suffix. Select one match type.
`present_match`	bool	No	`true`: the header must be present, regardless of value. `false`: the header must not be present.
`invert_match`	bool	No	Whether to invert the match result. Default: `false`.
`distinct`	bool	No	Whether to allocate separate rate limiting buckets for different values of this header. When set to `true`, other match types cannot be used. Note ASM 1.25 or later.

QueryParameterMatcher

Field	Type	Required	Description
`name`	string	Yes	Query parameter name.
`exact_match`	string	No	Match by exact value. Select one match type.
`prefix_match`	string	No	Match by prefix. Select one match type.
`suffix_match`	string	No	Match by suffix. Select one match type.
`regex_match`	string	No	Match by regular expression. Select one match type.
`contains_match`	string	No	Match by substring. Select one match type.
`present_match`	bool	No	`true`: the query parameter must be present, regardless of value. Cannot be set to `false` (equivalent to not configuring this field).
`ignore_case`	bool	No	Whether to ignore case when matching.