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.

Google Cloud Armor has two types of rate-based rules:

1. Throttle: You can enforce a maximum request limit per client or across all clients by throttling individual clients to a user-configured threshold.
2. 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 Rate limiting based on multiple keys.

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

Google 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 clients whose requests satisfy the rule match condition.
• IP: A unique key for each client source 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 source IP address of the client, 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/region from which the request originates.
• 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. For more information about JA3, see the rules language reference.
• 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.

Note: The rate-limiting key data is classified as Service Data, which is processed as described in Google Cloud Privacy Notice. Rate-limiting key data is not treated as Customer Data. If your workload is subject to regulatory regimes or other compliance requirements that necessitate access transparency or access approval, review the key types whose values might contain sensitive information.

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, Google 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, Google 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 error code is returned (valid values are 403, 404, 429 and 502). We recommend using the 429 (Too Many Requests) response 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: This is the action performed when the number of requests is under the rate_limit_threshold_count. This 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, Google 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, this immediately allows the request to proceed to the backend service. When a client's traffic rate exceeds the specified rate_limit_threshold_count, Google 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, regardless of 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 does not 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, Google 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 error code is returned. Valid values for the error code are 403, 404, 429 and 502. We recommend using the response 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.
• 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: This is the action performed when the number of requests is under the rate_limit_threshold_count. This is always an allow action.
• ban_threshold_count: This is the number of requests per client allowed within a specified time interval, over which Google Cloud Armor bans requests. If specified, the key is banned for the configured ban_duration_sec when the number of requests that exceed the rate_limit_threshold_count also exceed this ban_threshold_count.
  • ban_threshold_interval_sec: The number of seconds in the time interval for your ban_threshold_count. The value must be 10, 30, 60, 120, 180, 240, 300, 600, 900, 1200, 1800, 2700, or 3600 seconds.
• ban_duration_sec: This is the additional number of seconds for which a client is banned after the interval_sec period elapses. The value must be 60, 120, 180, 240, 300, 600, 900, 1200, 1800, 2700, or 3600 seconds.

Default rate limiting security policy

When you configure a default security policy during load balancer creation, the default threshold is 500 requests during each one-minute interval (a rate_limit_threshold_count and interval_sec of 500 and 60, respectively). If you want to select a different threshold, we recommend that you use the following steps to tune your parameters:

1. Enable Cloud Logging and query the maximum number of requests that arrived per IP address and per minute over a day or longer at your Google Cloud Armor-protected backend service.

   For example, suppose that you believe that 99% of the network traffic that you receive should not be impacted by the rate limit rule. In this scenario, we recommend that you set your rate limit threshold to the 99th percentile of the maximum number of requests per IP address and per minute of the distribution that is generated from the Cloud Logging data.

2. If you still notice default rate limit rules blocking legitimate traffic, consider the following additional steps:

   1. Enable caching (Cloud CDN or Media CDN).
   2. Increase throttle time interval (requests received per several minutes, instead of per 60 seconds).
   3. You can ban clients to reduce attack impact further after the initial wave. The Google Cloud Armor rate_based_ban action lets you do this by banning all clients that exceed the limits too many times within a user-specified window. For example, clients that exceed the limits 10 times within a minute can be banned for 15 minutes.

Threshold enforcement

The configured thresholds for throttling and rate-based bans are enforced independently in each of the Google Cloud regions where your HTTP(S) backend services are deployed. For example, if your service is deployed in two regions, each of the two regions rate limits each key to the configured threshold, so your backend service might experience cross-region aggregated traffic volumes that are twice the configured threshold. If the configured threshold is set to 5,000 requests, the backend service might receive 5,000 requests from one region and 5,000 requests from the second region.

However, for the key type IP address, it is reasonable to assume that traffic from the same client IP address is directed to the region that is closest to the region where your backends are deployed. In this case, rate limiting can be considered to be enforced at a backend service level, regardless of the regions it is deployed in.

It is important to note that the enforced rate limits are approximate and might not be strictly accurate compared to the configured thresholds. Also, in rare cases, because of internal routing behavior, it is possible that rate limiting might be enforced in more regions than the regions you are deployed in, thus impacting accuracy. For these reasons, we recommend that you use rate limiting only for abuse mitigation or maintaining application and service availability, not for enforcing strict quota or licensing requirements.

Logging

Cloud Logging records the security policy name, matched rate limit rule priority, rule ID, the associated action, and other information in your request logs. For more information about logging, see Using request logging.

Integration with reCAPTCHA

You can apply rate limiting to some reCAPTCHA resources in order to mitigate token abuse and limit token re-use. These resources include action-tokens, session-tokens, and exemption cookies. For more information about using rate limiting with reCAPTCHA, see the bot management overview.

What's next

• Configure rate limiting