feat(redis): [proof of concept] add AWS IAM authentication for ElastiCache

[aaron-zeisler]

Summary

Adds opt-in AWS IAM authentication for ElastiCache (Redis / Valkey), so operators running Relay Proxy on AWS can authenticate via IAM identities (IRSA, EKS Pod Identity) instead of long-lived static Redis passwords.

Jira: SDK-2472 — child of epic SDK-2471 "Relay Proxy: Support IAM for Elasticache". Resolves #680.

Status: proof of concept. We do not expect to ship this before Relay Proxy v9. The v9 work will fold this feature into a broader effort to upgrade go-redis to its latest version and consolidate Relay's two Redis libraries down to one (go-redis), at which point the v8-era OnConnect wiring and the manual connection-recycling below are replaced by go-redis v9's native CredentialsProvider (which re-auths in place). This branch is the hardened reference prototype that feeds that plan.

Depends on companion upstream PR launchdarkly/go-server-sdk-redis-redigo#45, which adds the PasswordProvider and MaxConnLifetime builder methods this branch consumes. go.mod pins to a pseudo-version against the upstream branch HEAD; before merge it should be re-pinned to a real release tag once that branch ships in a v3.x release.

Background

Long-lived Redis passwords are an operational burden and a security risk. The reporter (#680) asked for IAM-based auth gated behind a config flag, citing #127 (DynamoDB IRSA) as precedent.

DynamoDB was a one-line SDK bump — once the AWS SDK supported IRSA, every DynamoDB API call was transparently signed. ElastiCache is fundamentally different. Redis speaks its own wire protocol, not AWS APIs. Each Redis client must:

1. Use AWS credentials to generate a SigV4-presigned URL (action=connect, service=elasticache).
2. Pass that URL as the password in Redis AUTH / HELLO.
3. The token is valid for 15 minutes; new connections need fresh tokens.

Relay constructs Redis clients in three places, using two different libraries, all reading the same RedisConfig:

Use case	Library	Site
SDK persistent data store	redigo via go-server-sdk-redis-redigo	internal/sdks/data_stores.go
Big segments store	go-redis/v8	internal/bigsegments/store_redis.go
Auto-config cache	go-redis/v8	internal/autoconfigcache/redis_store.go

All three are in scope here — skipping any leaves a partial feature where enabling IAM auth silently breaks one of them.

A consolidated design and decision register lives at docs/agents/aws-iam-redis-design.md (gitignored, agent-only) and is mirrored to Confluence.

Changes

Configuration surface (config/config.go, config/config_validation.go):

• AWSAuth bool (REDIS_AWS_AUTH) and AWSCacheName string (REDIS_AWS_CACHE_NAME) on RedisConfig.
• AWSServerless bool (REDIS_AWS_SERVERLESS) — experimental, not functionally supported. Set true for an ElastiCache Serverless cache; this adds the ResourceType=ServerlessCache the signed token requires (without it auth fails with an opaque WRONGPASS). It covers the auth handshake only: Serverless is cluster-mode-only and Relay's Redis clients are not cluster-aware, so multi-key data-store and big-segments (Watch/TxPipelined) operations will hit CROSSSLOT. Full Serverless support is blocked on the future cluster-aware data-store work (Relay v9 "M4a" milestone). Do not use in production.
• AWSRegion string (REDIS_AWS_REGION) — optional override for the SigV4 signing region. Empty falls back to the standard AWS credential chain (unchanged behavior). A wrong region also surfaces as WRONGPASS, so the resolved region is logged at startup (see below).
• Validation in normalizeRedisConfig: when AWSAuth=true, requires REDIS_TLS=true, REDIS_USERNAME, and REDIS_AWS_CACHE_NAME; rejects both REDIS_PASSWORD and URL-embedded passwords (rediss://user:pw@host); silently lowercases AWSCacheName to match AWS-side canonicalization.

Token generation (internal/awsredisauth/):

• Stateless TokenProvider that SigV4-presigns https://<cache-name>/?Action=connect&User=<user> (plus &ResourceType=ServerlessCache when serverless) against the elasticache service. Token lifetime parameterized (default 900 s — the AWS-documented max). No caching, no background goroutine — each call retrieves credentials from aws.Config.Credentials and re-signs.
• SharedTokenProvider memoizes one provider per (cacheName, username, region, serverless) fingerprint, so the three wiring sites share a single LoadDefaultConfig, credential cache, and fail-fast Token() startup probe — without changing relay.New's signature. It logs once at startup: ElastiCache IAM auth enabled (cache=%s, region=%s, serverless=%t).

Wiring: all three Redis client construction sites updated. In IAM mode:

• The redigo data-store path uses the upstream PasswordProvider (callback invoked per Dial) plus DialUsername (ElastiCache IAM requires the ACL AUTH <user> <token> form) plus a jittered MaxConnLifetime.
• The two go-redis paths set OnConnect to call cn.AuthACL(ctx, username, token) and a jittered MaxConnAge. opts.Password / opts.Username are explicitly zeroed before installing OnConnect as defense-in-depth — go-redis runs a pipeline-AUTH before OnConnect would fire, and a leftover password (e.g., from URL parsing) would otherwise be sent to ElastiCache as static credentials.

Connection recycling / jitter: AWS disconnects IAM-authenticated connections after a hard 12-hour ceiling (active or idle). JitteredMaxConnAge() recycles each pool at a uniformly random age in [10h30m, 11h], computed once per pool. This staggers reconnects across pods (independent random draws) and across the three pools within a pod. It does not stagger connections within a single pool created at the same instant (e.g. all reconnecting after a Redis failover) — that residual is inherent to a single per-pool max-age (neither redigo nor go-redis/v8 supports per-connection max-age) and is resolved by the planned go-redis v9 migration's native CredentialsProvider, which re-auths in place rather than forcing a TCP recycle.

Docs: docs/configuration.md (env-var reference, incl. REDIS_AWS_SERVERLESS / REDIS_AWS_REGION) and docs/persistent-storage.md (the "AWS IAM authentication for ElastiCache" section with prerequisites, example config, region notes, and the 12-hour connection-lifetime note). REDIS_AWS_SERVERLESS is documented as experimental / not functionally supported (auth-handshake-only; Serverless is cluster-mode-only and Relay's clients are not cluster-aware), with a prominent caveat that resolves the existing "clustered Redis is unsupported" contradiction.

Tests:

• Validation rules incl. URL-embedded-password rejection; serverless and region-override config parsing.
• Token-provider units incl. ResourceType=ServerlessCache present/absent and region flow-through.
• SharedTokenProvider memoization (same instance per fingerprint, distinct per fingerprint, probe/log once, test reset hook).
• JitteredMaxConnAge range bound [10h30m, 11h].
• Per-site wiring tests (credentials-error propagation across the three Redis sites).
• Integration test under build tag integration: an in-process TTL-enforcing RESP mock drives the redigo path through 4 simulated token-expiry boundaries with zero command failures, enforcing the two-arg ACL AUTH form so any regression of the DialUsername wiring fails it.