apache / apache/apisix

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

Open
#13,738 1 comment 0 reactions 0 assignees View on GitHub
CI doc
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.