KiviDB on Kubernetes: kividb-operator 0.4.0
Murtaza Shajapurwala ·
Today we're announcing the KiviDB operator for Kubernetes. It's open source, it installs with one Helm command, and version 0.4.0 is out now.
You describe a cluster in YAML, and the operator runs it: a master and its replicas as a StatefulSet, Services that always point at the right pod, failover when the master goes away, and backups to any S3-compatible bucket.
apiVersion: kividb.io/v1alpha1
kind: KividbCluster
metadata:
name: orders
spec:
replicas: 2
storage: {size: 10Gi}
That's a complete cluster: one master, two replicas, 10 GiB of disk each.
Install it
You need Kubernetes 1.27 or later and Helm 3.9 or later.
helm install kividb-operator oci://quay.io/kividbio/kividb-operator-chart \
--version 0.4.0 \
-n kividb-operator-system --create-namespace
Then apply a KividbCluster and watch it come up:
kubectl get kividbcluster -w

The full walkthrough, including kustomize and air-gapped installs, is in Install on Kubernetes.
What the operator manages
- Replication and failover. The operator picks a master, points the replicas at it and watches it. If the master stops answering, it promotes the replica that was most caught up and moves the master Service to it. Clients keep using the same Service name.
- Separate read and write endpoints. A master Service for writes and a replica Service for reads, so you can spread read traffic without any client-side logic.
- Users and passwords.
KividbAclConfigdefines users and their permissions. Changes reach running pods without a restart. - Configuration.
KividbConfigholds engine settings. Changing it rolls the pods safely, one at a time. - Backups.
KividbSnapshotConfigtakes scheduled snapshots to S3 or any S3-compatible store, with retention.
New in 0.4.0
Rolling updates that don't lose writes
This is the change we care about most. When a cluster's pods need replacing (a new image, new resources, a config change, or an operator upgrade), the operator now does it itself:
- One pod at a time, replicas first.
- The next pod only once every replica has finished resyncing.
- The master is never restarted while it's the master. Its role is handed to the most caught-up replica first, then it's replaced as a replica.
The result is about one second of refused writes when the master role moves, and no acknowledged writes lost. Under 0.3.0 a rolling update could lose a minute of writes or more.
Declarative restarts with KividbDbOps
Restarting a cluster is now a resource you apply and can watch:
apiVersion: kividb.io/v1alpha1
kind: KividbDbOps
metadata:
name: orders-restart
spec:
clusterRef:
name: orders
op: restart
It follows the same order as a rolling update, and kubectl get kdbops shows which pod it's on and what it's waiting for.
Restore a snapshot into a new cluster
A new cluster can start from a backup instead of starting empty:
spec:
replicas: 2
storage: {size: 10Gi}
bootstrapFromSnapshot:
snapshotRef:
name: orders-backup-29849655
The operator restores the snapshot into the first pod's volume before anything starts, and the replicas sync from it. It only ever applies to a new cluster, never to one that's already running.
A management GUI
The GUI is on by default and is now a console as well as a dashboard. It shows live status, 24 hours of metrics, pod logs and a command console. It can also run a rolling restart, scale replicas, promote a replica and take a snapshot.
Write actions need a login. Point gui.auth.existingSecret at a Secret with a username and password. Without one, the GUI is read-only.
Safer failover
- A master that comes back after a failover can no longer take its role back and discard the writes made in between.
- Replicas that haven't finished syncing, or that hold no data, aren't promoted.
KiviDB 1.0.5 is the default engine
New clusters run KiviDB 1.0.5, with the full search engine, JSON indexing and the security fixes from that release. Two behaviour changes matter when you upgrade:
- The
defaultuser's password is enforced. Clients that connected withoutAUTHwill getNOAUTHonce a password is set. maxmemoryis enforced. A limit set long ago that never took effect now applies.
Clusters can stay on an older engine by pinning spec.image. The release notes cover the upgrade from 0.3.0 step by step.
Get started
- Install guide: Install on Kubernetes
- Source, issues and Helm chart: github.com/kividbio/kividb-operator
- Prefer not to run it yourself? KiviDB Cloud runs the same engine on AWS, Azure and Google Cloud.