Rate limiting overview

Google Cloud Armor provides capabilities to help protect your Google Cloud applications against a variety of Layer 3 and Layer 7 attacks. Rate-based rules help you protect your applications from a large volume of requests that flood your instances and block access for legitimate users.

Rate limiting can do the following:

  • Prevent any particular client from exhausting application resources.
  • Protect your application instances from erratic and unpredictable spikes in the rate of client requests.

In addition, when a resource is presented with a high volume of traffic from a small number of clients, you can prevent your other clients from being affected by large spikes of traffic from that small number of clients, enabling your resources to handle as many requests as possible.

Cloud Armor has two types of rate-based rules:

  • Throttle. You can enforce a maximum request limit per client or across all clients by throttling individual clients to a user-configured threshold.
  • Rate-based ban. You can rate limit requests that match a rule on a per-client basis and then temporarily ban those clients for a configured period of time if they exceed a user-configured threshold.

When you configure a rule with a rate-based ban action, you can't change it to a throttle action later. However, when you configure a rule with a throttle action, you can change it to a rate-based ban action later. For more information, see Change a throttle rule to a rate-based ban rule.

Cloud Armor applies the rate limiting threshold to each associated backend. For example, if you have two backend services and you configure a rate limiting rule with a threshold of 1,000 requests per minute, then each backend service can receive 1,000 requests per minute before Cloud Armor applies the rule action.

You can preview the effects of rate limiting rules in a security policy by using preview mode and examining your request logs.

Identifying clients for rate limiting

Cloud Armor identifies individual clients for rate limiting by using the following key types for aggregating requests and enforcing rate limits:

  • ALL: a single key for all requests that satisfy the rule match condition.
  • IP: a unique key for each client IP address whose requests satisfy the rule match condition.
  • HTTP_HEADER: a unique key for each unique HTTP header value whose name is configured. The key value is truncated to the first 128 bytes of the header value. The key type defaults to ALL if no such header is present, or if you attempt to use this key type with an external proxy Network Load Balancer.
  • XFF_IP: a unique key for each original client IP address, that is, the first IP address in the list of IPs specified in the X-Forwarded-For HTTP header. The key type defaults to IP address if no such header is present, if the value is not a valid IP address, or if you attempt to use this key type with an external proxy Network Load Balancer.
  • HTTP_COOKIE: a unique key for each HTTP cookie value whose name is configured. The key value is truncated to the first 128 bytes of the cookie value. The key type defaults to ALL if no such cookie is present, or if you attempt to use this key type with an external proxy Network Load Balancer.
  • HTTP_PATH: the URL path of the HTTP request. The key value is truncated to the first 128 bytes.
  • SNI: the server name indication in the TLS session of the HTTPS request. The key value is truncated to the first 128 bytes. The key type defaults to ALL on an HTTP session.
  • REGION_CODE: the country or region from which the request originates.
  • TLS_JA4_FINGERPRINT: JA4 TLS/SSL fingerprint if the client connects using HTTPS, HTTP/2 or HTTP/3. If not available, the key type defaults to ALL. For more information about JA4, see the rules language reference.
  • TLS_JA3_FINGERPRINT: JA3 TLS/SSL fingerprint if the client connects using HTTPS, HTTP/2 or HTTP/3. If not available, the key type defaults to ALL.
  • USER_IP: The IP address of the originating client, included in the headers configured under userIpRequestHeaders and whose value is filled by an upstream proxy. If there is no userIpRequestHeaders configuration, or an IP address cannot be resolved from it, the key type defaults to IP. For more information, see the rules language reference.

You can use the preceding keys individually, or you can apply rate limiting based on a combination of up to three keys. You can use multiple HTTP-HEADER or HTTP-COOKIE keys, and only one of each other key type. For more information, see Rate limiting based on multiple keys.

Choose between rate based ban and throttle rate limiting rules

Cloud Armor rate-based ban and throttle rate limiting rules differ in how they handle traffic exceeding the configured threshold.

  • rate_based_ban: when the rate of requests exceeds the defined threshold, Cloud Armor blocks all further requests from the source or target of those requests for a specified period.
  • throttle: instead of blocking all traffic, throttling limits the rate of requests to a defined maximum. Throttling allows some traffic to pass through, but at a controlled rate that prevents overload.

The most appropriate rule depends on your specific needs and the type of traffic you're dealing with. For example, if you're facing a DDoS attack, a rate-based ban might be more appropriate to quickly block the malicious traffic. Alternatively, if you're experiencing a sudden surge in legitimate traffic, throttling might be a better option to maintain service availability while preventing overload.

Throttling traffic

The throttle action in a rule lets you enforce a per-client request threshold to protect backend services. This rule enforces the threshold to limit traffic from each client that satisfies the match conditions in the rule. The threshold is configured as a specified number of requests in a specified time interval.

For example, you might set the request threshold to 2,000 requests within 1,200 seconds (20 minutes). If a client sends 2,500 requests within any 1,200 second period, approximately 20% of the client's traffic is throttled until the permitted request volume is at or below the configured threshold.

When a client's traffic rate is under or equal to the rate_limit_threshold_count, requests follow the conform_action, which is always an allow action. The request is allowed through the security policy and permitted to reach its destination. When a client's traffic rate exceeds the specified rate_limit_threshold_count, Cloud Armor applies the exceed_action, which can be either deny or redirect, for requests over the limit for the rest of the threshold interval.

You set these parameters to control the action:

  • rate_limit_threshold_count: the number of requests per client allowed within a specified time interval. The minimum value is 1 and the maximum value is 1,000,000.
    • interval_sec: the number of seconds in the time interval. The value must be 10, 30, 60, 120, 180, 240, 300, 600, 900, 1200, 1800, 2700, or 3600 seconds.
  • exceed_action: when a request exceeds the rate_limit_threshold_count, Cloud Armor applies the configured exceed_action. Possible values for the exceed_action follow:
    • deny(status): the request is denied and the specified status code is returned. Valid values are 403 Forbidden, 404 Page Not Found, 429 Too Many Requests, and 502 Bad Gateway. We recommend using the 429 Too Many Requests status code.
    • redirect: the request is either redirected for reCAPTCHA assessment or to a different URL, based on the exceed_redirect_options parameter.
  • exceed_redirect_options: when the exceed_action is redirect, use this parameter to specify the redirect action:
    • type: type for the redirect action, either GOOGLE_RECAPTCHA or EXTERNAL_302.
    • target: URL target for the redirect action. Only applicable when the type is EXTERNAL_302.
  • conform_action: the action performed when the number of requests is under the rate_limit_threshold_count. This action is always an allow action.

Banning clients based on request rates

The rate_based_ban action in a rule lets you enforce a per-client threshold to temporarily ban clients that exceed the limit by applying the configured exceed_action for all requests from the client for a configurable time period. The threshold is configured as a specified number of requests in a specified time interval. You can temporarily ban traffic for a user-configured time period ('ban_duration_sec'), provided that the traffic matches the specified match condition and exceeds the configured threshold.

For example, you might set the request threshold to 2,000 requests within 1,200 seconds (20 minutes). If a client sends 2,500 requests within any 1,200 seconds, Cloud Armor applies the exceed_action to traffic from that client exceeding the 2,000 request threshold until the full 1,200 seconds has elapsed and for an additional number of seconds that you set as the ban duration period. If the ban duration period is set to 3600, for example, traffic from the client would be banned for 3,600 seconds (one hour) beyond the end of the threshold interval.

When a client's request rate is under the rate limit threshold, the request can immediately proceed to the backend service. When a client's traffic rate exceeds the specified rate_limit_threshold_count, Cloud Armor applies the exceed_action to all incoming requests from the client for the rest of the threshold interval and for the next ban_duration_sec seconds, whether or not the threshold is exceeded.

With this configuration, it is possible to accidentally ban welcome clients that only occasionally exceed the allowable request rate. To prevent this, and ban only clients that frequently exceed the request rate, you can optionally track the total client requests against an additional, preferably longer, threshold configuration called the ban_threshold_count. In this mode, the client is banned for the configured ban_duration_sec only if the request rate crosses the configured ban_threshold_count. If the request rate doesn't exceed the ban_threshold_count, the requests keep getting throttled to rate_limit_threshold_count. For the purpose of ban_threshold_count, the total requests from the client, consisting of all incoming requests before throttling, are counted.

These parameters control the action of a rate_based_ban rule:

  • rate_limit_threshold_count: the number of requests per client allowed within a specified time interval. The minimum value is 1 request and the maximum value is 10,000 requests.
    • interval_sec: the number of seconds in the time interval. The value must be 10, 30, 60, 120, 180, 240, 300, 600, 900, 1200, 1800, 2700, or 3600 seconds.
  • exceed_action: when a request exceeds the rate_limit_threshold_count, Cloud Armor applies the configured exceed_action. Possible values for the exceed_action are as follows:
    • deny(status): the request is denied and the specified status code is returned. Valid values are 403 Forbidden, 404 Page Not Found, 429 Too Many Requests, and 502 Bad Gateway. We recommend using the status code 429 Too Many Requests.
    • redirect: the request is either redirected for reCAPTCHA assessment or to a different URL, based on the exceed_redirect_options parameter.