A Stacktape redis resource is a managed, Redis-compatible in-memory store on AWS ElastiCache. It delivers sub-millisecond reads and writes for caching, session storage, rate limiting, queues and pub/sub. Traffic is encrypted in transit, and the cache runs inside your stack's VPC with no public endpoint.
The cache runs Valkey, the open-source continuation of Redis that AWS maintains. Valkey speaks the Redis protocol, so Redis client libraries (ioredis, node-redis, redis-py, Jedis and others) work unchanged.
When to use
Redis is the right choice when your workload needs fast, ephemeral or semi-persistent data access that would be too slow or too expensive to serve from a relational database or DynamoDB.
- Application caching — cache database query results, API responses, or computed values to cut latency and reduce load on your primary database.
- Session storage — store user sessions with automatic expiration, shared across multiple container instances or Lambda functions.
- Rate limiting and counters — atomic increments with TTL make Redis ideal for request throttling and real-time counters.
- Queues and pub/sub — use Redis lists, streams or pub/sub channels for lightweight inter-service messaging.
- Rich data structures — lists, sets, sorted sets, hashes, and streams beyond simple key-value.
When NOT to use
- You need a persistent primary database. Redis is an in-memory store. While backups are available, it is not designed to be your system of record. Use a relational database or DynamoDB instead.
- You need access from outside AWS without a VPC. The cache has no public endpoint. Upstash Redis is reachable over the internet and over HTTPS.
Choose an engine
engine.type decides which software runs the cache and how AWS runs it. There is no default: the choice changes cost and which command patterns work.
valkey-serverless | valkey | redis | |
|---|---|---|---|
| How it runs | Serverless, scales automatically | Fixed-size nodes | Fixed-size Redis OSS nodes |
| Billing | Per GB stored + per request | Per node-hour | Per node-hour (25% more than Valkey) |
| Smallest cost | ~$6/month idle (100 MB minimum) | ~$9.40/month (cache.t4g.micro) | ~$11.70/month (cache.t4g.micro) |
| High availability | Built in, across Availability Zones | Add replicas + automatic failover | Add replicas + automatic failover |
| Cache creation | About 2 minutes | About 5 minutes | About 5 minutes |
| Multi-key commands | Keys must share a hash slot | Unrestricted | Unrestricted |
| Use for | New caches with small or spiky data | Large datasets, any client pattern | Existing caches only |
Prices are approximate for us-east-1.
Valkey Serverless
There are no instances to size. The cache stores up to 5,000 GB and is billed for the data it holds (minimum 100 MB) plus ElastiCache Processing Units (ECPUs) for requests. A GET or SET of up to 1 KB uses 1 ECPU. Storage costs about $61 per GB-month, so above roughly 150 MB of data a small valkey node costs less.
Compatibility. A serverless cache always runs in cluster mode with all keys behind one endpoint. Standard (non-cluster) clients connect unchanged. Commands that touch several keys — MGET, MSET, transactions, and Lua scripts — fail with a CROSSSLOT error unless all their keys share a hash slot. Put a common hash tag in the key names, such as {user:42}:cart and {user:42}:profile. Queue libraries need the same: for BullMQ, use a prefix with braces, for example prefix: '{bull}'. Keyspace notifications are not supported.
Cost limits. Two optional limits cap the bill:
maxDataGbcaps stored data. At the limit, Valkey evicts the least recently used keys that have a TTL; if no key has a TTL, writes fail with an out-of-memory error. Set TTLs on cached keys when you use it.maxEcpuPerSecondcaps request throughput (minimum 1,000). Requests above it are throttled.
Clients connect on port 6379. Port 6380 serves lower-latency, eventually consistent reads to clients that send READONLY; its connection details are the reader* parameters.
Node-based Valkey
This creates a single node running the latest Valkey version. It works with every Redis client and command pattern. Slow-query logging is enabled by default and sent to CloudWatch.
Redis OSS (existing caches)
AWS publishes no Redis OSS versions after 7.1, so new caches must use Valkey. engine.type: redis keeps caches created before Valkey support running on the version they have:
Switching to Valkey. Change engine.type from redis to valkey. AWS migrates the cache in place, which took about 20 minutes for a single cache.t4g.micro node: the endpoint and data stay, writes pause for a few seconds during a failover (longer when the cache has no replicas), and the switch cannot be reversed.
Changing engines later
| Change | Result |
|---|---|
redis → valkey | In place; brief write pause; cannot be reversed |
valkey → redis | Not supported |
| Serverless ↔ node-based | Not allowed: AWS would replace the cache, with a new endpoint and no data |
| Version upgrade | In place |
| Version downgrade | Not supported |
To move between serverless and node-based, create a new resource with a different name, move your application to it, then remove the old one.
Versions
Without engine.properties.version, a new cache gets the latest version and an existing cache keeps the version it runs. A Stacktape update never upgrades a cache on its own.
valkey-serverless: major versions9,8,7.valkey:9.1,9.0,8.2,8.1,8.0,7.2.redis:7.1,7.0,6.2,6.0(required).
Instance sizing
For valkey and redis, engine.properties.instanceSize determines the memory, CPU, and cost of every node (primary and replicas). You can change it after creation without data loss.
| Instance | Family | Memory | Approx. Valkey cost | Best for |
|---|---|---|---|---|
cache.t4g.micro | Burstable (Graviton) | 0.5 GB | ~$0.013/hr | Dev/test, low-traffic apps |
cache.t4g.small | Burstable (Graviton) | 1.37 GB | ~$0.026/hr | Small production, session stores |
cache.m7g.large | General purpose (Graviton) | 6.38 GB | ~$0.12/hr | Moderate production workloads |
cache.r7g.large | Memory-optimized (Graviton) | 13.07 GB | ~$0.16/hr | Large datasets, heavy caching |
t(burstable) — cheapest, variable CPU performance. Good for development and intermittent traffic.m(general purpose) — consistent CPU performance for production workloads.r(memory-optimized) — highest memory-to-CPU ratio for large datasets.- Graviton suffix (
g) — ARM-based instances with better price-performance. Prefert4g/m7g/r7g.
High availability (node-based)
Serverless caches replicate across Availability Zones automatically. Node-based caches have a single primary node by default.
Read replicas and automatic failover
Set numReplicaNodes to add read replicas, and enableAutomaticFailover to promote a replica when the primary fails.
Each replica runs the same instance size as the primary, so two replicas triple the cost. Failover causes a brief connectivity interruption; clients should reconnect and retry.
Deploy replicas first, then enable enableAutomaticFailover in a separate deployment.
Sharding
enableSharding splits the key space across numShards shards, each with its own primary and replicas. Clients must support cluster mode. Sharding requires numReplicaNodes >= 1 and must be set when the cache is created.
Most teams don't need sharding: add replicas to scale reads, or use valkey-serverless, which scales without sharding decisions.
Networking
Caches run inside your stack's VPC and have no public IP addresses.
vpc(default) — any resource in the same VPC can connect: container workloads, batch jobs, and Lambda functions withjoinDefaultVpc: true.scoping-workloads-in-vpc— only resources that list this cache in theirconnectTocan connect.
To connect from your local machine, deploy a bastion host and use stacktape bastion tunnel or stacktape query redis.
Connecting from workloads
Use connectTo to grant a workload access. Stacktape opens the security group rules and injects connection details as environment variables, for example STP_CACHE_HOST and STP_CACHE_PORT for a resource named cache. To pass a complete connection URL, use the connectionString referenceable parameter:
Lambda functions must set joinDefaultVpc: true to reach the cache. Container workloads and batch jobs are already in the VPC.
Example handler
The connection string uses rediss:// (TLS) and the default user. All traffic is encrypted in transit, so the client library must support TLS.
Backups
Set automatedBackupRetentionDays to keep daily snapshots for that many days (maximum 35 for serverless caches). 0 (the default) disables backups.
Logging (node-based)
Node-based caches send slow-query logs to CloudWatch by default, retained for 30 days. View them with stacktape logs. Customize them with engine.properties.logging (format, retentionDays, disabled, and log forwarding). Serverless caches have no slow-query log.
Dev mode
During stacktape dev, the cache runs locally in Docker: Valkey for valkey and valkey-serverless, Redis for redis. For valkey-serverless, the local container runs in cluster mode, so CROSSSLOT errors show up locally the same way they do in AWS. Keyspace notifications still work locally; set dev.remote: true to test against the deployed cache.
Migrating from redis-cluster
Stacktape v4 renamed redis-cluster to redis and moved node settings under engine.properties. To keep a deployed cache unchanged, set engine.type: redis with the version it runs (6.2 if engineVersion was not set):
The cache keeps its endpoint and data. Switch it to Valkey afterwards by changing engine.type to valkey.
Referenceable parameters
The following parameters can be easily referenced using $ResourceParam directive directive.
To learn more about referencing parameters, refer to referencing parameters.
In case of NON-sharded cluster(default), this is a hostname of the primary instance that can be used for both reads and writes. In case of sharded cluster, this is cluster's configuration endpoint that can be used for all operations.
- Usage:
$ResourceParam('<<resource-name>>', 'host')
Hostname (address) that can be used for reads only. (only available for NON-sharded clusters). If you use multiple replicas, it is advised to use readerHost for read operations to offload the primary host. ReaderHost automatically balances requests between available read replicas.
- Usage:
$ResourceParam('<<resource-name>>', 'readerHost')
Port of the cluster.
- Usage:
$ResourceParam('<<resource-name>>', 'port')
Indicates whether cluster is sharded. Available values:
enabledordisabled.- Usage:
$ResourceParam('<<resource-name>>', 'sharding')
API Reference
RedisPropsRedis FAQ
Which engine should I choose?
Use valkey-serverless for new caches with small or variable data when your code does not run multi-key commands across unrelated keys, or when you can add hash tags. Use valkey when you store more than a few hundred MB, need predictable hourly pricing, or use libraries that send multi-key commands you cannot change.
Is Valkey compatible with my Redis client?
Yes. Valkey is a fork of Redis 7.2 and speaks the same protocol and commands. ioredis, node-redis, redis-py, Jedis, Lettuce and go-redis work without changes.
Can I connect to the cache from my local machine?
The cache runs inside your VPC with no public endpoint. Deploy a bastion host and use stacktape bastion tunnel or stacktape query redis. During dev mode, the cache runs locally in Docker.
What's the difference between Stacktape Redis and Upstash Redis?
A Stacktape redis resource is an AWS ElastiCache cache inside your VPC. Upstash Redis is a third-party serverless service reachable over the internet, with per-request pricing.
Why can't my Lambda function reach the cache?
The cache lives inside the VPC, so a Lambda must set joinDefaultVpc: true; without it, connections time out. With valkey-serverless, the security group must allow both ports 6379 and 6380, which Stacktape configures for you.