# KubeBlocks: one operator and one CRD set for many database engines on Kubernetes

> A Kubernetes operator from ApeCloud that replaces per-database operators with a single abstraction layer, backed by addons for 35 engines. It reads like an operator framework, and the alpha maturity badge says the framework is still settling.

**apecloud/kubeblocks** — KubeBlocks is a Kubernetes Operator designed to manage a variety of databases and streaming systems, including MySQL, PostgreSQL, MongoDB, Redis, RabbitMQ, RocketMQ, and more, within Kubernetes environments.

- Repository: https://github.com/apecloud/kubeblocks
- Website: https://kubeblocks.io
- Stars: 3,140 · Forks: 280
- Language: Go
- License: AGPL-3.0
- Published: 2026-10-06 · Updated: 2026-10-06 · Language: en
- Canonical page: https://hysenlabs.com/projects/apecloud-kubeblocks

## One CRD set across relational, cache, queue and vector engines

The motivating problem in the README is stated plainly, and it is worth restating because it defines the whole project. If your application uses several kinds of database and you plan to run both the application and the databases on Kubernetes, you need a separate operator for each engine. Each one has its own CRDs, its own annotations, its own upgrade procedure, and its own failure modes to learn.

KubeBlocks replaces that with a single abstraction. The README's example is that the same `Cluster` resource can create a PostgreSQL cluster, a Redis cluster or a Kafka cluster. One resource, many engines, and the operator code that reconciles them is shared rather than forked per vendor.

The supported list is broader than the storage categories alone would suggest. The README names RDBMS engines (MySQL, PostgreSQL), caches (Redis), NoSQL (MongoDB), message queues (Kafka, Pulsar), vector databases (Milvus, Qdrant, Weaviate) and data warehouses or search (ClickHouse, ElasticSearch, OpenSearch, Doris, StarRocks), and states that it currently supports 35 types of engine. The `examples/` directory in the repository carries a matching sample per engine for MySQL, PostgreSQL, Redis, MongoDB, Kafka, RabbitMQ, Milvus, Qdrant and ElasticSearch, which is the quickest way to see what a real resource looks like.

The repository layout follows the standard operator shape, with `apis/` for the CRD types, `controllers/` for the reconcile loops, `config/` for the Kubernetes manifests, `deploy/`, `hack/`, `pkg/` and a `version/` directory. That structure is standard, but the scale is not: one operator core serving nine different example directories in a single tree.

## Addons live in a second repository, not in this one

The design decision that most affects how you evaluate the project is where engine-specific code actually lives. The README is explicit that adding a new engine is done by writing a KubeBlocks addon, and the addon table it publishes points every engine at the separate `apecloud/kubeblocks-addons` repository, with a directory per engine such as `addons/clickhouse` and `addons/elasticsearch`.

So the abstraction is real but it is split across two codebases. This repository holds the control plane: the CRDs, the controllers, the shared day-2 logic, the CLI plumbing and the addon framework that loads engine definitions. The addons repository holds the knowledge of how each database is actually configured and started. A new engine means new code in the second repository, which means the breadth you see in the README is breadth you do not read in this tree.

Each listed addon also has a dedicated landing page on kubeblocks.io that documents the operator and engine capabilities. That is where the per-engine detail belongs, and it is worth reading before you assume a given engine is as complete as MySQL. The README describes the community as actively integrating more engines, and given the AGPL-3.0 licence and the young version numbers, this is a project whose coverage will change faster than its core API.

## Day-2 operations through kbcli next to plain YAML

KubeBlocks does not hide `kubectl`. The API is declarative and YAML based, and a `Cluster` resource for a PostgreSQL cluster is something you can read, diff and put in Git. On top of that sits `kbcli`, an interactive command line tool the README frames as a complement to `kubectl` rather than a replacement.

The set of day-2 operations the README calls out is the real test of an operator: upgrading, scaling, monitoring, backup and restore. That list is exactly what separates a database operator from a deployment tool, and it is the part most worth checking against your own runbook. Scaling a stateful engine means rebalancing data, and scaling down means making sure per-pod Services and persistent identities are handled correctly.

The release notes show that last part is still a live problem. v1.0.3-beta.14, published on 2026-09-15, contains a single fix: retaining per-pod services during scale-in. That is a small change on paper and an outage-shaped change in practice, because a scale-in that drops the headless service leaves remaining replicas unable to find each other. The presence of the fix tells you more about the current state of the operator than any claim in the README does.

A second release from the same day, v1.1.0-beta.12, adds automatic rerendering of configurations when resource requests change. It is a small feature with a large blast radius in the sense that a configuration template re-rendered on every resource edit is exactly the kind of behaviour you want to understand before you let it touch production parameters.

## High availability comes from the patterns each community already uses

KubeBlocks does not invent a replication model per engine. The README lists the mature high availability practices it integrates, and they are recognisable names from the individual database communities: Orchestrator for MySQL, Patroni for PostgreSQL, Sentinel for Redis. Each engine keeps the consensus or leader election mechanism its own community has already debugged, and the operator's job is to wire it into Kubernetes lifecycle events.

Backup is where the operator adds something engines usually do not have for you. The README claims full backups, continuous backups and point-in-time recovery. The dependency list supports that story: `go.mod` pulls in both `github.com/kubernetes-csi/external-snapshotter/client/v3` and the v6 client, which is the CSI volume snapshot API, so volume-level snapshots are the mechanism underneath those features rather than a hand-written file copy.

Two other dependencies say interesting things about the design. `github.com/authzed/controller-idioms` suggests the project has settled on a mature pattern for controller authorization and RBAC rather than rolling its own. `github.com/google/cel-go` brings in the Common Expression Language, which is the usual choice when a controller needs a policy language evaluable at admission or inside a reconcile decision instead of in Go code.

## CUE, gRPC and Prometheus are what the control plane is built from

Reading `go.mod` is the fastest way to understand the shape of a Go operator, and KubeBlocks is conventional in its foundations. The module targets a recent toolchain:

```go
module github.com/apecloud/kubeblocks
go 1.25.0
toolchain go1.25.13
```

It depends on the Kubernetes client libraries at v0.29.14, which is worth noting on its own: a project building against Kubernetes 1.29 APIs while compiling with a much newer Go toolchain is a deliberate compatibility choice, and it tells you which cluster versions to test against.

Configuration templating is done with `cuelang.org/go` alongside the Sprig function library, which is how a single parameter schema can drive per-engine config files across 35 engines. Serving and internals use gRPC and protobuf, `spf13/viper` for configuration, `fasthttp/router` for HTTP, and `go.uber.org/zap` for logging. For observability there is `prometheus/client_golang`, matching the README's claim that metrics integrate with the Prometheus stack alongside provided Grafana templates. Tests use Ginkgo and Gomega, and the `Makefile` sets `SHELL = /usr/bin/env bash -o pipefail` with `.SHELLFLAGS = -ec` so that a failing recipe line stops the build, which is required for its envtest-based test target.

The `Makefile` also carries a `VERSION ?= 1.0.0-alpha.0` default alongside `APP_NAME = kubeblocks`, and the repository has an OpenSSF Best Practices badge plus CodeQL and Codecov badges in the README.

## Two beta lines and an alpha badge describe the maturity honestly

The README carries a maturity badge that reads alpha in red, and the release tags agree with it. The three most recent releases are v1.0.3-beta.15 on 2026-09-17, v1.0.3-beta.14 on 2026-09-15 and v1.1.0-beta.12 on 2026-09-15. Two separate beta lines shipping on the same day is the detail that matters for anyone pinning versions, because it means the project has not yet settled on which line is the forward path.

The project is under AGPL-3.0, which is a meaningful choice for infrastructure software. The AGPL's network clause reaches users who interact with the software over a network, which is a different question from linking a library into a proprietary binary. Anyone distributing a KubeBlocks-based platform should read the licence rather than take this paragraph as legal advice. Source file headers in the repository, for instance the header on the `Makefile` and on `go.mod`, carry the Apache 2.0 boilerplate, and the tree includes both `LICENSE` and `LICENSING.md`, so the licensing files are worth reading directly.

The governance files are present too: `GOVERNANCE.md`, `CODE_OF_CONDUCT.md`, `MAINTAINERS.md` and `SECURITY.md`, alongside a `PROJECT` file and a `.golangci.yaml` for lint configuration. The repository is not archived and the last push was on 2026-09-23. Whether that pace translates into operational stability for your specific engine combination is a question only the addon documentation and the release notes for that engine can answer.

## Conclusion

KubeBlocks is aimed at teams running several database engines on Kubernetes who are tired of learning one operator API per engine, and the per-pod service bug fixed in v1.0.3-beta.14 is exactly the class of problem this project exists to solve. It is the wrong choice if you run one database and are happy with its vendor operator, since you would be trading a well-understood API for a wider one. Check three things: whether the engine you need has a maintained addon in kubeblocks-addons, which beta line your installation would track given that both 1.0.3 and 1.1.0 tags shipped on 2026-09-15, and what the AGPL-3.0 licence means for your distribution model. Start with the install guide at kubeblocks.io and one of the per-engine example directories under `examples/` before wiring anything into production.

## FAQ

### What is KubeBlocks used for on Kubernetes?

It is a control plane for running many kinds of database on Kubernetes through one set of custom resource definitions. Instead of learning a separate operator API for MySQL, PostgreSQL, Redis and Kafka, you use the same `Cluster` resource and the same operator, with engine-specific behaviour supplied by addons.

### Which database engines does KubeBlocks support?

The README lists relational engines such as MySQL and PostgreSQL, Redis, MongoDB, Kafka and Pulsar, vector databases including Milvus, Qdrant and Weaviate, and search or warehouse engines including ClickHouse, ElasticSearch, OpenSearch, Doris and StarRocks, and states that 35 engine types are supported in total. The engine implementations live in the separate kubeblocks-addons repository.

### How do you add a new database engine to KubeBlocks?

By writing an addon. The addon mechanism is the extension point described in the README, and each addon lives in its own directory under the `apecloud/kubeblocks-addons` repository, with a matching landing page on kubeblocks.io documenting what that engine supports.

## Sources

- [apecloud/kubeblocks on GitHub](https://github.com/apecloud/kubeblocks)
- [License: AGPL-3.0](https://github.com/apecloud/kubeblocks/blob/main/LICENSE)
- [Project website](https://kubeblocks.io)
- [README](https://github.com/apecloud/kubeblocks/blob/main/README.md)
- [Releases](https://github.com/apecloud/kubeblocks/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/apecloud-kubeblocks