Description of ASMGlobalRateLimiter CRD - Alibaba Cloud Service Mesh

Service Mesh (ASM) lets you declaratively define ASMGlobalRateLimiter configurations using a Custom Resource Definition (CRD) to implement global throttling. This topic describes the fields of the ASMGlobalRateLimiter CRD.

Configuration examples

Example 1: Server-side throttling

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 per minute.

Click to view the YAML file

apiVersion: istio.alibabacloud.com/v1
kind: ASMGlobalRateLimiter
metadata:
  name: global-test
spec:
  configs:
  - limit:
      quota: 1
      unit: MINUTE
    target_services:
    - name: httpbin
      port: 8000
    name: default
  applyToTraffic: sidecar_inbound
  rateLimitService:
    host: ratelimit.default.svc.cluster.local # Queries this service to determine whether the current request needs to be throttled.
    port: 8081
    timeout:
      seconds: 5
  workloadSelector:
    labels:
      app: httpbin

Example 2: Client-side throttling

Note

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

The following example limits the sleep application to accessing the httpbin service only once per minute.

Click to view the YAML file

apiVersion: istio.alibabacloud.com/v1
kind: ASMGlobalRateLimiter
metadata:
  name: global-test
spec:
  configs:
  - limit:
      quota: 1
      unit: MINUTE
    target_services:
    - name: httpbin
      port: 8000
    name: default
  applyToTraffic: sidecar_outbound
  rateLimitService:
    host: ratelimit.default.svc.cluster.local # Queries this service to determine whether the current request needs to be throttled.
    port: 8081
    timeout:
      seconds: 5
  workloadSelector:
    labels:
      app: sleep

Example 3: Waypoint throttling

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

This example configures a throttling rule for an application on the default waypoint. If a request contains the x-user request header, a bucket is allocated based on the header value to limit access to once per minute. If the request does not contain the header, access is limited to 20 times per minute.

Click to view the YAML file

apiVersion: istio.alibabacloud.com/v1
kind: ASMGlobalRateLimiter
metadata:
  name: global-test
spec:
  configs:
  - limit_overrides:
    - limit:
        quota: 1
        unit: MINUTE
      request_match:
        header_match:
        - distinct: true
          name: x-user
    limit:
      quota: 20
      unit: MINUTE
    target_services:
    - name: httpbin
      port: 8000
    name: default
  applyToTraffic: waypoint
  rateLimitService:
    host: ratelimit.default.svc.cluster.local # Queries this service to determine whether the current request needs to be throttled.
    port: 8081
    timeout:
      seconds: 5
  workloadSelector:
    labels:
      gateway.networking.k8s.io/gateway-name: default

spec

Field	Type	Required	Description
workloadSelector	map<string, string>	Yes	One or more labels that specify a set of workloads 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.
rateLimitService	RateLimitServiceConfig	Yes	The configurations of the global throttling service.
configs	GlobalRateLimiterConfig[]	Yes	The global throttling rules. You can configure multiple rules.
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.

RateLimitServiceConfig

Field	Type	Required	Description
host	string	Yes	The domain name of the cluster in which the global throttling service resides.
port	int	Yes	The gRPC service port of the global throttling service.
timeout	Duration	No	The timeout period for the mesh proxy to connect to the global throttling service. Examples: `seconds: 1` and `nanos: 1000`. nanos indicates nanoseconds.

GlobalRateLimiterConfig

Field	Type	Required	Description
name	string	Yes	The name of the throttling rule.
match	RatelimitMatch	Yes	The match criteria.
limit	GlobalServiceLimitConfig	Yes	The throttling threshold configurations.
limit_overrides	GlobalRateLimitOverrideConfig[]	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.
target_services	TargetServiceRef[]	No	The service to which the throttling policy is applied. 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

RatelimitMatch

Field

Type

Required

Description

vhost

VirtualHostMatch

Yes

The match criteria for the virtual host.

GlobalServiceLimitConfig

Field

Type

Required

Description

unit

string

Yes

The unit of the throttling time. Valid values:

MINUTE: minutes
SECOND: seconds

quota

int

Yes

The total number of requests allowed per unit time.

GlobalRateLimitOverrideConfig

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	GlobalServiceLimitConfig	Yes	The throttling threshold specified in the throttling threshold override configuration.

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

The name of the route to be matched. This field specifies a single route in a virtual service.

header_match

HeaderMatcher[]

The header of the service requests to be matched. You can configure multiple headers.

Note

In ASM instances of V1.19.0 and later, this field is deprecated. We recommend that you use GlobalRateLimitOverrideConfig to match requests.

RequestMatcher

Note

You can use multiple fields in the RequestMatcher section at the same time. If you do, a request is matched only if it meets the criteria of all specified fields.

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

RemoteAddressMatcher

Field	Type	Required	Description
address	string	Yes	The source IP address for matching requests.
v4_prefix_mask_len	uint32	No	If you want to match an IPv4 address range, enter the subnet mask length of the IPv4 address in this field, and enter the IPv4 address in the address field. The address range calculated after the subnet mask is used will be matched.
v6_prefix_mask_len	uint32	No	If you want to match an IPv6 address range, enter the subnet mask length of the IPv6 address in this field, and enter the IPv6 address in the address field. The address range calculated after the subnet mask is used will be matched.

HeaderMatcher

Field		Type	Required	Description
name		string	No	The name of the header.
Select one of the following	regex_match	string	No	The regular expression used to perform a header match.
	exact_match	string	No	The value used to perform an exact match.
	prefix_match	string	No	The prefix used to perform a prefix match.
	suffix_match	string	No	The suffix used to perform a suffix match.
	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 value is ignored. If you set this parameter to false, the header match is performed based on whether the header is absent.
invert_match		bool	No	The default value is false. If you set this parameter to true, the match result is inverted. If you set this parameter to false, the match result is not inverted.

QueryParameterMatcher

Field		Type	Required	Description
name		string	Yes	The name of the query parameter.
Select one of the following	exact_match	string	No	The value used to perform an exact match on the query parameter.
	prefix_match	string	No	The prefix used to perform a prefix match on the query parameter.
	suffix_match	string	No	The suffix used to perform a suffix match on the query parameter.
	regex_match	string	No	The regular expression used to perform a regular expression match on the query parameter.
	contains_match	string	No	The content used to perform a contains match on the query parameter. The value of the query parameter must contain the specified substring.
	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 content is ignored. 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.

References

For more information, see Use ASMGlobalRateLimiter to configure global throttling for ingress gateways and inbound traffic to services.