Redis
Redis is a managed, in-memory store next to your code, for caches, queues, locks, streams, and pub/sub. Your code keeps its usual client: ioredis, node-redis, redis-py, or BullMQ. It has no public endpoint: only workloads in the same deployment can reach it.
import * as alien from "@alienplatform/core"
const cache = new alien.Redis("cache")
.memory("4Gi")
.evictionPolicy("volatile-lru")
.build()
const api = new alien.Container("api")
.code({ type: "image", image: "ghcr.io/acme/api:1.4.0" })
.cpu(1)
.memory("1Gi")
.port(8080)
.link(cache)
.permissions("execution")
.build()
export default new alien.Stack("acme")
.add(cache, "frozen")
.add(api, "live")
.permissions({ profiles: { execution: { cache: ["redis/data-access"] } } })
.build()In this stack:
.link(cache)connects the server to theapiContainer, the workload (the running code) that uses it. Alien injects the server's connection details, its binding, into the Container.- The
executionpermission profile, the named set of cloud permissions a workload runs with, grantsredis/data-access. "frozen"means the customer's admin creates the server during initial setup."live"resources, like the Container, are created and updated by Alien on every release. See Frozen and live.
The api Container reads the connection details from the binding and connects with its usual client:
import { redis } from "@alienplatform/sdk"
import { Redis } from "ioredis"
const conn = await redis("cache").connection()
const client = new Redis({
host: conn.host,
port: conn.port,
username: conn.username,
password: conn.password,
tls: conn.tls || undefined,
})Platforms
cache becomes a single-endpoint server on a private network:
| Platform | Backing service | Created by |
|---|---|---|
| AWS | ElastiCache for Valkey 9.0, a replication group with cluster mode disabled | Alien |
| Google Cloud | Memorystore for Valkey 9.0, instance mode CLUSTER_DISABLED, reached through Private Service Connect | Alien |
| Azure | Azure Managed Redis (Redis 7.4), clustering policy NoCluster, reached through a private endpoint | Alien |
| Kubernetes | Any Redis-compatible server the customer provides | The customer, through an external binding |
| Machines | Any Redis-compatible server the customer provides | The customer, through an external binding. The resource must be "frozen". See Machines. |
| Local | The official Valkey 9.0 image, run in Docker | Alien |
On AWS, Google Cloud, and Azure, a Redis resource adds a Network to the stack, because the server lives on a private network.
Every platform runs a single shard with one endpoint. Multi-key Lua scripts, MULTI/EXEC, Streams, pub/sub, and blocking commands work as on a plain Redis server, with no hash tags needed. Cluster mode is not offered.
Frozen or live
Redis can be "frozen" or "live":
- Frozen: the setup template creates the server during initial setup, and Alien monitors it.
- Live: Alien creates, updates, and deletes it.
See Frozen and live.
Alternatives
The binding only resolves connection details. You connect with your usual client.
- For small values looked up by key with a TTL, and no server to size, use KV.
- For a managed message queue, use Queue.
- For relational data, use Postgres.
Options
| Method | Type | Default | Notes |
|---|---|---|---|
.memory(v) | string | smallest tier of at least 1 GiB | Memory for data, a binary unit (Ki, Mi, Gi, Ti), such as "4Gi". A number without a unit means GiB. Alien picks the smallest tier that fits. Larger than the biggest single-endpoint tier is rejected, not capped. See sizing. |
.evictionPolicy(p) | "noeviction" | "allkeys-lru" | "allkeys-lfu" | "allkeys-random" | "volatile-lru" | "volatile-lfu" | "volatile-random" | "volatile-ttl" | "volatile-lru" | What the server does when memory is full. volatile-* policies only evict keys that have a TTL. Queues such as BullMQ need "noeviction". Pure caches usually want "allkeys-lru". |
.persistence(on = true) | boolean | false | Keep data across a restart or maintenance. On AWS, Google Cloud, and Azure it requires .highAvailability(). See Persistence. |
.highAvailability(on = true) | boolean | false | One replica in another zone with automatic failover. Can't change after the server exists. No effect on Local. |
.encryptionKey(key) | Key | provider-managed key | Encrypts data at rest with a customer-managed Key. Can't change after the server exists. |
.enabled(input) | boolean stack input | always on | Creates the resource only when the input is true. |
Not options: engine and version, node size, cluster mode, public access, TLS, authentication, and the port. Alien sets them, and TLS and a password are always on in the clouds.
Use it from code
redis(name).connection() returns everything a client needs. On AWS, Google Cloud, and Azure it reads the password from the cloud with the workload's own identity.
import { redis } from "@alienplatform/sdk"
import { Redis } from "ioredis"
const conn = await redis("cache").connection()
const client = new Redis({
host: conn.host,
port: conn.port,
username: conn.username,
password: conn.password,
tls: conn.tls || undefined,
})
await client.set("greeting", "hello", "EX", 60)With node-redis, pass the same fields:
import { createClient } from "redis"
const client = createClient({
url: conn.url,
socket: conn.tls ? { tls: true, ...conn.tls } : undefined,
})
await client.connect()With BullMQ, pass the connection options and set maxRetriesPerRequest: null, which BullMQ requires:
import { Queue } from "bullmq"
const queue = new Queue("jobs", {
connection: {
host: conn.host,
port: conn.port,
username: conn.username,
password: conn.password,
tls: conn.tls || undefined,
maxRetriesPerRequest: null,
},
})Set the queue's server to .evictionPolicy("noeviction").
Every connection field is in the API reference.
Common patterns
Apps that read REDIS_URL
If your app reads one environment variable at startup, set it before importing the module that creates the client:
import { redis } from "@alienplatform/sdk"
process.env.REDIS_URL = (await redis("cache").connection()).url
await import("./app.js")url has the username and password percent-encoded, so a generated password can't break it. If your app takes TLS and the database index as separate settings, such as REDIS_SSL=true and REDIS_DB=0, set those from conn.tls and conn.database. The database is always 0.
Queues
BullMQ and similar job queues store jobs as keys without a TTL. Use .evictionPolicy("noeviction") so the server rejects writes when full instead of dropping jobs, and alert on memory use.
Caches
For a pure cache, use .evictionPolicy("allkeys-lru") and leave persistence off. Code should treat any key as able to disappear.
Permissions
| Set | Grants |
|---|---|
redis/data-access | Reading the connection password: the Secrets Manager secret on AWS, the instance's auth token in Memorystore on Google Cloud, and listing access keys on the one database on Azure. |
redis/heartbeat | Used by Alien's management identity to read server status and memory metrics. |
On AWS, a "live" Redis resource takes the grant at stack scope, execution: { "*": ["redis/data-access"] }. The deploy refuses a grant on the resource ID, because exact-resource policies on AWS are created at initial setup. A "frozen" server, like cache above, can take either.
Network access is separate from permissions. On the clouds, only workloads in the deployment's network can reach the server. See Permissions.