Install the Upstash Rate Limiting integration
Install Upstash Rate Limiting from Azion Marketplace and run it on a firewall to limit requests per window and penalize clients that exceed the limit.
You install the Upstash Rate Limiting integration from Azion Marketplace and run it on a Firewall, from Azion Console. The integration limits incoming traffic to avoid bottlenecks, manage traffic spikes, and protect your applications from threats such as DDoS, fuzzing, or brute force attacks. It uses the upstash/ratelimit library and counts the rate limit globally: it sums the requests received across all of Azion’s distributed infrastructure, instead of counting them separately at each location.
Five objects have to exist before a request is counted: the installed function, a firewall carrying the Functions module, a function instance holding the arguments, a Rules Engine rule with the Run Function behavior, and a workload deployment bound to the firewall. Each section below creates one of them.
Prerequisites
- An Azion account. To sign in, refer to How to access Azion Console.
- An application served by a workload, whose deployment you bind to the firewall in the last section.
- An Upstash account.
- A Global Database, created in the Upstash Console. Its URL and its token are arguments of the function instance.
- The Azion CLI installed and authorized, for the last section.
- Turning on a product or a module can generate usage costs. For more information, refer to Pricing.
Install the integration
The function is installed once per account. To install it:
Access Azion Console > Marketplace.
Enter Upstash Rate Limiting in the Search on Marketplace field, then select the integration’s card. Browsing the cards and the categories reaches the same page.
The card shows Successfully installed! and Latest version installed!, and the function appears in the Function list of the Create Instance drawer.
Create the firewall
The firewall is where the function is instanced and where the rule that runs it lives. To create one:
Access Azion Console > Firewalls, then create a firewall.
In the General section, enter a Name. For example: rate-limiting-firewall.
In the Modules section, turn on the Functions switch.
The firewall shows a Functions Instances tab while the Functions module stays on. To use an existing firewall instead, turn on its Functions module and save it. For every setting on this form, refer to Set a firewall’s main settings.
Create the function instance
The instance holds your Upstash credentials and the rate limit windows. To create it:
In Firewalls, select your firewall, then select the Functions Instances tab.
A firewall that has no instance shows the same action as Function Instance. The Create Instance drawer opens.
In Name, enter a name. For example: upstash-rate-limiting.
In Function, select the Upstash Rate Limiting function. The list holds only the functions that run on a firewall.
In Arguments, the editor is prefilled with the integration’s default arguments in JSON. Enter your Upstash credentials and your variables, as the next section describes.
The instance is listed in the Functions Instances tab.
Arguments
The instance takes your Upstash credentials and your variables:
| Variable | Description |
|---|---|
upstash_redis_rest_url | The URL of your Upstash database, which stores the rate limit and penalty data |
upstash_redis_rest_token | Your Upstash API access token |
rate_limit_prefix | The prefix of every rate limit key. Use it to avoid overlaps between different instances of the function |
rate_limit_key_metadata | The metadata variables that generate the rate limit key on Azion’s platform |
rate_limit_key_header | The headers that generate the rate limit key on Azion’s platform |
rate_limit_key_hostname | If true, the URL generates the rate limit key |
rate_limit_repenalize | If true, the penalty time is calculated again every time a penalized user makes a request |
rate_limits | The rate limit windows, as objects. You must add at least one object |
algorithm | The rate limit algorithm to apply. Possible values: fixed_window, sliding_window, token_bucket |
requests | The maximum number of requests until the rate limit is reached |
interval | The time interval of the rate limit window. It follows the Upstash standard XXXX y, where X is the number and y is the unit: s for seconds or m for minutes. Example: 120 s |
start and end | The time window, in the 24-hour format and the UTC time zone |
penalty_in_seconds | The penalty time, a block that returns the 403 status code, applied to users who violate the rate limit |
Rate limit windows and algorithms
You can define different rate limit windows for different periods of the day. For example: a limit of 10 requests/minute from 00:00 to 12:00, and 15 requests/minute from 12:01 to 23:59.
- If
startis not defined, its default value is00:00. Ifendis not defined, its default value is23:59. - If two rate limits overlap, the first one in the JSON arguments applies.
- If
penalty_in_secondsis empty, the rate limit applies no penalty and works as a simple rate limit.
The algorithm variable takes three values:
fixed_windowdivides time into fixed durations, or windows.sliding_windowbuilds on the fixed window but uses a rolling window. For example: for a rate limit of 10 requests per minute, time is divided into 1-minute slices, as in the fixed window algorithm.token_bucketdefines the maximum number of tokens that fill a bucket and the interval at which the bucket is cleaned. Every request removes one token. If no token is left, the request is rejected.
The token_bucket algorithm takes two more variables:
max_tokens: the number of tokens, or keys, that the rate limit allows.refil_rate: the number of buckets cleaned at each time interval.
In this example, 5 buckets are cleaned every 10 seconds, out of a maximum of 5 "busy" buckets.
Create the rule
The instance counts nothing until a rule runs it. A Rules Engine for Firewall rule selects the requests that reach the instance, through a Run Function behavior. To create the rule:
In Firewalls, select your firewall, then select the Rules Engine tab.
In Name, enter a name. For example: Run Upstash Rate Limiting.
In the Criteria section, select the domains that run the integration. For example: if Host matches yourdomain.com.
In the Behaviors section, select Run Function, then select the instance by the name you gave it.
The firewall runs the instance on every request to the domain in the criterion.
Bind the firewall to the workload
The binding is on the workload’s deployment, so create a deployment that names both the application and the firewall:
The command prints the id of the new deployment:
Requests to the workload’s domain reach the firewall, and the rule runs the Upstash Rate Limiting instance on each one.
How it works
The integration applies a penalty configuration that checks the validity of each request:
- If the request is not valid, the function blocks it and returns the
403 Forbiddenstatus code. - If the request is valid, the function counts it. When the count reaches the rate limit, the function stops the request and returns the
429 Too Many Requestsstatus code.
Watch a tutorial on rate limiting with a penalty on Azion and Upstash DB on Azion’s YouTube channel.