--- name: azion-install-the-upstash-rate-limiting-integration description: >- 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. --- # Install the Upstash Rate Limiting integration You install the Upstash Rate Limiting integration from Azion Marketplace and run it on a [Firewall](/en/documentation/platform/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](/en/documentation/guides/platform/account-and-billing/how-to-access-azion-console/). - An application served by a [workload](/en/documentation/platform/workloads/), whose deployment you bind to the firewall in the last section. - An [Upstash account](https://console.upstash.com/). - A Global Database, created in the [Upstash Console](https://console.upstash.com/). Its URL and its token are arguments of the function instance. - The [Azion CLI](/en/documentation/devtools/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](/en/documentation/fundamentals/pricing/). --- ## Install the integration The function is installed once per account. To install it: 1. **Open Marketplace** Access [Azion Console](https://console.azion.com/) > **Marketplace**. 2. **Find the integration** 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. 3. **Select Install** 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: 1. **Open the Firewalls page** Access [Azion Console](https://console.azion.com/) > **Firewalls**, then create a firewall. 2. **Name the firewall** In the **General** section, enter a **Name**. For example: `rate-limiting-firewall`. 3. **Turn on the Functions module** In the **Modules** section, turn on the **Functions** switch. 4. **Save the firewall** 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](/en/documentation/guides/application-security/firewall-and-waf/firewall-configure-main-settings/). --- ## Create the function instance The instance holds your Upstash credentials and the rate limit windows. To create it: 1. **Open the Functions Instances tab** In **Firewalls**, select your firewall, then select the **Functions Instances** tab. 2. **Select + Function** A firewall that has no instance shows the same action as **Function Instance**. The **Create Instance** drawer opens. 3. **Name the instance** In **Name**, enter a name. For example: `upstash-rate-limiting`. 4. **Select the installed function** In **Function**, select the Upstash Rate Limiting function. The list holds only the functions that run on a firewall. 5. **Enter the arguments** 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. 6. **Select Save** The instance is listed in the **Functions Instances** tab. ### Arguments The instance takes your Upstash credentials and your variables: ```json { "upstash_redis_rest_url": "https://your-database.upstash.io", "upstash_redis_rest_token": "Your upstash token", "rate_limit_prefix": "my_rate_limit", "rate_limit_key_metadata": [ "remote_addr" ], "rate_limit_key_header": [ "x-a-custom-header" ], "rate_limit_key_hostname": true, "rate_limit_repenalize": true, "rate_limits": [ { "algorithm": "sliding_window", "requests": 2, "interval": "20 s", "start": "00:00", "end": "12:00", "penalty_in_seconds": 45 }, { "algorithm": "fixed_window", "requests": 3, "interval": "120 s", "start": "12:01", "end": "23:00", }, { "algorithm": "token_bucket", "refil_rate": 5, "max_tokens": 5, "interval": "10 s", "start": "23:01", "penalty_in_seconds": 55 } ] } ``` | 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 | > **Note** > > The key of a rate limit is the combination of all these variables. In this code sample, the final key is: > `my_rate_limit + User IP + X-a-custom-reader Value + Hostname used in the request`. > > Example: > `my_rate_limit_127.0.0.1_Value_azion.com`. #### 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 `start` is not defined, its default value is `00:00`. If `end` is not defined, its default value is `23:59`. - If two rate limits overlap, the first one in the JSON arguments applies. - If `penalty_in_seconds` is empty, the rate limit applies no penalty and works as a simple rate limit. The `algorithm` variable takes three values: - `fixed_window` divides time into fixed durations, or windows. - `sliding_window` builds 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_bucket` defines 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. ```json "algorithm": "token_bucket", "refil_rate": 5, "max_tokens": 5, "interval": "10 s", "start": "23:01", "penalty_in_seconds": 55 ``` 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](/en/documentation/platform/firewall/rules-engine/) rule selects the requests that reach the instance, through a **Run Function** behavior. To create the rule: 1. **Open the Rules Engine tab** In **Firewalls**, select your firewall, then select the **Rules Engine** tab. 2. **Select + Rule** 3. **Name the rule** In **Name**, enter a name. For example: `Run Upstash Rate Limiting`. 4. **Set the criterion** In the **Criteria** section, select the domains that run the integration. For example: if `Host` *matches* `yourdomain.com`. 5. **Add the Run Function behavior** In the **Behaviors** section, select **Run Function**, then select the instance by the name you gave it. 6. **Select Save** 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: ```bash azion create workload-deployment --workload-id --name \ --application-id --firewall-id --strategy-type default \ --active true --current true ``` The command prints the id of the new deployment: ```text Created Workload Deployment with ID 123456 ``` 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 Forbidden` status 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 Requests` status code. Watch a tutorial on rate limiting with a penalty on Azion and Upstash DB on Azion's YouTube channel. [How to Install Upstash Rate Limiting](https://www.youtube.com/watch?v=3qsiKK2GzRw) This integration allows you to control incoming traffic before it reaches your origin and protect your applications. --- ## Next steps - [Marketplace integrations](/en/documentation/platform/marketplace/integrations.md): Every integration Azion Marketplace offers, and where each one runs. - [Rules Engine for Firewall](/en/documentation/platform/firewall/rules-engine.md): Every criterion and behavior a firewall rule accepts. - [Update an integration](/en/documentation/guides/application-development/integrations/update-an-integration.md): Move an installed integration to its latest version.