{
  "schema_version": 2,
  "id": "integrate/apisix",
  "title": "Redis with Apache APISIX",
  "url": "https://redis.io/docs/latest/integrate/apisix/",
  "summary": "Share rate limits across Apache APISIX nodes with Redis.",
  "tags": [
    "docs",
    "integrate",
    "oss",
    "rs",
    "rc"
  ],
  "last_updated": "2026-11-17T16:52:03Z",
  "children": [],
  "page_type": "content",
  "content_hash": "df3d465b54f412b5cf287827c446a3ef3d93349ebd6c57bfd9730600fafc7608",
  "sections": [
    {
      "id": "overview",
      "title": "Overview",
      "role": "overview",
      "text": "[Apache APISIX](https://apisix.apache.org/) is an API gateway. Its `limit-count` plugin can keep\nits counters in Redis, so that several APISIX nodes enforce one shared limit. See 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 Apache APISIX 3.13 in standalone mode against Redis 8.0,\nwith two APISIX nodes sharing 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": "limit-requests-with-a-redis-policy",
      "title": "Limit requests with a Redis policy",
      "role": "limits",
      "text": "The `policy` setting of `limit-count` selects where APISIX keeps the counters. `local` is the\ndefault, which gives each node its own limit. The other documented values are `redis`,\n`redis-cluster`, and `redis-sentinel`. This route allows 3 requests a minute for each client address\nand keeps the counters in Redis. In standalone mode, which reads its routes from a file, set\n`config_provider: yaml` in `config.yaml`:\n\n[code example]\n\nThen put the route in `apisix.yaml`:\n\n[code example]\n\nIn a test with two APISIX nodes behind the same Redis server, five requests that alternated\nbetween the nodes returned `200`, `200`, `200`, `429`, and `429`. Each response carried\n`X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers."
    },
    {
      "id": "redis-connection-options",
      "title": "Redis connection options",
      "role": "content",
      "text": "The plugin's Redis settings are `redis_host`, `redis_port` (default `6379`), `redis_username`,\n`redis_password`, `redis_database` (default `0`), `redis_timeout` (default `1000` milliseconds),\nand the TLS settings `redis_ssl`, `redis_ssl_verify`, and `redis_server_name`. The cluster policy\nuses `redis_cluster_nodes` and `redis_cluster_name`. See the\n[limit-count documentation](https://apisix.apache.org/docs/apisix/plugins/limit-count/) for the\nfull list. According to that page, Redis Sentinel support needs APISIX 3.18.0 or later, which the examples on this page don't cover."
    },
    {
      "id": "what-apisix-stores-in-redis",
      "title": "What APISIX stores in Redis",
      "role": "content",
      "text": "APISIX keeps one string for each route and client, with a TTL equal to the `time_window`:\n\n[code example]\n\nUnlike Kong and Envoy, APISIX stores the remaining quota, not a count of requests. After five\nrequests against a limit of 3, the value was `-2`."
    },
    {
      "id": "when-redis-is-unavailable",
      "title": "When Redis is unavailable",
      "role": "content",
      "text": "By default, APISIX rejects requests with a `500` error when it can't reach Redis. In the test, with\nthe Redis server stopped, each request returned `500` within about 0.1 seconds. Set\n`allow_degradation: true` on the plugin to fail open instead. With that setting, the same\nrequests returned `200`."
    },
    {
      "id": "other-plugins",
      "title": "Other plugins",
      "role": "content",
      "text": "According to the APISIX documentation, `limit-req` and `limit-conn` also accept a Redis policy\n(`redis` or `redis-cluster`), and the `openid-connect` plugin can store sessions in Redis with\n`session.storage: redis`. The examples on this page don't cover these."
    },
    {
      "id": "more-information",
      "title": "More information",
      "role": "content",
      "text": "- [limit-count plugin](https://apisix.apache.org/docs/apisix/plugins/limit-count/)\n- [openid-connect plugin](https://apisix.apache.org/docs/apisix/plugins/openid-connect/)"
    }
  ],
  "examples": [
    {
      "id": "limit-requests-with-a-redis-policy-ex0",
      "language": "yaml",
      "code": "deployment:\n  role: data_plane\n  role_data_plane:\n    config_provider: yaml",
      "section_id": "limit-requests-with-a-redis-policy"
    },
    {
      "id": "limit-requests-with-a-redis-policy-ex1",
      "language": "yaml",
      "code": "routes:\n  - uri: /api/*\n    plugins:\n      limit-count:\n        count: 3\n        time_window: 60\n        key_type: var\n        key: remote_addr\n        rejected_code: 429\n        policy: redis\n        redis_host: <your-redis-host>\n        redis_port: 6379\n        redis_database: 0\n    upstream:\n      type: roundrobin\n      nodes:\n        \"<your-upstream>\": 1\n#END",
      "section_id": "limit-requests-with-a-redis-policy"
    },
    {
      "id": "what-apisix-stores-in-redis-ex0",
      "language": "plaintext",
      "code": "plugin-limit-count<route-key>:<route-version>:<client-ip>",
      "section_id": "what-apisix-stores-in-redis"
    }
  ]
}
