{
  "schema_version": 2,
  "id": "integrate/envoy",
  "title": "Redis with Envoy",
  "url": "https://redis.io/docs/latest/integrate/envoy/",
  "summary": "Use Redis for global rate limiting in Envoy through the rate limit service.",
  "tags": [
    "docs",
    "integrate",
    "oss",
    "rs",
    "rc"
  ],
  "last_updated": "2026-11-17T16:52:03Z",
  "children": [],
  "page_type": "content",
  "content_hash": "2c4dafdea086eab698721a8da3e68050c6cb0bf9cbfe7541d6376128de884486",
  "sections": [
    {
      "id": "overview",
      "title": "Overview",
      "role": "overview",
      "text": "[Envoy](https://www.envoyproxy.io/) is a proxy that is often used as an API gateway and service\nproxy. Envoy itself doesn't store rate limit counters in Redis. Instead, it calls a *rate limit\nservice* over gRPC, and the reference implementation,\n[`envoyproxy/ratelimit`](https://github.com/envoyproxy/ratelimit), keeps its counters in Redis.\nSee the [rate limiter use case](https://redis.io/docs/latest/develop/use-cases/rate-limiter) for when to choose\nthis pattern."
    },
    {
      "id": "requirements",
      "title": "Requirements",
      "role": "content",
      "text": "The examples on this page were run with Envoy 1.34 and the `envoyproxy/ratelimit` image against\nRedis 8.0, with two Envoy instances sharing one rate limit service and one Redis server.\n\nYou also need a running Redis server. You can run one locally with\n[Redis Open Source](https://redis.io/docs/latest/operate/oss_and_stack/install/archive/install-redis),\nuse [Docker](https://hub.docker.com/_/redis), or connect to\n[Redis Cloud](https://redis.io/cloud/)."
    },
    {
      "id": "configure-the-rate-limit-service",
      "title": "Configure the rate limit service",
      "role": "configuration",
      "text": "The service reads its rules from YAML files. This file allows 3 requests a minute for the\ndescriptor `generic_key: api` in the `demo` domain:\n\n[code example]\n\nStart the service with environment variables that point at Redis and at the configuration\ndirectory:\n\n[code example]\n\nThe service reads configuration files from\n`RUNTIME_ROOT/RUNTIME_SUBDIRECTORY/config/`. The service's\n[README](https://github.com/envoyproxy/ratelimit) lists the other Redis settings, including\n`REDIS_AUTH`, `REDIS_TLS`, and Sentinel and Cluster modes."
    },
    {
      "id": "configure-envoy",
      "title": "Configure Envoy",
      "role": "configuration",
      "text": "In the Envoy configuration, a route action produces the descriptor, the `ratelimit` HTTP filter\ncalls the service for it, and a cluster with HTTP/2 enabled points at the service:\n\n[code example]\n\nIn a test with two Envoy instances, five requests that alternated between them returned `200`,\n`200`, `200`, `429`, and `429`."
    },
    {
      "id": "what-the-rate-limit-service-stores-in-redis",
      "title": "What the rate limit service stores in Redis",
      "role": "content",
      "text": "The service keeps one counter for each descriptor and time window, as a string:\n\n[code example]\n\nIn the test the key was `demo_generic_key_api_<window-start>`. It held `5` after the five\nrequests, and its TTL was 91 seconds for a 60-second window, so the TTL is longer than the\nwindow."
    },
    {
      "id": "when-redis-or-the-service-is-unavailable",
      "title": "When Redis or the service is unavailable",
      "role": "content",
      "text": "With `failure_mode_deny: false`, Envoy lets requests through when the rate limit check fails. In\nthe test, every request returned `200` with no added latency when the rate limit service was\nstopped, and again when the service was running but Redis was stopped. Set `failure_mode_deny:\ntrue` if you want Envoy to reject requests when it can't check the limit. The examples on this page don't cover that setting."
    },
    {
      "id": "envoy-as-a-redis-proxy",
      "title": "Envoy as a Redis proxy",
      "role": "content",
      "text": "Envoy also has a Redis proxy filter, which lets Envoy act as a proxy for the Redis protocol and\npartition commands among the instances of a Redis cluster. See the\n[Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/other_protocols/redis).\nThe examples on this page don't cover it, and it isn't part of rate limiting."
    },
    {
      "id": "more-information",
      "title": "More information",
      "role": "content",
      "text": "- [Global rate limiting in Envoy](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/other_features/global_rate_limiting)\n- [envoyproxy/ratelimit](https://github.com/envoyproxy/ratelimit)"
    }
  ],
  "examples": [
    {
      "id": "configure-the-rate-limit-service-ex0",
      "language": "yaml",
      "code": "# <runtime-root>/ratelimit/config/config.yaml\ndomain: demo\ndescriptors:\n  - key: generic_key\n    value: api\n    rate_limit:\n      unit: minute\n      requests_per_unit: 3",
      "section_id": "configure-the-rate-limit-service"
    },
    {
      "id": "configure-the-rate-limit-service-ex1",
      "language": "bash",
      "code": "USE_STATSD=false \\\nREDIS_SOCKET_TYPE=tcp \\\nREDIS_URL=<your-redis-host>:6379 \\\nRUNTIME_ROOT=<runtime-root> \\\nRUNTIME_SUBDIRECTORY=ratelimit \\\nratelimit",
      "section_id": "configure-the-rate-limit-service"
    },
    {
      "id": "configure-envoy-ex0",
      "language": "yaml",
      "code": "# In the route\nrate_limits:\n- actions:\n  - generic_key: { descriptor_value: api }\n\n# In http_filters, before the router filter\n- name: envoy.filters.http.ratelimit\n  typed_config:\n    \"@type\": type.googleapis.com/envoy.extensions.filters.http.ratelimit.v3.RateLimit\n    domain: demo\n    failure_mode_deny: false\n    rate_limit_service:\n      transport_api_version: V3\n      grpc_service:\n        envoy_grpc: { cluster_name: ratelimit }\n\n# In clusters\n- name: ratelimit\n  type: STRICT_DNS\n  typed_extension_protocol_options:\n    envoy.extensions.upstreams.http.v3.HttpProtocolOptions:\n      \"@type\": type.googleapis.com/envoy.extensions.upstreams.http.v3.HttpProtocolOptions\n      explicit_http_config:\n        http2_protocol_options: {}\n  load_assignment:\n    cluster_name: ratelimit\n    endpoints:\n    - lb_endpoints:\n      - endpoint: { address: { socket_address: { address: <ratelimit-host>, port_value: 8081 } } }",
      "section_id": "configure-envoy"
    },
    {
      "id": "what-the-rate-limit-service-stores-in-redis-ex0",
      "language": "plaintext",
      "code": "<domain>_<key>_<value>_<window-start-seconds>",
      "section_id": "what-the-rate-limit-service-stores-in-redis"
    }
  ]
}
