Deploy Memcached with YAML

A managed Memcached instance lives inside a project and is reachable from any container in that project. Run a single node for caches you can afford to lose, or scale out to multiple nodes for higher capacity.

Updated 16 Jul 20262 min read

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 multi-node 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

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`
`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.

A single-node instance has one hostname/port pair you can point a memcached client at directly. Multi-node instances work with any consistent-hashing client (twemproxy, mcrouter, libmemcached-based clients); each node is a separate hostname, issued 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 or adding nodes — 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