> ## Documentation Index
> Fetch the complete documentation index at: https://docs.controlplane.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate Limiting

> Configure rate limiting for workloads using the Envoy Rate Limit project with a Redis backend deployed on Control Plane.

Rate limiting can be added to [Workloads](/reference/workload) by configuring an endpoint which serves the Envoy Rate Limit project. This endpoint receives a rate limit request from a configured Workload and decides if the request should be limited.

Follow the steps below to configure your [Workload](/reference/workload) with a
rate limiting policy.

## Prerequisites

* An existing [Workload](/reference/workload) that requires rate limiting.
* Review the Rate Limiting project's [README](https://github.com/envoyproxy/ratelimit).

## Configuration Steps

Envoy's Rate Limit project is deployed as a [Workload](/reference/workload) at Control Plane and requires a local Redis [Workload](/reference/workload).

Follow the steps below to download and apply a YAML manifest file which will deploy, create, and configure:

* The Rate Limit [Workload](/reference/workload).
* The Redis [Workload](/reference/workload).
* An [opaque secret](/reference/secret#opaque) containing the rate limiting definition.
* A [Workload Identity](/reference/identity) for the Rate Limit Workload.
* A [Policy](/reference/policy) allowing the Rate Limit Workload to reveal the secret.

### Step One - Configure the Rate Limiting Workload

* Download and review the [YAML manifest file](https://raw.githubusercontent.com/controlplane-com/examples/main/examples/rate-limiting/rate-limiting.yaml) that will be applied.
* Using the UI or [CLI](/cli-reference/overview):
  * Create a [GVC](/reference/gvc) named `ratelimit`. If you choose a different GVC name, update the YAML manifest file accordingly.
  * Within that GVC, use the [cpln apply](/guides/cpln-apply) command to deploy the manifest file.

<Tip>
  The latest `envoyproxy/ratelimit` deployment can be obtained from the [envoyproxy/ratelimit Docker Hub page](https://hub.docker.com/r/envoyproxy/ratelimit/tags?page=1\&ordering=last_updated).

  The downloaded YAML manifest file uses the image `envoyproxy/ratelimit:5b6e65da`. If there is a newer tag, it can be substituted in the YAML file before executing the `cpln apply` command.
</Tip>

### Step Two - Customize the Config File

The rate limit config file is stored as an [opaque secret](/reference/secret#opaque) named `ratelimit-config` that was created when applying the YAML manifest file.

The configuration that was deployed with the manifest file sets a limit of 10 requests per minute for any request that contains an `authorization` header (see sample config below).

To adjust the rate limit per your requirements, use the UI or CLI to edit the `ratelimit-config` secret using the pattern in the [ratelimit configuration documentation](https://github.com/envoyproxy/ratelimit#configuration).

#### Sample Config

```yaml YAML theme={null}
domain: cpln
descriptors:
  - key: authorization
    rate_limit:
      unit: minute
      requests_per_unit: 10
```

<Note>
  After saving the updated secret, it's recommended to perform a `Force Redeploy` of the `ratelimit` Workload to reload the config file.
</Note>

### Step Three - Configure Rate Limiting on a Workload

Add the following [tags](/core/misc#tags) to enable rate limiting on the desired [Workload](/reference/workload).

* `cpln/rateLimitAddress`
  * **Required**
  * Use the `Global Endpoint` of the Rate Limiting [Workload](/reference/workload) that was configured in [step one](#step-one-configure-the-rate-limiting-workload). This endpoint
    can be obtained by browsing to the `Info` page of the `ratelimit` Workload. Include only the hostname without the `https://` protocol prefix.
* `cpln/rateLimitScheme`
  * Optional.
  * Default is: `https`.
* `cpln/rateLimitPort`
  * Optional.
  * Default is: `443`.
* `cpln/rateLimitDomain`
  * Optional.
  * Default is: `cpln`.
  * This value corresponds to the domain entry within the config file that was configured in [step 2](#step-two-customize-the-config-file).
* `cpln/rateLimitDescriptors`
  * Optional. Default is: `authorization`.
  * Allowed values: `authorization`, `host`, `path`.
  * This value corresponds to the descriptor entry within the config file that was configured in [step 2](#step-two-customize-the-config-file).

After saving these tags and the Workload has deployed successfuly, the rate limits defined within the config file will be enforced. If a client hits the limit, an HTTP 429 (Too Many Requests) response will be returned.