Deploy Valkey with YAML

A managed Valkey instance lives inside a project and is reachable from any container in that project — a Redis-compatible key-value datastore. Choose the cache purpose for data you can afford to lose, or store for persistent workloads.

Updated 12 Aug 20264 min read

A managed Valkey instance lives inside a project and is reachable from any container in that project — a Redis-compatible key-value datastore. Choose the cache purpose for data you can afford to lose, or store for persistent workloads.

Valkey is rolling out gradually. If it is not yet visible for your organisation, contact support to request access.

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

Minimal example

kind: valkey
project: my-project
handle: session-cache
name: Session Cache
tier: single
purpose: cache
memory: 256
regions:
  - falkenstein-1

Apply it:

reis apply -f session-cache.yml

That gets you a single-node Valkey cache with 256 MB of memory. Sensible defaults take care of everything else — auth is on with a generated password you can reveal once from the console.

A persistent, highly available store

The store purpose enables persistence and requires persistence.storage. The ha tier runs a Sentinel topology — your application needs a Sentinel-aware client driver.

kind: valkey
project: my-project
handle: job-queue
name: Job Queue
tier: ha
purpose: store
memory: 1024
regions:
  - falkenstein-1
 
topology:
  size: standard          # standard | hardened — controls replicas per shard
 
persistence:
  storage: 10             # GB per node, required for purpose: store
 
backup:
  backup: true
  backup_schedule: "0 3 * * *"

Backups are free and retained as 7 daily snapshots.

Externally exposed with TLS

Any tier can be exposed at the platform edge on port 6379. External access requires all three of TLS, auth and a non-empty IP allowlist.

kind: valkey
project: my-project
handle: shared-cache
name: Shared Cache
tier: single
purpose: cache
memory: 512
regions:
  - falkenstein-1
 
security:
  tls: true               # auth is already on by default
 
exposure:
  external: true
  allowed_ips:
    - 198.51.100.0/24
  hostnames:
    - hostname: cache.example.com

With tls: true and no tls_bundle, the platform issues a TLS bundle and manages it in your vault. To serve your own certificate, set security.tls_bundle to the handle of a TLS bundle in your vault — it must cover every hostname the instance answers to.

Custom hostnames are vanity names: point a CNAME at the instance's default per-region hostname (<default_hostname>.<region>.valkey.on.bahriya.app).

Sharded cluster with tuning

The sharded tier runs a cluster topology (minimum 3 shards) — your application needs a cluster-aware client driver. Shards are grow-only in self-service; lowering the count is handled through a support ticket.

kind: valkey
project: my-project
handle: catalog
name: Catalog
tier: sharded
purpose: cache
memory: 2048
regions:
  - falkenstein-1
  - singapore-1
 
topology:
  size: hardened
  shards: 3
 
tuning:
  maxmemory_policy: allkeys-lfu
  config:
    tcp-keepalive: 300
    databases: 16

Field reference

YAML path	Description	Default
`tier`	`single`, `ha` or `sharded`	required
`purpose`	`cache` or `store` — immutable after creation	required
`memory`	Memory per node in MB	required
`regions`	Regions to deploy to — each runs an independent copy with its own data	required
`topology.size`	`standard` or `hardened` (ha and sharded tiers)	`standard`
`topology.shards`	Shard count (sharded tier, minimum 3, grow-only)	`3`
`persistence.storage`	Storage per node in GB — required for `purpose: store`	—
`tuning.maxmemory_policy`	Eviction policy — defaults from purpose	`allkeys-lru` / `noeviction`
`tuning.config`	Allowlisted keys: `tcp-keepalive`, `timeout`, `tcp-backlog`, `databases`, `loglevel`	—
`security.auth`	Require the connection password	`true`
`security.password`	Explicit password — omit and the platform generates one	generated
`security.tls`	Serve TLS	`false`
`security.tls_bundle`	Handle of your own TLS bundle to serve	platform-managed
`exposure.external`	Expose at the platform edge on port 6379	`false`
`exposure.allowed_ips`	CIDR allowlist — required non-empty while external is on	—
`exposure.hostnames`	Custom hostnames (`- hostname: cache.example.com`)	—
`backup.backup`	Daily backups (store purpose only)	`false`
`backup.backup_schedule`	Backup cron schedule — retention is fixed at 7 daily snapshots	—
`networking.network_policies`	Network policies narrowed to this instance, by handle	—

Connecting from a container

Once the instance is running, containers in the same project reach it on the internal network at <handle>:6379. The tier decides the client driver: single works with any client, ha needs a Sentinel-aware driver, sharded a cluster-aware one.

Updating an instance

Re-apply the same file with any changes:

reis apply -f session-cache.yml

Common edits — bumping memory, enabling backups, growing shards — all happen the same way. Reis matches by handle. purpose is immutable; changing it requires a new instance.

Deploy Valkey with flags — flag-mode equivalent
Deploy an HTTP container with YAML — for the service that uses the datastore