All Products
Search

This Product

    Alibaba Cloud Service Mesh:Configure global rate limiting for an ingress gateway

    Document Center

    Alibaba Cloud Service Mesh:Configure global rate limiting for an ingress gateway

    Last Updated:Sep 11, 2026

    To manage traffic bursts, service overload, resource exhaustion, or malicious attacks, configure global throttling on specific gateway routes. This enables precise traffic control to protect backend services, lower costs, and enhance the user experience.

    Prerequisites

    Before you begin

    Deploy the rate limiting service

    1. Create a file named ratelimit-svc.yaml with the following content.

      Ratelimit-svc.yaml

      apiVersion: v1
kind: ServiceAccount
metadata:
  name: redis
---
apiVersion: v1
kind: Service
metadata:
  name: redis
  labels:
    app: redis
spec:
  ports:
  - name: redis
    port: 6379
  selector:
    app: redis
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: redis
spec:
  replicas: 1
  selector:
    matchLabels:
      app: redis
  template:
   metadata:
      labels:
        app: redis
        sidecar.istio.io/inject: "false"
   spec:
      containers:
      - image: registry-cn-hangzhou.ack.aliyuncs.com/dev/redis:alpine
        imagePullPolicy: Always
        name: redis
        ports:
        - name: redis
          containerPort: 6379
      restartPolicy: Always
      serviceAccountName: redis
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: ratelimit-config
data:
  config.yaml: |
    {}
---
apiVersion: v1
kind: Service
metadata:
  name: ratelimit
  labels:
    app: ratelimit
spec:
  ports:
  - name: http-port
    port: 8080
    targetPort: 8080
    protocol: TCP
  - name: grpc-port
    port: 8081
    targetPort: 8081
    protocol: TCP
  - name: http-debug
    port: 6070
    targetPort: 6070
    protocol: TCP
  selector:
    app: ratelimit
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: ratelimit
spec:
  replicas: 1
  selector:
    matchLabels:
      app: ratelimit
  strategy:
    type: Recreate
  template:
    metadata:
      labels:
        app: ratelimit
        sidecar.istio.io/inject: "false"
    spec:
      containers:
        # Latest image from https://hub.docker.com/r/envoyproxy/ratelimit/tags
      - image: registry-cn-hangzhou.ack.aliyuncs.com/dev/envoyproxy/ratelimit:e059638d
        imagePullPolicy: Always
        name: ratelimit
        command: ["/bin/ratelimit"]
        env:
        - name: LOG_LEVEL
          value: debug
        - name: REDIS_SOCKET_TYPE
          value: tcp
        - name: REDIS_URL
          value: redis.default.svc.cluster.local:6379
        - name: USE_STATSD
          value: "false"
        - name: RUNTIME_ROOT
          value: /data
        - name: RUNTIME_SUBDIRECTORY
          value: ratelimit
        - name: RUNTIME_WATCH_ROOT
          value: "false"
        - name: RUNTIME_IGNOREDOTFILES
          value: "true"
        ports:
        - containerPort: 8080
        - containerPort: 8081
        - containerPort: 6070
        volumeMounts:
        - name: config-volume
          # $RUNTIME_ROOT/$RUNTIME_SUBDIRECTORY/$RUNTIME_APPDIRECTORY/config.yaml
          mountPath: /data/ratelimit/config
      volumes:
      - name: config-volume
        configMap:
          name: ratelimit-config

    2. In your ACK cluster's kubeconfig environment, run the following command to create the rate limiting service and its required Redis service.

      To learn how to connect to a cluster by using kubectl, see Obtain the kubeconfig of a cluster and use kubectl to connect to the cluster.

      kubectl apply -f ratelimit-svc.yaml

    Deploy the Bookinfo sample application

    1. Download the YAML manifest for the Bookinfo application (bookinfo.yaml) from the Istio project repository on GitHub.

    2. In your ACK cluster's kubeconfig environment, run the following command to deploy the Bookinfo application to the cluster associated with the ASM instance.

      kubectl apply -f bookinfo.yaml

    3. Create bookinfo-gateway.yaml with the following content.

      Bookinfo-gateway.yaml

      apiVersion: networking.istio.io/v1beta1
kind: Gateway
metadata:
  name: bookinfo-gateway
  namespace: default
spec:
  selector:
    istio: ingressgateway
  servers:
    - hosts:
        - bf2.example.com
      port:
        name: http
        number: 80
        protocol: http
---
apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
  name: bookinfo
  namespace: default
spec:
  gateways:
    - bookinfo-gateway
  hosts:
    - bf2.example.com
  http:
    - match:
        - uri:
            exact: /productpage
        - uri:
            prefix: /static
        - uri:
            exact: /login
        - uri:
            exact: /logout
        - uri:
            prefix: /api/v1/products
      name: productpage-route-name1
      route:
        - destination:
            host: productpage
            port:
              number: 9080

    4. In your ASM instance's kubeconfig environment, run the following command to create a route rule for the Bookinfo application on the ingress gateway.

      The route rule is named productpage-route-name1 and matches requests for the bf2.example.com domain. To learn how to connect to an ASM instance by using kubectl, see Access Istio resources by using control plane kubectl.

      kubectl apply -f bookinfo-gateway.yaml

    Scenario 1: Configure a global rate limit on a gateway route

    This scenario shows how to configure a rate limit rule for the productpage-route-name1 route, which applies to the domain name and port combination bf2.example.com:80. productpage-route-name1 is a route entry in the bookinfo VirtualService that you created in Before you begin. This route matches requests for paths like /productpage, /static, /login, and /logout, and forwards them to the productpage service. After you configure the rule, the specified rate limit applies to all requests for these paths.

    1. Create a file named global-ratelimit-gw.yaml with the following content.

      global-ratelimit-gw.yaml

      apiVersion: istio.alibabacloud.com/v1beta1
kind: ASMGlobalRateLimiter
metadata:
  name: global-test
  namespace: istio-system
spec:
  workloadSelector:
    labels:
      istio: ingressgateway
  rateLimitService: # Configuration for the rate limit service deployed in the prerequisites.
    host: ratelimit.default.svc.cluster.local
    port: 8081
    timeout:
      seconds: 5
  isGateway: true
  configs:
  - name: productpage
    limit:
      unit: MINUTE
      quota: 1
    match:
      vhost:
        name: bf2.example.com # This name must match the domain name in the VirtualService.
        port: 80 # This port must match the ASM gateway port.
        route:
          name_match: productpage-route-name1  # This name must match the name of the route in the VirtualService.

      This table describes the key fields. For details, see ASMGlobalRateLimiter CRD reference.

      Parameter

      Description

      workloadSelector

      Selects the workload for the rate limit. In this example, the global rate limit applies to the ingress gateway workload, selected by the label istio: ingressgateway.

      isGateway

      Specifies whether the rule applies to a gateway. Set to true for this example.

      rateLimitService

      Specifies the domain name, port, and connection timeout for the rate limit service. Based on the service deployed in Before you begin, the configuration is as follows:

         host: ratelimit.default.svc.cluster.local
    port: 8081
    timeout:
      seconds: 5

      limit

      The rate limit parameters. The unit specifies the time interval, and quota specifies the number of requests allowed per interval.

      In this example, unit is set to MINUTE and quota is set to 1. This allows only one request per minute for the matched route. The system rejects subsequent requests.

      vhost

      The matching conditions for the domain name and route. The name must match the domain name in the VirtualService, and the port must match the ingress gateway port. The route name specified in route.name_match must match the name of the route entry in the VirtualService.

    2. In the kubeconfig environment for your ASM instance, run the following command to create the global rate limit rule for the productpage-route-name1 route on the gateway.

      kubectl apply -f global-ratelimit-gw.yaml

    3. Run the following command to get the configuration of the reconciled global rate limit rule.

      kubectl get asmglobalratelimiter global-test -n istio-system -o yaml

      Expected output

      apiVersion: istio.alibabacloud.com/v1beta1
kind: ASMGlobalRateLimiter
metadata:
  name: global-test
  namespace: istio-system
spec:
  configs:
  - limit:
      quota: 1
      unit: MINUTE
    match:
      vhost:
        name: bf2.example.com
        port: 80
        route:
          name_match: productpage-route-name1
    name: productpage
  isGateway: true
  rateLimitService:
    host: ratelimit.default.svc.cluster.local
    port: 8081
    timeout:
      seconds: 5
  workloadSelector:
    labels:
      app: istio-ingressgateway
status:
  config.yaml: |
    descriptors:
    - key: generic_key
      rate_limit:
        requests_per_unit: 1
        unit: MINUTE
      value: RateLimit[global-test.istio-system]-Id[597770312]
    domain: ratelimit.default.svc.cluster.local
  message: ok
  status: successful

    4. Paste the config.yaml content from the status field of the ASMGlobalRateLimiter resource output in the previous step into ratelimit-config.yaml to generate the global rate-limiting service configuration.

      The string content of the config.yaml field under the status field of ASMGlobalRateLimiter must be pasted as-is into the config.yaml field in the data field of the ConfigMap.

      ratelimit-config.yaml

      apiVersion: v1
kind: ConfigMap
metadata:
  name: ratelimit-config
data:
  config.yaml: |
    descriptors:
    - key: generic_key
      rate_limit:
        requests_per_unit: 1
        unit: MINUTE
      value: RateLimit[global-test.istio-system]-Id[597770312]
    domain: ratelimit.default.svc.cluster.local

    5. In the kubeconfig environment for your ACK cluster, run the following command to apply the new configuration to the global rate limit service.

      kubectl apply -f ratelimit-config.yaml

    6. Run the following command twice in a row to access the bookinfo application.

      Replace <ASM_GATEWAY_IP> with the IP address of your ASM gateway. For information about how to obtain the gateway IP address, see Obtain the IP address of an ingress gateway.

      curl -H 'host: bf2.example.com'  http://<ASM_GATEWAY_IP>/productpage -v
curl -H 'host: bf2.example.com'  http://<ASM_GATEWAY_IP>/productpage -v

      The expected output for the second request is as follows:

      < HTTP/1.1 429 Too Many Requests
< x-envoy-ratelimited: true
< x-ratelimit-limit: 1, 1;w=60
< x-ratelimit-remaining: 0
< x-ratelimit-reset: 48
< date: Thu, 26 Oct 2023 04:10:11 GMT
< server: istio-envoy
< content-length: 0
< 
* Connection #0 to host 116.62.XXX.XXX left intact

      The global rate limit is configured to allow only one request per minute. When you send two consecutive requests, the first one succeeds, but the gateway rejects the second one with a 429 Too Many Requests status. This confirms that the global rate limit for the route is effective.

    Scenario 2: Global rate limiting on an ingress gateway

    This scenario shows how to configure a global rate limit rule for the bf2.example.com:80 domain and port combination. After you apply the rule, all requests sent to this domain and port combination are subject to the specified rate limit.

    1. Create a file named global-ratelimit-gw.yaml with the following content.

      Global-ratelimit-gw.yaml

      apiVersion: istio.alibabacloud.com/v1beta1
kind: ASMGlobalRateLimiter
metadata:
  name: global-test
  namespace: istio-system
spec:
  workloadSelector:
    labels:
      istio: ingressgateway
  rateLimitService: # Configuration for the rate limiting service deployed in the preparation step.
    host: ratelimit.default.svc.cluster.local
    port: 8081
    timeout:
      seconds: 5
  isGateway: true
  configs:
  - name: productpage
    limit:
      unit: MINUTE
      quota: 1
    match:
      vhost:
        name: bf2.example.com # This name must match the domain in the VirtualService.
        port: 80 # This port must match the ASM gateway port.

      The following table describes key fields. For more information, see ASMGlobalRateLimiter CRD reference.

      Parameter

      Description

      workloadSelector

      Specifies the target workload for the rate limit rule. In this example, the rule targets the ingress gateway workload, which is identified by the label istio: ingressgateway.

      isGateway

      Specifies whether the rule applies to a gateway. Set to true for this example.

      rateLimitService

      Specifies the domain, port, and connection timeout for the rate limiting service. Based on the service deployed in the Preparation step, the configuration is as follows:

          host: ratelimit.default.svc.cluster.local
    port: 8081
    timeout:
      seconds: 5

      limit

      Defines the rate limit. The unit field specifies the time interval, and the quota field specifies the number of requests allowed per interval.

      In this example, unit is set to MINUTE and quota is set to 1. This setting allows only one request per minute for the matched route. Subsequent requests within that minute are rejected.

      vhost

      Specifies the domain and route to match. The name and port must match the domain from the VirtualService and the ingress gateway port, respectively.

    2. In the kubeconfig environment for your ASM instance, run the following command to apply the global rate limit rule for the productpage route on the gateway.

      kubectl apply -f global-ratelimit-gw.yaml

    3. Run the following command to get the configuration of the reconciled global rate limit rule.

      kubectl get asmglobalratelimiter global-test -n istio-system -o yaml

      Expected output

      apiVersion: istio.alibabacloud.com/v1
kind: ASMGlobalRateLimiter
metadata:
  name: global-test
  namespace: istio-system
spec:
  configs:
  - limit:
      quota: 1
      unit: MINUTE
    match:
      vhost:
        name: bf2.example.com
        port: 80
    name: productpage
  isGateway: true
  rateLimitService:
    host: ratelimit.default.svc.cluster.local
    port: 8081
    timeout:
      seconds: 5
  workloadSelector:
    labels:
      istio: ingressgateway
status:
  config.yaml: |
    descriptors:
    - key: generic_key
      rate_limit:
        requests_per_unit: 1
        unit: MINUTE
      value: RateLimit[global-test.istio-system]-Id[2100900480]
    domain: ratelimit.default.svc.cluster.local
  message: ok
  status: successful

    4. Copy the content of the config.yaml key from the status field in the preceding output, and paste it into a file named ratelimit-config.yaml to configure the global rate limiting service.

      The string content of the config.yaml field within the status field of the ASMGlobalRateLimiter must be pasted as-is into the config.yaml field of the same name within the data field of the ConfigMap.

      Ratelimit-config.yaml

      apiVersion: v1
kind: ConfigMap
metadata:
  name: ratelimit-config
data:
  config.yaml: |
    descriptors:
    - key: generic_key
      rate_limit:
        requests_per_unit: 1
        unit: MINUTE
      value: RateLimit[global-test.istio-system]-Id[2100900480]
    domain: ratelimit.default.svc.cluster.local

    5. In the kubeconfig environment for your ACK cluster, run the following command to update the global rate limiting service configuration.

      kubectl apply -f ratelimit-config.yaml

    6. Run the following command twice in a row to access the Bookinfo application.

      Replace <ASM_GATEWAY_IP> with the IP address of your ASM gateway. For more information about how to obtain the gateway IP address, see Obtain the IP address of an ingress gateway.

      curl -H 'host: bf2.example.com'  http://<ASM_GATEWAY_IP>/productpage -v
curl -H 'host: bf2.example.com'  http://<ASM_GATEWAY_IP>/productpage -v

      The expected output for the second request is as follows:

      < HTTP/1.1 429 Too Many Requests
< x-envoy-ratelimited: true
< x-ratelimit-limit: 1, 1;w=60
< x-ratelimit-remaining: 0
< x-ratelimit-reset: 48
< date: Thu, 26 Oct 2023 04:10:11 GMT
< server: istio-envoy
< content-length: 0
< 
* Connection #0 to host 116.62.XXX.XXX left intact

      The global rate limit rule restricts access to the bf2.example.com:80 domain and port combination to one request per minute. When you send two consecutive requests, the first one succeeds, but the second one is rejected. This confirms that the rate limit rule on the ingress gateway is working correctly.

    Use case 3: Conditional rate limiting on a gateway route

    Note

    This use case requires an ASM instance of version 1.19.0 or later. For update instructions, see Update an ASM instance.

    Configure a rate-limiting rule for the productpage-route-name1 route on the bf2.example.com:80 domain and port. The rule applies only to requests that contain the ratelimit: "true" request header and the ratelimit=enabled query parameter. Other requests on this route are not affected by the rate-limiting rule. The route matches requests for paths such as /productpage, /static, /login, and /logout, and forwards the matched requests to the productpage service. After the rate-limiting rule is configured, requests that are sent to these paths and meet the specified conditions will be rate-limited.

    1. Create a file named global-ratelimit-gw.yaml with the following content.

      global-ratelimit-gw.yaml

      apiVersion: istio.alibabacloud.com/v1beta1
kind: ASMGlobalRateLimiter
metadata:
  name: global-test
  namespace: istio-system
spec:
  workloadSelector:
    labels:
      app: istio-ingressgateway
  rateLimitService:
    host: ratelimit.default.svc.cluster.local
    port: 8081
    timeout:
      seconds: 5
  isGateway: true
  configs:
  - name: productpage
    limit:
      unit: SECOND
      quota: 100000
    match:
      vhost:
        name: bf2.example.com
        port: 80
        route:
          name_match: productpage-route-name1  # This name must match the route name in the virtual service.
    limit_overrides:
    - request_match:
        header_match:
        - name: ratelimit
          exact_match: "true"
        query_match:
        - name: ratelimit
          exact_match: "enabled"
      limit:
        unit: MINUTE
        quota: 1

      The following table describes key fields. For more information, see ASMGlobalRateLimiter CRD reference.

      Parameter

      Description

      workloadSelector

      Specifies the workloads that are subject to rate limiting. In this example, the global rate limit applies to the ingress gateway and is set to istio: ingressgateway.

      isGateway

      Specifies whether this applies to the gateway. In this example, it is set to true.

      rateLimitService

      Specifies the domain name, port, and connection timeout for the rate-limiting service. Based on the service deployed in the Preparation step, the configuration is as follows:

          host: ratelimit.default.svc.cluster.local
    port: 8081
    timeout:
      seconds: 5

      limit

      Defines the base rate-limiting parameters for the virtual service route. The unit field specifies the time interval, and quota specifies the number of requests allowed per interval. This example sets unit to SECOND and quota to 100000, which allows 100,000 requests per second. This high limit effectively disables rate limiting for requests that do not match a more specific override, ensuring they are not rate-limited.

      vhost

      Specifies the matching conditions for the domain and route. The name and port fields must match the domain from the virtual service and the ingress gateway port, respectively. The route name in route.name_match must match the route name in the virtual service.

      limit_overrides

      Overrides the default rate limit. Use this field to apply a more specific rate limit to certain requests. In this example:

      • Under limit_overrides, the request_match field matches requests that contain both the ratelimit: "true" request header and the ratelimit=enabled query parameter.

      • In the limit field of limit_overrides, setting unit to MINUTE and quota to 1 restricts requests that meet the conditions specified by request_match to one per minute.

    2. In the kubeconfig environment of the corresponding ASM instance, run the following command to create a global rate-limiting rule for the productpage-route-name1 route on the gateway.

      kubectl apply -f global-ratelimit-gw.yaml

    3. Run the following command to get the reconciled configuration of the global rate-limiting rule.

      kubectl get asmglobalratelimiter global-test -n istio-system -o yaml

      Expected output

      apiVersion: istio.alibabacloud.com/v1
kind: ASMGlobalRateLimiter
metadata:
  name: global-test
  namespace: istio-system
spec:
  configs:
  - limit:
      quota: 100000
      unit: SECOND
    limit_overrides:
    - limit:
        quota: 1
        unit: MINUTE
      request_match:
        header_match:
        - exact_match: "true"
          name: ratelimit
        query_match:
        - exact_match: enabled
          name: ratelimit
    match:
      vhost:
        name: bf2.example.com
        port: 80
        route:
          name_match: productpage-route-name1
    name: productpage
  isGateway: true
  rateLimitService:
    host: ratelimit.default.svc.cluster.local
    port: 8081
    timeout:
      seconds: 5
  workloadSelector:
    labels:
      app: istio-ingressgateway
status:
  config.yaml: |
    descriptors:
    - descriptors:
      - descriptors:
        - key: query_match
          rate_limit:
            requests_per_unit: 1
            unit: MINUTE
          value: RateLimit[global-test.istio-system]-Id[1102463266]
        key: header_match
        value: RateLimit[global-test.istio-system]-Id[1102463266]
      key: generic_key
      rate_limit:
        requests_per_unit: 100000
        unit: SECOND
      value: RateLimit[global-test.istio-system]-Id[1102463266]
    domain: ratelimit.default.svc.cluster.local
  message: ok
  status: successful

    4. Paste the content of config.yaml from the status field of the ASMGlobalRateLimiter resource (from the expected output of the previous step) into the ratelimit-config.yaml file to generate the global rate-limiting service configuration.

      The string content of the status field under the config.yaml field of ASMGlobalRateLimiter must be pasted as-is into the config.yaml field of the same name under the data field of the ConfigMap.

      ratelimit-config.yaml

      apiVersion: v1
kind: ConfigMap
metadata:
  name: ratelimit-config
data:
  config.yaml: |
    descriptors:
    - descriptors:
      - descriptors:
        - key: query_match
          rate_limit:
            requests_per_unit: 1
            unit: MINUTE
          value: RateLimit[global-test.istio-system]-Id[1102463266]
        key: header_match
        value: RateLimit[global-test.istio-system]-Id[1102463266]
      key: generic_key
      rate_limit:
        requests_per_unit: 100000
        unit: SECOND
      value: RateLimit[global-test.istio-system]-Id[1102463266]
    domain: ratelimit.default.svc.cluster.local

    5. From your kubeconfig environment for the ACK cluster, run the following command to update the global rate-limiting service configuration in the cluster.

      kubectl apply -f ratelimit-config.yaml

    6. Run the following command twice in a row to access the Bookinfo application.

      Replace <ASM_GATEWAY_IP> with your gateway IP. For information about how to obtain the gateway IP, see Obtain the IP address of an ingress gateway.

      curl -H 'host: bf2.example.com'  http://<ASM_GATEWAY_IP>/productpage -v
curl -H 'host: bf2.example.com'  http://<ASM_GATEWAY_IP>/productpage -v

      The expected output for the second request to the Bookinfo application is as follows:

      < HTTP/1.1 429 Too Many Requests
< x-envoy-ratelimited: true
< x-ratelimit-limit: 1, 1;w=60
< x-ratelimit-remaining: 0
< x-ratelimit-reset: 48
< date: Thu, 26 Oct 2023 04:10:11 GMT
< server: istio-envoy
< content-length: 0
< 
* Connection #0 to host 116.62.XXX.XXX left intact

      In the global rate limiting configuration, requests to the bookinfo application are limited to one per minute if they contain the ratelimit: "true" request header and the ratelimit=enabled query parameter. When you make two consecutive requests to the bookinfo application with this header and query parameter, you can see that the first request is successful and the second is rate-limited, which indicates that the global rate limiting configuration for matching specific requests on the ingress gateway is successful.

    7. Run the following command to access the bookinfo application again without the ratelimit: "true" request header or the query parameter ratelimit=enabled.

      curl -H 'host: bf2.example.com'  http://<ASM_GATEWAY_IP>/productpage -v

      The output shows that the Bookinfo application is accessed successfully and no 429 status code is returned. This confirms that the rate-limiting rule does not affect other requests on the route.

    Scenario 4: Configure IP-based throttling for a virtual service route

    Note

    • This scenario requires an ASM instance of version 1.19.0 or later. For upgrade instructions, see Update an ASM instance.

    • To configure throttling for specific client IP addresses on an ASM ingress gateway, you must first ensure that the external traffic policy of the ingress gateway is set to Local. To learn how to create an ingress gateway and its configuration options, see Create an ingress gateway.

    • You can find the client IP address for requests to the gateway in the downstream_remote_address field of the gateway's access log. In this example, configure the rule using the client IP address that you want to throttle.

    This scenario shows how to configure a throttling rule for the productpage-route-name1 virtual service route, which is associated with the domain and port combination bf2.example.com:80. The rule is designed to apply only to requests from specific client IP addresses, leaving other requests on the same route unaffected.

    1. Create a file named global-ratelimit-gw.yaml with the following content.

      global-ratelimit-gw.yaml

      apiVersion: istio.alibabacloud.com/v1beta1
kind: ASMGlobalRateLimiter
metadata:
  name: global-test
  namespace: istio-system
spec:
  workloadSelector:
    labels:
      app: istio-ingressgateway
  rateLimitService:
    host: ratelimit.default.svc.cluster.local
    port: 8081
    timeout:
      seconds: 5
  isGateway: true
  configs:
  - name: productpage
    limit:
      unit: SECOND
      quota: 100000
    match:
      vhost:
        name: bf2.example.com
        port: 80
        route:
          name_match: productpage-route-name1  # This name must match the route name in the virtual service.
    limit_overrides:
    - request_match:
        remote_address:
          address: xxx.xxx.xxx.xxx # The client IP address.
          v4_prefix_mask_len: xx # The subnet mask for the client IP range.
      limit:
        unit: MINUTE
        quota: 1

      The following table describes key fields. For details on these fields, see ASMGlobalRateLimiter CRD reference.

      Parameter

      Description

      workloadSelector

      Selects the workload to which throttling applies. This example applies global throttling to the ingress gateway workload, selected using the label app: istio-ingressgateway.

      isGateway

      Specifies whether the rule applies to a gateway. In this example, it is set to true.

      rateLimitService

      The domain, port, and connection timeout for the throttling service. Based on the throttling service deployed in the prerequisites, the configuration is as follows:

          host: ratelimit.default.svc.cluster.local
    port: 8081
    timeout:
      seconds: 5

      limit

      The base throttling parameters for the virtual service route. The unit specifies the time interval, and quota specifies the number of requests allowed per interval.

      This example sets unit to SECOND and quota to 100000, which allows 100,000 requests per second. This high limit effectively disables throttling for requests that do not match a specific override.

      vhost

      The matching conditions for the domain and route. The name and port must match the domain from the virtual service and the ingress gateway port, respectively. The route name specified in route.name_match must match the name of the route in the virtual service.

      limit_overrides

      Defines a more specific throttling threshold for certain requests. In this example:

      • The request_match field matches requests based on the client's source IP address using remote_address.address. You can also specify an optional IP address range by defining a subnet mask length in the remote_address.v4_prefix_mask_len field.

      • In the limit_overrides field, the limit field is configured with unit set to MINUTE and quota set to 1, which means that for requests that match the conditions specified by request_match, only one request is allowed per minute.

    2. Using the kubeconfig for your ASM instance, run the following command to create the global throttling rule for the productpage-route-name1 route on the ingress gateway.

      kubectl apply -f global-ratelimit-gw.yaml

    3. Run the following command to retrieve the reconciled configuration of the global throttling rule.

      kubectl get asmglobalratelimiter global-test -n istio-system -o yaml

      Expected output

      apiVersion: istio.alibabacloud.com/v1
kind: ASMGlobalRateLimiter
metadata:
  name: global-test
  namespace: istio-system
spec:
  configs:
  - limit:
      quota: 100000
      unit: SECOND
    limit_overrides:
    - limit:
        quota: 1
        unit: MINUTE
      request_match:
        remote_address:
          address: 106.11.XX.XX
          v4_prefix_mask_len: 24
    match:
      vhost:
        name: bf2.example.com
        port: 80
        route:
          name_match: productpage-route-name1
    name: productpage
  isGateway: true
  rateLimitService:
    host: ratelimit.default.svc.cluster.local
    port: 8081
    timeout:
      seconds: 5
  workloadSelector:
    labels:
      app: istio-ingressgateway
status:
  config.yaml: |
    descriptors:
    - descriptors:
      - key: masked_remote_address
        rate_limit:
          requests_per_unit: 1
          unit: MINUTE
        value: xxxxxx
      key: generic_key
      rate_limit:
        requests_per_unit: 100000
        unit: SECOND
      value: RateLimit[global-test.istio-system]-Id[1102463266]
    domain: ratelimit.default.svc.cluster.local
  message: ok
  status: successful

    4. Copy the config.yaml content from the status field of the ASMGlobalRateLimiter resource output in the previous step, and paste it into ratelimit-config.yaml to configure the global throttling service.

      The string content of the config.yaml field, which is under the status field of the ASMGlobalRateLimiter resource, must be pasted verbatim into the config.yaml field under the data field of the ConfigMap.

      ratelimit-config.yaml

      apiVersion: v1
kind: ConfigMap
metadata:
  name: ratelimit-config
data:
  config.yaml: |
    descriptors:
    - descriptors:
      - key: masked_remote_address
        rate_limit:
          requests_per_unit: 1
          unit: MINUTE
        value: xxxxxx
      key: generic_key
      rate_limit:
        requests_per_unit: 100000
        unit: SECOND
      value: RateLimit[global-test.istio-system]-Id[1102463266]
    domain: ratelimit.default.svc.cluster.local

    5. Using the kubeconfig for your ACK cluster, run the following command to update the global throttling service configuration.

      kubectl apply -f ratelimit-config.yaml

    6. From a client with the specified IP address, run the following commands twice in a row to access the bookinfo application.

      Replace <ASM_GATEWAY_IP> with your actual gateway IP address. To learn how to obtain the gateway IP address, see Obtain the IP address of an ingress gateway.

      curl -H 'host: bf2.example.com'  http://<ASM_GATEWAY_IP>/productpage -v
curl -H 'host: bf2.example.com'  http://<ASM_GATEWAY_IP>/productpage -v

      The expected output for the second request is as follows:

      < HTTP/1.1 429 Too Many Requests
< x-envoy-ratelimited: true
< x-ratelimit-limit: 1, 1;w=60
< x-ratelimit-remaining: 0
< x-ratelimit-reset: 48
< date: Thu, 26 Oct 2023 04:10:11 GMT
< server: istio-envoy
< content-length: 0
< 
* Connection #0 to host 116.62.XXX.XXX left intact

      The global throttling configuration limits requests from the specified IP address (or range) to one request per minute. When you send two consecutive requests from a client with that IP address, the first one succeeds, but the second one is throttled. This confirms that the global throttling rule for the ingress gateway is functioning as expected.

    7. From a client with a different IP address, run the following command to access the bookinfo application again.

      curl -H 'host: bf2.example.com'  http://<ASM_GATEWAY_IP>/productpage -v

      The request succeeds, and no HTTP 429 status code is returned. This indicates that other requests on the route are not affected by the global throttling rule.

    Scenario 5: Configure per-client IP rate limiting on a route

    Note

    1. This scenario requires an ASM instance of version 1.25.0 or later. For upgrade instructions, see Upgrade an ASM instance.

    2. In this scenario, you must set the external traffic policy of the ASM ingress gateway to Local. This preserves the original client IP address. For more information about how to create an ingress gateway and its configuration options, see Create an ingress gateway.

    3. You can find the client IP address of a request to the gateway in the downstream_remote_address field of the access log. In this example, the rate limiting rule is configured based on the actual client IP address.

    In this scenario, you will configure a rate-limiting rule for the productpage-route-name1 virtual service route at bf2.example.com:80 to rate-limit each unique client IP address to one request per minute.

    1. Create a file named global-ratelimit-gw.yaml.

      apiVersion: istio.alibabacloud.com/v1beta1
kind: ASMGlobalRateLimiter
metadata:
  name: global-test
  namespace: istio-system
spec:
  workloadSelector:
    labels:
      app: istio-ingressgateway
  rateLimitService:
    host: ratelimit.default.svc.cluster.local
    port: 8081
    timeout:
      seconds: 5
  isGateway: true
  configs:
  - name: productpage
    limit:
      unit: SECOND
      quota: 100000
    target_services:
    - name: bookinfo
      namespace: default
      kind: VirtualService
      port: 80
      section_name: productpage-route-name1
    limit_overrides:
    - request_match:
        remote_address:
          distinct: true # Apply rate limiting to each client IP address individually.
      limit:
        unit: MINUTE
        quota: 1

      The following table describes key fields. For more information about the fields, see ASMGlobalRateLimiter CRD reference.

      Parameter

      Description

      workloadSelector

      Selects the workload to which the rate limiting rule applies. In this example, global rate limiting is applied to the ingress gateway, which is selected by the label app: istio-ingressgateway.

      isGateway

      Specifies whether the rule applies to a gateway. In this example, it is set to true.

      rateLimitService

      The domain, port, and connection timeout settings for the rate limiting service. Based on the rate limiting service deployed in the Prerequisites section, the configuration is as follows:

          host: ratelimit.default.svc.cluster.local
    port: 8081
    timeout:
      seconds: 5

      limit

      The rate limiting parameters that apply to the virtual service route. It includes the following fields:

      • unit: The time interval for rate limit checks.

      • quota: The number of requests allowed per time interval.

      In this example, unit is set to SECOND and quota is set to 100000. This high limit effectively disables rate limiting for requests not covered by a specific override, ensuring that other traffic remains unaffected.

      limit_overrides

      Overrides the default rate limit for specific requests. In this example:

      • The request_match field specifies conditions for the override:

        • The remote_address field matches requests by client IP address.

        • Setting the distinct parameter to true applies this limit to each client individually.

        • remote_addess.v4_prefix_mask_len matches the subnet mask for the client source IP address range (Optional).

      • The limit field within limit_overrides sets unit to MINUTE and quota to 1. This limits requests matching the request_match conditions to one per minute.

      target_services

      Specifies the virtual service route to which the rate limiting rule applies.

      • kind specifies that the rule targets a virtual service.

      • namespace and name specify the namespace and name of the virtual service.

      • port restricts the rule to traffic on port 80.

      • section_name specifies that the rule applies to the route named productpage-route-name1 within the virtual service.

    2. Apply the global rate limiting rule.

      kubectl apply -f global-ratelimit-gw.yaml

    3. View the reconciled configuration of the global rate limiting rule.

      kubectl get asmglobalratelimiter global-test -n istio-system -o yaml |grep status: -A 50

      Expected output:

      status:
  config.yaml: |
    descriptors:
    - descriptors:
      - key: remote_address
        rate_limit:
          requests_per_unit: 1
          unit: MINUTE
      key: generic_key
      rate_limit:
        requests_per_unit: 100000
        unit: SECOND
      value: RateLimit[global-test.istio-system]-Id[537612397]
    domain: ratelimit.default.svc.cluster.local
  message: ok
  status: successful

    4. Edit the ratelimit-config ConfigMap from the Prerequisites section, replacing the value of the config.yaml key with the status output from the previous step.

      kubectl edit ConfigMap ratelimit-config

      Updated content:

      apiVersion: v1
kind: ConfigMap
metadata:
  name: ratelimit-config
data:
  config.yaml: |
    descriptors:
    - descriptors:
      - key: remote_address
        rate_limit:
          requests_per_unit: 1
          unit: MINUTE
      key: generic_key
      rate_limit:
        requests_per_unit: 100000
        unit: SECOND
      value: RateLimit[global-test.istio-system]-Id[537612397]
    domain: ratelimit.default.svc.cluster.local

    5. From a client, access the bookinfo application twice consecutively.

      export GATEWAY_URL=$(kubectl -n istio-system get service istio-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
curl -H 'host: bf2.example.com' http://$GATEWAY_URL:80/productpage -v
curl -H 'host: bf2.example.com' http://$GATEWAY_URL:80/productpage -v

      Expected output for the second request:

      < HTTP/1.1 429 Too Many Requests
< x-envoy-ratelimited: true
< x-ratelimit-limit: 1, 1;w=60
< x-ratelimit-remaining: 0
< x-ratelimit-reset: 48
< date: Thu, 26 Jul 2025 04:10:11 GMT
< server: istio-envoy
< content-length: 0
< 
* Connection #0 to host 116.62.XXX.XXX left intact

      The output shows that the second request is rate-limited, confirming that the global rate limiting rule for the ingress gateway is configured correctly.

    Related documents