Skip to content

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 #13738

Description

@daric93

Description

Hi! I'd like to propose adding official documentation (and CI coverage) for using Valkey 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    CIdocDocumentation things

    Type

    No type

    Projects

    Status
    📋 Backlog

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions