feat: As a user, I want official documentation and CI coverage for using Valkey with the redis-backed plugins, so that I can rely on it with confidence
- Dominant language
- Lua
- Stars
- 17.1k
- Forks
- 2.9k
- Avg merge
- 3d 16h
- Merged PRs (30d)
- 63
Description
### Description
Hi! I'd like to propose adding official documentation (and CI coverage) for using [Valkey](https://valkey.io/) as the backend for APISIX's redis-backed plugins.
**Context**
Valkey is a Linux Foundation, BSD-licensed fork of Redis that is protocol (RESP) compatible. Since the plugins that support `policy: redis` / `redis-cluster` (`limit-count`, `limit-req`, `limit-conn`, `ai-rate-limiting`, `ai-cache` **exact-match cache only**, `openid-connect` session storage) speak the Redis protocol, they already work against Valkey unmodified. Users are in fact already running this in production — for example #13584 and #12282 both describe deployments using Valkey / AWS ElastiCache for Valkey with the limit plugins.
> **Scope note on `ai-cache`:** `ai-cache` has two cache layers. Only the **exact-match (L1)** layer — the default (`layers: ["exact"]`) — works against Valkey unmodified and is in scope here. The **semantic (L2)** layer is a vector store built on the **RediSearch module** (`FT.CREATE` / `FT.SEARCH` over an HNSW index), which stock Valkey does not ship, so it is **out of scope** for this issue. (Valkey can back L2 via the `valkey-search` module, but that requires small driver changes and belongs in a separate issue.)
However, the repository currently has no mention of Valkey in docs, tests, or CI, so users have no official signal that this is a supported and tested combination.
**Proposal**
1. **Docs**: add short notes to the relevant plugin docs (or a single shared page) stating Valkey compatibility, with a connection example. This helps users on Valkey-based infrastructure (increasingly common since the Redis license change, e.g. ElastiCache for Valkey) adopt APISIX with confidence.
2. **CI**: since the redis-backed plugins are already tested in CI (the `apisix_redis` service in `ci/pod/docker-compose.common.yml` and tests such as `t/plugin/limit-count-redis*.t`), add a `valkey/valkey` service and run a small set of the existing redis plugin tests against it. This turns "should work because RESP-compatible" into "verified in CI" at low cost. I'm happy to keep this minimal — e.g. a single test file against the Valkey service — if CI time is a concern.
**Why it's worth it**
- Zero changes to plugin code — this is documentation + test infrastructure only.
- Serves existing users who already run this combination but currently have no official guidance.
- Other gateways (e.g. Kong) already document and test Valkey as a supported data store, so this keeps APISIX's compatibility story on par.
Contributor guide
Research direction
Start with ci/pod/docker-compose.common.yml and the existing tests such as t/plugin/limit-count-redis*.t to understand the current Redis service and test flow. Review the relevant redis-backed plugin documentation, then add Valkey guidance and a connection example and run a small existing test set against a valkey/valkey service. Done means the in-scope Valkey compatibility is documented and covered in CI, with ai-cache limited to exact-match caching.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- docker, redis
- Domain
- ci-cd, documentation, testing
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 56/100