Configure Retention

Events Store persists messages to disk. Without retention policies, a store on the legacy engine grows indefinitely. KubeMQ provides three types of retention controls there: time-based, size-based, and count-based. You can combine them — the most restrictive policy wins.

Retention Options

How Retention Works

As events accumulate, KubeMQ checks each retention threshold and purges the oldest events by time, size, or count — keeping everything that still fits within every limit.

Configure via Docker

Set retention options using environment variables on a server running the legacy engine. <RunKubeMQ> starts the current (next) engine, so the example below does not enforce these limits; it shows the variable names and shapes for a legacy deployment.

docker run -d \  --pull always \  --platform linux/amd64 \  --name kubemq \  --hostname kubemq \  -p 127.0.0.1:50000:50000 \  -p 127.0.0.1:9090:9090 \  -p 127.0.0.1:8080:8080 \  -e STORE_ENGINE=next \  -e STORE_NEXT_ACK_POLICY=strict \  -e STORE_STORE_PATH=/kubemq/store \  -e API_BIND_ADDRESS=0.0.0.0 \  -e STORE_MAX_RETENTION=4320 \  -e STORE_MAX_QUEUE_SIZE=1073741824 \  -e STORE_MAX_MESSAGES=1000000 \  -e STORE_MAX_PURGE_INACTIVE=10080 \  -v kubemq-data:/kubemq/store \  europe-docker.pkg.dev/kubemq/images/kubemq-next:latest

This configures:

• 3-day retention (4320 minutes)
• 1 GB max per channel (1073741824 bytes)
• 1 million messages max per channel
• 7-day inactive channel purge (10080 minutes)

Configure on Kubernetes

Add the limits to the cluster-values.yaml you created in Install on Kubernetes. The Kubernetes names differ from the config.yaml names; Storage & Queues lists both.

store:
  messagesRetentionMinutes: 4320
  maxChannelSize: 1073741824
  maxMessages: 1000000
  purgeInactiveMinutes: 10080

Apply it with the commands in Apply a settings change. On a KubemqCluster resource you manage yourself, the same keys go under spec.store.

Common Retention Strategies

Development (Short Retention)

STORE_MAX_RETENTION=60          # 1 hour
STORE_MAX_MESSAGES=10000        # 10K messages
STORE_CLEAN_STORE=true          # Clean on restart

Production — Event Streaming

STORE_MAX_RETENTION=10080       # 7 days
STORE_MAX_QUEUE_SIZE=5368709120 # 5 GB per channel
STORE_MAX_MESSAGES=0            # Unlimited messages

Production — Event Sourcing

STORE_MAX_RETENTION=0           # Unlimited (no time expiry)
STORE_MAX_QUEUE_SIZE=0          # Unlimited size
STORE_MAX_MESSAGES=0            # Unlimited messages

Production — Compliance (Fixed Window)

STORE_MAX_RETENTION=525600      # 365 days (1 year)
STORE_MAX_QUEUE_SIZE=0          # Unlimited size
STORE_MAX_MESSAGES=0            # Unlimited messages
STORE_MAX_PURGE_INACTIVE=525600 # Purge inactive after 1 year

Persistence and Recovery

Clean Start

To clear all stored data on startup:

docker run -d \  --pull always \  --platform linux/amd64 \  --name kubemq \  --hostname kubemq \  -p 127.0.0.1:50000:50000 \  -p 127.0.0.1:9090:9090 \  -p 127.0.0.1:8080:8080 \  -p 127.0.0.1:9092:9092 \  -e STORE_ENGINE=next \  -e STORE_NEXT_ACK_POLICY=strict \  -e STORE_STORE_PATH=/kubemq/store \  -e API_BIND_ADDRESS=0.0.0.0 \  -e STORE_CLEAN_STORE=true \  -v kubemq-data:/kubemq/store \  europe-docker.pkg.dev/kubemq/images/kubemq-next:latest

Volume Persistence

For data to survive container restarts, mount a volume to the store path:

docker run -d \  --pull always \  --platform linux/amd64 \  --name kubemq \  --hostname kubemq \  -p 127.0.0.1:50000:50000 \  -e STORE_ENGINE=next \  -e STORE_NEXT_ACK_POLICY=strict \  -e STORE_STORE_PATH=/kubemq/store \  -e API_BIND_ADDRESS=0.0.0.0 \  -v kubemq-data:/kubemq/store \  europe-docker.pkg.dev/kubemq/images/kubemq-next:latest

Recovery from Corruption

If the server detects recovery errors on startup, it automatically removes and recreates the store directory. The TruncateUnexpectedEOF option (enabled by default) truncates corrupted file tails rather than failing.

Related

• Monitor Storage Utilization for disk usage thresholds
• Resume After Disconnect for durable subscription behavior
• Events Store Reference for complete configuration