Description of ASMLocalRateLimiter fields - Alibaba Cloud Service Mesh

Service Mesh (ASM) allows you to declaratively define the configurations of ASMLocalRateLimiter by using a CustomResourceDefinition (CRD) to achieve local rate limiting. This topic describes the fields of ASMLocalRateLimiter and provides a configuration example.

Configuration example

The following configuration enforces rate limiting on the gateway to prevent downstream services from being overwhelmed by incoming traffic. Setting seconds to 1 and quota to 100 allows 100 tokens per second, meaning the gateway processes up to 100 requests per second.

Note

The limit.quota in the configuration applies only to a single gateway instance. If there are n gateway instances, the backend service rate-limiting threshold for the route becomes n*quota. Adjust the threshold accordingly if the number of gateway instances changes.

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" # If multiple vhosts are configured on the gateway, enter the name of the last vhost. 
          port: 80
          route:
            name_match: "test1" # The name of the route that is configured for the virtual service. If the virtual service does not have the specified route, the rate limiting does not take 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

Field description

apiVersion

ASM 1.15.3.105 or later supports using istio.alibabacloud.com/v1. If you have set the apiVersion field to istio.alibabacloud.com/v1beta1 when you configured ASMCircuitBreaker in the Container Service for Kubernetes (ACK) cluster, change the value to istio.alibabacloud.com/v1, and deploy the cluster again.
For ASM prior to 1.15.3.105, set the apiVersion field to istio.alibabacloud.com/v1beta1.

spec

The following table describes the fields in the spec section. For more information, see Configure local rate limiting on an ingress gateway.

Field	Type	Required	Description
workloadSelector	map<string, string>	Yes	Through labels to specify a set of pods on which the rate limiting rule takes effect. The scope of label-based search is restricted to the namespace in which the resources reside. For more information, see Workload Selector.
isGateway	bool	No	Specifies whether the rate limiting rule takes effect on a gateway. Default value: `false`.
configs	LocalRateLimiterConfig[]	Yes	The local rate limiting rules.

LocalRateLimiterConfig

Field	Type	Required	Description
name	string	Yes	The name of the rate limiting rule.
match	RatelimitMatch	Yes	The matched criteria.
limit	LimitConfig	Yes	The rate limiting threshold configurations.
limit_overrides	RateLimitOverrideConfig[]	No	Specifies whether to override the configured rate limiting threshold. You can use this field to specify a rate limiting threshold for certain requests. ASM prior to V1.19.0 does not support this field.

RatelimitMatch

Field	Type	Required	Description
vhost	VirtualHostMatch	No	The matched criteria for the virtual host.

LimitConfig

Field	Type	Required	Description
status	int	No	The status code returned when the traffic exceeds the rate limit. Default to 429. Must be greater than or equal to 400. ASM prior to V1.24.6.64 does not support this field.
fill_interval	Duration	No	The interval at which tokens are issued. Examples: `seconds: 1` and `nanos: 1000`. nanos indicates nano seconds.
quota	int	No	The number of tokens. The value must be an integer. Example: 1000.
per_downstream_connection	bool	No	Specifies the scope in which you can share the token bucket. Default value: `false`. Valid values: `false`: A token bucket is shared by all worker threads, and rate limiting is applied to each Envoy process. `true`: A token bucket is assigned to each connection. Rate limiting applies to every connection. ASM prior to V1.13.4 does not support this field.
custom_response_body	string	No	The body content that is returned when a request is denied due to rate limiting. ASM prior to V1.13.4 does not support this field.
response_header_to_add	map[string]string	No	The custom headers that are added to the response when a request is denied due to rate limiting. ASM prior to V1.13.4 does not support this field.

RateLimitOverrideConfig

Field

Type

Required

Description

request_match

RequestMatcher

Yes

The match rule.

limit

LimitConfig

Yes

The rate limit which matched requests will be restricted to.

If it is declared in RateLimitOverrideConfig, only fill_interval and quota take effect. Other fields including per_downstream_connection, custom_response_body, response_header_to_add remain the same as that in LocalRateLimiterConfig.limit.

VirtualHostMatch

Field	Type	Required	Description
name	string	Yes	The name of the matched virtual host.
port	int	No	The matched request port.
route	RouteMatch	No	The name of the route corresponding to the matched request port.

RouteMatch

Field	Type	Required	Description
name_match	string	No	The name of the matched route. It specifies a single route in a virtual service.
header_match	HeaderMatcher[]	No	The matched header. In ASM V1.19.0 and later, this field is deprecated. Use RateLimitOverrideConfig instead.

RequestMatcher

Note

When fields below are declared at the same time, only requests that meet the rules specified in both fields can be matched.

Field	Type	Required	Description
header_match	HeaderMatcher[]	No	The matched header.
query_match	QueryParameterMatcher[]	No	The matched query.

HeaderMatcher

Field		Type	Required	Description
name		string	No	The name of the header.
Specify one of the fields based on the match mode	regex_match	string	No	The regular expression.
	exact_match	string	No	The exact match expression.
	prefix_match	string	No	The prefix match expression.
	suffix_match	string	No	The suffix match expression.
	present_match	bool	No	true means as long as the header exists no matter of its value. false means the header does not exist.
invert_match		bool	No	Default value: false. false means a request that meets the specified match criteria is considered a matched request. true means the match result will be the opposite.

QueryParameterMatcher

Field		Type	Required	Description
name		string	Yes	The name of the query parameter.
Specify one of the fields based on the match mode	exact_match	string	No	The exact expression.
	prefix_match	string	No	The prefix match expression.
	suffix_match	string	No	The suffix match expression.
	regex_match	string	No	The regular match expression.
	contains_match	string	No	The query parameter value must contain the specified content.
	present_match	bool	No	`true` enables existence matching, which checks for the presence of a specified query parameter without considering its value. `false` is not allowed; it is equivalent to not configuring it, and other matching conditions must be specified..
ignore_case		bool	No	Specifies whether to ignore case sensitivity.