A Kubernetes operator for kividb, a Redis-RESP-compatible in-memory store written in Rust. It manages a KividbCluster custom resource describing a single-master, N-replica kividb cluster — plus four companion CRDs (KividbConfig/KividbAclConfig/KividbSnapshotConfig/KividbSnapshot, see Custom resources below) — and handles:

• Automatic failover — an unhealthy master is detected and replaced by promoting the most caught-up replica, with pod labels (not Service specs) moved to reflect the new topology.
• Separate master/replica Services, each independently configurable as ClusterIP, NodePort, or LoadBalancer (with static IP / annotations / source-range support).
• Explicit, user-pinned image plus a declared standard/tls/lua/ full variant so the operator wires up the right configuration (TLS certificate mounting from a Kubernetes Secret, etc.) for whichever build you point it at.
• ACL user management and legacy requirepass, rendered into kividb's Redis-compatible ACL file from Kubernetes Secrets.
• Scheduled snapshot backups to any S3-compatible object storage (AWS S3, MinIO, R2, B2, Ceph RGW, ...), via a native Kubernetes CronJob, configurable master-or-replica sourcing, per-pod retention pruning, and a queryable record (KividbSnapshot) of every run.
• Standard scheduling controls — resources, tolerations, nodeSelector, affinity — plus Prometheus metrics and a read-only web dashboard.

See docs/ARCHITECTURE.md for how it all fits together, including a sequence diagram of what actually happens during a failover and a backup.

Custom resources

Configuration, ACLs, and backup destinations are their own reusable CRDs — referenced by name from a KividbCluster, not embedded in it — the same shape as StackGres's SGPostgresConfig/SGObjectStorage split:

Kind	Short name	Purpose
KividbCluster	kdb	The cluster: topology, storage, Services, monitoring, failover.
KividbConfig	kdbc	Reusable kividb.conf directives + TLS settings.
KividbAclConfig	kdbacl	Reusable ACL users / requirepass.
KividbSnapshotConfig	kdbsc	Reusable backup schedule, S3 destination, retention.
KividbSnapshot	kdbs	Operator-created record of one backup run (read-only).

Full field reference: docs/CONFIGURATION.md.

How it works, in one picture

Every kividb pod runs two containers — kividb (the database itself) and agent (a small Go sidecar that speaks HTTP to the controller and RESP to kividb — kividb has no HTTP API of its own) — plus a third, optional redis-exporter container (oliver006/redis_exporter) when spec.monitoring.enabled: true, for Prometheus metrics in the standard Redis-ecosystem format. The controller never talks RESP directly; it only calls the agent.

KividbCluster (CRD)
        │
        ▼
  operator controller ──HTTP──▶ agent sidecar ──RESP──▶ kividb
        │                         (per pod)
        ├─▶ StatefulSet (pods, role tracked via label kividb.io/role)
        ├─▶ Service <name>-master     (selects role=master)
        ├─▶ Service <name>-replicas   (selects role=replica)
        ├─▶ ConfigMap <name>-config   (kividb.conf)
        ├─▶ Secret <name>-auth        (ACL file)
        └─▶ CronJob <name>-backup     (triggers agent's /backup over HTTP)

Quickstart

Prerequisites: a Kubernetes cluster (1.27+) and kubectl. Helm 3 is recommended for install; a kubectl apply -k (kustomize) path is also available. See docs/INSTALL.md for both, plus upgrade and uninstall instructions.

# 1. Install the operator (CRD + controller + read-only GUI) into its own namespace
helm install kividb-operator charts/kividb-operator \
  -n kividb-operator-system --create-namespace

# 2. Apply a minimal cluster
kubectl apply -f config/samples/kividb.io_v1alpha1_kividbcluster_minimal.yaml

# 3. Watch it come up
kubectl get kividbcluster -w
kubectl get pods -l kividb.io/cluster=kividb-sample

# 4. Connect (from inside the cluster, or via port-forward)
kubectl port-forward svc/kividb-sample-master 6380:6380
redis-cli -p 6380 ping

For a full-featured example — replicas, custom kividbConfig directives, ACL users, tolerations/nodeSelector, S3-backed backups, a LoadBalancer master Service, and monitoring — see config/samples/kividb.io_v1alpha1_kividbcluster_full.yaml (paired with ..._full-secrets.yaml for the Secrets it references) and the full field reference in docs/CONFIGURATION.md.

The web GUI

A read-only dashboard (cmd/gui) ships alongside the operator (gui.enabled: true by default in the Helm chart) listing every KividbCluster, its phase, master/replica pods with readiness and replication offset, and recent events. It never has RBAC access to Secrets. See docs/GUI.md.

kubectl port-forward -n kividb-operator-system svc/kividb-operator-gui 8090:8090
# open http://localhost:8090

Documentation

Doc	Covers
docs/ARCHITECTURE.md	Design decisions, the agent sidecar, failover and backup sequence diagrams
docs/INSTALL.md	Helm and kustomize install, upgrade, uninstall
docs/CONFIGURATION.md	Full KividbCluster CRD field reference
docs/BACKUP_RESTORE.md	Configuring S3 backups, triggering one on demand, manual restore procedure
docs/TROUBLESHOOTING.md	Symptom → cause → fix for common issues
docs/GUI.md	Running and deploying the dashboard
docs/ROADMAP.md	What's shipped in 0.4.0, and what's required before 1.0.0
docs/RELEASING.md	Versioning and the release pipeline
docs/VERSIONING.md	How an external site can fetch these docs at a specific released version
CONTRIBUTING.md	Local dev setup, code layout, PR checklist

Status

This project is at v0.4.0 — see CHANGELOG.md. Validated against kividb v1.0.5 (that tag is also the default when spec.image is unset). The CRD API version is kividb.io/v1alpha1: expect it to evolve.

License

Apache License 2.0.