# How to Install Upstash Rate Limiting **Upstash Rate Limiting** allows you to control incoming traffic right at the edge of the network, avoiding bottlenecks, managing traffic spikes, and protecting your applications from potential threats such as DDoS, fuzzing, or brute force attacks. With this integration, based on an function, you can define: - **Limiting requests** and **window limit**, including specific rate limit windows for different periods of the day. - A **penalty** configuration that analyzes the validity of each request. - If the request isn't valid, it blocks the request and returns the user a `403 Forbidden` status code. - If the request is valid, it counts the request and, in case it reaches the defined rate limit, it interrupts the request and returns a `429 Too Many Requests` status code. Upstash Rate Limiting is integrated with the `upstash/ratelimit` library and provides a global accounting of the rate limit, summing up all the requests received across the entire network, instead of counting separately for each edge location. --- ## Requirements To start using this integration, you need to: - Create an [Upstash account](https://console.upstash.com/). - Create a Global Database for the best available edge latency in the [Upstash Console](https://console.upstash.com/). --- ## Getting the integration To install this integration: 1. Access [Azion Console](/en/documentation/products/guides/how-to-access-azion-console/) > **Marketplace**. 2. On the Marketplace homepage, select the integration's card. 3. On the integration page, click the **Install** button. You'll see a message indicating that your integration was successfully installed. Then, you'll need to complete the steps explained below to instantiate the function and configure a firewall. --- ## Configuring the integration ### Setting up a firewall To instantiate the **Upstash Rate Limiting** integration, follow the steps: 1. Open the **Products menu** and select **Firewall** in the **Secure** section. 2. Click the **+ Firewall** button. 3. Give an easy-to-remember name to your firewall. 4. Enable the **Functions** switch in the **Modules** section. - This action gives access to functions on your firewall. 5. Click the **Save** button. Done. Now you've instantiated the firewall for your function. ### Setting up the Firewall function While still on the **Firewall** page: 1. Select the **Functions Instances** tab. 2. Click the **+ Function Instance** button. 3. Give an easy-to-remember name to your instance. 4. On the dropdown menu, select the **Upstash Rate Limiting** function. - This action will load the **Arguments** tab. 5. In the **Arguments** tab, you'll pass your Upstash credentials and your variables: ```bash { "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 } ] } ``` Where: | Variable | Description | | ---- | ---- | | `upstash_redis_rest_url` | The URL of your Upstash database that will store the rate limit and penalty data | | `upstash_redis_rest_token` | Your Upstash API access token | | `rate_limit_prefix` | It defines a prefix to be used in all the rate limit keys. This variable is crucial to avoid overlaps between different instances of the function | | `rate_limit_key_metadata` | It defines which metadata variables will be used to generate the rate limit key in Azion's platform | | `rate_limit_key_header` | It defines which headers will be used to generate the rate limit key in Azion's platform | | `rate_limit_key_hostname` | If `true`, the URL will be used to generate the Rate Limit "key" | | `rate_limit_repenalize` | If `true`, the penalty time is recalculated every time a penalized user makes a request | | `rate_limits` | It defines the rate limit windows as an object. You must **add at least one** object | | `algorithm` | It defines the rate limit algorithm to be applied. Possible values: `fixed_window`, `sliding_window`, `token_bucket`. [Read more](#important) | | `requests` | Maximum number of requests until reaching the rate limit | | `interval` | Rate limit window time interval. This variable follows the Upstash standard: `XXXX y`, where the X are the numeral and y is the unit of measurement, which can be `s` for seconds or `m` for minutes. Example: `120 s` | | `start` and `end`| These variables define the time window. It uses the 24-hour format and the UTC time zone. [Read more](#important) | | `penalty_in_seconds` | Penalty time (blocking that returns `403` status code) that users will be subjected to after violating the rate limit [Read more](#important) | :::note The key to a rate limit is made up of the combination of all these variables. In this code sample, the final key would be: `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`. ::: 6. Click the **Save** button. #### Important - This integration allows you to define different rate limit windows for different periods of the day, according to your needs. Example: you can define a limit of `10 requests/minute` from `00:00` to `12:00`, and `15 requests/minute` from `12:01` to `23:59`. - This integration supports three possible values for `algorithm`: - `fixed_window` divides time into fixed durations/windows. - `sliding_window` builds on top of fixed window but uses a rolling window. Example: you want to define a rate limit of 10 requests per 1 minute, then, you divide the time into 1 minute slices, as in the `fixed window` algorithm. - `token_bucket` defines the maximum number of tokens to fill a bucket and the interval which the bucket will be cleaned. Every request removes one token and if there's no token to take, the request is rejected. - The `token_bucket` includes different values, where: - `max_tokens` defines the number of tokens (or keys) that this rate limit will allow. - `refil_rate` defines the number of buckets that will be "cleaned" at each time interval. ```bash "algorithm": "token_bucket", "refil_rate": 5, "max_tokens": 5, "interval": "10 s", "start": "23:01", "penalty_in_seconds": 55 ``` In this example, every `10 seconds`, `5 buckets` are cleaned, out of a maximum of `5 "busy" buckets`. - If `start` isn't defined, the default value will be `00:00`. If `end` isn't defined, the default value of `23:59`" will be assumed. In case of overlaps between rate limits, the rate limit that is first in the JSON Args will be considered. - When the `penalty_in_seconds` variable isn't filled in, the rate limit won't apply a penalty, behaving like a *simple* rate limit. ### Setting up the Rules Engine To finish, you have to set up a rule in **Rules Engine** to configure the **criteria** and the **behavior** to run the function. Still in the **Firewall** page: 1. Select the **Rules Engine** tab. 2. Click the **+ Rule Engine** button. 3. Give a name to the rule. 4. Select a *criteria* to run and catch the domains that you want to run the integration on. - Example: if `Host` *matches* `yourdomain.com`. 5. Below, select a *behavior* to the *criteria*. In this case, it'll be **Run Function**. - Select the adequate function according to the name you gave it during the instantiation step. 6. Click the **Save** button. On the Console, you must now configure your domain so your firewall protects it. 7. On the **Products menu**, select **Workloads**. 8. Click on the domain you want to protect with your Upstash Rate Limiting function. 9. In the **Settings** section, click on the `Firewall` selector and choose the firewall you created. 10. Click the **Save** button. Done. Now **Upstash Rate Limiting** is running and protecting your domains. Discover how to enhance your web application's performance with this tutorial on **Rate Limit with Penalty on Azion + Upstash DB**. Watch now on Azion's YouTube channel.