Redis with Envoy

Use Redis for global rate limiting in Envoy through the rate limit service.

Envoy is a proxy that is often used as an API gateway and service proxy. Envoy itself doesn't store rate limit counters in Redis. Instead, it calls a rate limit service over gRPC, and the reference implementation, envoyproxy/ratelimit, keeps its counters in Redis. See the rate limiter use case for when to choose this pattern.

Requirements

The examples on this page were run with Envoy 1.34 and the envoyproxy/ratelimit image against Redis 8.0, with two Envoy instances sharing one rate limit service and one Redis server.

You also need a running Redis server. You can run one locally with Redis Open Source, use Docker, or connect to Redis Cloud.

Configure the rate limit service

The service reads its rules from YAML files. This file allows 3 requests a minute for the descriptor generic_key: api in the demo domain:

# <runtime-root>/ratelimit/config/config.yaml
domain: demo
descriptors:
  - key: generic_key
    value: api
    rate_limit:
      unit: minute
      requests_per_unit: 3

Start the service with environment variables that point at Redis and at the configuration directory:

USE_STATSD=false \
REDIS_SOCKET_TYPE=tcp \
REDIS_URL=<your-redis-host>:6379 \
RUNTIME_ROOT=<runtime-root> \
RUNTIME_SUBDIRECTORY=ratelimit \
ratelimit

The service reads configuration files from RUNTIME_ROOT/RUNTIME_SUBDIRECTORY/config/. The service's README lists the other Redis settings, including REDIS_AUTH, REDIS_TLS, and Sentinel and Cluster modes.

Configure Envoy

In the Envoy configuration, a route action produces the descriptor, the ratelimit HTTP filter calls the service for it, and a cluster with HTTP/2 enabled points at the service:

# In the route
rate_limits:
- actions:
  - generic_key: { descriptor_value: api }

# In http_filters, before the router filter
- name: envoy.filters.http.ratelimit
  typed_config:
    "@type": type.googleapis.com/envoy.extensions.filters.http.ratelimit.v3.RateLimit
    domain: demo
    failure_mode_deny: false
    rate_limit_service:
      transport_api_version: V3
      grpc_service:
        envoy_grpc: { cluster_name: ratelimit }

# In clusters
- name: ratelimit
  type: STRICT_DNS
  typed_extension_protocol_options:
    envoy.extensions.upstreams.http.v3.HttpProtocolOptions:
      "@type": type.googleapis.com/envoy.extensions.upstreams.http.v3.HttpProtocolOptions
      explicit_http_config:
        http2_protocol_options: {}
  load_assignment:
    cluster_name: ratelimit
    endpoints:
    - lb_endpoints:
      - endpoint: { address: { socket_address: { address: <ratelimit-host>, port_value: 8081 } } }

In a test with two Envoy instances, five requests that alternated between them returned 200, 200, 200, 429, and 429.

What the rate limit service stores in Redis

The service keeps one counter for each descriptor and time window, as a string:

<domain>_<key>_<value>_<window-start-seconds>

In the test the key was demo_generic_key_api_<window-start>. It held 5 after the five requests, and its TTL was 91 seconds for a 60-second window, so the TTL is longer than the window.

When Redis or the service is unavailable

With failure_mode_deny: false, Envoy lets requests through when the rate limit check fails. In the test, every request returned 200 with no added latency when the rate limit service was stopped, and again when the service was running but Redis was stopped. Set failure_mode_deny: true if you want Envoy to reject requests when it can't check the limit. The examples on this page don't cover that setting.

Envoy as a Redis proxy

Envoy also has a Redis proxy filter, which lets Envoy act as a proxy for the Redis protocol and partition commands among the instances of a Redis cluster. See the Envoy documentation. The examples on this page don't cover it, and it isn't part of rate limiting.

More information

RATE THIS PAGE
Back to top ↑