Google Cloud Armor provides capabilities to help protect your Google Cloud applicationsagainst a variety of Layer 3 and Layer 7 attacks. Rate-based rules help youprotect your applications from a large volume of requests that flood yourinstances 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 spikesin the rate of client requests.

In addition, when a resource is presented with a high volume of traffic from asmall number of clients, you can prevent your other clients from being affectedby large spikes of traffic from that small number of clients, enabling yourresources 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 allclients by throttling individual clients to a user-configured threshold.
• Rate-based ban. You can rate limit requests that match a rule on a per-clientbasis and then temporarily ban those clients for a configured period of timeif they exceed a user-configured threshold.

When you configure a rule with a rate-based ban action, you can't change it to athrottle 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, seeChange a throttle rule to a rate-based ban rule.

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

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

Identifying clients for rate limiting

Cloud Armor identifies individual clients for rate limiting by usingthe 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 requestssatisfy the rule match condition.
• HTTP_HEADER: a unique key for each unique HTTP header value whose name isconfigured. The key value is truncated to the first 128 bytes of the headervalue. The key type defaults to ALL if no such header is present, or if youattempt 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 theX-Forwarded-For HTTP header. The key type defaults to IP address if nosuch header is present, if the value is not a valid IP address, or if youattempt to use this key type with an external proxy Network Load Balancer.
• HTTP_COOKIE: a unique key for each HTTP cookie value whose name isconfigured. The key value is truncated to the first 128 bytes of the cookievalue. The key type defaults to ALL if no such cookie is present, or if youattempt 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 tothe 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 typedefaults 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 usingHTTPS,HTTP/2 orHTTP/3. If not available, the key type defaults toALL. For more information about JA4, see therules language reference.
• TLS_JA3_FINGERPRINT: JA3 TLS/SSL fingerprint if the client connects usingHTTPS,HTTP/2 orHTTP/3. If not available, the key type defaults toALL.
• USER_IP: The IP address of the originating client, included in the headersconfigured underuserIpRequestHeaders and whose value is filled by anupstream proxy. If there is nouserIpRequestHeaders configuration, or an IPaddress cannot be resolved from it, the key type defaults to IP. For moreinformation, see therules language reference.

You can use the preceding keys individually, or you can apply rate limitingbased on a combination of up to three keys. You can use multipleHTTP-HEADERorHTTP-COOKIE keys, and only one of each other key type. For moreinformation, seeRate limiting based on multiple keys.

Note: The rate-limiting key data is classified as service data, which isprocessed as described inGoogle Cloud Privacy Notice.Rate-limiting key data isn't treated ascustomer data.If your workload is subject to regulatory regimes or other compliancerequirements that necessitateaccess transparency or access approval,review the key types whose values might contain sensitive information.

Choose between rate based ban and throttle rate limiting rules

Cloud Armorrate-based ban andthrottle rate limiting rules differin 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 targetof those requests for a specified period.
• throttle: instead of blocking all traffic, throttling limits the rate ofrequests 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 trafficyou're dealing with. For example, if you're facing a DDoS attack, a rate-basedban 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 whilepreventing overload.

Throttling traffic

Thethrottle action in a rule lets you enforce a per-client requestthreshold to protect backend services. This rule enforces the threshold to limittraffic from each client that satisfies the match conditions in the rule. Thethreshold is configured as a specified number of requests in a specified timeinterval.

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

When a client's traffic rate is under or equal to therate_limit_threshold_count, requests follow theconform_action, which isalways anallow action. The request is allowed through the security policyand permitted to reach its destination. When a client's traffic rate exceedsthe specifiedrate_limit_threshold_count, Cloud Armor applies theexceed_action, which can be eitherdeny orredirect, for requests overthe 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 aspecified time interval. The minimum value is 1 and the maximum value is1,000,000.
  • interval_sec: the number of seconds in the time interval. The value must be10, 30, 60, 120, 180, 240, 300, 600, 900, 1200, 1800, 2700, or 3600 seconds.
• exceed_action: when a request exceeds therate_limit_threshold_count,Cloud Armor applies the configuredexceed_action. Possible valuesfor theexceed_action follow:
  • deny(status): the request is denied and the specified status code isreturned. Valid values are403 Forbidden,404 Page Not Found,429 Too Many Requests, and502 Bad Gateway. We recommendusing the429 Too Many Requests status code.
  • redirect: the request is either redirected for reCAPTCHAassessment or to a different URL, based on theexceed_redirect_optionsparameter.
• exceed_redirect_options: when theexceed_action isredirect, use thisparameter to specify the redirect action:
  • type: type for the redirect action, eitherGOOGLE_RECAPTCHA orEXTERNAL_302.
  • target: URL target for the redirect action. Only applicable when thetype isEXTERNAL_302.
• conform_action: the action performed when the number of requests isunder therate_limit_threshold_count. This action is always anallow action.

Banning clients based on request rates

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

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

When a client's request rate is under the rate limit threshold, the request canimmediately proceed to the backend service. When a client's trafficrate exceeds the specifiedrate_limit_threshold_count, Cloud Armorapplies theexceed_action to all incoming requests from the client for therest of the threshold interval and for the nextban_duration_sec seconds,whether or not the threshold is exceeded.

With this configuration, it is possible to accidentally ban welcome clients thatonly occasionally exceed the allowable request rate. To prevent this, and banonly clients that frequently exceed the request rate, you canoptionally track the total client requests against an additional, preferablylonger, threshold configuration called theban_threshold_count. In this mode,the client is banned for the configuredban_duration_sec only if therequest rate crosses the configuredban_threshold_count. If the request ratedoesn't exceed theban_threshold_count, the requests keep getting throttledtorate_limit_threshold_count. For the purpose ofban_threshold_count, the totalrequests from the client, consisting of all incoming requests before throttling,are counted.

These parameters control the action of arate_based_ban rule:

• rate_limit_threshold_count: the number of requests per client allowed withina specified time interval. The minimum value is 1 request and the maximumvalue is 10,000 requests.
  • interval_sec: the number of seconds in the time interval. The value mustbe 10, 30, 60, 120, 180, 240, 300, 600, 900, 1200, 1800, 2700, or 3600seconds.
• exceed_action: when a request exceeds therate_limit_threshold_count,Cloud Armor applies the configuredexceed_action. Possible valuesfor theexceed_action are as follows:
  • deny(status): the request is denied and the specified status code isreturned. Valid values are403 Forbidden,404 Page Not Found,429 Too Many Requests, and502 Bad Gateway. We recommend using thestatus code429 Too Many Requests.
  • redirect: the request is either redirected for reCAPTCHAassessment or to a different URL, based on theexceed_redirect_optionsparameter.
• exceed_redirect_options: when theexceed_action isredirect, use thisparameter to specify the redirect action:
  • type: the type for the redirect action, eitherGOOGLE_RECAPTCHA orEXTERNAL_302.
  • target: the URL target for the redirect action. This URL target is onlyapplicable when thetype isEXTERNAL_302.
• conform_action: the action performed when the number of requests isunder therate_limit_threshold_count. This action is always anallowaction.
• ban_threshold_count: the number of requests per client allowedwithin a specified time interval, over which Cloud Armor bansrequests. If specified, the key is banned for the configuredban_duration_sec when the number of requests that exceed therate_limit_threshold_count also exceed thisban_threshold_count.
  • ban_threshold_interval_sec: the number of seconds in the time interval foryourban_threshold_count. Theban_threshold_interval_sec value must be10, 30, 60, 120, 180, 240, 300, 600, 900, 1200, 1800, 2700, or 3600 seconds.
• ban_duration_sec: the additional number of seconds for which aclient is banned after theinterval_sec period elapses. Theban_duration_sec value must be 60, 120, 180, 240, 300, 600, 900, 1200,1800, 2700, or 3600 seconds.

Default rate limiting security policy

When you configure adefault security policy duringload balancer creation, the default threshold is 500 requests during eachone-minute interval (arate_limit_threshold_count andinterval_sec of500and60, respectively). If you want to select a different threshold, werecommend that you use the following steps to tune your parameters:

1. EnableCloud Logging and query the maximumnumber of requests that arrived per IP address and per minute over a day orlonger at your Cloud Armor-protected backend service.

   For example, suppose that you believe that 99% of the network traffic thatyou receive isn't impacted by the rate limit rule. In this scenario,we recommend that you set your rate limit threshold to the 99th percentile ofthe maximum number of requests per IP address and per minute of thedistribution 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 severalminutes, instead of per 60 seconds).
   3. You can ban clients to reduce attack impact further after the initialwave. The Cloud Armorrate_based_ban action lets you ban allclients that exceed the limits too many times within auser-specified window. For example, clients that exceed thelimits 10 times within a minute can be banned for 15 minutes.

Threshold enforcement

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

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

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

Rate limiting based on REGION_CODE considers the region where the requestoriginates from and doesn't consider the region of the backends in thebackend service, regardless of their type. Backends include instance groups,any type of network endpoint group (NEG) supported by the load balancers, andCloud Storage buckets. Supported backends can be found inSecurity policy overview.

Logging

Cloud Logging records the security policy name, matched rate limit rulepriority, rule ID, the associated action, and other information in your requestlogs. For more information about logging, seeUse request logging.

Integration with reCAPTCHA

You can apply rate limiting to some reCAPTCHA resources in order tomitigate token abuse and limit token reuse. These resources includeaction tokens, session tokens, and exemption cookies. For more information aboutusing rate limiting with reCAPTCHA, see thebot management overview.

Custom error responses

You can apply custom error responses to Cloud Armor rate limiting,includingthrottle andrate_based_ban traffic. When these limits areenforced, custom error messages are sent to end users. In addition, when youuse a global external Application Load Balancer, you can configure custom error responses forspecific HTTP status codes generated by load balancers or backend instances.

For more information about custom error responses, see theCustom error response overview.To configure custom error responses, seeConfigure custom error responses.

Cloud Armor with Cloud Service Mesh

Note: Thefairshare rate limiting action is only available for rules ininternal service security policies.

You can configure internal service security policies for your service mesh toenforce global server-side rate limiting per client, helping you fairly shareyour service's available capacity and mitigating the risk of malicious ormisbehaving clients overloading your services. You attach a security policy to aCloud Service Mesh endpoint policy to enforce rate limiting on inboundtraffic on the server-side. However, you can't configure a Google Cloud Armorsecurity policy if you are using TCP traffic routing. For more information aboutusing Cloud Armor with Cloud Service Mesh, seeConfigure rate limiting with Cloud Armor.

What's next

• Configure rate limiting