Skip to main content
Version: Preview



An addon is an efficient and open extension mechanism. With the KubeBlocks addon, developers can quickly add a new database engine to KubeBlocks and obtain specific foundational management functionalities of that database engine, including but not limited to lifecycle management, data backup and recovery, metrics and log collection, etc.


An ActionSet declares a set of commands to perform backup and restore operations using specific tools, such as commands to backup MySQL using xtrabackup, as well as commands to restore data from the backup.


A BackupPolicy represents a backup strategy for a Cluster, including details such as the backup repository (BackupRepo), backup targets, and backup methods. Multiple backup methods can be defined within a backup policy, with each method referring to a corresponding ActionSet. When creating a backup, the backup policy and backup method can be specified for the backup process.


BackupRepo is the storage repository for backup data. Its principle involves using a CSI driver to upload backup data to various storage systems, such as object storage systems like S3, GCS, as well as storage servers like FTP, NFS, and others.


BackupSchedule declares the configuration for automatic backups in a Cluster, including backup frequency, retention period, backup policy, and backup method. The BackupSchedule Controller creates a CronJob to automatically backup the Cluster based on the configuration specified in the Custom Resource (CR).


Cluster is composed by components.


A component is the fundamental assembly component used to build a data storage and processing system. A Component utilizes a StatefulSet (either native to Kubernetes or specified by the customer, such as OpenKruise) to manage one to multiple Pods.


ComponentRef is used to select the component and its fields to be referenced.


KubeBlocks abstracts engine configuration files into ConfigConstraints to better support configuration changes. The abstracted information within ConfigConstraints includes the following content:

  • the format of the configuration file;
  • the dynamic and static parameters and the immutable parameters;
  • the dynamically changing parameters;
  • the parameter parity rules.
CRD (Custom Resource Definition)

CRD (Custom Resource Definition) extends the Kubernetes API, empowering developers to introduce new data types and objects known as custom resources.


Operator, a type of custom resource, automates tasks typically performed by human operators when managing one or more applications or services. By ensuring that a resource's defined state consistently aligns with its observed state, an operator supports Kubernetes in its management responsibilities.


Ops is short for "Operations," representing database maintenance operations. It defines the operations tasks related to database management, specifying which operations are supported by the cluster and components.


An OpsRequest represents a single operation request.

RBAC (Role-Based Access Control)

RBAC (Role-Based Access Control), also known as role-based security, is a methodology employed in computer systems security to limit access to a system's network and resources exclusively to authorized users. Kubernetes features a built-in API for managing roles within namespaces and clusters, enabling their association with specific resources and individuals.

RSM (ReplicatedStateMachines)

ReplicatedStateMachines is a workload that manages native Kubernetes objects such as StatefulSet and Pods.


The ServiceDescriptor is a Custom Resource (CR) object used to describe API objects that reference storage services. It allows users to abstract a service provided either by Kubernetes or non-Kubernetes environments, making it available for referencing by other Cluster objects within KubeBlocks. The "ServiceDescriptor" can be used to address issues such as service dependencies, component dependencies, and component sharing within KubeBlocks.

The management of containerized distributed database by KubeBlocks is mapped to objects at four levels: Cluster, Component, InstanceSet, and Instance, forming a layered architecture:

Cluster layer

A Cluster object represents a complete distributed database cluster. Cluster is the top-level abstraction, including all components and services of the database.

Component layer

A Component represents logical components that make up the Cluster object, such as metadata management, data storage, query engine, etc. Each Component object has its specific task and functions. A Cluster object contains one or more Component objects.

InstanceSet layer

An InstanceSet object manages the workload required for multiple replicas inside a Component object, perceiving the roles of the replicas. A Component object contains an InstanceSet object.

Instance layer

An Instance object represents an actual running instance within an InstanceSet object, corresponding to a Pod in Kubernetes. An InstanceSet object can manage zero to multiple Instance objects.


ComponentDefinition is an API used to define components of a distributed database, describing the implementation details and behavior of the components. With ComponentDefinition, you can define key information about components such as container images, configuration templates, startup scripts, storage volumes, etc. They can also set the behavior and logic of components for different events (e.g., node joining, node leaving, addition of components, removal of components, role switching, etc.). Each component can have its own independent ComponentDefinition or share the same ComponentDefinition.


ClusterDefinition is an API used to define the overall structure and topology of a distributed database cluster. Within ClusterDefinition, you can reference ComponentDefinitions of its included components, and define dependencies and references between components.