redis-operator

Redis Operator creates/configures/manages redis-failovers atop Kubernetes.

This is a fork of spotahome/redis-operator → Saremox/redis-operator → buildio/redis-operator.

What's New in v4.0.0

Breaking Change: Instance Manager Required

v4.0.0 makes the instance manager the default and only mode. Legacy exec probes are removed.

Key changes:

Sentinel disabled by default - operator-managed failover is now the default
Instance manager is always enabled (no opt-out)
HTTP health probes (/healthz, /readyz) are now the only probe type
Chart version aligned with operator version (4.0.0)

Minimal configuration (operator-managed failover, no sentinel):

apiVersion: databases.spotahome.com/v1
kind: RedisFailover
metadata:
  name: my-redis
spec:
  redis:
    replicas: 2

With Redis Sentinel (opt-in):

apiVersion: databases.spotahome.com/v1
kind: RedisFailover
metadata:
  name: my-redis
spec:
  redis:
    replicas: 2
  sentinel:
    enabled: true
    replicas: 3

What's New in v1.7.0

Sentinel-Free Architecture (#9)

v1.7.0 introduced operator-managed failover as an alternative to Redis Sentinel, reducing pod overhead from 5 pods (2 Redis + 3 Sentinel) to just 2 pods (Redis only).

How it works:

Operator monitors Redis pods and detects master failures
On failure, promotes the replica with highest replication offset (minimizes data loss)
Automatically reconfigures remaining replicas to follow new master
Master Service (rfrm-<name>) endpoints update automatically via label selectors

When to use:

Development/testing environments where you want fewer pods
Cost-sensitive deployments where 3 Sentinel pods are overhead
Simple HA setups where operator-managed failover is sufficient

When to keep Sentinel:

Production environments requiring sub-second failover
Complex topologies with multiple Redis clusters
When you need Sentinel's pub/sub notifications

What's New in v1.6.1

Disable Service Links (#3)

v1.6.1 sets enableServiceLinks: false on all pods to prevent startup failures in namespaces with many services. Kubernetes by default injects environment variables for every service in the namespace, which can exceed limits and cause pod failures.

What's New in v1.6.0

CNPG-style Instance Manager (#2)

v1.6.0 introduces an optional instance manager that runs as PID 1 in Redis containers, following the CloudNativePG model which has proven reliable at scale.

Features:

RDB tempfile cleanup - Automatically removes stale temp-*.rdb files on startup, preventing disk exhaustion during crash loops
Zombie process reaper - Properly handles SIGCHLD for BGSAVE/BGREWRITEAOF child processes
Graceful shutdown - Timeout escalation (SIGTERM → SIGKILL) for reliable shutdown

Enabled by default in v4.0.0+ - no configuration needed.

Roadmap

Version	Features	Notes
v1.6.0	Instance Manager opt-in	`instanceManagerImage` field
v1.6.1	Disable service links	Prevents startup failures in busy namespaces
v1.7.0	Sentinel-free mode	`sentinel.enabled: false`
v4.0.0	Instance Manager required	Current release - legacy probes removed, chart/operator versions aligned

See Issue #2 for instance manager details and Issue #9 for sentinel-free architecture.

Requirements

Kubernetes: 1.21+
Redis: 6+ (also supports Valkey 8)

Tested against Kubernetes 1.29, 1.30, 1.31, 1.32, 1.33, 1.34 and Redis 6, 7.

Versioning

Starting with 4.0.0, we no longer use 'v' prefix anywhere:

Git Tag	Chart Version	Image Tag
4.0.0	4.0.0	4.0.0

Warning: Previous releases used v prefix for git tags (e.g., v1.7.0). Starting with 4.0.0, git tags are bare version numbers (e.g., 4.0.0).

If you don't specify image.tag, the chart automatically uses the appVersion.

Quick Start

Install from GitHub Container Registry (Recommended)

# Install CRD
kubectl apply --server-side -f https://raw.githubusercontent.com/buildio/redis-operator/main/manifests/databases.spotahome.com_redisfailovers.yaml

# Install operator (uses default image version matching chart)
helm upgrade --install redis-operator oci://ghcr.io/buildio/redis-operator/charts/redisoperator \
  --namespace redis-operator --create-namespace

No additional parameters required - the chart defaults to the correct image version.

Install with Helm Repository

helm repo add redis-operator https://buildio.github.io/redis-operator
helm repo update
helm install redis-operator redis-operator/redis-operator

Install with kubectl

REDIS_OPERATOR_VERSION=4.0.0
kubectl apply --server-side -f https://raw.githubusercontent.com/buildio/redis-operator/${REDIS_OPERATOR_VERSION}/manifests/databases.spotahome.com_redisfailovers.yaml
kubectl apply -f https://raw.githubusercontent.com/buildio/redis-operator/${REDIS_OPERATOR_VERSION}/example/operator/all-redis-operator-resources.yaml

Install with Kustomize

# Default installation with RBAC, service account, resource limits
kustomize build github.com/buildio/redis-operator/manifests/kustomize/overlays/default?ref=4.0.0 | kubectl apply -f -

# Minimal installation
kustomize build github.com/buildio/redis-operator/manifests/kustomize/overlays/minimal?ref=4.0.0 | kubectl apply -f -

# Full installation with Prometheus ServiceMonitor
kustomize build github.com/buildio/redis-operator/manifests/kustomize/overlays/full?ref=4.0.0 | kubectl apply -f -

Updating

Update CRD

Helm only manages CRD creation on first install. To update the CRD:

REDIS_OPERATOR_VERSION=4.0.0
kubectl replace --server-side -f https://raw.githubusercontent.com/buildio/redis-operator/${REDIS_OPERATOR_VERSION}/manifests/databases.spotahome.com_redisfailovers.yaml

Then upgrade the operator:

helm upgrade redis-operator redis-operator/redis-operator

Usage

Create a Redis Failover

kubectl apply -f https://raw.githubusercontent.com/buildio/redis-operator/4.0.0/example/redisfailover/basic.yaml

This creates the following resources:

rfr-<NAME>: Redis StatefulSet and ConfigMap
rfs-<NAME>: Sentinel Deployment, ConfigMap, and Service

Note: The RedisFailover name must be ≤48 characters.

Enable Instance Manager

To use the CNPG-style instance manager for improved reliability:

apiVersion: databases.spotahome.com/v1
kind: RedisFailover
metadata:
  name: my-redis
spec:
  redis:
    replicas: 2
  sentinel:
    replicas: 3

The instance manager is enabled by default:

An init container copies the redis-instance binary to a shared volume
The main container runs redis-instance run as PID 1
The instance manager performs cleanup and manages Redis as a child process

Sentinel-Free Mode

For simpler deployments, disable Sentinel and let the operator manage failover:

apiVersion: databases.spotahome.com/v1
kind: RedisFailover
metadata:
  name: my-redis
spec:
  redis:
    replicas: 2
  sentinel:
    enabled: false
    failoverTimeout: "10s"  # Optional, defaults to 10s

How failure detection works:

The instance manager provides HTTP health endpoints (/healthz, /readyz) that enable:

HTTP health probes (faster than exec probes)
Immediate detection of Redis process crashes
No process spawning overhead during health checks

This creates only:

rfr-<NAME>: Redis StatefulSet (2 pods)
rfrm-<NAME>: Master Service (points to current master via label selector)
rfrs-<NAME>: Slave Service (points to replicas)

No Sentinel pods are created.

The operator handles failover by:

Detecting master failure via health checks
Selecting the replica with highest replication offset
Promoting it to master (SLAVEOF NO ONE)
Reconfiguring other replicas to follow the new master
Updating pod labels so Services route correctly

Instance Manager CLI

The redis-instance binary provides the following commands:

# Run as instance manager (PID 1 mode)
redis-instance run --redis-conf /redis/redis.conf --data-dir /data --db-filename dump.rdb

# Standalone cleanup (removes stale RDB files)
redis-instance cleanup --data-dir /data --db-filename dump.rdb

# Dry-run cleanup (show what would be removed)
redis-instance cleanup --data-dir /data --dry-run

Connection

With Sentinel (default):

Connect using a Sentinel-ready client library:

url: rfs-<NAME>
port: 26379
master-name: mymaster

Without Sentinel (sentinel.enabled: false):

Connect directly to the master service:

url: rfrm-<NAME>
port: 6379

The master service automatically routes to the current master pod.

Enable Authentication

kubectl create secret generic redis-auth --from-literal=password=your-password

apiVersion: databases.spotahome.com/v1
kind: RedisFailover
metadata:
  name: my-redis
spec:
  redis:
    replicas: 3
  sentinel:
    replicas: 3
  auth:
    secretPath: redis-auth

Persistence

Enable persistent storage with a PVC:

spec:
  redis:
    storage:
      persistentVolumeClaim:
        metadata:
          name: redis-data
        spec:
          accessModes: [ReadWriteOnce]
          resources:
            requests:
              storage: 10Gi
      keepAfterDeletion: true  # Optional: retain PVCs when RedisFailover is deleted

See persistent-storage.yaml for a complete example.

Custom Configuration

Configure Redis and Sentinel via customConfig:

spec:
  redis:
    customConfig:
      - maxmemory 2gb
      - maxmemory-policy allkeys-lru
  sentinel:
    customConfig:
      - down-after-milliseconds 5000

Note: Configuration is applied via CONFIG SET at runtime. Do not modify control options like port, bind, or dir.

Affinity and Tolerations

Security Context

Bootstrapping

Migrate from an existing Redis instance:

spec:
  bootstrapNode:
    host: existing-redis.example.com
    port: "6379"
    allowSentinels: false  # Set true to also create Sentinels pointing to bootstrap node

See bootstrapping.yaml for details.

CI/CD

This project includes comprehensive GitHub Actions workflows:

Workflow	Triggers	Description
CI	Push, PR	Build, lint, unit tests, integration tests, Docker build
E2E	PR	Full end-to-end tests in minikube cluster
Release	Tags	Multi-arch image build and push to GHCR

E2E Tests

The E2E workflow validates:

Instance manager runs as PID 1
RDB cleanup works on pod restart
Redis remains functional after restart
Sentinel-free mode: no Sentinel resources created
Sentinel-free mode: operator-managed failover works

Development

Generate CRD

Requires controller-gen v0.20.0+ for Go 1.25+:

go install sigs.k8s.io/controller-tools/cmd/controller-gen@latest
make generate-crd

Run Tests

make ci-unit-test
make ci-integration-test

Build Docker Image

make image

Cleanup

Remove Operator

helm uninstall redis-operator
kubectl delete crd redisfailovers.databases.spotahome.com

Warning: Deleting the CRD removes all RedisFailover resources and their managed objects.

Remove Single RedisFailover

kubectl delete redisfailover <NAME>

All managed resources are automatically cleaned up via OwnerReferences.

Docker Images

Images are published to GitHub Container Registry:

Operator & Instance Manager: ghcr.io/buildio/redis-operator
Helm Chart: oci://ghcr.io/buildio/redis-operator/charts/redisoperator

Name		Name	Last commit message	Last commit date
.github		.github
api/redisfailover		api/redisfailover
charts		charts
client/k8s/clientset/versioned		client/k8s/clientset/versioned
cmd		cmd
docker		docker
docs		docs
example		example
log		log
manifests		manifests
metrics		metrics
mocks		mocks
operator/redisfailover		operator/redisfailover
scripts		scripts
service		service
test/integration/redisfailover		test/integration/redisfailover
.gitattributes		.gitattributes
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
go.mod		go.mod
go.sum		go.sum

Uh oh!

Latest commit

History

Folders and files

Repository files navigation