mariadb-operator: declarative MariaDB on Kubernetes with four HA topologies

Kubernetes CRDs as the primary interface to MariaDB operations

Running MariaDB on Kubernetes without an operator means managing StatefulSets, secrets, configuration files and backup jobs by hand, and HA topologies require extra coordination that kubectl cannot express declaratively. mariadb-operator removes that gap by mapping every MariaDB operation onto Kubernetes custom resource definitions.

Every action that would otherwise require a DBA script becomes a YAML manifest: provisioning an instance, configuring Galera multi-master, scheduling a backup to S3, creating a database user, rotating the root password. In the project's own words: 'Declaratively manage your MariaDB using Kubernetes CRDs rather than imperative commands.'

The target audience is teams already running workloads on Kubernetes or OpenShift who want database provisioning and lifecycle management to follow the same workflow as their application deployments. It is written in Go using controller-runtime v0.24.1, and Go 1.27.0 is the minimum Go version, as specified in go.mod. Minimum Kubernetes compatibility follows from the k8s.io/api v0.36.1 dependency.

Four HA topologies from standalone to cross-cluster replication

The operator supports four HA topologies, and they differ in their consistency guarantees, not just their scale.

Standalone mode is a single MariaDB pod with no replication. Asynchronous replication adds a primary and replicas that receive changes after the primary commits. A failover under async replication may lose writes that were on the primary but had not yet arrived at the replica, because commits on the primary do not wait for replica acknowledgment.

Synchronous multi-master via Galera addresses that gap. All nodes certify a write before any of them commits it, so the cluster never holds an uncommitted write on only one member. The trade-off is that Galera requires all members to be reachable: a network partition can stop the cluster from accepting writes if quorum cannot be confirmed. The Galera library path must match the Linux layout of the container image, which is covered in a later section.

The fourth topology, marked in the README as a new addition, is multi-cluster: cross-cluster replication for multi-region deployments, disaster recovery, and blue-green upgrades. MaxScale, the database proxy, sits alongside these topologies to load balance requests and perform failover and switchover operations.

Installing via Helm, OLM, or static manifests, in cluster-wide or namespace scope

Three install paths are available. Helm is the primary path, with the chart published to Artifact Hub at artifacthub.io/packages/helm/mariadb-operator/mariadb-operator. OLM targets OpenShift and clusters with the Operator Lifecycle Manager, and the chart is also on OperatorHub at operatorhub.io/operator/mariadb-operator. For air-gapped or non-Helm environments, static manifests live in the deploy/manifests directory of the repository.

Two deployment modes are available: cluster-wide and single namespace. In cluster-wide mode, one operator instance manages CRDs across all namespaces. In single namespace mode, the operator manages only its own namespace. The documentation for both modes is in docs/helm.md, which the README links to but does not reproduce.

Operator images are at ghcr.io/mariadb-operator/mariadb-operator, with 26.10.0 as the current version. MariaDB 12.3.3 is the default database image. MaxScale defaults to version 23.08.13-2, and mysqld-exporter defaults to v0.15.1. There are no explicit install commands in the README itself; the full Helm and OLM setup steps are in docs/helm.md.

Physical and logical backup paths each have their own storage options

Physical backups use mariadb-backup, which is MariaDB's own hot backup tool. Logical backups use mariadb-dump. Physical backups copy the data files and can be faster to restore on large datasets. Logical backups produce SQL output, which is more portable but slower to restore. Both paths are supported.

The storage backends for backup data are S3-compatible storage, Azure Blob Storage, PVCs, Kubernetes volumes, and VolumeSnapshots. That list appears in the README under physical backup documentation. The bootstrap section adds that new instances can be initialized from any of the same sources, so a backup stored in Azure Blob Storage can be used to start a new cluster in a different region.

Backup configuration covers scheduling, compression, encryption with customer-provided keys (SSE-C), a retention policy, a target policy, a timeout, and a staging area. The target recovery time feature restores the closest available backup to a specified time, which requires both a base backup and a stored binary log stream to be in place.

Point-in-time recovery requires binary log archiving to be configured first

PITR is not automatic. As docs/pitr.md explains, binary logs must be collected and shipped to a storage backend before point-in-time restoration is possible. The operator supports archiving binary logs to the same backends as regular backups: S3, Azure Blob Storage, PVCs and VolumeSnapshots. Only after archiving is running does the target recovery time feature have a log stream to work with.

The consequence is that a team that installs the operator without configuring binary log archiving cannot use PITR retroactively. A backup taken before archiving started cannot be supplemented with binary logs from that period, because those logs were never preserved.

The README calls the benefit 'significantly reduce RPO,' where RPO is recovery point objective. The degree of reduction depends entirely on the archiving interval and the backup storage backend, neither of which has a default value documented in the README here.

The UBI MariaDB image requires a different Galera library path than the standard image

The Makefile defines the Galera library path as `MARIADB_GALERA_LIB_PATH ?= /usr/lib/galera/libgalera_smm.so`. The line immediately below it, commented out, reads `# MARIADB_GALERA_LIB_PATH ?= /usr/lib64/galera/libgalera_smm.so`. Alongside those two lines, the standard MariaDB image version is `12.3.3` and the commented-out variant reads `12.3.3-ubi`. Both pairs go together: UBI-based images, which Red Hat builds on the Universal Base Image for OpenShift, install libraries under `/usr/lib64`, while Debian and Alpine-based images use `/usr/lib`.

Any deployment using the UBI MariaDB image with the default Galera library path will find the library absent at `/usr/lib/galera/libgalera_smm.so`, and Galera will not initialize. This detail appears nowhere in the README: it is visible only in the Makefile's commented-out lines. Teams deploying on OpenShift with UBI images need to change both the MariaDB image to the `-ubi` variant and the Galera library path to `/usr/lib64/galera/libgalera_smm.so`.

cert-manager and prometheus-operator integrations each require a prior install

The operator has native integration with cert-manager: when cert-manager is present in the cluster, the operator automatically creates Certificate resources for TLS and handles rotation. Root password rotation works separately by watching for changes to the referenced Kubernetes Secret and reapplying automatically.

Prometheus integration works through mysqld-exporter v0.15.1 and a MaxScale exporter. When prometheus-operator is present, the operator creates ServiceMonitor resources automatically. Both integrations are additive: cert-manager and prometheus-operator must already be installed, because the mariadb-operator does not install either.

The operator also supports an SQL resource layer: users, grants and logical databases can be declared as CRDs in the same way as the MariaDB instance itself. SQL scripts can be orchestrated and scheduled through a CRD called sqljobs. Managing resources in external MariaDB instances that were not provisioned by the operator is supported through the ExternalMariaDB resource kind.

Validation webhooks enforce CRD immutability, which prevents accidental changes to fields that should not change after creation. The degree to which this constraint can be relaxed without editing the CRD definitions is not documented in the repository.

Editorial conclusion

mariadb-operator suits Kubernetes and OpenShift teams that want database provisioning and lifecycle management to follow the same declarative workflow as their application deployments. Teams outside of Kubernetes have no use for it, because the entire management surface is CRDs. Before adopting it, verify that your target Kubernetes version is compatible with k8s.io/api v0.36.1. If you plan to use Galera on OpenShift with UBI-based MariaDB images, confirm whether your image installs the Galera library under /usr/lib or /usr/lib64, because the operator defaults to /usr/lib/galera/libgalera_smm.so and a mismatch will prevent Galera from initializing.

Frequently asked questions

Official sources

1. License: MIT
2. mariadb-operator/mariadb-operator on GitHub
3. Project website
4. README
5. Releases