ASMLocalRateLimiter CRD fields - Alibaba Cloud Service Mesh

Service Mesh (ASM) lets you declaratively configure local rate limiting using the ASMLocalRateLimiter CustomResourceDefinition (CRD). This topic provides configuration examples and describes the fields for ASMLocalRateLimiter.

Configuration examples

Example 1: Gateway rate limiting

The following configuration enforces rate limiting on the gateway to prevent downstream services from being overwhelmed by incoming traffic. By setting seconds to 1 and quota to 100, 100 tokens are issued per second, which means the gateway can process a maximum of 100 requests per second.

Note

The limit.quota in the configuration applies to a single gateway instance. If the gateway has n instances, the rate limiting threshold for the backend service of the test1 route is n × quota. If you adjust the number of gateway instances, you must also adjust the rate limiting threshold.

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"   # If multiple host domain names are configured in the gateway, you only need to enter the last one.
          port: 80
          route:
            name_match: "test1"   # The name of the route in the VirtualService routing configuration. If no route with the corresponding name exists in the VirtualService routing configuration, this configuration 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

Example 2: Client-side rate limiting

Note

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

The following example limits the sleep application to one request to the httpbin service every 10 seconds.

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

Example 3: Server-side rate limiting

Note

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

The following example limits access to the httpbin application to once every 10 seconds.

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

Example 4: Waypoint rate limiting

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

This example applies only to the Ambient mode and requires an ASM instance of version 1.25.6.74 or later.

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

apiVersion

If your ASM instance is version 1.15.3.105 or later, you can use apiVersion: istio.alibabacloud.com/v1. If you have existing configurations in an ACK cluster, change apiVersion: istio.alibabacloud.com/v1beta1 in the corresponding ASMLocalRateLimiter CRD to apiVersion: istio.alibabacloud.com/v1 and then redeploy.
If your ASM instance version is earlier than 1.15.3.105, you can use apiVersion: istio.alibabacloud.com/v1beta1.

spec

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

Field	Type	Required	Description
workloadSelector	map<string, string>	Yes	One or more labels that are used to specify a specific set of pods on which the rate limiting configuration takes effect. The scope of label search is limited to the configuration namespace where the resource resides. For more information, see Workload Selector.
isGateway	bool	No	Specifies whether the configuration applies to a gateway. The default value is `false`.
configs	LocalRateLimiterConfig[]	Yes	The local rate limiting configurations. You can configure multiple configurations.
applyToTraffic	string	No	The traffic type to which the rate limiting policy is applied. Optional parameters: `sidecar_inbound`: Inbound traffic of the sidecar, which is the traffic received by the application with a sidecar attached acting as a server. `sidecar_outbound`: Outbound traffic of the sidecar, which is the traffic sent by the application with a sidecar attached acting as a client. `waypoint`: Traffic processed by a Waypoint in Ambient mode. `gateway`: Gateway traffic. The default value is `sidecar_inbound`. Note This field is supported only in ASM 1.25 and later versions.

LocalRateLimiterConfig

Field	Type	Required	Description
name	string	Yes	The name of a single rate limiting configuration.
match	RatelimitMatch	Yes	The matching conditions.
limit	LimitConfig	Yes	The rate limiting threshold configuration.
limit_overrides	RateLimitOverrideConfig[]	No	The rate limiting threshold override configuration. You can use this field to specify a separate rate limiting threshold for specific requests. You can configure multiple override configurations. Note Supported only in ASM 1.19.0 and later versions.
target_services	TargetServiceRef[]	No	The services to which the rate limiting policy applies. Note This field is supported only in ASM 1.25 and later versions.

TargetServiceRef

Note

This field is supported only in ASM 1.25 and later versions.

Field	Type	Required	Description
kind	string	No	The kind of the service to which the rate limiting policy applies. Valid values: `Service` `ServiceEntry` `VirtualService` The default value is `Service`.
name	string	Yes	The name of the service to which the rate limiting policy applies.
namespace	string	No	The namespace where the service to which the rate limiting policy applies resides. The default value is the namespace where you define the rate limiting policy.
port	int32	No	The port of the service to which the rate limiting policy applies.
section_name	string	No	Additional properties of the service. This field is valid only for `VirtualService`. `VirtualService`: The value is the name of the route defined in the `VirtualService`.

Example 1

The following example applies to port 8000 of the httpbin Service in the default namespace.

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

Example 2

Assume that the following ServiceEntry exists in the current instance.

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

The following policy applies to port 80 of this ServiceEntry.

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

Example 3

Assume that the following VirtualService exists in the current instance.

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

The following policy applies to the routing rule named default in the VirtualService.

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

RemoteAddressMatcher

Field	Type	Required	Description
distinct	bool	No	Specifies whether to apply rate limiting to different source IPs of requests separately. If `distinct` is set to true, you cannot specify address. Note This field is supported only in ASM 1.25 and later versions.

RatelimitMatch

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

LimitConfig

Field	Type	Required	Description
status	int	No	The custom HTTP response code for throttled requests. When a request is throttled, this response code is returned. The default value is 429. The value must be greater than or equal to 400. Note This field is supported in ASM 1.24.6.64 and later versions.
fill_interval	Duration	No	The time unit for token filling, for example, `seconds: 1` or `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	The scope of the rate limiter's token bucket. The default value is `false`. Valid values: `false`: The token bucket is shared among all worker threads, and rate limiting is applied to each Envoy process. `true`: A token bucket is allocated for each connection. Rate limiting is applied to each connection, allowing requests to be rate-limited on a per-connection basis. Note Supported only in ASM 1.13.4 and later versions.
custom_response_body	string	No	The custom response body content to return when a request is throttled. Note Supported only in ASM 1.13.4 and later versions.
response_header_to_add	map[string]string	No	The custom header content to add when a request is throttled. Note Supported only in ASM 1.13.4 and later versions.

RateLimitOverrideConfig

Field	Type	Required	Description
request_match	RequestMatcher	Yes	The request matching conditions specified by the rate limiting threshold override configuration. Only requests that meet the matching conditions will have the rate limiting threshold in the override configuration applied.
limit	LimitConfig	Yes	The request rate limiting threshold specified by the rate limiting threshold override configuration. Note When the limit field is declared in the rate limiting threshold override configuration (RateLimitOverrideConfig), only the fill_interval and quota fields take effect. Other fields (per_downstream_connection, custom_response_body, and response_header_to_add) remain consistent with the declarations in the LocalRateLimiterConfig.limit field.

VirtualHostMatch

Field	Type	Required	Description
name	string	Yes	The name of the `VirtualHost` to match.
port	int	No	The request port to match.
route	RouteMatch	No	The name of the route corresponding to the request interface to match.

RouteMatch

Field	Type	Required	Description
name_match	string	No	The name of the route to match, which corresponds to a single route name under `VirtualService`.
header_match	HeaderMatcher[]	No	The headers of the service request to match. You can configure multiple headers. Important In ASM 1.19.0 and later versions, this field is deprecated. Use RateLimitOverrideConfig to match requests.

RequestMatcher

Note

You can use multiple fields in RequestMatcher at the same time. When multiple fields are used, a request must meet all the matching conditions to be considered a match.

Field	Type	Required	Description
header_match	HeaderMatcher[]	No	The request headers to match. You can configure multiple headers.
query_match	QueryParameterMatcher[]	No	The query parameters of the request to match. You can configure multiple query parameters.

HeaderMatcher

Field		Type	Required	Description
name		string	No	The header name.
Select one of the following	regex_match	string	No	Regular expression match.
	exact_match	string	No	Exact match.
	prefix_match	string	No	Prefix match. Matches based on what the string starts with.
	suffix_match	string	No	Suffix match. Matches based on what the string ends with.
	present_match	bool	No	If this parameter is set to true, the request header must be present, regardless of its value. If this parameter is set to false, the request header must not be present.
invert_match		bool	No	The default value is false. If this parameter is set to true, the matching result is inverted. If this parameter is set to false, the original matching result is used.
distinct		bool	No	Specifies whether to assign separate rate limiting buckets for different values of the same request header. If distinct is set to true, you cannot use other match types. Note This field is supported only in ASM 1.25 and later versions.

QueryParameterMatcher

Field		Type	Required	Description
name		string	Yes	The name of the query parameter.
Select one of the following	exact_match	string	No	Exactly matches the content of the query parameter.
	prefix_match	string	No	Prefix matches the content of the query parameter.
	suffix_match	string	No	Suffix matches the content of the query parameter.
	regex_match	string	No	Regular expression matches the content of the query parameter.
	contains_match	string	No	Contains match for the content of the query parameter. This requires that the content of the query parameter must contain a certain substring.
	present_match	bool	No	If this parameter is set to true, existence matching is performed. The specified query parameter must be present, regardless of its value. You cannot set this parameter to false. Setting it to false is equivalent to not configuring it, and you must specify other matching conditions.
ignore_case		bool	No	Specifies whether to ignore case sensitivity when matching query parameters.