Skip to content
Waypoint

Redis

Waypoint stores all cross-instance coordination state in Redis (or Valkey):

  • Per-user concurrent-connection counts and byte budgets.
  • Distributed locks for role provisioning (so two Waypoint instances don’t race to create the same backend user).
  • Heartbeat records that waypoint-monitor uses to discover instances.
[redis]
address = "localhost:6379"
# password = ""
# db = 0
key_prefix = "waypoint:"
# service_name = "redis"

address

Section titled “address”

host:port. Required.

password / db

Section titled “password / db”

Optional. Use password for AUTH-protected instances; db selects a logical database (default 0).

key_prefix

Section titled “key_prefix”

Every key Waypoint writes is prefixed with this string. ✓ TestNewRedisStore_DefaultPrefix internal/restrict/redis_test.go:22 ✓ TestRedisStore_Key internal/restrict/redis_test.go:33 Pick something distinctive so you can run multiple Waypoint deployments against one Redis instance without collisions ✓ TestRedisStore_ScopedKeysIsolation internal/restrict/redis_test.go:262 , and so you can KEYS waypoint:* for debugging.

service_name

Section titled “service_name”

Sets the peer.service attribute on Redis spans in OpenTelemetry traces. Default is redis. Override if you have multiple Redis backends you want to distinguish in tracing UIs.

Reliability

Section titled “Reliability”

Waypoint treats Redis as a hard dependency for authorization decisions. Per-user connection counts are tracked cross-instance via Redis with atomic acquire/release. ✓ TestIntegration_Tracker_AcquireRelease internal/restrict/tracker_integration_test.go:19 ✓ TestIntegration_Tracker_ConcurrentAcquire internal/restrict/tracker_integration_test.go:55 ✓ TestIntegration_Tracker_AcquireReleaseCycle_CountConsistency internal/restrict/tracker_integration_test.go:164 If Redis is unreachable, new connections fail closed (rejected) — the proxy will not silently drop limit enforcement. Existing connections continue until the next revalidation tick.

For HA, point Waypoint at a Sentinel-fronted or clustered Redis. The client (github.com/redis/go-redis/v9) follows redirects and reconnects automatically.