Deploy Memcached with YAML

A managed Memcached instance lives inside a project and is reachable from any container in that project. Pick between a single node (standalone) for caches you can afford to lose and a multi-node cluster for higher capacity and partition tolerance.

Updated 23 Jun 20262 min read

A managed Memcached instance lives inside a project and is reachable from any container in that project. Pick between a single node (standalone) for caches you can afford to lose and a multi-node cluster for higher capacity and partition tolerance.

This guide covers the YAML shape. For the flag-mode equivalent, see Deploy Memcached with flags.

Minimal example

kind: memcached
project: my-project
handle: session-cache
name: Session Cache
regions:
  - falkenstein-1
 
tuning:
  memory: 256

Apply it:

reis apply -f session-cache.yml

That gets you a single-node Memcached instance with 256 MB of memory. Sensible defaults take care of everything else.

A more typical deploy

A clustered cache sized for a busy production workload:

kind: memcached
project: my-project
handle: session-cache
name: Session Cache
regions:
  - falkenstein-1
  - virginia-1
 
tuning:
  memory: 1024                       # MB per node
  max_connections: 4096
  threads: 8
  max_item_size_mb: 4
 
topology:
  nodes: 3                           # 1-9
  mode: cluster                      # standalone | cluster

Field reference

YAML path	Description	Default
`tuning.memory`	Memory per node in MB	required
`tuning.max_connections`	Concurrent connections per node	`1024`
`tuning.threads`	Worker threads per node	`4`
`tuning.max_item_size_mb`	Largest item the cache will accept (max `128`)	`1`
`topology.nodes`	Number of nodes (1-9)	`1`
`topology.mode`	`standalone` (single node) or `cluster`	`cluster`
`regions`	Regions to deploy to	required

Connecting from a container

Once the instance is running, the platform exposes its hostname inside the project's private network. The container can reach it directly — no further configuration needed.

The exact connection string depends on the topology:

standalone — single hostname/port pair, point your memcached client at it directly.
cluster — consistent-hashing clients (twemproxy, mcrouter, the libmemcached-based clients) work out of the box. Each node is a separate hostname; the platform issues them deterministically from the instance handle.

Updating an instance

Re-apply the same file with any changes:

reis apply -f session-cache.yml

Common edits — bumping memory, adding nodes, switching modes — all happen the same way. Reis matches by handle.

Deploy Memcached with flags — flag-mode equivalent
Deploy an HTTP container with YAML — for the service that fronts the cache