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 throttling. This topic describes the fields of ASMLocalRateLimiter and provides a configuration example.

Configuration example

The following YAML code shows the configurations used to throttle traffic by using a gateway to prevent downstream services from being overloaded. The gateway acts as a traffic ingress. In the YAML code, the seconds parameter is set to 1 and the quota parameter is set to 100. This indicates that 100 tokens are issued within 1 second, that is, the gateway can process up to 100 requests within 1 second.

Note

In the configurations, the setting of the limit.quota field applies only to a single gateway pod. If the gateway runs in n pods, the throttling threshold for the backend service corresponding to the test1 route is n multiplied by the value of the quota field. If the number of gateway pods is changed, you must change the throttling threshold accordingly.

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 throttling 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

If the version of your ASM instance is 1.15.3.105 or later, you can set the apiVersion field to 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 in the ASMCircuitBreaker CRD, and deploy the cluster again.
If the version of your ASM instance is earlier than 1.15.3.105, you can set the apiVersion field to istio.alibabacloud.com/v1beta1.

spec

The following table describes the fields in the spec section. For more information about the features and examples of ASMLocalRateLimiter, see Configure local throttling on an ingress gateway.

Field	Type	Required	Description
workloadSelector	map<string, string>	Yes	One or more labels that specify a set of pods on which the throttling 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 throttling rule takes effect on a gateway. Default value: `false`.
configs	LocalRateLimiterConfig[]	Yes	The local throttling rules.

LocalRateLimiterConfig

Field	Type	Required	Description
name	string	Yes	The name of the throttling rule.
match	RatelimitMatch	Yes	The match criteria.
limit	LimitConfig	Yes	The throttling threshold configurations.
limit_overrides	RateLimitOverrideConfig[]	No	Specifies whether to override the configured throttling threshold. You can use this field to specify a throttling threshold individually for specific requests. You can configure multiple throttling threshold overrides. Note This field is supported only by ASM instances of V1.19.0 or later.

RatelimitMatch

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

LimitConfig

Field	Type	Required	Description
fill_interval	Duration	No	The interval at which tokens are issued. Examples: `seconds: 1` and `nanos: 1000`. nanos indicates nanoseconds.
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 to which rate limiting is applied. Rate limiting can be implemented on requests over each connection. Note This field is supported only by ASM instances of V1.13.4 or later.
custom_response_body	string	No	The body content that is returned when a request is denied due to throttling. Note This field is supported only by ASM instances of V1.13.4 or later.
response_header_to_add	map[string]string	No	The custom headers that are added to the response when a request is denied due to throttling. Note This field is supported only by ASM instances of V1.13.4 or later.

RateLimitOverrideConfig

Field	Type	Required	Description
request_match	RequestMatcher	Yes	The criteria that requests must match when a throttling threshold override configuration is applied. The throttling threshold specified in the override configuration is applied only to the requests that match the criteria.
limit	LimitConfig	Yes	The throttling threshold specified in the throttling threshold override configuration. Note If you declare the limit field in the RateLimitOverrideConfig section, only the fill_interval and quota fields in the LocalRateLimiterConfig.limit sections are overridden. Other fields such as per_downstream_connection, custom_response_body, and response_header_to_add, are the same as those declared in the LocalRateLimiterConfig.limit section.

VirtualHostMatch

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

RouteMatch

Field	Type	Required	Description
name_match	string	No	The name of the route to be matched. This parameter specifies a single route in a virtual service.
header_match	HeaderMatcher[]	No	The header for matching service requests. You can configure multiple headers. Important In ASM instances of V1.19.0 and later, this field is deprecated. We recommend that you use RateLimitOverrideConfig to match requests.

RequestMatcher

Note

Multiple fields in the RequestMatcher section can be used at the same time. If you use multiple fields at the same time, only requests that meet the criteria of each field can be matched.

Field	Type	Required	Description
header_match	HeaderMatcher[]	No	The header for matching requests. You can configure multiple headers.
query_match	QueryParameterMatcher[]	No	The query parameters for matching requests. You can configure multiple query parameters.

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 used to perform a header match. The header value must match the specified regular expression.
	exact_match	string	No	The value used to perform a header match. The header value must exactly match the specified value.
	prefix_match	string	No	The prefix used to perform a header match. The header value must start with the specified characters.
	suffix_match	string	No	The suffix used to perform a header match. The header value must end with the specified characters.
	present_match	bool	No	If you set this parameter to true, the header match is performed based on whether the header is in the request. The header with the specified name must exist in the request. If you set this parameter to false, the header match is performed based on whether the header is absent. The header with the specified name cannot exist in the request.
invert_match		bool	No	Specifies whether to invert the match result. Default value: false. If you set this parameter to true, the match result will be inverted. For example, a request that does not meet the specified match criteria is considered a matched request. If you set this parameter to false, a request that meets the specified match criteria is considered a matched request.

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 value used to perform a query parameter match. The query parameter value must exactly match the specified value.
	prefix_match	string	No	The prefix used to perform a query parameter match. The query parameter value must start with the specified characters.
	suffix_match	string	No	The suffix used to perform a query parameter match. The query parameter value must end with the specified characters.
	regex_match	string	No	The regular expression used to perform a query parameter match. The query parameter value must match the specified regular expression.
	contains_match	string	No	The content used to perform a query parameter match. The query parameter value must contain the specified content.
	present_match	bool	No	If you set this parameter to true, the query parameter match is performed based on whether the query parameter is in the request. The query parameter with the specified name must exist in the request. You cannot set this parameter to false. If you set this parameter to false, no configuration is specified and you must specify other match criteria.
ignore_case		bool	No	Specifies whether to ignore case sensitivity when you perform a query parameter match.