Cluster API Reference

Packages:

• apps.kubeblocks.io/v1
• apps.kubeblocks.io/v1alpha1
• apps.kubeblocks.io/v1beta1
• workloads.kubeblocks.io/v1
• workloads.kubeblocks.io/v1alpha1

apps.kubeblocks.io/v1

Resource Types:

• Cluster
• ClusterDefinition
• Component
• ComponentDefinition
• ComponentVersion
• ServiceDescriptor
• ShardingDefinition
• SidecarDefinition

Cluster

Cluster offers a unified management interface for a wide variety of database and storage systems:

• Relational databases: MySQL, PostgreSQL, MariaDB

• NoSQL databases: Redis, MongoDB

• KV stores: ZooKeeper, etcd

• Analytics systems: ElasticSearch, OpenSearch, ClickHouse, Doris, StarRocks, Solr

• Message queues: Kafka, Pulsar

• Distributed SQL: TiDB, OceanBase

• Vector databases: Qdrant, Milvus, Weaviate

• Object storage: Minio

KubeBlocks utilizes an abstraction layer to encapsulate the characteristics of these diverse systems. A Cluster is composed of multiple Components, each defined by vendors or KubeBlocks Addon developers via ComponentDefinition, arranged in Directed Acyclic Graph (DAG) topologies. The topologies, defined in a ClusterDefinition, coordinate reconciliation across Cluster’s lifecycle phases: Creating, Running, Updating, Stopping, Stopped, Deleting. Lifecycle management ensures that each Component operates in harmony, executing appropriate actions at each lifecycle stage.

For sharded-nothing architecture, the Cluster supports managing multiple shards, each shard managed by a separate Component, supporting dynamic resharding.

The Cluster object is aimed to maintain the overall integrity and availability of a database cluster, serves as the central control point, abstracting the complexity of multiple-component management, and providing a unified interface for cluster-wide operations.

Field	Description
apiVersion string	apps.kubeblocks.io/v1
kind string	Cluster
metadata Kubernetes meta/v1.ObjectMeta	Refer to the Kubernetes API documentation for the fields of the metadata field.
spec ClusterSpec	clusterDef string (Optional) Specifies the name of the ClusterDefinition to use when creating a Cluster. This field enables users to create a Cluster based on a specific ClusterDefinition. Which, in conjunction with the topology field, determine: The Components to be included in the Cluster. The sequences in which the Components are created, updated, and terminate. This facilitates multiple-components management with predefined ClusterDefinition. Users with advanced requirements can bypass this general setting and specify more precise control over the composition of the Cluster by directly referencing specific ComponentDefinitions for each component within componentSpecs[*].componentDef. If this field is not provided, each component must be explicitly defined in componentSpecs[*].componentDef. Note: Once set, this field cannot be modified; it is immutable. topology string (Optional) Specifies the name of the ClusterTopology to be used when creating the Cluster. This field defines which set of Components, as outlined in the ClusterDefinition, will be used to construct the Cluster based on the named topology. The ClusterDefinition may list multiple topologies under clusterdefinition.spec.topologies[*], each tailored to different use cases or environments. If topology is not specified, the Cluster will use the default topology defined in the ClusterDefinition. Note: Once set during the Cluster creation, the topology field cannot be modified. It establishes the initial composition and structure of the Cluster and is intended for one-time configuration. terminationPolicy TerminationPolicyType Specifies the behavior when a Cluster is deleted. It defines how resources, data, and backups associated with a Cluster are managed during termination. Choose a policy based on the desired level of resource cleanup and data preservation: DoNotTerminate: Prevents deletion of the Cluster. This policy ensures that all resources remain intact. Delete: Deletes all runtime resources belong to the Cluster. WipeOut: An aggressive policy that deletes all Cluster resources, including volume snapshots and backups in external storage. This results in complete data removal and should be used cautiously, primarily in non-production environments to avoid irreversible data loss. Warning: Choosing an inappropriate termination policy can result in data loss. The WipeOut policy is particularly risky in production environments due to its irreversible nature. componentSpecs []ClusterComponentSpec (Optional) Specifies a list of ClusterComponentSpec objects used to define the individual Components that make up a Cluster. This field allows for detailed configuration of each Component within the Cluster. Note: shardings and componentSpecs cannot both be empty; at least one must be defined to configure a Cluster. shardings []ClusterSharding (Optional) Specifies a list of ClusterSharding objects that manage the sharding topology for Cluster Components. Each ClusterSharding organizes components into shards, with each shard corresponding to a Component. Components within a shard are all based on a common ClusterComponentSpec template, ensuring uniform configurations. This field supports dynamic resharding by facilitating the addition or removal of shards through the shards field in ClusterSharding. Note: shardings and componentSpecs cannot both be empty; at least one must be defined to configure a Cluster. runtimeClassName string (Optional) Specifies runtimeClassName for all Pods managed by this Cluster. schedulingPolicy SchedulingPolicy (Optional) Specifies the scheduling policy for the Cluster. services []ClusterService (Optional) Defines a list of additional Services that are exposed by a Cluster. This field allows Services of selected Components, either from componentSpecs or shardings to be exposed, alongside Services defined with ComponentService. Services defined here can be referenced by other clusters using the ServiceRefClusterSelector. backup ClusterBackup (Optional) Specifies the backup configuration of the Cluster.
status ClusterStatus

ClusterDefinition

ClusterDefinition defines the topology for databases or storage systems, offering a variety of topological configurations to meet diverse deployment needs and scenarios.

It includes a list of Components and/or Shardings, each linked to a ComponentDefinition or a ShardingDefinition, which enhances reusability and reduce redundancy. For example, widely used components such as etcd and Zookeeper can be defined once and reused across multiple ClusterDefinitions, simplifying the setup of new systems.

Additionally, ClusterDefinition also specifies the sequence of startup, upgrade, and shutdown between Components and/or Shardings, ensuring a controlled and predictable management of cluster lifecycles.

Field	Description
apiVersion string	apps.kubeblocks.io/v1
kind string	ClusterDefinition
metadata Kubernetes meta/v1.ObjectMeta	Refer to the Kubernetes API documentation for the fields of the metadata field.
spec ClusterDefinitionSpec	topologies []ClusterTopology (Optional) Topologies defines all possible topologies within the cluster.
status ClusterDefinitionStatus

Component

Component is a fundamental building block of a Cluster object. For example, a Redis Cluster can include Components like ‘redis’, ‘sentinel’, and potentially a proxy like ‘twemproxy’.

The Component object is responsible for managing the lifecycle of all replicas within a Cluster component, It supports a wide range of operations including provisioning, stopping, restarting, termination, upgrading, configuration changes, vertical and horizontal scaling, failover, switchover, cross-node migration, scheduling configuration, exposing Services, managing system accounts, enabling/disabling exporter, and configuring log collection.

Component is an internal sub-object derived from the user-submitted Cluster object. It is designed primarily to be used by the KubeBlocks controllers, users are discouraged from modifying Component objects directly and should use them only for monitoring Component statuses.

Field	Description
apiVersion string	apps.kubeblocks.io/v1
kind string	Component
metadata Kubernetes meta/v1.ObjectMeta	Refer to the Kubernetes API documentation for the fields of the metadata field.
spec ComponentSpec	compDef string Specifies the name of the referenced ComponentDefinition. serviceVersion string (Optional) ServiceVersion specifies the version of the Service expected to be provisioned by this Component. The version should follow the syntax and semantics of the “Semantic Versioning” specification (http://semver.org/). serviceRefs []ServiceRef (Optional) Defines a list of ServiceRef for a Component, enabling access to both external services and Services provided by other Clusters. Types of services: External services: Not managed by KubeBlocks or managed by a different KubeBlocks operator; Require a ServiceDescriptor for connection details. Services provided by a Cluster: Managed by the same KubeBlocks operator; identified using Cluster, Component and Service names. ServiceRefs with identical serviceRef.name in the same Cluster are considered the same. Example: serviceRefs: name: "redis-sentinel" serviceDescriptor: name: "external-redis-sentinel" name: "postgres-cluster" clusterServiceSelector: cluster: "my-postgres-cluster" service: component: "postgresql" The example above includes ServiceRefs to an external Redis Sentinel service and a PostgreSQL Cluster. labels map[string]string (Optional) Specifies Labels to override or add for underlying Pods, PVCs, Account & TLS Secrets, Services Owned by Component. annotations map[string]string (Optional) Specifies Annotations to override or add for underlying Pods, PVCs, Account & TLS Secrets, Services Owned by Component. env []Kubernetes core/v1.EnvVar (Optional) List of environment variables to add. resources Kubernetes core/v1.ResourceRequirements (Optional) Specifies the resources required by the Component. It allows defining the CPU, memory requirements and limits for the Component’s containers. volumeClaimTemplates []ClusterComponentVolumeClaimTemplate (Optional) Specifies a list of PersistentVolumeClaim templates that define the storage requirements for the Component. Each template specifies the desired characteristics of a persistent volume, such as storage class, size, and access modes. These templates are used to dynamically provision persistent volumes for the Component. volumes []Kubernetes core/v1.Volume (Optional) List of volumes to override. services []ComponentService (Optional) Overrides Services defined in referenced ComponentDefinition. systemAccounts []ComponentSystemAccount (Optional) Overrides system accounts defined in referenced ComponentDefinition. replicas int32 Specifies the desired number of replicas in the Component for enhancing availability and durability, or load balancing. configs []ClusterComponentConfig (Optional) Specifies the configuration content of a config template. serviceAccountName string (Optional) Specifies the name of the ServiceAccount required by the running Component. This ServiceAccount is used to grant necessary permissions for the Component’s Pods to interact with other Kubernetes resources, such as modifying Pod labels or sending events. If not specified, KubeBlocks automatically creates a default ServiceAccount named “kb-{componentdefinition.name}”, bound to a role with rules defined in ComponentDefinition’s policyRules field. If needed (currently this means if any lifecycleAction is enabled), it will also be bound to a default role named “kubeblocks-cluster-pod-role”, which is installed together with KubeBlocks. If multiple components use the same ComponentDefinition, they will share one ServiceAccount. If the field is not empty, the specified ServiceAccount will be used, and KubeBlocks will not create a ServiceAccount. But KubeBlocks does create RoleBindings for the specified ServiceAccount. parallelPodManagementConcurrency Kubernetes api utils intstr.IntOrString (Optional) Controls the concurrency of pods during initial scale up, when replacing pods on nodes, or when scaling down. It only used when PodManagementPolicy is set to Parallel. The default Concurrency is 100%. podUpdatePolicy PodUpdatePolicyType (Optional) PodUpdatePolicy indicates how pods should be updated StrictInPlace indicates that only allows in-place upgrades. Any attempt to modify other fields will be rejected. PreferInPlace indicates that we will first attempt an in-place upgrade of the Pod. If that fails, it will fall back to the ReCreate, where pod will be recreated. Default value is “PreferInPlace” schedulingPolicy SchedulingPolicy (Optional) Specifies the scheduling policy for the Component. tlsConfig TLSConfig (Optional) Specifies the TLS configuration for the Component, including: A boolean flag that indicates whether the Component should use Transport Layer Security (TLS) for secure communication. An optional field that specifies the configuration for the TLS certificates issuer when TLS is enabled. It allows defining the issuer name and the reference to the secret containing the TLS certificates and key. The secret should contain the CA certificate, TLS certificate, and private key in the specified keys. instances []InstanceTemplate (Optional) Allows for the customization of configuration values for each instance within a Component. An Instance represent a single replica (Pod and associated K8s resources like PVCs, Services, and ConfigMaps). While instances typically share a common configuration as defined in the ClusterComponentSpec, they can require unique settings in various scenarios: For example: A database Component might require different resource allocations for primary and secondary instances, with primaries needing more resources. During a rolling upgrade, a Component may first update the image for one or a few instances, and then update the remaining instances after verifying that the updated instances are functioning correctly. InstanceTemplate allows for specifying these unique configurations per instance. Each instance’s name is constructed using the pattern: $(component.name)-$(template.name)-$(ordinal), starting with an ordinal of 0. It is crucial to maintain unique names for each InstanceTemplate to avoid conflicts. The sum of replicas across all InstanceTemplates should not exceed the total number of Replicas specified for the Component. Any remaining replicas will be generated using the default template and will follow the default naming rules. offlineInstances []string (Optional) Specifies the names of instances to be transitioned to offline status. Marking an instance as offline results in the following: The associated Pod is stopped, and its PersistentVolumeClaim (PVC) is retained for potential future reuse or data recovery, but it is no longer actively used. The ordinal number assigned to this instance is preserved, ensuring it remains unique and avoiding conflicts with new instances. Setting instances to offline allows for a controlled scale-in process, preserving their data and maintaining ordinal consistency within the Cluster. Note that offline instances and their associated resources, such as PVCs, are not automatically deleted. The administrator must manually manage the cleanup and removal of these resources when they are no longer needed. runtimeClassName string (Optional) Defines runtimeClassName for all Pods managed by this Component. disableExporter bool (Optional) Determines whether metrics exporter information is annotated on the Component’s headless Service. If set to true, the following annotations will not be patched into the Service: “monitor.kubeblocks.io/path” “monitor.kubeblocks.io/port” “monitor.kubeblocks.io/scheme” These annotations allow the Prometheus installed by KubeBlocks to discover and scrape metrics from the exporter. stop bool (Optional) Stop the Component. If set, all the computing resources will be released. sidecars []Sidecar (Optional) Specifies the sidecars to be injected into the Component.
status ComponentStatus

ComponentDefinition

ComponentDefinition serves as a reusable blueprint for creating Components, encapsulating essential static settings such as Component description, Pod templates, configuration file templates, scripts, parameter lists, injected environment variables and their sources, and event handlers. ComponentDefinition works in conjunction with dynamic settings from the ClusterComponentSpec, to instantiate Components during Cluster creation.

Key aspects that can be defined in a ComponentDefinition include:

• PodSpec template: Specifies the PodSpec template used by the Component.

• Configuration templates: Specify the configuration file templates required by the Component.

• Scripts: Provide the necessary scripts for Component management and operations.

• Storage volumes: Specify the storage volumes and their configurations for the Component.

• Pod roles: Outlines various roles of Pods within the Component along with their capabilities.

• Exposed Kubernetes Services: Specify the Services that need to be exposed by the Component.

• System accounts: Define the system accounts required for the Component.

• Monitoring and logging: Configure the exporter and logging settings for the Component.

ComponentDefinitions also enable defining reactive behaviors of the Component in response to events, such as member join/leave, Component addition/deletion, role changes, switch over, and more. This allows for automatic event handling, thus encapsulating complex behaviors within the Component.

Referencing a ComponentDefinition when creating individual Components ensures inheritance of predefined configurations, promoting reusability and consistency across different deployments and cluster topologies.

Field	Description
apiVersion string	apps.kubeblocks.io/v1
kind string	ComponentDefinition
metadata Kubernetes meta/v1.ObjectMeta	Refer to the Kubernetes API documentation for the fields of the metadata field.
spec ComponentDefinitionSpec	provider string (Optional) Specifies the name of the Component provider, typically the vendor or developer name. It identifies the entity responsible for creating and maintaining the Component. When specifying the provider name, consider the following guidelines: Keep the name concise and relevant to the Component. Use a consistent naming convention across Components from the same provider. Avoid using trademarked or copyrighted names without proper permission. description string (Optional) Provides a brief and concise explanation of the Component’s purpose, functionality, and any relevant details. It serves as a quick reference for users to understand the Component’s role and characteristics. serviceKind string (Optional) Defines the type of well-known service protocol that the Component provides. It specifies the standard or widely recognized protocol used by the Component to offer its Services. The serviceKind field allows users to quickly identify the type of Service provided by the Component based on common protocols or service types. This information helps in understanding the compatibility, interoperability, and usage of the Component within a system. Some examples of well-known service protocols include: “MySQL”: Indicates that the Component provides a MySQL database service. “PostgreSQL”: Indicates that the Component offers a PostgreSQL database service. “Redis”: Signifies that the Component functions as a Redis key-value store. “ETCD”: Denotes that the Component serves as an ETCD distributed key-value store. The serviceKind value is case-insensitive, allowing for flexibility in specifying the protocol name. When specifying the serviceKind, consider the following guidelines: Use well-established and widely recognized protocol names or service types. Ensure that the serviceKind accurately represents the primary service type offered by the Component. If the Component provides multiple services, choose the most prominent or commonly used protocol. Limit the serviceKind to a maximum of 32 characters for conciseness and readability. Note: The serviceKind field is optional and can be left empty if the Component does not fit into a well-known service category or if the protocol is not widely recognized. It is primarily used to convey information about the Component’s service type to users and facilitate discovery and integration. The serviceKind field is immutable and cannot be updated. serviceVersion string (Optional) Specifies the version of the Service provided by the Component. It follows the syntax and semantics of the “Semantic Versioning” specification (http://semver.org/). The Semantic Versioning specification defines a version number format of X.Y.Z (MAJOR.MINOR.PATCH), where: X represents the major version and indicates incompatible API changes. Y represents the minor version and indicates added functionality in a backward-compatible manner. Z represents the patch version and indicates backward-compatible bug fixes. Additional labels for pre-release and build metadata are available as extensions to the X.Y.Z format: Use pre-release labels (e.g., -alpha, -beta) for versions that are not yet stable or ready for production use. Use build metadata (e.g., +build.1) for additional version information if needed. Examples of valid ServiceVersion values: “1.0.0” “2.3.1” “3.0.0-alpha.1” “4.5.2+build.1” The serviceVersion field is immutable and cannot be updated. labels map[string]string (Optional) Specifies static labels that will be patched to all Kubernetes resources created for the Component. Note: If a label key in the labels field conflicts with any system labels or user-specified labels, it will be silently ignored to avoid overriding higher-priority labels. This field is immutable. annotations map[string]string (Optional) Specifies static annotations that will be patched to all Kubernetes resources created for the Component. Note: If an annotation key in the annotations field conflicts with any system annotations or user-specified annotations, it will be silently ignored to avoid overriding higher-priority annotations. This field is immutable. runtime Kubernetes core/v1.PodSpec Specifies the PodSpec template used in the Component. It includes the following elements: Init containers Containers Image Commands Args Envs Mounts Ports Security context Probes Lifecycle Volumes This field is intended to define static settings that remain consistent across all instantiated Components. Dynamic settings such as CPU and memory resource limits, as well as scheduling settings (affinity, toleration, priority), may vary among different instantiated Components. They should be specified in the cluster.spec.componentSpecs (ClusterComponentSpec). Specific instances of a Component may override settings defined here, such as using a different container image or modifying environment variable values. These instance-specific overrides can be specified in cluster.spec.componentSpecs[*].instances. This field is immutable and cannot be updated once set. vars []EnvVar (Optional) Defines variables which are determined after Cluster instantiation and reflect dynamic or runtime attributes of instantiated Clusters. These variables serve as placeholders for setting environment variables in Pods and Actions, or for rendering configuration and script templates before actual values are finalized. These variables are placed in front of the environment variables declared in the Pod if used as environment variables. Variable values can be sourced from: ConfigMap: Select and extract a value from a specific key within a ConfigMap. Secret: Select and extract a value from a specific key within a Secret. HostNetwork: Retrieves values (including ports) from host-network resources. Service: Retrieves values (including address, port, NodePort) from a selected Service. Intended to obtain the address of a ComponentService within the same Cluster. Credential: Retrieves account name and password from a SystemAccount variable. ServiceRef: Retrieves address, port, account name and password from a selected ServiceRefDeclaration. Designed to obtain the address bound to a ServiceRef, such as a ClusterService or ComponentService of another cluster or an external service. Component: Retrieves values from a selected Component, including replicas and instance name list. This field is immutable. volumes []ComponentVolume (Optional) Defines the volumes used by the Component and some static attributes of the volumes. After defining the volumes here, user can reference them in the cluster.spec.componentSpecs[*].volumeClaimTemplates field to configure dynamic properties such as volume capacity and storage class. This field allows you to specify the following: Snapshot behavior: Determines whether a snapshot of the volume should be taken when performing a snapshot backup of the Component. Disk high watermark: Sets the high watermark for the volume’s disk usage. When the disk usage reaches the specified threshold, it triggers an alert or action. By configuring these volume behaviors, you can control how the volumes are managed and monitored within the Component. This field is immutable. hostNetwork HostNetwork (Optional) Specifies the host network configuration for the Component. When hostNetwork option is enabled, the Pods share the host’s network namespace and can directly access the host’s network interfaces. This means that if multiple Pods need to use the same port, they cannot run on the same host simultaneously due to port conflicts. The DNSPolicy field in the Pod spec determines how containers within the Pod perform DNS resolution. When using hostNetwork, the operator will set the DNSPolicy to ‘ClusterFirstWithHostNet’. With this policy, DNS queries will first go through the K8s cluster’s DNS service. If the query fails, it will fall back to the host’s DNS settings. If set, the DNS policy will be automatically set to “ClusterFirstWithHostNet”. This field is immutable. services []ComponentService (Optional) Defines additional Services to expose the Component’s endpoints. A default headless Service, named {cluster.name}-{component.name}-headless, is automatically created for internal Cluster communication. This field enables customization of additional Services to expose the Component’s endpoints to other Components within the same or different Clusters, and to external applications. Each Service entry in this list can include properties such as ports, type, and selectors. For intra-Cluster access, Components can reference Services using variables declared in componentDefinition.spec.vars[*].valueFrom.serviceVarRef. For inter-Cluster access, reference Services use variables declared in componentDefinition.spec.vars[*].valueFrom.serviceRefVarRef, and bind Services at Cluster creation time with clusterComponentSpec.ServiceRef[*].clusterServiceSelector. This field is immutable. configs []ComponentConfigSpec (Optional) Specifies the configuration file templates and volume mount parameters used by the Component. It also includes descriptions of the parameters in the ConfigMaps, such as value range limitations. This field specifies a list of templates that will be rendered into Component containers’ configuration files. Each template is represented as a ConfigMap and may contain multiple configuration files, with each file being a key in the ConfigMap. The rendered configuration files will be mounted into the Component’s containers according to the specified volume mount parameters. This field is immutable. logConfigs []LogConfig (Optional) Defines the types of logs generated by instances of the Component and their corresponding file paths. These logs can be collected for further analysis and monitoring. The logConfigs field is an optional list of LogConfig objects, where each object represents a specific log type and its configuration. It allows you to specify multiple log types and their respective file paths for the Component. Examples: logConfigs: filePathPattern: /data/mysql/log/mysqld-error.log name: error filePathPattern: /data/mysql/log/mysqld.log name: general filePathPattern: /data/mysql/log/mysqld-slowquery.log name: slow This field is immutable. scripts []ComponentTemplateSpec (Optional) Specifies groups of scripts, each provided via a ConfigMap, to be mounted as volumes in the container. These scripts can be executed during container startup or via specific actions. Each script group is encapsulated in a ComponentTemplateSpec that includes: The ConfigMap containing the scripts. The mount point where the scripts will be mounted inside the container. This field is immutable. systemAccounts []SystemAccount (Optional) An array of SystemAccount objects that define the system accounts needed for the management operations of the Component. Each SystemAccount includes: Account name. The SQL statement template: Used to create the system account. Password Source: Either generated based on certain rules or retrieved from a Secret. Use cases for system accounts typically involve tasks like system initialization, backups, monitoring, health checks, replication, and other system-level operations. System accounts are distinct from user accounts, although both are database accounts. System Accounts: Created during Cluster setup by the KubeBlocks operator, these accounts have higher privileges for system management and are fully managed through a declarative API by the operator. User Accounts: Managed by users or administrator. User account permissions should follow the principle of least privilege, granting only the necessary access rights to complete their required tasks. This field is immutable. tls TLS (Optional) Specifies the TLS configuration for the Component. This field is immutable. replicasLimit ReplicasLimit (Optional) Defines the upper limit of the number of replicas supported by the Component. It defines the maximum number of replicas that can be created for the Component. This field allows you to set a limit on the scalability of the Component, preventing it from exceeding a certain number of replicas. This field is immutable. available ComponentAvailable (Optional) Specifies the strategies for determining the available status of the Component. This field is immutable. roles []ReplicaRole (Optional) Enumerate all possible roles assigned to each replica of the Component, influencing its behavior. A replica can have zero or one role. KubeBlocks operator determines the role of each replica by invoking the lifecycleActions.roleProbe method. This action returns the role for each replica, and the returned role must be predefined here. The roles assigned to a replica can influence various aspects of the Component’s behavior, such as: Service selection: The Component’s exposed Services may target replicas based on their roles using roleSelector. Update order: The roles can determine the order in which replicas are updated during a Component update. For instance, replicas with a “follower” role can be updated first, while the replica with the “leader” role is updated last. This helps minimize the number of leader changes during the update process. This field is immutable. minReadySeconds int32 (Optional) minReadySeconds is the minimum duration in seconds that a new Pod should remain in the ready state without any of its containers crashing to be considered available. This ensures the Pod’s stability and readiness to serve requests. A default value of 0 seconds means the Pod is considered available as soon as it enters the ready state. updateStrategy UpdateStrategy (Optional) Specifies the concurrency strategy for updating multiple instances of the Component. Available strategies: Serial: Updates replicas one at a time, ensuring minimal downtime by waiting for each replica to become ready before updating the next. Parallel: Updates all replicas simultaneously, optimizing for speed but potentially reducing availability during the update. BestEffortParallel: Updates replicas concurrently with a limit on simultaneous updates to ensure a minimum number of operational replicas for maintaining quorum. For example, in a 5-replica component, updating a maximum of 2 replicas simultaneously keeps at least 3 operational for quorum. This field is immutable and defaults to ‘Serial’. podManagementPolicy Kubernetes apps/v1.PodManagementPolicyType (Optional) InstanceSet controls the creation of pods during initial scale up, replacement of pods on nodes, and scaling down. OrderedReady: Creates pods in increasing order (pod-0, then pod-1, etc). The controller waits until each pod is ready before continuing. Pods are removed in reverse order when scaling down. Parallel: Creates pods in parallel to match the desired scale without waiting. All pods are deleted at once when scaling down. policyRules []Kubernetes rbac/v1.PolicyRule (Optional) Defines the namespaced policy rules required by the Component. The policyRules field is an array of rbacv1.PolicyRule objects that define the policy rules needed by the Component to operate within a namespace. These policy rules determine the permissions and verbs the Component is allowed to perform on Kubernetes resources within the namespace. The purpose of this field is to automatically generate the necessary RBAC roles for the Component based on the specified policy rules. This ensures that the Pods in the Component has appropriate permissions to function. This field is immutable. lifecycleActions ComponentLifecycleActions (Optional) Defines a set of hooks and procedures that customize the behavior of a Component throughout its lifecycle. Actions are triggered at specific lifecycle stages: postProvision: Defines the hook to be executed after the creation of a Component, with preCondition specifying when the action should be fired relative to the Component’s lifecycle stages: Immediately, RuntimeReady, ComponentReady, and ClusterReady. preTerminate: Defines the hook to be executed before terminating a Component. roleProbe: Defines the procedure which is invoked regularly to assess the role of replicas. switchover: Defines the procedure for a controlled transition of a role to a new replica. This approach aims to minimize downtime and maintain availability in systems with a leader-follower topology, such as before planned maintenance or upgrades on the current leader node. memberJoin: Defines the procedure to add a new replica to the replication group. memberLeave: Defines the method to remove a replica from the replication group. readOnly: Defines the procedure to switch a replica into the read-only state. readWrite: transition a replica from the read-only state back to the read-write state. dataDump: Defines the procedure to export the data from a replica. dataLoad: Defines the procedure to import data into a replica. reconfigure: Defines the procedure that update a replica with new configuration file. accountProvision: Defines the procedure to generate a new database account. This field is immutable. serviceRefDeclarations []ServiceRefDeclaration (Optional) Lists external service dependencies of the Component, including services from other Clusters or outside the K8s environment. This field is immutable. exporter Exporter (Optional) Defines the built-in metrics exporter container.
status ComponentDefinitionStatus

ComponentVersion

ComponentVersion is the Schema for the componentversions API

Field	Description
apiVersion string	apps.kubeblocks.io/v1
kind string	ComponentVersion
metadata Kubernetes meta/v1.ObjectMeta	Refer to the Kubernetes API documentation for the fields of the metadata field.
spec ComponentVersionSpec	compatibilityRules []ComponentVersionCompatibilityRule CompatibilityRules defines compatibility rules between sets of component definitions and releases. releases []ComponentVersionRelease Releases represents different releases of component instances within this ComponentVersion.
status ComponentVersionStatus

ServiceDescriptor

ServiceDescriptor describes a service provided by external sources. It contains the necessary details such as the service’s address and connection credentials. To enable a Cluster to access this service, the ServiceDescriptor’s name should be specified in the Cluster configuration under clusterComponent.serviceRefs[*].serviceDescriptor.

Field	Description
apiVersion string	apps.kubeblocks.io/v1
kind string	ServiceDescriptor
metadata Kubernetes meta/v1.ObjectMeta	Refer to the Kubernetes API documentation for the fields of the metadata field.
spec ServiceDescriptorSpec	serviceKind string Describes the type of database service provided by the external service. For example, “mysql”, “redis”, “mongodb”. This field categorizes databases by their functionality, protocol and compatibility, facilitating appropriate service integration based on their unique capabilities. This field is case-insensitive. It also supports abbreviations for some well-known databases: “pg”, “pgsql”, “postgres”, “postgresql”: PostgreSQL service “zk”, “zookeeper”: ZooKeeper service “es”, “elasticsearch”: Elasticsearch service “mongo”, “mongodb”: MongoDB service “ch”, “clickhouse”: ClickHouse service serviceVersion string Describes the version of the service provided by the external service. This is crucial for ensuring compatibility between different components of the system, as different versions of a service may have varying features. endpoint CredentialVar (Optional) Specifies the endpoint of the external service. If the service is exposed via a cluster, the endpoint will be provided in the format of host:port. host CredentialVar (Optional) Specifies the service or IP address of the external service. port CredentialVar (Optional) Specifies the port of the external service. podFQDNs CredentialVar (Optional) Specifies the pod FQDNs of the external service. auth ConnectionCredentialAuth (Optional) Specifies the authentication credentials required for accessing an external service.
status ServiceDescriptorStatus

ShardingDefinition

ShardingDefinition is the Schema for the shardingdefinitions API

Field	Description
apiVersion string	apps.kubeblocks.io/v1
kind string	ShardingDefinition
metadata Kubernetes meta/v1.ObjectMeta	Refer to the Kubernetes API documentation for the fields of the metadata field.
spec ShardingDefinitionSpec	template ShardingTemplate This field is immutable. shardsLimit ShardsLimit (Optional) Defines the upper limit of the number of shards supported by the sharding. This field is immutable. provisionStrategy UpdateStrategy (Optional) Specifies the strategy for provisioning shards of the sharding. Only Serial and Parallel are supported. This field is immutable. updateStrategy UpdateStrategy (Optional) Specifies the strategy for updating shards of the sharding. Only Serial and Parallel are supported. This field is immutable. lifecycleActions ShardingLifecycleActions (Optional) Defines a set of hooks and procedures that customize the behavior of a sharding throughout its lifecycle. This field is immutable. systemAccounts []ShardingSystemAccount (Optional) Defines the system accounts for the sharding. This field is immutable. tls ShardingTLS (Optional) Defines the TLS for the sharding. This field is immutable.
status ShardingDefinitionStatus

SidecarDefinition

SidecarDefinition is the Schema for the sidecardefinitions API

Field	Description
apiVersion string	apps.kubeblocks.io/v1
kind string	SidecarDefinition
metadata Kubernetes meta/v1.ObjectMeta	Refer to the Kubernetes API documentation for the fields of the metadata field.
spec SidecarDefinitionSpec	name string Specifies the name of the sidecar. owner string Specifies the component definition that the sidecar belongs to. For a specific cluster object, if there is any components provided by the component definition of @owner, the sidecar will be created and injected into the components which are provided by the component definition of @selectors automatically. This field is immutable. selectors []string Specifies the component definition of components that the sidecar along with. This field is immutable. containers []Kubernetes core/v1.Container List of containers for the sidecar. Cannot be updated. vars []EnvVar (Optional) Defines variables which are needed by the sidecar. This field is immutable. configs []ComponentTemplateSpec (Optional) Specifies the configuration file templates used by the Sidecar. This field is immutable. scripts []ComponentTemplateSpec (Optional) Specifies the scripts used by the Sidecar. This field is immutable.
status SidecarDefinitionStatus

Action

(Appears on:ComponentLifecycleActions, Probe, ShardingLifecycleActions, MembershipReconfiguration)

Action defines a customizable hook or procedure tailored for different database engines, designed to be invoked at predetermined points within the lifecycle of a Component instance. It provides a modular and extensible way to customize a Component’s behavior through the execution of defined actions.

Available Action triggers include:

• postProvision: Defines the hook to be executed after the creation of a Component, with preCondition specifying when the action should be fired relative to the Component’s lifecycle stages: Immediately, RuntimeReady, ComponentReady, and ClusterReady.

• preTerminate: Defines the hook to be executed before terminating a Component.

• roleProbe: Defines the procedure which is invoked regularly to assess the role of replicas.

• switchover: Defines the procedure for a controlled transition of a role to a new replica.

• memberJoin: Defines the procedure to add a new replica to the replication group.

• memberLeave: Defines the method to remove a replica from the replication group.

• readOnly: Defines the procedure to switch a replica into the read-only state.

• readWrite: Defines the procedure to transition a replica from the read-only state back to the read-write state.

• dataDump: Defines the procedure to export the data from a replica.

• dataLoad: Defines the procedure to import data into a replica.

• reconfigure: Defines the procedure that update a replica with new configuration.

• accountProvision: Defines the procedure to generate a new database account.

Actions can be executed in different ways:

• ExecAction: Executes a command inside a container. A set of predefined environment variables are available and can be leveraged within the exec.command to access context information such as details about pods, components, the overall cluster state, or database connection credentials. These variables provide a dynamic and context-aware mechanism for script execution.

• HTTPAction: Performs an HTTP request. HTTPAction is to be implemented in future version.

• GRPCAction: In future version, Actions will support initiating gRPC calls. This allows developers to implement Actions using plugins written in programming language like Go, providing greater flexibility and extensibility.

An action is considered successful on returning 0, or HTTP 200 for status HTTP(s) Actions. Any other return value or HTTP status codes indicate failure, and the action may be retried based on the configured retry policy.

• If an action exceeds the specified timeout duration, it will be terminated, and the action is considered failed.

• If an action produces any data as output, it should be written to stdout, or included in the HTTP response payload for HTTP(s) actions.

• If an action encounters any errors, error messages should be written to stderr, or detailed in the HTTP response with the appropriate non-200 status code.

Field	Description
exec ExecAction	(Optional) Defines the command to run. This field cannot be updated.
timeoutSeconds int32	(Optional) Specifies the maximum duration in seconds that the Action is allowed to run. If the Action does not complete within this time frame, it will be terminated. This field cannot be updated.
retryPolicy RetryPolicy	(Optional) Defines the strategy to be taken when retrying the Action after a failure. It specifies the conditions under which the Action should be retried and the limits to apply, such as the maximum number of retries and backoff strategy. This field cannot be updated.
preCondition PreConditionType	(Optional) Specifies the state that the cluster must reach before the Action is executed. Currently, this is only applicable to the postProvision action. The conditions are as follows: Immediately: Executed right after the Component object is created. The readiness of the Component and its resources is not guaranteed at this stage. RuntimeReady: The Action is triggered after the Component object has been created and all associated runtime resources (e.g. Pods) are in a ready state. ComponentReady: The Action is triggered after the Component itself is in a ready state. This process does not affect the readiness state of the Component or the Cluster. ClusterReady: The Action is executed after the Cluster is in a ready state. This execution does not alter the Component or the Cluster’s state of readiness. This field cannot be updated.

ActionAssertion

(Appears on:ComponentAvailableProbeAssertion)

ActionAssertion defines the custom assertions for evaluating the success or failure of an action.

Field	Description
succeed bool	(Optional) Whether the action should succeed or fail. This field is immutable once set.
stdout ActionOutputMatcher	(Optional) Specifies the stdout matcher for the action. This field is immutable once set.
stderr ActionOutputMatcher	(Optional) Specifies the stderr matcher for the action. This field is immutable once set.

ActionOutputMatcher

(Appears on:ActionAssertion)

ActionOutputMatcher defines the matcher for the output of an action.

Field	Description
equalTo string	(Optional) The output of the action should be equal to the specified value. This field is immutable once set.
contains string	(Optional) The output of the action should contain the specified value. This field is immutable once set.

ClusterBackup

(Appears on:ClusterSpec)

Field	Description
enabled bool	(Optional) Specifies whether automated backup is enabled for the Cluster.
retentionPeriod github.com/apecloud/kubeblocks/apis/dataprotection/v1alpha1.RetentionPeriod	(Optional) Determines the duration to retain backups. Backups older than this period are automatically removed. For example, RetentionPeriod of 30d will keep only the backups of last 30 days. Sample duration format: years: 2y months: 6mo days: 30d hours: 12h minutes: 30m You can also combine the above durations. For example: 30d12h30m. Default value is 7d.
method string	Specifies the backup method to use, as defined in backupPolicy.
cronExpression string	(Optional) The cron expression for the schedule. The timezone is in UTC. See https://en.wikipedia.org/wiki/Cron.
startingDeadlineMinutes int64	(Optional) Specifies the maximum time in minutes that the system will wait to start a missed backup job. If the scheduled backup time is missed for any reason, the backup job must start within this deadline. Values must be between 0 (immediate execution) and 1440 (one day).
repoName string	(Optional) Specifies the name of the backupRepo. If not set, the default backupRepo will be used.
pitrEnabled bool	(Optional) Specifies whether to enable point-in-time recovery.
incrementalBackupEnabled bool	(Optional) Specifies whether to enable incremental backup.
incrementalCronExpression string	(Optional) The cron expression for the incremental backup schedule. The timezone is in UTC. See https://en.wikipedia.org/wiki/Cron.

ClusterComponentConfig

(Appears on:ClusterComponentSpec, ComponentSpec)

ClusterComponentConfig represents a config with its source bound.

Field	Description
name string	(Optional) The name of the config.
ClusterComponentConfigSource ClusterComponentConfigSource	(Members of ClusterComponentConfigSource are embedded into this type.) The source of the config.

ClusterComponentConfigSource

(Appears on:ClusterComponentConfig)

ClusterComponentConfigSource represents the source of a config.

Field	Description
configMap Kubernetes core/v1.ConfigMapVolumeSource	(Optional) ConfigMap source for the config.

ClusterComponentService

(Appears on:ClusterComponentSpec)

Field	Description
name string	References the ComponentService name defined in the componentDefinition.spec.services[*].name.
serviceType Kubernetes core/v1.ServiceType	(Optional) Determines how the Service is exposed. Valid options are ClusterIP, NodePort, and LoadBalancer. ClusterIP allocates a Cluster-internal IP address for load-balancing to endpoints. Endpoints are determined by the selector or if that is not specified, they are determined by manual construction of an Endpoints object or EndpointSlice objects. NodePort builds on ClusterIP and allocates a port on every node which routes to the same endpoints as the ClusterIP. LoadBalancer builds on NodePort and creates an external load-balancer (if supported in the current cloud) which routes to the same endpoints as the ClusterIP. Note: although K8s Service type allows the ‘ExternalName’ type, it is not a valid option for ClusterComponentService. For more info, see: https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services-service-types.
annotations map[string]string	(Optional) If ServiceType is LoadBalancer, cloud provider related parameters can be put here. More info: https://kubernetes.io/docs/concepts/services-networking/service/#loadbalancer.
podService bool	(Optional) Indicates whether to generate individual Services for each Pod. If set to true, a separate Service will be created for each Pod in the Cluster.

ClusterComponentSpec

(Appears on:ClusterSharding, ClusterSpec)

ClusterComponentSpec defines the specification of a Component within a Cluster.

Field	Description
name string	(Optional) Specifies the Component’s name. It’s part of the Service DNS name and must comply with the IANA service naming rule. The name is optional when ClusterComponentSpec is used as a template (e.g., in clusterSharding), but required otherwise.
componentDef string	(Optional) Specifies the ComponentDefinition custom resource (CR) that defines the Component’s characteristics and behavior. Supports three different ways to specify the ComponentDefinition: the regular expression - recommended the full name - recommended the name prefix
serviceVersion string	(Optional) ServiceVersion specifies the version of the Service expected to be provisioned by this Component. The version should follow the syntax and semantics of the “Semantic Versioning” specification (http://semver.org/). If no version is specified, the latest available version will be used.
serviceRefs []ServiceRef	(Optional) Defines a list of ServiceRef for a Component, enabling access to both external services and Services provided by other Clusters. Types of services: External services: Not managed by KubeBlocks or managed by a different KubeBlocks operator; Require a ServiceDescriptor for connection details. Services provided by a Cluster: Managed by the same KubeBlocks operator; identified using Cluster, Component and Service names. ServiceRefs with identical serviceRef.name in the same Cluster are considered the same. Example: serviceRefs: name: "redis-sentinel" serviceDescriptor: name: "external-redis-sentinel" name: "postgres-cluster" clusterServiceSelector: cluster: "my-postgres-cluster" service: component: "postgresql" The example above includes ServiceRefs to an external Redis Sentinel service and a PostgreSQL Cluster.
labels map[string]string	(Optional) Specifies Labels to override or add for underlying Pods, PVCs, Account & TLS Secrets, Services Owned by Component.
annotations map[string]string	(Optional) Specifies Annotations to override or add for underlying Pods, PVCs, Account & TLS Secrets, Services Owned by Component.
env []Kubernetes core/v1.EnvVar	(Optional) List of environment variables to add. These environment variables will be placed after the environment variables declared in the Pod.
replicas int32	Specifies the desired number of replicas in the Component for enhancing availability and durability, or load balancing.
schedulingPolicy SchedulingPolicy	(Optional) Specifies the scheduling policy for the Component.
resources Kubernetes core/v1.ResourceRequirements	(Optional) Specifies the resources required by the Component. It allows defining the CPU, memory requirements and limits for the Component’s containers.
volumeClaimTemplates []ClusterComponentVolumeClaimTemplate	(Optional) Specifies a list of PersistentVolumeClaim templates that represent the storage requirements for the Component. Each template specifies the desired characteristics of a persistent volume, such as storage class, size, and access modes. These templates are used to dynamically provision persistent volumes for the Component.
volumes []Kubernetes core/v1.Volume	(Optional) List of volumes to override.
services []ClusterComponentService	(Optional) Overrides services defined in referenced ComponentDefinition.
systemAccounts []ComponentSystemAccount	(Optional) Overrides system accounts defined in referenced ComponentDefinition.
configs []ClusterComponentConfig	(Optional) Specifies the configuration content of a config template.
tls bool	(Optional) A boolean flag that indicates whether the Component should use Transport Layer Security (TLS) for secure communication. When set to true, the Component will be configured to use TLS encryption for its network connections. This ensures that the data transmitted between the Component and its clients or other Components is encrypted and protected from unauthorized access. If TLS is enabled, the Component may require additional configuration, such as specifying TLS certificates and keys, to properly set up the secure communication channel.
issuer Issuer	(Optional) Specifies the configuration for the TLS certificates issuer. It allows defining the issuer name and the reference to the secret containing the TLS certificates and key. The secret should contain the CA certificate, TLS certificate, and private key in the specified keys. Required when TLS is enabled.
serviceAccountName string	(Optional) Specifies the name of the ServiceAccount required by the running Component. This ServiceAccount is used to grant necessary permissions for the Component’s Pods to interact with other Kubernetes resources, such as modifying Pod labels or sending events. If not specified, KubeBlocks automatically creates a default ServiceAccount named “kb-{componentdefinition.name}”, bound to a role with rules defined in ComponentDefinition’s policyRules field. If needed (currently this means if any lifecycleAction is enabled), it will also be bound to a default role named “kubeblocks-cluster-pod-role”, which is installed together with KubeBlocks. If multiple components use the same ComponentDefinition, they will share one ServiceAccount. If the field is not empty, the specified ServiceAccount will be used, and KubeBlocks will not create a ServiceAccount. But KubeBlocks does create RoleBindings for the specified ServiceAccount.
parallelPodManagementConcurrency Kubernetes api utils intstr.IntOrString	(Optional) Controls the concurrency of pods during initial scale up, when replacing pods on nodes, or when scaling down. It only used when PodManagementPolicy is set to Parallel. The default Concurrency is 100%.
podUpdatePolicy PodUpdatePolicyType	(Optional) PodUpdatePolicy indicates how pods should be updated StrictInPlace indicates that only allows in-place upgrades. Any attempt to modify other fields will be rejected. PreferInPlace indicates that we will first attempt an in-place upgrade of the Pod. If that fails, it will fall back to the ReCreate, where pod will be recreated. Default value is “PreferInPlace”
instances []InstanceTemplate	(Optional) Allows for the customization of configuration values for each instance within a Component. An instance represent a single replica (Pod and associated K8s resources like PVCs, Services, and ConfigMaps). While instances typically share a common configuration as defined in the ClusterComponentSpec, they can require unique settings in various scenarios: For example: A database Component might require different resource allocations for primary and secondary instances, with primaries needing more resources. During a rolling upgrade, a Component may first update the image for one or a few instances, and then update the remaining instances after verifying that the updated instances are functioning correctly. InstanceTemplate allows for specifying these unique configurations per instance. Each instance’s name is constructed using the pattern: $(component.name)-$(template.name)-$(ordinal), starting with an ordinal of 0. It is crucial to maintain unique names for each InstanceTemplate to avoid conflicts. The sum of replicas across all InstanceTemplates should not exceed the total number of replicas specified for the Component. Any remaining replicas will be generated using the default template and will follow the default naming rules.
offlineInstances []string	(Optional) Specifies the names of instances to be transitioned to offline status. Marking an instance as offline results in the following: The associated Pod is stopped, and its PersistentVolumeClaim (PVC) is retained for potential future reuse or data recovery, but it is no longer actively used. The ordinal number assigned to this instance is preserved, ensuring it remains unique and avoiding conflicts with new instances. Setting instances to offline allows for a controlled scale-in process, preserving their data and maintaining ordinal consistency within the Cluster. Note that offline instances and their associated resources, such as PVCs, are not automatically deleted. The administrator must manually manage the cleanup and removal of these resources when they are no longer needed.
disableExporter bool	(Optional) Determines whether metrics exporter information is annotated on the Component’s headless Service. If set to true, the following annotations will not be patched into the Service: “monitor.kubeblocks.io/path” “monitor.kubeblocks.io/port” “monitor.kubeblocks.io/scheme” These annotations allow the Prometheus installed by KubeBlocks to discover and scrape metrics from the exporter.
stop bool	(Optional) Stop the Component. If set, all the computing resources will be released.

ClusterComponentStatus

(Appears on:ClusterStatus)

ClusterComponentStatus records Component status.

Field	Description
phase ComponentPhase	Specifies the current state of the Component.
message map[string]string	(Optional) Records detailed information about the Component in its current phase. The keys are either podName, deployName, or statefulSetName, formatted as ‘ObjectKind/Name’.

ClusterComponentVolumeClaimTemplate

(Appears on:ClusterComponentSpec, ComponentSpec, InstanceTemplate)

Field	Description
name string	Refers to the name of a volumeMount defined in either: componentDefinition.spec.runtime.containers[*].volumeMounts clusterDefinition.spec.componentDefs[*].podSpec.containers[*].volumeMounts (deprecated) The value of name must match the name field of a volumeMount specified in the corresponding volumeMounts array.
spec PersistentVolumeClaimSpec	(Optional) Defines the desired characteristics of a PersistentVolumeClaim that will be created for the volume with the mount name specified in the name field. When a Pod is created for this ClusterComponent, a new PVC will be created based on the specification defined in the spec field. The PVC will be associated with the volume mount specified by the name field. accessModes []Kubernetes core/v1.PersistentVolumeAccessMode (Optional) Contains the desired access modes the volume should have. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#access-modes-1. resources Kubernetes core/v1.VolumeResourceRequirements (Optional) Represents the minimum resources the volume should have. If the RecoverVolumeExpansionFailure feature is enabled, users are allowed to specify resource requirements that are lower than the previous value but must still be higher than the capacity recorded in the status field of the claim. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#resources. storageClassName string (Optional) The name of the StorageClass required by the claim. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#class-1. volumeMode Kubernetes core/v1.PersistentVolumeMode (Optional) Defines what type of volume is required by the claim, either Block or Filesystem. volumeAttributesClassName string (Optional) volumeAttributesClassName may be used to set the VolumeAttributesClass used by this claim. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#volumeattributesclass

ClusterDefinitionSpec

(Appears on:ClusterDefinition)

ClusterDefinitionSpec defines the desired state of ClusterDefinition.

Field	Description
topologies []ClusterTopology	(Optional) Topologies defines all possible topologies within the cluster.

ClusterDefinitionStatus

(Appears on:ClusterDefinition)

ClusterDefinitionStatus defines the observed state of ClusterDefinition

Field	Description
observedGeneration int64	(Optional) Represents the most recent generation observed for this ClusterDefinition.
phase Phase	Specifies the current phase of the ClusterDefinition. Valid values are empty, Available, Unavailable. When Available, the ClusterDefinition is ready and can be referenced by related objects.
message string	(Optional) Provides additional information about the current phase.
topologies string	(Optional) Topologies this ClusterDefinition supported.

ClusterObjectReference

(Appears on:ComponentVarSelector, CredentialVarSelector, HostNetworkVarSelector, ServiceRefVarSelector, ServiceVarSelector, TLSVarSelector)

ClusterObjectReference defines information to let you locate the referenced object inside the same Cluster.

Field	Description
compDef string	(Optional) Specifies the exact name, name prefix, or regular expression pattern for matching the name of the ComponentDefinition custom resource (CR) used by the component that the referent object resident in. If not specified, the component itself will be used.
name string	(Optional) Name of the referent object.
optional bool	(Optional) Specify whether the object must be defined.
multipleClusterObjectOption MultipleClusterObjectOption	(Optional) This option defines the behavior when multiple component objects match the specified @CompDef. If not provided, an error will be raised when handling multiple matches.

ClusterPhase (string alias)

(Appears on:ClusterStatus)

ClusterPhase defines the phase of the Cluster within the .status.phase field.

Value	Description
"Abnormal"	AbnormalClusterPhase represents some components are in Failed phase, indicates that the cluster is in a fragile state and troubleshooting is required.
"Creating"	CreatingClusterPhase represents all components are in Creating phase.
"Deleting"	DeletingClusterPhase indicates the cluster is being deleted.
"Failed"	FailedClusterPhase represents all components are in Failed phase, indicates that the cluster is unavailable.
"Running"	RunningClusterPhase represents all components are in Running phase, indicates that the cluster is functioning properly.
"Stopped"	StoppedClusterPhase represents all components are in Stopped phase, indicates that the cluster has stopped and is not providing any functionality.
"Stopping"	StoppingClusterPhase represents at least one component is in Stopping phase, indicates that the cluster is in the process of stopping.
"Updating"	UpdatingClusterPhase represents all components are in Creating, Running or Updating phase, and at least one component is in Creating or Updating phase, indicates that the cluster is undergoing an update.

ClusterService

(Appears on:ClusterSpec)

ClusterService defines a service that is exposed externally, allowing entities outside the cluster to access it. For example, external applications, or other Clusters. And another Cluster managed by the same KubeBlocks operator can resolve the address exposed by a ClusterService using the serviceRef field.

When a Component needs to access another Cluster’s ClusterService using the serviceRef field, it must also define the service type and version information in the componentDefinition.spec.serviceRefDeclarations section.

Field	Description
Service Service	(Members of Service are embedded into this type.)
componentSelector string	(Optional) Extends the ServiceSpec.Selector by allowing the specification of components, to be used as a selector for the service. If the componentSelector is set as the name of a sharding, the service will be exposed to all components in the sharding.

ClusterSharding

(Appears on:ClusterSpec)

ClusterSharding defines how KubeBlocks manage dynamic provisioned shards. A typical design pattern for distributed databases is to distribute data across multiple shards, with each shard consisting of multiple replicas. Therefore, KubeBlocks supports representing a shard with a Component and dynamically instantiating Components using a template when shards are added. When shards are removed, the corresponding Components are also deleted.

Field	Description
name string	Represents the common parent part of all shard names. This identifier is included as part of the Service DNS name and must comply with IANA service naming rules. It is used to generate the names of underlying Components following the pattern $(clusterSharding.name)-$(ShardID). ShardID is a random string that is appended to the Name to generate unique identifiers for each shard. For example, if the sharding specification name is “my-shard” and the ShardID is “abc”, the resulting Component name would be “my-shard-abc”. Note that the name defined in Component template(clusterSharding.template.name) will be disregarded when generating the Component names of the shards. The clusterSharding.name field takes precedence.
shardingDef string	(Optional) Specifies the ShardingDefinition custom resource (CR) that defines the sharding’s characteristics and behavior. The full name or regular expression is supported to match the ShardingDefinition.
template ClusterComponentSpec	The template for generating Components for shards, where each shard consists of one Component. This field is of type ClusterComponentSpec, which encapsulates all the required details and definitions for creating and managing the Components. KubeBlocks uses this template to generate a set of identical Components of shards. All the generated Components will have the same specifications and definitions as specified in the template field. This allows for the creation of multiple Components with consistent configurations, enabling sharding and distribution of workloads across Components.
shards int32	Specifies the desired number of shards. Users can declare the desired number of shards through this field. KubeBlocks dynamically creates and deletes Components based on the difference between the desired and actual number of shards. KubeBlocks provides lifecycle management for sharding, including: Executing the shardProvision Action defined in the ShardingDefinition when the number of shards increases. This allows for custom actions to be performed after a new shard is provisioned. Executing the shardTerminate Action defined in the ShardingDefinition when the number of shards decreases. This enables custom cleanup or data migration tasks to be executed before a shard is terminated. Resources and data associated with the corresponding Component will also be deleted.

ClusterSpec

(Appears on:Cluster)

ClusterSpec defines the desired state of Cluster.

Field	Description
clusterDef string	(Optional) Specifies the name of the ClusterDefinition to use when creating a Cluster. This field enables users to create a Cluster based on a specific ClusterDefinition. Which, in conjunction with the topology field, determine: The Components to be included in the Cluster. The sequences in which the Components are created, updated, and terminate. This facilitates multiple-components management with predefined ClusterDefinition. Users with advanced requirements can bypass this general setting and specify more precise control over the composition of the Cluster by directly referencing specific ComponentDefinitions for each component within componentSpecs[*].componentDef. If this field is not provided, each component must be explicitly defined in componentSpecs[*].componentDef. Note: Once set, this field cannot be modified; it is immutable.
topology string	(Optional) Specifies the name of the ClusterTopology to be used when creating the Cluster. This field defines which set of Components, as outlined in the ClusterDefinition, will be used to construct the Cluster based on the named topology. The ClusterDefinition may list multiple topologies under clusterdefinition.spec.topologies[*], each tailored to different use cases or environments. If topology is not specified, the Cluster will use the default topology defined in the ClusterDefinition. Note: Once set during the Cluster creation, the topology field cannot be modified. It establishes the initial composition and structure of the Cluster and is intended for one-time configuration.
terminationPolicy TerminationPolicyType	Specifies the behavior when a Cluster is deleted. It defines how resources, data, and backups associated with a Cluster are managed during termination. Choose a policy based on the desired level of resource cleanup and data preservation: DoNotTerminate: Prevents deletion of the Cluster. This policy ensures that all resources remain intact. Delete: Deletes all runtime resources belong to the Cluster. WipeOut: An aggressive policy that deletes all Cluster resources, including volume snapshots and backups in external storage. This results in complete data removal and should be used cautiously, primarily in non-production environments to avoid irreversible data loss. Warning: Choosing an inappropriate termination policy can result in data loss. The WipeOut policy is particularly risky in production environments due to its irreversible nature.
componentSpecs []ClusterComponentSpec	(Optional) Specifies a list of ClusterComponentSpec objects used to define the individual Components that make up a Cluster. This field allows for detailed configuration of each Component within the Cluster. Note: shardings and componentSpecs cannot both be empty; at least one must be defined to configure a Cluster.
shardings []ClusterSharding	(Optional) Specifies a list of ClusterSharding objects that manage the sharding topology for Cluster Components. Each ClusterSharding organizes components into shards, with each shard corresponding to a Component. Components within a shard are all based on a common ClusterComponentSpec template, ensuring uniform configurations. This field supports dynamic resharding by facilitating the addition or removal of shards through the shards field in ClusterSharding. Note: shardings and componentSpecs cannot both be empty; at least one must be defined to configure a Cluster.
runtimeClassName string	(Optional) Specifies runtimeClassName for all Pods managed by this Cluster.
schedulingPolicy SchedulingPolicy	(Optional) Specifies the scheduling policy for the Cluster.
services []ClusterService	(Optional) Defines a list of additional Services that are exposed by a Cluster. This field allows Services of selected Components, either from componentSpecs or shardings to be exposed, alongside Services defined with ComponentService. Services defined here can be referenced by other clusters using the ServiceRefClusterSelector.
backup ClusterBackup	(Optional) Specifies the backup configuration of the Cluster.

ClusterStatus

(Appears on:Cluster)

ClusterStatus defines the observed state of the Cluster.

Field	Description
observedGeneration int64	(Optional) The most recent generation number of the Cluster object that has been observed by the controller.
phase ClusterPhase	(Optional) The current phase of the Cluster includes: Creating, Running, Updating, Stopping, Stopped, Deleting, Failed, Abnormal.
message string	(Optional) Provides additional information about the current phase.
components map[string]github.com/apecloud/kubeblocks/apis/apps/v1.ClusterComponentStatus	(Optional) Records the current status information of all Components within the Cluster.
shardings map[string]github.com/apecloud/kubeblocks/apis/apps/v1.ClusterComponentStatus	(Optional) Records the current status information of all shardings within the Cluster.
conditions []Kubernetes meta/v1.Condition	(Optional) Represents a list of detailed status of the Cluster object. Each condition in the list provides real-time information about certain aspect of the Cluster object. This field is crucial for administrators and developers to monitor and respond to changes within the Cluster. It provides a history of state transitions and a snapshot of the current state that can be used for automated logic or direct inspection.

ClusterTopology

(Appears on:ClusterDefinitionSpec)

ClusterTopology represents the definition for a specific cluster topology.

Field	Description
name string	Name is the unique identifier for the cluster topology. Cannot be updated.
components []ClusterTopologyComponent	(Optional) Components specifies the components in the topology.
shardings []ClusterTopologySharding	(Optional) Shardings specifies the shardings in the topology.
orders ClusterTopologyOrders	(Optional) Specifies the sequence in which components within a cluster topology are started, stopped, and upgraded. This ordering is crucial for maintaining the correct dependencies and operational flow across components.
default bool	(Optional) Default indicates whether this topology serves as the default configuration. When set to true, this topology is automatically used unless another is explicitly specified.

ClusterTopologyComponent

(Appears on:ClusterTopology)

ClusterTopologyComponent defines a Component within a ClusterTopology.

Field	Description
name string	Defines the unique identifier of the component within the cluster topology. It follows IANA Service naming rules and is used as part of the Service’s DNS name. The name must start with a lowercase letter, can contain lowercase letters, numbers, and hyphens, and must end with a lowercase letter or number. If the @template field is set to true, the name will be used as a prefix to match the specific components dynamically created. Cannot be updated once set.
compDef string	Specifies the exact name, name prefix, or regular expression pattern for matching the name of the ComponentDefinition custom resource (CR) that defines the Component’s characteristics and behavior. The system selects the ComponentDefinition CR with the latest version that matches the pattern. This approach allows: Precise selection by providing the exact name of a ComponentDefinition CR. Flexible and automatic selection of the most up-to-date ComponentDefinition CR by specifying a name prefix or regular expression pattern. Cannot be updated once set.
template bool	(Optional) Specifies whether the topology component will be considered as a template for instantiating components upon user requests dynamically. Cannot be updated once set.

ClusterTopologyOrders

(Appears on:ClusterTopology)

ClusterTopologyOrders manages the lifecycle of components within a cluster by defining their provisioning, terminating, and updating sequences. It organizes components into stages or groups, where each group indicates a set of components that can be managed concurrently. These groups are processed sequentially, allowing precise control based on component dependencies and requirements.

Field	Description
provision []string	(Optional) Specifies the order for creating and initializing entities. This is designed for entities that depend on one another. Entities without dependencies can be grouped together. Entities that can be provisioned independently or have no dependencies can be listed together in the same stage, separated by commas.
terminate []string	(Optional) Outlines the order for stopping and deleting entities. This sequence is designed for entities that require a graceful shutdown or have interdependencies. Entities that can be terminated independently or have no dependencies can be listed together in the same stage, separated by commas.
update []string	(Optional) Update determines the order for updating entities’ specifications, such as image upgrades or resource scaling. This sequence is designed for entities that have dependencies or require specific update procedures. Entities that can be updated independently or have no dependencies can be listed together in the same stage, separated by commas.

ClusterTopologySharding

(Appears on:ClusterTopology)

ClusterTopologySharding defines a sharding within a ClusterTopology.

Field	Description
name string	Defines the unique identifier of the sharding within the cluster topology. It follows IANA Service naming rules and is used as part of the Service’s DNS name. The name must start with a lowercase letter, can contain lowercase letters, numbers, and hyphens, and must end with a lowercase letter or number. Cannot be updated once set.
shardingDef string	Specifies the sharding definition that defines the characteristics and behavior of the sharding. The system selects the ShardingDefinition CR with the latest version that matches the pattern. This approach allows: Precise selection by providing the exact name of a ShardingDefinition CR. Flexible and automatic selection of the most up-to-date ShardingDefinition CR by specifying a regular expression pattern. Once set, this field cannot be updated.

ClusterVarSelector

(Appears on:VarSource)

ClusterVarSelector selects a var from a Cluster.

Field	Description
ClusterVars ClusterVars	(Members of ClusterVars are embedded into this type.)

ClusterVars

(Appears on:ClusterVarSelector)

Field	Description
namespace VarOption	(Optional) Reference to the namespace of the Cluster object.
clusterName VarOption	(Optional) Reference to the name of the Cluster object.
clusterUID VarOption	(Optional) Reference to the UID of the Cluster object.

ComponentAvailable

(Appears on:ComponentDefinitionSpec)

ComponentAvailable defines the strategies for determining whether the component is available.

Field	Description
withPhases string	(Optional) Specifies the phases that the component will go through to be considered available. This field is immutable once set.
withProbe ComponentAvailableWithProbe	(Optional) Specifies the strategies for determining whether the component is available based on the available probe. This field is immutable once set.

ComponentAvailableCondition

(Appears on:ComponentAvailableWithProbe)

Field	Description
ComponentAvailableExpression ComponentAvailableExpression	(Members of ComponentAvailableExpression are embedded into this type.)
and []ComponentAvailableExpression	(Optional) Logical And to combine multiple expressions. This field is immutable once set.
or []ComponentAvailableExpression	(Optional) Logical Or to combine multiple expressions. This field is immutable once set.
not ComponentAvailableExpression	(Optional) Logical Not to negate the expression. This field is immutable once set.

ComponentAvailableExpression

(Appears on:ComponentAvailableCondition)

Field	Description
all ComponentAvailableProbeAssertion	(Optional) All replicas must satisfy the assertion. This field is immutable once set.
any ComponentAvailableProbeAssertion	(Optional) At least one replica must satisfy the assertion. This field is immutable once set.
none ComponentAvailableProbeAssertion	(Optional) None of the replicas must satisfy the assertion. This field is immutable once set.
majority ComponentAvailableProbeAssertion	(Optional) Majority replicas must satisfy the assertion. This field is immutable once set.

ComponentAvailableProbeAssertion

(Appears on:ComponentAvailableExpression)

Field	Description
ActionAssertion ActionAssertion	(Members of ActionAssertion are embedded into this type.)
and []ActionAssertion	(Optional) Logical And to combine multiple assertions. This field is immutable once set.
or []ActionAssertion	(Optional) Logical Or to combine multiple assertions. This field is immutable once set.
not ActionAssertion	(Optional) Logical Not to negate the assertions. This field is immutable once set.
strict bool	(Optional) Specifies whether apply the assertions strictly to all replicas. This field is immutable once set.

ComponentAvailableWithProbe

(Appears on:ComponentAvailable)

Field	Description
timeWindowSeconds int32	(Optional) This field is immutable once set.
condition ComponentAvailableCondition	(Optional) Specifies the conditions that the component will go through to be considered available. This field is immutable once set.
description string	(Optional) A brief description for the condition when the component is available.

ComponentConfigSpec

(Appears on:ComponentDefinitionSpec)

Field	Description
ComponentTemplateSpec ComponentTemplateSpec	(Members of ComponentTemplateSpec are embedded into this type.)
keys []string	(Optional) Specifies the configuration files within the ConfigMap that support dynamic updates. A configuration template (provided in the form of a ConfigMap) may contain templates for multiple configuration files. Each configuration file corresponds to a key in the ConfigMap. Some of these configuration files may support dynamic modification and reloading without requiring a pod restart. If empty or omitted, all configuration files in the ConfigMap are assumed to support dynamic updates, and ConfigConstraint applies to all keys.
constraintRef string	(Optional) Specifies the name of the referenced configuration constraints object.
asEnvFrom []string	(Optional) Specifies the containers to inject the ConfigMap parameters as environment variables. This is useful when application images accept parameters through environment variables and generate the final configuration file in the startup script based on these variables. This field allows users to specify a list of container names, and KubeBlocks will inject the environment variables converted from the ConfigMap into these designated containers. This provides a flexible way to pass the configuration items from the ConfigMap to the container without modifying the image. Deprecated: asEnvFrom has been deprecated since 0.9.0 and will be removed in 0.10.0. Use injectEnvTo instead.
injectEnvTo []string	(Optional) Specifies the containers to inject the ConfigMap parameters as environment variables. This is useful when application images accept parameters through environment variables and generate the final configuration file in the startup script based on these variables. This field allows users to specify a list of container names, and KubeBlocks will inject the environment variables converted from the ConfigMap into these designated containers. This provides a flexible way to pass the configuration items from the ConfigMap to the container without modifying the image.
reRenderResourceTypes []RerenderResourceType	(Optional) Specifies whether the configuration needs to be re-rendered after v-scale or h-scale operations to reflect changes. In some scenarios, the configuration may need to be updated to reflect the changes in resource allocation or cluster topology. Examples: Redis: adjust maxmemory after v-scale operation. MySQL: increase max connections after v-scale operation. Zookeeper: update zoo.cfg with new node addresses after h-scale operation.
asSecret bool	(Optional) Whether to store the final rendered parameters as a secret.

ComponentDefinitionSpec

(Appears on:ComponentDefinition)

Field	Description
provider string	(Optional) Specifies the name of the Component provider, typically the vendor or developer name. It identifies the entity responsible for creating and maintaining the Component. When specifying the provider name, consider the following guidelines: Keep the name concise and relevant to the Component. Use a consistent naming convention across Components from the same provider. Avoid using trademarked or copyrighted names without proper permission.
description string	(Optional) Provides a brief and concise explanation of the Component’s purpose, functionality, and any relevant details. It serves as a quick reference for users to understand the Component’s role and characteristics.
serviceKind string	(Optional) Defines the type of well-known service protocol that the Component provides. It specifies the standard or widely recognized protocol used by the Component to offer its Services. The serviceKind field allows users to quickly identify the type of Service provided by the Component based on common protocols or service types. This information helps in understanding the compatibility, interoperability, and usage of the Component within a system. Some examples of well-known service protocols include: “MySQL”: Indicates that the Component provides a MySQL database service. “PostgreSQL”: Indicates that the Component offers a PostgreSQL database service. “Redis”: Signifies that the Component functions as a Redis key-value store. “ETCD”: Denotes that the Component serves as an ETCD distributed key-value store. The serviceKind value is case-insensitive, allowing for flexibility in specifying the protocol name. When specifying the serviceKind, consider the following guidelines: Use well-established and widely recognized protocol names or service types. Ensure that the serviceKind accurately represents the primary service type offered by the Component. If the Component provides multiple services, choose the most prominent or commonly used protocol. Limit the serviceKind to a maximum of 32 characters for conciseness and readability. Note: The serviceKind field is optional and can be left empty if the Component does not fit into a well-known service category or if the protocol is not widely recognized. It is primarily used to convey information about the Component’s service type to users and facilitate discovery and integration. The serviceKind field is immutable and cannot be updated.
serviceVersion string	(Optional) Specifies the version of the Service provided by the Component. It follows the syntax and semantics of the “Semantic Versioning” specification (http://semver.org/). The Semantic Versioning specification defines a version number format of X.Y.Z (MAJOR.MINOR.PATCH), where: X represents the major version and indicates incompatible API changes. Y represents the minor version and indicates added functionality in a backward-compatible manner. Z represents the patch version and indicates backward-compatible bug fixes. Additional labels for pre-release and build metadata are available as extensions to the X.Y.Z format: Use pre-release labels (e.g., -alpha, -beta) for versions that are not yet stable or ready for production use. Use build metadata (e.g., +build.1) for additional version information if needed. Examples of valid ServiceVersion values: “1.0.0” “2.3.1” “3.0.0-alpha.1” “4.5.2+build.1” The serviceVersion field is immutable and cannot be updated.
labels map[string]string	(Optional) Specifies static labels that will be patched to all Kubernetes resources created for the Component. Note: If a label key in the labels field conflicts with any system labels or user-specified labels, it will be silently ignored to avoid overriding higher-priority labels. This field is immutable.
annotations map[string]string	(Optional) Specifies static annotations that will be patched to all Kubernetes resources created for the Component. Note: If an annotation key in the annotations field conflicts with any system annotations or user-specified annotations, it will be silently ignored to avoid overriding higher-priority annotations. This field is immutable.
runtime Kubernetes core/v1.PodSpec	Specifies the PodSpec template used in the Component. It includes the following elements: Init containers Containers Image Commands Args Envs Mounts Ports Security context Probes Lifecycle Volumes This field is intended to define static settings that remain consistent across all instantiated Components. Dynamic settings such as CPU and memory resource limits, as well as scheduling settings (affinity, toleration, priority), may vary among different instantiated Components. They should be specified in the cluster.spec.componentSpecs (ClusterComponentSpec). Specific instances of a Component may override settings defined here, such as using a different container image or modifying environment variable values. These instance-specific overrides can be specified in cluster.spec.componentSpecs[*].instances. This field is immutable and cannot be updated once set.
vars []EnvVar	(Optional) Defines variables which are determined after Cluster instantiation and reflect dynamic or runtime attributes of instantiated Clusters. These variables serve as placeholders for setting environment variables in Pods and Actions, or for rendering configuration and script templates before actual values are finalized. These variables are placed in front of the environment variables declared in the Pod if used as environment variables. Variable values can be sourced from: ConfigMap: Select and extract a value from a specific key within a ConfigMap. Secret: Select and extract a value from a specific key within a Secret. HostNetwork: Retrieves values (including ports) from host-network resources. Service: Retrieves values (including address, port, NodePort) from a selected Service. Intended to obtain the address of a ComponentService within the same Cluster. Credential: Retrieves account name and password from a SystemAccount variable. ServiceRef: Retrieves address, port, account name and password from a selected ServiceRefDeclaration. Designed to obtain the address bound to a ServiceRef, such as a ClusterService or ComponentService of another cluster or an external service. Component: Retrieves values from a selected Component, including replicas and instance name list. This field is immutable.
volumes []ComponentVolume	(Optional) Defines the volumes used by the Component and some static attributes of the volumes. After defining the volumes here, user can reference them in the cluster.spec.componentSpecs[*].volumeClaimTemplates field to configure dynamic properties such as volume capacity and storage class. This field allows you to specify the following: Snapshot behavior: Determines whether a snapshot of the volume should be taken when performing a snapshot backup of the Component. Disk high watermark: Sets the high watermark for the volume’s disk usage. When the disk usage reaches the specified threshold, it triggers an alert or action. By configuring these volume behaviors, you can control how the volumes are managed and monitored within the Component. This field is immutable.
hostNetwork HostNetwork	(Optional) Specifies the host network configuration for the Component. When hostNetwork option is enabled, the Pods share the host’s network namespace and can directly access the host’s network interfaces. This means that if multiple Pods need to use the same port, they cannot run on the same host simultaneously due to port conflicts. The DNSPolicy field in the Pod spec determines how containers within the Pod perform DNS resolution. When using hostNetwork, the operator will set the DNSPolicy to ‘ClusterFirstWithHostNet’. With this policy, DNS queries will first go through the K8s cluster’s DNS service. If the query fails, it will fall back to the host’s DNS settings. If set, the DNS policy will be automatically set to “ClusterFirstWithHostNet”. This field is immutable.
services []ComponentService	(Optional) Defines additional Services to expose the Component’s endpoints. A default headless Service, named {cluster.name}-{component.name}-headless, is automatically created for internal Cluster communication. This field enables customization of additional Services to expose the Component’s endpoints to other Components within the same or different Clusters, and to external applications. Each Service entry in this list can include properties such as ports, type, and selectors. For intra-Cluster access, Components can reference Services using variables declared in componentDefinition.spec.vars[*].valueFrom.serviceVarRef. For inter-Cluster access, reference Services use variables declared in componentDefinition.spec.vars[*].valueFrom.serviceRefVarRef, and bind Services at Cluster creation time with clusterComponentSpec.ServiceRef[*].clusterServiceSelector. This field is immutable.
configs []ComponentConfigSpec	(Optional) Specifies the configuration file templates and volume mount parameters used by the Component. It also includes descriptions of the parameters in the ConfigMaps, such as value range limitations. This field specifies a list of templates that will be rendered into Component containers’ configuration files. Each template is represented as a ConfigMap and may contain multiple configuration files, with each file being a key in the ConfigMap. The rendered configuration files will be mounted into the Component’s containers according to the specified volume mount parameters. This field is immutable.
logConfigs []LogConfig	(Optional) Defines the types of logs generated by instances of the Component and their corresponding file paths. These logs can be collected for further analysis and monitoring. The logConfigs field is an optional list of LogConfig objects, where each object represents a specific log type and its configuration. It allows you to specify multiple log types and their respective file paths for the Component. Examples: logConfigs: filePathPattern: /data/mysql/log/mysqld-error.log name: error filePathPattern: /data/mysql/log/mysqld.log name: general filePathPattern: /data/mysql/log/mysqld-slowquery.log name: slow This field is immutable.
scripts []ComponentTemplateSpec	(Optional) Specifies groups of scripts, each provided via a ConfigMap, to be mounted as volumes in the container. These scripts can be executed during container startup or via specific actions. Each script group is encapsulated in a ComponentTemplateSpec that includes: The ConfigMap containing the scripts. The mount point where the scripts will be mounted inside the container. This field is immutable.
systemAccounts []SystemAccount	(Optional) An array of SystemAccount objects that define the system accounts needed for the management operations of the Component. Each SystemAccount includes: Account name. The SQL statement template: Used to create the system account. Password Source: Either generated based on certain rules or retrieved from a Secret. Use cases for system accounts typically involve tasks like system initialization, backups, monitoring, health checks, replication, and other system-level operations. System accounts are distinct from user accounts, although both are database accounts. System Accounts: Created during Cluster setup by the KubeBlocks operator, these accounts have higher privileges for system management and are fully managed through a declarative API by the operator. User Accounts: Managed by users or administrator. User account permissions should follow the principle of least privilege, granting only the necessary access rights to complete their required tasks. This field is immutable.
tls TLS	(Optional) Specifies the TLS configuration for the Component. This field is immutable.
replicasLimit ReplicasLimit	(Optional) Defines the upper limit of the number of replicas supported by the Component. It defines the maximum number of replicas that can be created for the Component. This field allows you to set a limit on the scalability of the Component, preventing it from exceeding a certain number of replicas. This field is immutable.
available ComponentAvailable	(Optional) Specifies the strategies for determining the available status of the Component. This field is immutable.
roles []ReplicaRole	(Optional) Enumerate all possible roles assigned to each replica of the Component, influencing its behavior. A replica can have zero or one role. KubeBlocks operator determines the role of each replica by invoking the lifecycleActions.roleProbe method. This action returns the role for each replica, and the returned role must be predefined here. The roles assigned to a replica can influence various aspects of the Component’s behavior, such as: Service selection: The Component’s exposed Services may target replicas based on their roles using roleSelector. Update order: The roles can determine the order in which replicas are updated during a Component update. For instance, replicas with a “follower” role can be updated first, while the replica with the “leader” role is updated last. This helps minimize the number of leader changes during the update process. This field is immutable.
minReadySeconds int32	(Optional) minReadySeconds is the minimum duration in seconds that a new Pod should remain in the ready state without any of its containers crashing to be considered available. This ensures the Pod’s stability and readiness to serve requests. A default value of 0 seconds means the Pod is considered available as soon as it enters the ready state.
updateStrategy UpdateStrategy	(Optional) Specifies the concurrency strategy for updating multiple instances of the Component. Available strategies: Serial: Updates replicas one at a time, ensuring minimal downtime by waiting for each replica to become ready before updating the next. Parallel: Updates all replicas simultaneously, optimizing for speed but potentially reducing availability during the update. BestEffortParallel: Updates replicas concurrently with a limit on simultaneous updates to ensure a minimum number of operational replicas for maintaining quorum. For example, in a 5-replica component, updating a maximum of 2 replicas simultaneously keeps at least 3 operational for quorum. This field is immutable and defaults to ‘Serial’.
podManagementPolicy Kubernetes apps/v1.PodManagementPolicyType	(Optional) InstanceSet controls the creation of pods during initial scale up, replacement of pods on nodes, and scaling down. OrderedReady: Creates pods in increasing order (pod-0, then pod-1, etc). The controller waits until each pod is ready before continuing. Pods are removed in reverse order when scaling down. Parallel: Creates pods in parallel to match the desired scale without waiting. All pods are deleted at once when scaling down.
policyRules []Kubernetes rbac/v1.PolicyRule	(Optional) Defines the namespaced policy rules required by the Component. The policyRules field is an array of rbacv1.PolicyRule objects that define the policy rules needed by the Component to operate within a namespace. These policy rules determine the permissions and verbs the Component is allowed to perform on Kubernetes resources within the namespace. The purpose of this field is to automatically generate the necessary RBAC roles for the Component based on the specified policy rules. This ensures that the Pods in the Component has appropriate permissions to function. This field is immutable.
lifecycleActions ComponentLifecycleActions	(Optional) Defines a set of hooks and procedures that customize the behavior of a Component throughout its lifecycle. Actions are triggered at specific lifecycle stages: postProvision: Defines the hook to be executed after the creation of a Component, with preCondition specifying when the action should be fired relative to the Component’s lifecycle stages: Immediately, RuntimeReady, ComponentReady, and ClusterReady. preTerminate: Defines the hook to be executed before terminating a Component. roleProbe: Defines the procedure which is invoked regularly to assess the role of replicas. switchover: Defines the procedure for a controlled transition of a role to a new replica. This approach aims to minimize downtime and maintain availability in systems with a leader-follower topology, such as before planned maintenance or upgrades on the current leader node. memberJoin: Defines the procedure to add a new replica to the replication group. memberLeave: Defines the method to remove a replica from the replication group. readOnly: Defines the procedure to switch a replica into the read-only state. readWrite: transition a replica from the read-only state back to the read-write state. dataDump: Defines the procedure to export the data from a replica. dataLoad: Defines the procedure to import data into a replica. reconfigure: Defines the procedure that update a replica with new configuration file. accountProvision: Defines the procedure to generate a new database account. This field is immutable.
serviceRefDeclarations []ServiceRefDeclaration	(Optional) Lists external service dependencies of the Component, including services from other Clusters or outside the K8s environment. This field is immutable.
exporter Exporter	(Optional) Defines the built-in metrics exporter container.

ComponentDefinitionStatus

(Appears on:ComponentDefinition)

ComponentDefinitionStatus defines the observed state of ComponentDefinition.

Field	Description
observedGeneration int64	(Optional) Refers to the most recent generation that has been observed for the ComponentDefinition.
phase Phase	(Optional) Represents the current status of the ComponentDefinition. Valid values include ``,Available, andUnavailable<code>. When the status is</code>Available, the ComponentDefinition is ready and can be utilized by related objects.
message string	(Optional) Provides additional information about the current phase.

ComponentLifecycleActions

(Appears on:ComponentDefinitionSpec)

ComponentLifecycleActions defines a collection of Actions for customizing the behavior of a Component.

Field	Description
postProvision Action	(Optional) Specifies the hook to be executed after a component’s creation. By setting postProvision.customHandler.preCondition, you can determine the specific lifecycle stage at which the action should trigger: Immediately, RuntimeReady, ComponentReady, and ClusterReady. with ComponentReady being the default. The PostProvision Action is intended to run only once. Note: This field is immutable once it has been set.
preTerminate Action	(Optional) Specifies the hook to be executed prior to terminating a component. The PreTerminate Action is intended to run only once. This action is executed immediately when a scale-down operation for the Component is initiated. The actual termination and cleanup of the Component and its associated resources will not proceed until the PreTerminate action has completed successfully. Note: This field is immutable once it has been set.
roleProbe Probe	(Optional) Defines the procedure which is invoked regularly to assess the role of replicas. This action is periodically triggered at the specified interval to determine the role of each replica. Upon successful execution, the action’s output designates the role of the replica, which should match one of the predefined role names within componentDefinition.spec.roles. The output is then compared with the previous successful execution result. If a role change is detected, an event is generated to inform the controller, which initiates an update of the replica’s role. Defining a RoleProbe Action for a Component is required if roles are defined for the Component. It ensures replicas are correctly labeled with their respective roles. Without this, services that rely on roleSelectors might improperly direct traffic to wrong replicas. The container executing this action has access to following variables: KB_POD_FQDN: The FQDN of the Pod whose role is being assessed. Expected output of this action: On Success: The determined role of the replica, which must align with one of the roles specified in the component definition. On Failure: An error message, if applicable, indicating why the action failed. Note: This field is immutable once it has been set.
availableProbe Probe	(Optional) Defines the procedure which is invoked regularly to assess the availability of the component. Note: This field is immutable once it has been set.
switchover Action	(Optional) Defines the procedure for a controlled transition of a role to a new replica. This approach aims to minimize downtime and maintain availability during events such as planned maintenance or when performing stop, shutdown, restart, or upgrade operations. In a typical consensus system, this action is used to transfer leader role to another replica. The container executing this action has access to following variables: KB_SWITCHOVER_CANDIDATE_NAME: The name of the pod of the new role’s candidate, which may not be specified (empty). KB_SWITCHOVER_CANDIDATE_FQDN: The FQDN of the pod of the new role’s candidate, which may not be specified (empty). KB_SWITCHOVER_CURRENT_NAME: The name of the pod of the current role. KB_SWITCHOVER_CURRENT_FQDN: The FQDN of the pod of the current role. KB_SWITCHOVER_ROLE: The role that will be transferred to another replica. This variable can be empty if, for example, role probe does not succeed. It depends on the addon implementation what to do under such cases. Note: This field is immutable once it has been set.
memberJoin Action	(Optional) Defines the procedure to add a new replica to the replication group. This action is initiated after a replica pod becomes ready. The role of the replica (e.g., primary, secondary) will be determined and assigned as part of the action command implementation, or automatically by the database kernel or a sidecar utility like Patroni that implements a consensus algorithm. The container executing this action has access to following variables: KB_JOIN_MEMBER_POD_FQDN: The pod FQDN of the replica being added to the group. KB_JOIN_MEMBER_POD_NAME: The pod name of the replica being added to the group. Expected action output: On Failure: An error message detailing the reason for any failure encountered during the addition of the new member. For example, to add a new OBServer to an OceanBase Cluster in ‘zone1’, the following command may be used: command: bash -c | CLIENT="mysql -u $SERVICE_USER -p$SERVICE_PASSWORD -P $SERVICE_PORT -h $SERVICE_HOST -e" $CLIENT "ALTER SYSTEM ADD SERVER '$KB_POD_FQDN:$SERVICE_PORT' ZONE 'zone1'" Note: This field is immutable once it has been set.
memberLeave Action	(Optional) Defines the procedure to remove a replica from the replication group. This action is initiated before remove a replica from the group. The operator will wait for MemberLeave to complete successfully before releasing the replica and cleaning up related Kubernetes resources. The process typically includes updating configurations and informing other group members about the removal. Data migration is generally not part of this action and should be handled separately if needed. The container executing this action has access to following variables: KB_LEAVE_MEMBER_POD_FQDN: The pod name of the replica being removed from the group. KB_LEAVE_MEMBER_POD_NAME: The pod name of the replica being removed from the group. Expected action output: On Failure: An error message, if applicable, indicating why the action failed. For example, to remove an OBServer from an OceanBase Cluster in ‘zone1’, the following command can be executed: command: bash -c | CLIENT="mysql -u $SERVICE_USER -p$SERVICE_PASSWORD -P $SERVICE_PORT -h $SERVICE_HOST -e" $CLIENT "ALTER SYSTEM DELETE SERVER '$KB_POD_FQDN:$SERVICE_PORT' ZONE 'zone1'" Note: This field is immutable once it has been set.
readonly Action	(Optional) Defines the procedure to switch a replica into the read-only state. Use Case: This action is invoked when the database’s volume capacity nears its upper limit and space is about to be exhausted. The container executing this action has access to following environment variables: KB_POD_FQDN: The FQDN of the replica pod whose role is being checked. Expected action output: On Failure: An error message, if applicable, indicating why the action failed. Note: This field is immutable once it has been set.
readwrite Action	(Optional) Defines the procedure to transition a replica from the read-only state back to the read-write state. Use Case: This action is used to bring back a replica that was previously in a read-only state, which restricted write operations, to its normal operational state where it can handle both read and write operations. The container executing this action has access to following environment variables: KB_POD_FQDN: The FQDN of the replica pod whose role is being checked. Expected action output: On Failure: An error message, if applicable, indicating why the action failed. Note: This field is immutable once it has been set.
dataDump Action	(Optional) Defines the procedure for exporting the data from a replica. Use Case: This action is intended for initializing a newly created replica with data. It involves exporting data from an existing replica and importing it into the new, empty replica. This is essential for synchronizing the state of replicas across the system. Applicability: Some database engines or associated sidecar applications (e.g., Patroni) may already provide this functionality. In such cases, this action may not be required. The output should be a valid data dump streamed to stdout. It must exclude any irrelevant information to ensure that only the necessary data is exported for import into the new replica. The container executing this action has access to following environment variables: KB_TARGET_POD_NAME: The name of the replica pod into which the data will be loaded. Note: This field is immutable once it has been set.
dataLoad Action	(Optional) Defines the procedure for importing data into a replica. Use Case: This action is intended for initializing a newly created replica with data. It involves exporting data from an existing replica and importing it into the new, empty replica. This is essential for synchronizing the state of replicas across the system. Some database engines or associated sidecar applications (e.g., Patroni) may already provide this functionality. In such cases, this action may not be required. Data should be received through stdin. If any error occurs during the process, the action must be able to guarantee idempotence to allow for retries from the beginning. Note: This field is immutable once it has been set.
reconfigure Action	(Optional) Defines the procedure that update a replica with new configuration. Note: This field is immutable once it has been set. This Action is reserved for future versions.
accountProvision Action	(Optional) Defines the procedure to generate a new database account. Use Case: This action is designed to create system accounts that are utilized for replication, monitoring, backup, and other administrative tasks. The container executing this action has access to following variables: KB_ACCOUNT_NAME: The name of the system account to be created. KB_ACCOUNT_STATEMENT: The statement used to create the system account. Note: This field is immutable once it has been set.

ComponentPhase (string alias)

(Appears on:ClusterComponentStatus, ComponentStatus)

ComponentPhase defines the phase of the Component within the .status.phase field.

Value	Description
"Creating"	CreatingComponentPhase indicates the component is currently being created.
"Deleting"	DeletingComponentPhase indicates the component is currently being deleted.
"Failed"	FailedComponentPhase indicates that there are some pods of the component not in a ‘Running’ state.
"Running"	RunningComponentPhase indicates that all pods of the component are up-to-date and in a ‘Running’ state.
"Starting"	StartingComponentPhase indicates the component is currently being started.
"Stopped"	StoppedComponentPhase indicates the component is stopped.
"Stopping"	StoppingComponentPhase indicates the component is currently being stopped.
"Updating"	UpdatingComponentPhase indicates the component is currently being updated.

ComponentService

(Appears on:ComponentDefinitionSpec, ComponentSpec)

ComponentService defines a service that would be exposed as an inter-component service within a Cluster. A Service defined in the ComponentService is expected to be accessed by other Components within the same Cluster.

When a Component needs to use a ComponentService provided by another Component within the same Cluster, it can declare a variable in the componentDefinition.spec.vars section and bind it to the specific exposed address of the ComponentService using the serviceVarRef field.

Field	Description
Service Service	(Members of Service are embedded into this type.)
podService bool	(Optional) Indicates whether to create a corresponding Service for each Pod of the selected Component. When set to true, a set of Services will be automatically generated for each Pod, and the roleSelector field will be ignored. The names of the generated Services will follow the same suffix naming pattern: $(serviceName)-$(podOrdinal). The total number of generated Services will be equal to the number of replicas specified for the Component. Example usage: name: my-service serviceName: my-service podService: true disableAutoProvision: true spec: type: NodePort ports: name: http port: 80 targetPort: 8080 In this example, if the Component has 3 replicas, three Services will be generated: my-service-0: Points to the first Pod (podOrdinal: 0) my-service-1: Points to the second Pod (podOrdinal: 1) my-service-2: Points to the third Pod (podOrdinal: 2) Each generated Service will have the specified spec configuration and will target its respective Pod. This feature is useful when you need to expose each Pod of a Component individually, allowing external access to specific instances of the Component.
disableAutoProvision bool	(Optional) Indicates whether the automatic provisioning of the service should be disabled. If set to true, the service will not be automatically created at the component provisioning. Instead, you can enable the creation of this service by specifying it explicitly in the cluster API.

ComponentSpec

(Appears on:Component)

ComponentSpec defines the desired state of Component

Field	Description
compDef string	Specifies the name of the referenced ComponentDefinition.
serviceVersion string	(Optional) ServiceVersion specifies the version of the Service expected to be provisioned by this Component. The version should follow the syntax and semantics of the “Semantic Versioning” specification (http://semver.org/).
serviceRefs []ServiceRef	(Optional) Defines a list of ServiceRef for a Component, enabling access to both external services and Services provided by other Clusters. Types of services: External services: Not managed by KubeBlocks or managed by a different KubeBlocks operator; Require a ServiceDescriptor for connection details. Services provided by a Cluster: Managed by the same KubeBlocks operator; identified using Cluster, Component and Service names. ServiceRefs with identical serviceRef.name in the same Cluster are considered the same. Example: serviceRefs: name: "redis-sentinel" serviceDescriptor: name: "external-redis-sentinel" name: "postgres-cluster" clusterServiceSelector: cluster: "my-postgres-cluster" service: component: "postgresql" The example above includes ServiceRefs to an external Redis Sentinel service and a PostgreSQL Cluster.
labels map[string]string	(Optional) Specifies Labels to override or add for underlying Pods, PVCs, Account & TLS Secrets, Services Owned by Component.
annotations map[string]string	(Optional) Specifies Annotations to override or add for underlying Pods, PVCs, Account & TLS Secrets, Services Owned by Component.
env []Kubernetes core/v1.EnvVar	(Optional) List of environment variables to add.
resources Kubernetes core/v1.ResourceRequirements	(Optional) Specifies the resources required by the Component. It allows defining the CPU, memory requirements and limits for the Component’s containers.
volumeClaimTemplates []ClusterComponentVolumeClaimTemplate	(Optional) Specifies a list of PersistentVolumeClaim templates that define the storage requirements for the Component. Each template specifies the desired characteristics of a persistent volume, such as storage class, size, and access modes. These templates are used to dynamically provision persistent volumes for the Component.
volumes []Kubernetes core/v1.Volume	(Optional) List of volumes to override.
services []ComponentService	(Optional) Overrides Services defined in referenced ComponentDefinition.
systemAccounts []ComponentSystemAccount	(Optional) Overrides system accounts defined in referenced ComponentDefinition.
replicas int32	Specifies the desired number of replicas in the Component for enhancing availability and durability, or load balancing.
configs []ClusterComponentConfig	(Optional) Specifies the configuration content of a config template.
serviceAccountName string	(Optional) Specifies the name of the ServiceAccount required by the running Component. This ServiceAccount is used to grant necessary permissions for the Component’s Pods to interact with other Kubernetes resources, such as modifying Pod labels or sending events. If not specified, KubeBlocks automatically creates a default ServiceAccount named “kb-{componentdefinition.name}”, bound to a role with rules defined in ComponentDefinition’s policyRules field. If needed (currently this means if any lifecycleAction is enabled), it will also be bound to a default role named “kubeblocks-cluster-pod-role”, which is installed together with KubeBlocks. If multiple components use the same ComponentDefinition, they will share one ServiceAccount. If the field is not empty, the specified ServiceAccount will be used, and KubeBlocks will not create a ServiceAccount. But KubeBlocks does create RoleBindings for the specified ServiceAccount.
parallelPodManagementConcurrency Kubernetes api utils intstr.IntOrString	(Optional) Controls the concurrency of pods during initial scale up, when replacing pods on nodes, or when scaling down. It only used when PodManagementPolicy is set to Parallel. The default Concurrency is 100%.
podUpdatePolicy PodUpdatePolicyType	(Optional) PodUpdatePolicy indicates how pods should be updated StrictInPlace indicates that only allows in-place upgrades. Any attempt to modify other fields will be rejected. PreferInPlace indicates that we will first attempt an in-place upgrade of the Pod. If that fails, it will fall back to the ReCreate, where pod will be recreated. Default value is “PreferInPlace”
schedulingPolicy SchedulingPolicy	(Optional) Specifies the scheduling policy for the Component.
tlsConfig TLSConfig	(Optional) Specifies the TLS configuration for the Component, including: A boolean flag that indicates whether the Component should use Transport Layer Security (TLS) for secure communication. An optional field that specifies the configuration for the TLS certificates issuer when TLS is enabled. It allows defining the issuer name and the reference to the secret containing the TLS certificates and key. The secret should contain the CA certificate, TLS certificate, and private key in the specified keys.
instances []InstanceTemplate	(Optional) Allows for the customization of configuration values for each instance within a Component. An Instance represent a single replica (Pod and associated K8s resources like PVCs, Services, and ConfigMaps). While instances typically share a common configuration as defined in the ClusterComponentSpec, they can require unique settings in various scenarios: For example: A database Component might require different resource allocations for primary and secondary instances, with primaries needing more resources. During a rolling upgrade, a Component may first update the image for one or a few instances, and then update the remaining instances after verifying that the updated instances are functioning correctly. InstanceTemplate allows for specifying these unique configurations per instance. Each instance’s name is constructed using the pattern: $(component.name)-$(template.name)-$(ordinal), starting with an ordinal of 0. It is crucial to maintain unique names for each InstanceTemplate to avoid conflicts. The sum of replicas across all InstanceTemplates should not exceed the total number of Replicas specified for the Component. Any remaining replicas will be generated using the default template and will follow the default naming rules.
offlineInstances []string	(Optional) Specifies the names of instances to be transitioned to offline status. Marking an instance as offline results in the following: The associated Pod is stopped, and its PersistentVolumeClaim (PVC) is retained for potential future reuse or data recovery, but it is no longer actively used. The ordinal number assigned to this instance is preserved, ensuring it remains unique and avoiding conflicts with new instances. Setting instances to offline allows for a controlled scale-in process, preserving their data and maintaining ordinal consistency within the Cluster. Note that offline instances and their associated resources, such as PVCs, are not automatically deleted. The administrator must manually manage the cleanup and removal of these resources when they are no longer needed.
runtimeClassName string	(Optional) Defines runtimeClassName for all Pods managed by this Component.
disableExporter bool	(Optional) Determines whether metrics exporter information is annotated on the Component’s headless Service. If set to true, the following annotations will not be patched into the Service: “monitor.kubeblocks.io/path” “monitor.kubeblocks.io/port” “monitor.kubeblocks.io/scheme” These annotations allow the Prometheus installed by KubeBlocks to discover and scrape metrics from the exporter.
stop bool	(Optional) Stop the Component. If set, all the computing resources will be released.
sidecars []Sidecar	(Optional) Specifies the sidecars to be injected into the Component.

ComponentStatus

(Appears on:Component)

ComponentStatus represents the observed state of a Component within the Cluster.

Field	Description
observedGeneration int64	(Optional) Specifies the most recent generation observed for this Component object.
conditions []Kubernetes meta/v1.Condition	(Optional) Represents a list of detailed status of the Component object. Each condition in the list provides real-time information about certain aspect of the Component object. This field is crucial for administrators and developers to monitor and respond to changes within the Component. It provides a history of state transitions and a snapshot of the current state that can be used for automated logic or direct inspection.
phase ComponentPhase	Indicates the current phase of the Component, with each phase indicating specific conditions: Creating: The initial phase for new Components, transitioning from ‘empty’(“”). Running: All Pods are up-to-date and in a Running state. Updating: The Component is currently being updated, with no failed Pods present. Failed: A significant number of Pods have failed. Stopping: All Pods are being terminated, with current replica count at zero. Stopped: All associated Pods have been successfully deleted. Starting: Pods are being started. Deleting: The Component is being deleted.
message map[string]string	(Optional) A map that stores detailed message about the Component. Each entry in the map provides insights into specific elements of the Component, such as Pods or workloads. Keys in this map are formatted as ObjectKind/Name, where ObjectKind could be a type like Pod, and Name is the specific name of the object.

ComponentSystemAccount

(Appears on:ClusterComponentSpec, ComponentSpec)

Field	Description
name string	The name of the system account.
passwordConfig PasswordConfig	(Optional) Specifies the policy for generating the account’s password. This field is immutable once set.
secretRef ProvisionSecretRef	(Optional) Refers to the secret from which data will be copied to create the new account. This field is immutable once set.

ComponentTemplateSpec

(Appears on:ComponentConfigSpec, ComponentDefinitionSpec, SidecarDefinitionSpec)

Field	Description
name string	Specifies the name of the configuration template.
templateRef string	(Optional) Specifies the name of the referenced configuration template ConfigMap object.
namespace string	(Optional) Specifies the namespace of the referenced configuration template ConfigMap object. An empty namespace is equivalent to the “default” namespace.
volumeName string	(Optional) Refers to the volume name of PodTemplate. The configuration file produced through the configuration template will be mounted to the corresponding volume. Must be a DNS_LABEL name. The volume name must be defined in podSpec.containers[*].volumeMounts.
defaultMode int32	(Optional) The operator attempts to set default file permissions for scripts (0555) and configurations (0444). However, certain database engines may require different file permissions. You can specify the desired file permissions here. Must be specified as an octal value between 0000 and 0777 (inclusive), or as a decimal value between 0 and 511 (inclusive). YAML supports both octal and decimal values for file permissions. Please note that this setting only affects the permissions of the files themselves. Directories within the specified path are not impacted by this setting. It’s important to be aware that this setting might conflict with other options that influence the file mode, such as fsGroup. In such cases, the resulting file mode may have additional bits set. Refers to documents of k8s.ConfigMapVolumeSource.defaultMode for more information.

ComponentVarSelector

(Appears on:VarSource)

ComponentVarSelector selects a var from a Component.

Field	Description
ClusterObjectReference ClusterObjectReference	(Members of ClusterObjectReference are embedded into this type.) The Component to select from.
ComponentVars ComponentVars	(Members of ComponentVars are embedded into this type.)

ComponentVars

(Appears on:ComponentVarSelector)

Field	Description
componentName VarOption	(Optional) Reference to the name of the Component object.
shortName VarOption	(Optional) Reference to the short name of the Component object.
replicas VarOption	(Optional) Reference to the replicas of the component.
podNames VarOption	(Optional) Reference to the pod name list of the component. and the value will be presented in the following format: name1,name2,…
podFQDNs VarOption	(Optional) Reference to the pod FQDN list of the component. The value will be presented in the following format: FQDN1,FQDN2,…
podNamesForRole RoledVar	(Optional) Reference to the pod name list of the component that have a specific role. The value will be presented in the following format: name1,name2,…
podFQDNsForRole RoledVar	(Optional) Reference to the pod FQDN list of the component that have a specific role. The value will be presented in the following format: FQDN1,FQDN2,…

ComponentVersionCompatibilityRule

(Appears on:ComponentVersionSpec)

ComponentVersionCompatibilityRule defines the compatibility between a set of component definitions and a set of releases.

Field	Description
compDefs []string	CompDefs specifies names for the component definitions associated with this ComponentVersion. Each name in the list can represent an exact name, a name prefix, or a regular expression pattern. For example: “mysql-8.0.30-v1alpha1”: Matches the exact name “mysql-8.0.30-v1alpha1” “mysql-8.0.30”: Matches all names starting with “mysql-8.0.30” ”^mysql-8.0.\d{1,2}$“: Matches all names starting with “mysql-8.0.” followed by one or two digits.
releases []string	Releases is a list of identifiers for the releases.

ComponentVersionRelease

(Appears on:ComponentVersionSpec)

ComponentVersionRelease represents a release of component instances within a ComponentVersion.

Field	Description
name string	Name is a unique identifier for this release. Cannot be updated.
changes string	(Optional) Changes provides information about the changes made in this release.
serviceVersion string	ServiceVersion defines the version of the well-known service that the component provides. The version should follow the syntax and semantics of the “Semantic Versioning” specification (http://semver.org/). If the release is used, it will serve as the service version for component instances, overriding the one defined in the component definition. Cannot be updated.
images map[string]string	Images define the new images for containers, actions or external applications within the release. If an image is specified for a lifecycle action, the key should be the field name (case-insensitive) of the action in the LifecycleActions struct.

ComponentVersionSpec

(Appears on:ComponentVersion)

ComponentVersionSpec defines the desired state of ComponentVersion

Field	Description
compatibilityRules []ComponentVersionCompatibilityRule	CompatibilityRules defines compatibility rules between sets of component definitions and releases.
releases []ComponentVersionRelease	Releases represents different releases of component instances within this ComponentVersion.

ComponentVersionStatus

(Appears on:ComponentVersion)

ComponentVersionStatus defines the observed state of ComponentVersion

Field	Description
observedGeneration int64	(Optional) ObservedGeneration is the most recent generation observed for this ComponentVersion.
phase Phase	(Optional) Phase valid values are ``,Available, 'Unavailable`. Available is ComponentVersion become available, and can be used for co-related objects.
message string	(Optional) Extra message for current phase.
serviceVersions string	(Optional) ServiceVersions represent the supported service versions of this ComponentVersion.

ComponentVolume

(Appears on:ComponentDefinitionSpec)

Field	Description
name string	Specifies the name of the volume. It must be a DNS_LABEL and unique within the pod. More info can be found at: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names Note: This field cannot be updated.
needSnapshot bool	(Optional) Specifies whether the creation of a snapshot of this volume is necessary when performing a backup of the Component. Note: This field cannot be updated.
highWatermark int	(Optional) Sets the critical threshold for volume space utilization as a percentage (0-100). Exceeding this percentage triggers the system to switch the volume to read-only mode as specified in componentDefinition.spec.lifecycleActions.readOnly. This precaution helps prevent space depletion while maintaining read-only access. If the space utilization later falls below this threshold, the system reverts the volume to read-write mode as defined in componentDefinition.spec.lifecycleActions.readWrite, restoring full functionality. Note: This field cannot be updated.

ConfigTemplateExtension

Field	Description
templateRef string	Specifies the name of the referenced configuration template ConfigMap object.
namespace string	(Optional) Specifies the namespace of the referenced configuration template ConfigMap object. An empty namespace is equivalent to the “default” namespace.
policy MergedPolicy	(Optional) Defines the strategy for merging externally imported templates into component templates.

ConnectionCredentialAuth

(Appears on:ServiceDescriptorSpec)

ConnectionCredentialAuth specifies the authentication credentials required for accessing an external service.

Field	Description
username CredentialVar	(Optional) Specifies the username for the external service.
password CredentialVar	(Optional) Specifies the password for the external service.

ContainerVars

(Appears on:HostNetworkVars)

ContainerVars defines the vars that can be referenced from a Container.

Field	Description
name string	The name of the container.
port NamedVar	(Optional) Container port to reference.

CredentialVar

(Appears on:ConnectionCredentialAuth, ServiceDescriptorSpec)

CredentialVar represents a variable that retrieves its value either directly from a specified expression or from a source defined in valueFrom. Only one of these options may be used at a time.

Field	Description
value string	(Optional) Holds a direct string or an expression that can be evaluated to a string. It can include variables denoted by $(VAR_NAME). These variables are expanded to the value of the environment variables defined in the container. If a variable cannot be resolved, it remains unchanged in the output. To escape variable expansion and retain the literal value, use double $ characters. For example: ”$(VAR_NAME)” will be expanded to the value of the environment variable VAR_NAME. ”$$(VAR_NAME)” will result in “$(VAR_NAME)” in the output, without any variable expansion. Default value is an empty string.
valueFrom Kubernetes core/v1.EnvVarSource	(Optional) Specifies the source for the variable’s value.

CredentialVarSelector

(Appears on:VarSource)

CredentialVarSelector selects a var from a Credential (SystemAccount).

Field	Description
ClusterObjectReference ClusterObjectReference	(Members of ClusterObjectReference are embedded into this type.) The Credential (SystemAccount) to select from.
CredentialVars CredentialVars	(Members of CredentialVars are embedded into this type.)

CredentialVars

(Appears on:CredentialVarSelector, ServiceRefVars)

CredentialVars defines the vars that can be referenced from a Credential (SystemAccount). !!!!! CredentialVars will only be used as environment variables for Pods & Actions, and will not be used to render the templates.

Field	Description
username VarOption	(Optional)
password VarOption	(Optional)

EnvVar

(Appears on:ComponentDefinitionSpec, SidecarDefinitionSpec)

EnvVar represents a variable present in the env of Pod/Action or the template of config/script.

Field	Description
name string	Name of the variable. Must be a C_IDENTIFIER.
value string	(Optional) Variable references $(VAR_NAME) are expanded using the previously defined variables in the current context. If a variable cannot be resolved, the reference in the input string will be unchanged. Double $$ are reduced to a single $, which allows for escaping the $(VAR_NAME) syntax: i.e. $$(VAR_NAME) will produce the string literal $(VAR_NAME). Escaped references will never be expanded, regardless of whether the variable exists or not. Defaults to “”.
valueFrom VarSource	(Optional) Source for the variable’s value. Cannot be used if value is not empty.
expression string	(Optional) A Go template expression that will be applied to the resolved value of the var. The expression will only be evaluated if the var is successfully resolved to a non-credential value. The resolved value can be accessed by its name within the expression, system vars and other user-defined non-credential vars can be used within the expression in the same way. Notice that, when accessing vars by its name, you should replace all the “-” in the name with “_”, because of that “-” is not a valid identifier in Go. All expressions are evaluated in the order the vars are defined. If a var depends on any vars that also have expressions defined, be careful about the evaluation order as it may use intermediate values. The result of evaluation will be used as the final value of the var. If the expression fails to evaluate, the resolving of var will also be considered failed.

ExecAction

(Appears on:Action)

ExecAction describes an Action that executes a command inside a container.

Field	Description
image string	(Optional) Specifies the container image to be used for running the Action. When specified, a dedicated container will be created using this image to execute the Action. All actions with same image will share the same container. This field cannot be updated.
env []Kubernetes core/v1.EnvVar	(Optional) Represents a list of environment variables that will be injected into the container. These variables enable the container to adapt its behavior based on the environment it’s running in. This field cannot be updated.
command []string	(Optional) Specifies the command to be executed inside the container. The working directory for this command is the container’s root directory(‘/’). Commands are executed directly without a shell environment, meaning shell-specific syntax (‘|’, etc.) is not supported. If the shell is required, it must be explicitly invoked in the command. A successful execution is indicated by an exit status of 0; any non-zero status signifies a failure.
args []string	(Optional) Args represents the arguments that are passed to the command for execution.
targetPodSelector TargetPodSelector	(Optional) Defines the criteria used to select the target Pod(s) for executing the Action. This is useful when there is no default target replica identified. It allows for precise control over which Pod(s) the Action should run in. If not specified, the Action will be executed in the pod where the Action is triggered, such as the pod to be removed or added; or a random pod if the Action is triggered at the component level, such as post-provision or pre-terminate of the component. This field cannot be updated.
matchingKey string	(Optional) Used in conjunction with the targetPodSelector field to refine the selection of target pod(s) for Action execution. The impact of this field depends on the targetPodSelector value: When targetPodSelector is set to Any or All, this field will be ignored. When targetPodSelector is set to Role, only those replicas whose role matches the matchingKey will be selected for the Action. This field cannot be updated.
container string	(Optional) Specifies the name of the container within the same pod whose resources will be shared with the action. This allows the action to utilize the specified container’s resources without executing within it. The name must match one of the containers defined in componentDefinition.spec.runtime. The resources that can be shared are included: volume mounts This field cannot be updated.

Exporter

(Appears on:ComponentDefinitionSpec)

Field	Description
containerName string	(Optional) Specifies the name of the built-in metrics exporter container.
scrapePath string	(Optional) Specifies the http/https url path to scrape for metrics. If empty, Prometheus uses the default value (e.g. /metrics).
scrapePort string	(Optional) Specifies the port name to scrape for metrics.
scrapeScheme PrometheusScheme	(Optional) Specifies the schema to use for scraping. http and https are the expected values unless you rewrite the __scheme__ label via relabeling. If empty, Prometheus uses the default value http.

HostNetwork

(Appears on:ComponentDefinitionSpec)

Field	Description
containerPorts []HostNetworkContainerPort	(Optional) The list of container ports that are required by the component.

HostNetworkContainerPort

(Appears on:HostNetwork)

Field	Description
container string	Container specifies the target container within the Pod.
ports []string	Ports are named container ports within the specified container. These container ports must be defined in the container for proper port allocation.

HostNetworkVarSelector

(Appears on:VarSource)

HostNetworkVarSelector selects a var from host-network resources.

Field	Description
ClusterObjectReference ClusterObjectReference	(Members of ClusterObjectReference are embedded into this type.) The component to select from.
HostNetworkVars HostNetworkVars	(Members of HostNetworkVars are embedded into this type.)

HostNetworkVars

(Appears on:HostNetworkVarSelector)

HostNetworkVars defines the vars that can be referenced from host-network resources.

Field	Description
container ContainerVars	(Optional)

InstanceTemplate

(Appears on:ClusterComponentSpec, ComponentSpec, InstanceSetSpec)

InstanceTemplate allows customization of individual replica configurations in a Component.

Field	Description
name string	Name specifies the unique name of the instance Pod created using this InstanceTemplate. This name is constructed by concatenating the Component’s name, the template’s name, and the instance’s ordinal using the pattern: $(cluster.name)-$(component.name)-$(template.name)-$(ordinal). Ordinals start from 0. The specified name overrides any default naming conventions or patterns.
replicas int32	(Optional) Specifies the number of instances (Pods) to create from this InstanceTemplate. This field allows setting how many replicated instances of the Component, with the specific overrides in the InstanceTemplate, are created. The default value is 1. A value of 0 disables instance creation.
ordinals Ordinals	Specifies the desired Ordinals of this InstanceTemplate. The Ordinals used to specify the ordinal of the instance (pod) names to be generated under this InstanceTemplate. For example, if Ordinals is {ranges: [{start: 0, end: 1}], discrete: [7]}, then the instance names generated under this InstanceTemplate would be $(cluster.name)-$(component.name)-$(template.name)-0、$(cluster.name)-$(component.name)-$(template.name)-1 and $(cluster.name)-$(component.name)-$(template.name)-7
annotations map[string]string	(Optional) Specifies a map of key-value pairs to be merged into the Pod’s existing annotations. Existing keys will have their values overwritten, while new keys will be added to the annotations.
labels map[string]string	(Optional) Specifies a map of key-value pairs that will be merged into the Pod’s existing labels. Values for existing keys will be overwritten, and new keys will be added.
image string	(Optional) Specifies an override for the first container’s image in the Pod.
schedulingPolicy SchedulingPolicy	(Optional) Specifies the scheduling policy for the Component.
resources Kubernetes core/v1.ResourceRequirements	(Optional) Specifies an override for the resource requirements of the first container in the Pod. This field allows for customizing resource allocation (CPU, memory, etc.) for the container.
env []Kubernetes core/v1.EnvVar	(Optional) Defines Env to override. Add new or override existing envs.
volumes []Kubernetes core/v1.Volume	(Optional) Defines Volumes to override. Add new or override existing volumes.
volumeMounts []Kubernetes core/v1.VolumeMount	(Optional) Defines VolumeMounts to override. Add new or override existing volume mounts of the first container in the Pod.
volumeClaimTemplates []ClusterComponentVolumeClaimTemplate	(Optional) Defines VolumeClaimTemplates to override. Add new or override existing volume claim templates.

Issuer

(Appears on:ClusterComponentSpec, TLSConfig)

Issuer defines the TLS certificates issuer for the Cluster.

Field	Description
name IssuerName	The issuer for TLS certificates. It only allows two enum values: KubeBlocks and UserProvided. KubeBlocks indicates that the self-signed TLS certificates generated by the KubeBlocks Operator will be used. UserProvided means that the user is responsible for providing their own CA, Cert, and Key. In this case, the user-provided CA certificate, server certificate, and private key will be used for TLS communication.
secretRef TLSSecretRef	(Optional) SecretRef is the reference to the secret that contains user-provided certificates. It is required when the issuer is set to UserProvided.

IssuerName (string alias)

(Appears on:Issuer)

IssuerName defines the name of the TLS certificates issuer.

Value	Description
"KubeBlocks"	IssuerKubeBlocks represents certificates that are signed by the KubeBlocks Operator.
"UserProvided"	IssuerUserProvided indicates that the user has provided their own CA-signed certificates.

LetterCase (string alias)

(Appears on:PasswordConfig)

LetterCase defines the available cases to be used in password generation.

Value	Description
"LowerCases"	LowerCases represents the use of lower case letters only.
"MixedCases"	MixedCases represents the use of a mix of both lower and upper case letters.
"UpperCases"	UpperCases represents the use of upper case letters only.

LogConfig

(Appears on:ComponentDefinitionSpec)

Field	Description
name string	Specifies a descriptive label for the log type, such as ‘slow’ for a MySQL slow log file. It provides a clear identification of the log’s purpose and content.
filePathPattern string	Specifies the paths or patterns identifying where the log files are stored. This field allows the system to locate and manage log files effectively. Examples: /home/postgres/pgdata/pgroot/data/log/postgresql-* /data/mysql/log/mysqld-error.log

MergedPolicy (string alias)

(Appears on:ConfigTemplateExtension)

MergedPolicy defines how to merge external imported templates into component templates.

Value	Description
"none"
"add"
"patch"
"replace"

MultipleClusterObjectCombinedOption

(Appears on:MultipleClusterObjectOption)

MultipleClusterObjectCombinedOption defines options for handling combined variables.

Field	Description
newVarSuffix string	(Optional) If set, the existing variable will be kept, and a new variable will be defined with the specified suffix in pattern: $(var.name)_$(suffix). The new variable will be auto-created and placed behind the existing one. If not set, the existing variable will be reused with the value format defined below.
valueFormat MultipleClusterObjectValueFormat	(Optional) The format of the value that the operator will use to compose values from multiple components.
flattenFormat MultipleClusterObjectValueFormatFlatten	(Optional) The flatten format, default is: $(comp-name-1):value,$(comp-name-2):value.

MultipleClusterObjectOption

(Appears on:ClusterObjectReference)

MultipleClusterObjectOption defines the options for handling multiple cluster objects matched.

Field	Description
strategy MultipleClusterObjectStrategy	Define the strategy for handling multiple cluster objects.
combinedOption MultipleClusterObjectCombinedOption	(Optional) Define the options for handling combined variables. Valid only when the strategy is set to “combined”.

MultipleClusterObjectStrategy (string alias)

(Appears on:MultipleClusterObjectOption)

MultipleClusterObjectStrategy defines the strategy for handling multiple cluster objects.

Value	Description
"combined"	MultipleClusterObjectStrategyCombined - the values from all matched components will be combined into a single variable using the specified option.
"individual"	MultipleClusterObjectStrategyIndividual - each matched component will have its individual variable with its name as the suffix. This is required when referencing credential variables that cannot be passed by values.

MultipleClusterObjectValueFormat (string alias)

(Appears on:MultipleClusterObjectCombinedOption)

MultipleClusterObjectValueFormat defines the format details for the value.

Value	Description
"Flatten"

MultipleClusterObjectValueFormatFlatten

(Appears on:MultipleClusterObjectCombinedOption)

MultipleClusterObjectValueFormatFlatten defines the flatten format for the value.

Field	Description
delimiter string	Pair delimiter.
keyValueDelimiter string	Key-value delimiter.

NamedVar

(Appears on:ContainerVars, ServiceVars)

Field	Description
name string	(Optional)
option VarOption	(Optional)

Ordinals

(Appears on:InstanceTemplate, InstanceSetSpec)

Ordinals represents a combination of continuous segments and individual values.

Field	Description
ranges []Range
discrete []int32

PasswordConfig

(Appears on:ComponentSystemAccount, SystemAccount)

PasswordConfig helps provide to customize complexity of password generation pattern.

Field	Description
length int32	(Optional) The length of the password.
numDigits int32	(Optional) The number of digits in the password.
numSymbols int32	(Optional) The number of symbols in the password.
letterCase LetterCase	(Optional) The case of the letters in the password.
seed string	(Optional) Seed to generate the account’s password. Cannot be updated.

PersistentVolumeClaimSpec

(Appears on:ClusterComponentVolumeClaimTemplate)

Field	Description
accessModes []Kubernetes core/v1.PersistentVolumeAccessMode	(Optional) Contains the desired access modes the volume should have. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#access-modes-1.
resources Kubernetes core/v1.VolumeResourceRequirements	(Optional) Represents the minimum resources the volume should have. If the RecoverVolumeExpansionFailure feature is enabled, users are allowed to specify resource requirements that are lower than the previous value but must still be higher than the capacity recorded in the status field of the claim. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#resources.
storageClassName string	(Optional) The name of the StorageClass required by the claim. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#class-1.
volumeMode Kubernetes core/v1.PersistentVolumeMode	(Optional) Defines what type of volume is required by the claim, either Block or Filesystem.
volumeAttributesClassName string	(Optional) volumeAttributesClassName may be used to set the VolumeAttributesClass used by this claim. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#volumeattributesclass

Phase (string alias)

(Appears on:ClusterDefinitionStatus, ComponentDefinitionStatus, ComponentVersionStatus, ServiceDescriptorStatus, ShardingDefinitionStatus, SidecarDefinitionStatus)

Phase represents the status of a CR.

Value	Description
"Available"	AvailablePhase indicates that a CR is in an available state.
"Unavailable"	UnavailablePhase indicates that a CR is in an unavailable state.

PodUpdatePolicyType (string alias)

(Appears on:ClusterComponentSpec, ComponentSpec)

Value	Description
"PreferInPlace"	PreferInPlacePodUpdatePolicyType indicates that we will first attempt an in-place upgrade of the Pod. If that fails, it will fall back to the ReCreate, where pod will be recreated.
"StrictInPlace"	StrictInPlacePodUpdatePolicyType indicates that only allows in-place upgrades. Any attempt to modify other fields will be rejected.

PreConditionType (string alias)

(Appears on:Action)

PreConditionType defines the preCondition type of the action execution.

Value	Description
"ClusterReady"
"ComponentReady"
"Immediately"
"RuntimeReady"

Probe

(Appears on:ComponentLifecycleActions)

Field	Description
Action Action	(Members of Action are embedded into this type.)
initialDelaySeconds int32	(Optional) Specifies the number of seconds to wait after the container has started before the RoleProbe begins to detect the container’s role.
periodSeconds int32	(Optional) Specifies the frequency at which the probe is conducted. This value is expressed in seconds. Default to 10 seconds. Minimum value is 1.
successThreshold int32	(Optional) Minimum consecutive successes for the probe to be considered successful after having failed. Defaults to 1. Minimum value is 1.
failureThreshold int32	(Optional) Minimum consecutive failures for the probe to be considered failed after having succeeded. Defaults to 3. Minimum value is 1.

PrometheusScheme (string alias)

(Appears on:Exporter)

PrometheusScheme defines the protocol of prometheus scrape metrics.

Value	Description
"http"
"https"

ProvisionSecretRef

(Appears on:ComponentSystemAccount, SystemAccount)

ProvisionSecretRef represents the reference to a secret.

Field	Description
name string	The unique identifier of the secret.
namespace string	The namespace where the secret is located.

Range

(Appears on:Ordinals)

Range represents a range with a start and an end value. It is used to define a continuous segment.

Field	Description
start int32
end int32

ReplicaRole

(Appears on:ComponentDefinitionSpec, InstanceSetSpec, MemberStatus)

ReplicaRole represents a role that can be assigned to a component instance, defining its behavior and responsibilities.

Field	Description
name string	Name defines the role’s unique identifier. This value is used to set the “apps.kubeblocks.io/role” label on the corresponding object to identify its role. For example, common role names include: “leader”: The primary/master instance that handles write operations “follower”: Secondary/replica instances that replicate data from the leader “learner”: Read-only instances that don’t participate in elections This field is immutable once set.
updatePriority int	(Optional) UpdatePriority determines the order in which pods with different roles are updated. Pods are sorted by this priority (higher numbers = higher priority) and updated accordingly. Roles with the highest priority will be updated last. The default priority is 0. For example: Leader role may have priority 2 (updated last) Follower role may have priority 1 (updated before leader) Learner role may have priority 0 (updated first) This field is immutable once set.
participatesInQuorum bool	(Optional) ParticipatesInQuorum indicates if pods with this role are counted when determining quorum. This affects update strategies that need to maintain quorum for availability. Roles participate in quorum should have higher update priority than roles do not participate in quorum. The default value is false. For example, in a 5-pod component where: 2 learner pods (participatesInQuorum=false) 2 follower pods (participatesInQuorum=true) 1 leader pod (participatesInQuorum=true) The quorum size would be 3 (based on the 3 participating pods), allowing parallel updates of 2 learners and 1 follower while maintaining quorum. This field is immutable once set.

ReplicasLimit

(Appears on:ComponentDefinitionSpec)

ReplicasLimit defines the valid range of number of replicas supported.

Field	Description
minReplicas int32	The minimum limit of replicas.
maxReplicas int32	The maximum limit of replicas.

RerenderResourceType (string alias)

(Appears on:ComponentConfigSpec)

RerenderResourceType defines the resource requirements for a component.

Value	Description
"hscale"
"vscale"

RetryPolicy

(Appears on:Action)

Field	Description
maxRetries int	(Optional) Defines the maximum number of retry attempts that should be made for a given Action. This value is set to 0 by default, indicating that no retries will be made.
retryInterval time.Duration	(Optional) Indicates the duration of time to wait between each retry attempt. This value is set to 0 by default, indicating that there will be no delay between retry attempts.

RoledVar

(Appears on:ComponentVars)

Field	Description
role string	(Optional)
option VarOption	(Optional)

SchedulingPolicy

(Appears on:ClusterComponentSpec, ClusterSpec, ComponentSpec, InstanceTemplate)

Field	Description
schedulerName string	(Optional) If specified, the Pod will be dispatched by specified scheduler. If not specified, the Pod will be dispatched by default scheduler.
nodeSelector map[string]string	(Optional) NodeSelector is a selector which must be true for the Pod to fit on a node. Selector which must match a node’s labels for the Pod to be scheduled on that node. More info: https://kubernetes.io/docs/concepts/configuration/assign-pod-node/
nodeName string	(Optional) NodeName is a request to schedule this Pod onto a specific node. If it is non-empty, the scheduler simply schedules this Pod onto that node, assuming that it fits resource requirements.
affinity Kubernetes core/v1.Affinity	(Optional) Specifies a group of affinity scheduling rules of the Cluster, including NodeAffinity, PodAffinity, and PodAntiAffinity.
tolerations []Kubernetes core/v1.Toleration	(Optional) Allows Pods to be scheduled onto nodes with matching taints. Each toleration in the array allows the Pod to tolerate node taints based on specified key, value, effect, and operator. The key, value, and effect identify the taint that the toleration matches. The operator determines how the toleration matches the taint. Pods with matching tolerations are allowed to be scheduled on tainted nodes, typically reserved for specific purposes.
topologySpreadConstraints []Kubernetes core/v1.TopologySpreadConstraint	(Optional) TopologySpreadConstraints describes how a group of Pods ought to spread across topology domains. Scheduler will schedule Pods in a way which abides by the constraints. All topologySpreadConstraints are ANDed.

Service

(Appears on:ClusterService, ComponentService)

Field	Description
name string	Name defines the name of the service. otherwise, it indicates the name of the service. Others can refer to this service by its name. (e.g., connection credential) Cannot be updated.
serviceName string	(Optional) ServiceName defines the name of the underlying service object. If not specified, the default service name with different patterns will be used: CLUSTER_NAME: for cluster-level services CLUSTER_NAME-COMPONENT_NAME: for component-level services Only one default service name is allowed. Cannot be updated.
annotations map[string]string	(Optional) If ServiceType is LoadBalancer, cloud provider related parameters can be put here More info: https://kubernetes.io/docs/concepts/services-networking/service/#loadbalancer.
spec Kubernetes core/v1.ServiceSpec	(Optional) Spec defines the behavior of a service. https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status ports []Kubernetes core/v1.ServicePort The list of ports that are exposed by this service. More info: https://kubernetes.io/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies selector map[string]string (Optional) Route service traffic to pods with label keys and values matching this selector. If empty or not present, the service is assumed to have an external process managing its endpoints, which Kubernetes will not modify. Only applies to types ClusterIP, NodePort, and LoadBalancer. Ignored if type is ExternalName. More info: https://kubernetes.io/docs/concepts/services-networking/service/ clusterIP string (Optional) clusterIP is the IP address of the service and is usually assigned randomly. If an address is specified manually, is in-range (as per system configuration), and is not in use, it will be allocated to the service; otherwise creation of the service will fail. This field may not be changed through updates unless the type field is also being changed to ExternalName (which requires this field to be blank) or the type field is being changed from ExternalName (in which case this field may optionally be specified, as describe above). Valid values are “None”, empty string (“”), or a valid IP address. Setting this to “None” makes a “headless service” (no virtual IP), which is useful when direct endpoint connections are preferred and proxying is not required. Only applies to types ClusterIP, NodePort, and LoadBalancer. If this field is specified when creating a Service of type ExternalName, creation will fail. This field will be wiped when updating a Service to type ExternalName. More info: https://kubernetes.io/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies clusterIPs []string (Optional) ClusterIPs is a list of IP addresses assigned to this service, and are usually assigned randomly. If an address is specified manually, is in-range (as per system configuration), and is not in use, it will be allocated to the service; otherwise creation of the service will fail. This field may not be changed through updates unless the type field is also being changed to ExternalName (which requires this field to be empty) or the type field is being changed from ExternalName (in which case this field may optionally be specified, as describe above). Valid values are “None”, empty string (“”), or a valid IP address. Setting this to “None” makes a “headless service” (no virtual IP), which is useful when direct endpoint connections are preferred and proxying is not required. Only applies to types ClusterIP, NodePort, and LoadBalancer. If this field is specified when creating a Service of type ExternalName, creation will fail. This field will be wiped when updating a Service to type ExternalName. If this field is not specified, it will be initialized from the clusterIP field. If this field is specified, clients must ensure that clusterIPs[0] and clusterIP have the same value. This field may hold a maximum of two entries (dual-stack IPs, in either order). These IPs must correspond to the values of the ipFamilies field. Both clusterIPs and ipFamilies are governed by the ipFamilyPolicy field. More info: https://kubernetes.io/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies type Kubernetes core/v1.ServiceType (Optional) type determines how the Service is exposed. Defaults to ClusterIP. Valid options are ExternalName, ClusterIP, NodePort, and LoadBalancer. “ClusterIP” allocates a cluster-internal IP address for load-balancing to endpoints. Endpoints are determined by the selector or if that is not specified, by manual construction of an Endpoints object or EndpointSlice objects. If clusterIP is “None”, no virtual IP is allocated and the endpoints are published as a set of endpoints rather than a virtual IP. “NodePort” builds on ClusterIP and allocates a port on every node which routes to the same endpoints as the clusterIP. “LoadBalancer” builds on NodePort and creates an external load-balancer (if supported in the current cloud) which routes to the same endpoints as the clusterIP. “ExternalName” aliases this service to the specified externalName. Several other fields do not apply to ExternalName services. More info: https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services-service-types externalIPs []string (Optional) externalIPs is a list of IP addresses for which nodes in the cluster will also accept traffic for this service. These IPs are not managed by Kubernetes. The user is responsible for ensuring that traffic arrives at a node with this IP. A common example is external load-balancers that are not part of the Kubernetes system. sessionAffinity Kubernetes core/v1.ServiceAffinity (Optional) Supports “ClientIP” and “None”. Used to maintain session affinity. Enable client IP based session affinity. Must be ClientIP or None. Defaults to None. More info: https://kubernetes.io/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies loadBalancerIP string (Optional) Only applies to Service Type: LoadBalancer. This feature depends on whether the underlying cloud-provider supports specifying the loadBalancerIP when a load balancer is created. This field will be ignored if the cloud-provider does not support the feature. Deprecated: This field was under-specified and its meaning varies across implementations. Using it is non-portable and it may not support dual-stack. Users are encouraged to use implementation-specific annotations when available. loadBalancerSourceRanges []string (Optional) If specified and supported by the platform, this will restrict traffic through the cloud-provider load-balancer will be restricted to the specified client IPs. This field will be ignored if the cloud-provider does not support the feature.” More info: https://kubernetes.io/docs/tasks/access-application-cluster/create-external-load-balancer/ externalName string (Optional) externalName is the external reference that discovery mechanisms will return as an alias for this service (e.g. a DNS CNAME record). No proxying will be involved. Must be a lowercase RFC-1123 hostname (https://tools.ietf.org/html/rfc1123) and requires type to be “ExternalName”. externalTrafficPolicy Kubernetes core/v1.ServiceExternalTrafficPolicy (Optional) externalTrafficPolicy describes how nodes distribute service traffic they receive on one of the Service’s “externally-facing” addresses (NodePorts, ExternalIPs, and LoadBalancer IPs). If set to “Local”, the proxy will configure the service in a way that assumes that external load balancers will take care of balancing the service traffic between nodes, and so each node will deliver traffic only to the node-local endpoints of the service, without masquerading the client source IP. (Traffic mistakenly sent to a node with no endpoints will be dropped.) The default value, “Cluster”, uses the standard behavior of routing to all endpoints evenly (possibly modified by topology and other features). Note that traffic sent to an External IP or LoadBalancer IP from within the cluster will always get “Cluster” semantics, but clients sending to a NodePort from within the cluster may need to take traffic policy into account when picking a node. healthCheckNodePort int32 (Optional) healthCheckNodePort specifies the healthcheck nodePort for the service. This only applies when type is set to LoadBalancer and externalTrafficPolicy is set to Local. If a value is specified, is in-range, and is not in use, it will be used. If not specified, a value will be automatically allocated. External systems (e.g. load-balancers) can use this port to determine if a given node holds endpoints for this service or not. If this field is specified when creating a Service which does not need it, creation will fail. This field will be wiped when updating a Service to no longer need it (e.g. changing type). This field cannot be updated once set. publishNotReadyAddresses bool (Optional) publishNotReadyAddresses indicates that any agent which deals with endpoints for this Service should disregard any indications of ready/not-ready. The primary use case for setting this field is for a StatefulSet’s Headless Service to propagate SRV DNS records for its Pods for the purpose of peer discovery. The Kubernetes controllers that generate Endpoints and EndpointSlice resources for Services interpret this to mean that all endpoints are considered “ready” even if the Pods themselves are not. Agents which consume only Kubernetes generated endpoints through the Endpoints or EndpointSlice resources can safely assume this behavior. sessionAffinityConfig Kubernetes core/v1.SessionAffinityConfig (Optional) sessionAffinityConfig contains the configurations of session affinity. ipFamilies []Kubernetes core/v1.IPFamily (Optional) IPFamilies is a list of IP families (e.g. IPv4, IPv6) assigned to this service. This field is usually assigned automatically based on cluster configuration and the ipFamilyPolicy field. If this field is specified manually, the requested family is available in the cluster, and ipFamilyPolicy allows it, it will be used; otherwise creation of the service will fail. This field is conditionally mutable: it allows for adding or removing a secondary IP family, but it does not allow changing the primary IP family of the Service. Valid values are “IPv4” and “IPv6”. This field only applies to Services of types ClusterIP, NodePort, and LoadBalancer, and does apply to “headless” services. This field will be wiped when updating a Service to type ExternalName. This field may hold a maximum of two entries (dual-stack families, in either order). These families must correspond to the values of the clusterIPs field, if specified. Both clusterIPs and ipFamilies are governed by the ipFamilyPolicy field. ipFamilyPolicy Kubernetes core/v1.IPFamilyPolicy (Optional) IPFamilyPolicy represents the dual-stack-ness requested or required by this Service. If there is no value provided, then this field will be set to SingleStack. Services can be “SingleStack” (a single IP family), “PreferDualStack” (two IP families on dual-stack configured clusters or a single IP family on single-stack clusters), or “RequireDualStack” (two IP families on dual-stack configured clusters, otherwise fail). The ipFamilies and clusterIPs fields depend on the value of this field. This field will be wiped when updating a service to type ExternalName. allocateLoadBalancerNodePorts bool (Optional) allocateLoadBalancerNodePorts defines if NodePorts will be automatically allocated for services with type LoadBalancer. Default is “true”. It may be set to “false” if the cluster load-balancer does not rely on NodePorts. If the caller requests specific NodePorts (by specifying a value), those requests will be respected, regardless of this field. This field may only be set for services with type LoadBalancer and will be cleared if the type is changed to any other type. loadBalancerClass string (Optional) loadBalancerClass is the class of the load balancer implementation this Service belongs to. If specified, the value of this field must be a label-style identifier, with an optional prefix, e.g. “internal-vip” or “example.com/internal-vip”. Unprefixed names are reserved for end-users. This field can only be set when the Service type is ‘LoadBalancer’. If not set, the default load balancer implementation is used, today this is typically done through the cloud provider integration, but should apply for any default implementation. If set, it is assumed that a load balancer implementation is watching for Services with a matching class. Any default load balancer implementation (e.g. cloud providers) should ignore Services that set this field. This field can only be set when creating or updating a Service to type ‘LoadBalancer’. Once set, it can not be changed. This field will be wiped when a service is updated to a non ‘LoadBalancer’ type. internalTrafficPolicy Kubernetes core/v1.ServiceInternalTrafficPolicy (Optional) InternalTrafficPolicy describes how nodes distribute service traffic they receive on the ClusterIP. If set to “Local”, the proxy will assume that pods only want to talk to endpoints of the service on the same node as the pod, dropping the traffic if there are no local endpoints. The default value, “Cluster”, uses the standard behavior of routing to all endpoints evenly (possibly modified by topology and other features).
roleSelector string	(Optional) Extends the above serviceSpec.selector by allowing you to specify defined role as selector for the service. When roleSelector is set, it adds a label selector “kubeblocks.io/role: {roleSelector}” to the serviceSpec.selector. Example usage: roleSelector: "leader" In this example, setting roleSelector to “leader” will add a label selector “kubeblocks.io/role: leader” to the serviceSpec.selector. This means that the service will select and route traffic to Pods with the label “kubeblocks.io/role” set to “leader”. Note that if podService sets to true, RoleSelector will be ignored. The podService flag takes precedence over roleSelector and generates a service for each Pod.

ServiceDescriptorSpec

(Appears on:ServiceDescriptor)

ServiceDescriptorSpec defines the desired state of ServiceDescriptor

Field	Description
serviceKind string	Describes the type of database service provided by the external service. For example, “mysql”, “redis”, “mongodb”. This field categorizes databases by their functionality, protocol and compatibility, facilitating appropriate service integration based on their unique capabilities. This field is case-insensitive. It also supports abbreviations for some well-known databases: “pg”, “pgsql”, “postgres”, “postgresql”: PostgreSQL service “zk”, “zookeeper”: ZooKeeper service “es”, “elasticsearch”: Elasticsearch service “mongo”, “mongodb”: MongoDB service “ch”, “clickhouse”: ClickHouse service
serviceVersion string	Describes the version of the service provided by the external service. This is crucial for ensuring compatibility between different components of the system, as different versions of a service may have varying features.
endpoint CredentialVar	(Optional) Specifies the endpoint of the external service. If the service is exposed via a cluster, the endpoint will be provided in the format of host:port.
host CredentialVar	(Optional) Specifies the service or IP address of the external service.
port CredentialVar	(Optional) Specifies the port of the external service.
podFQDNs CredentialVar	(Optional) Specifies the pod FQDNs of the external service.
auth ConnectionCredentialAuth	(Optional) Specifies the authentication credentials required for accessing an external service.

ServiceDescriptorStatus

(Appears on:ServiceDescriptor)

ServiceDescriptorStatus defines the observed state of ServiceDescriptor

Field	Description
observedGeneration int64	(Optional) Represents the generation number that has been processed by the controller.
phase Phase	(Optional) Indicates the current lifecycle phase of the ServiceDescriptor. This can be either ‘Available’ or ‘Unavailable’.
message string	(Optional) Provides a human-readable explanation detailing the reason for the current phase of the ServiceConnectionCredential.

ServiceRef

(Appears on:ClusterComponentSpec, ComponentSpec)

Field	Description
name string	Specifies the identifier of the service reference declaration. It corresponds to the serviceRefDeclaration name defined in either: componentDefinition.spec.serviceRefDeclarations[*].name clusterDefinition.spec.componentDefs[*].serviceRefDeclarations[*].name (deprecated)
namespace string	(Optional) Specifies the namespace of the referenced Cluster or the namespace of the referenced ServiceDescriptor object. If not provided, the referenced Cluster and ServiceDescriptor will be searched in the namespace of the current Cluster by default.
cluster string	(Optional) Specifies the name of the KubeBlocks Cluster being referenced. This is used when services from another KubeBlocks Cluster are consumed. By default, the referenced KubeBlocks Cluster’s clusterDefinition.spec.connectionCredential will be utilized to bind to the current Component. This credential should include: endpoint, port, username, and password. Note: The ServiceKind and ServiceVersion specified in the service reference within the ClusterDefinition are not validated when using this approach. If both cluster and serviceDescriptor are present, cluster will take precedence. Deprecated since v0.9 since clusterDefinition.spec.connectionCredential is deprecated, use clusterServiceSelector instead. This field is maintained for backward compatibility and its use is discouraged. Existing usage should be updated to the current preferred approach to avoid compatibility issues in future releases.
clusterServiceSelector ServiceRefClusterSelector	(Optional) References a service provided by another KubeBlocks Cluster. It specifies the ClusterService and the account credentials needed for access.
serviceDescriptor string	(Optional) Specifies the name of the ServiceDescriptor object that describes a service provided by external sources. When referencing a service provided by external sources, a ServiceDescriptor object is required to establish the service binding. The serviceDescriptor.spec.serviceKind and serviceDescriptor.spec.serviceVersion should match the serviceKind and serviceVersion declared in the definition. If both cluster and serviceDescriptor are specified, the cluster takes precedence.

ServiceRefClusterSelector

(Appears on:ServiceRef)

Field	Description
cluster string	The name of the Cluster being referenced.
service ServiceRefServiceSelector	(Optional) Identifies a ClusterService from the list of Services defined in cluster.spec.services of the referenced Cluster.
podFQDNs ServiceRefPodFQDNsSelector	(Optional)
credential ServiceRefCredentialSelector	(Optional) Specifies the SystemAccount to authenticate and establish a connection with the referenced Cluster. The SystemAccount should be defined in componentDefinition.spec.systemAccounts of the Component providing the service in the referenced Cluster.

ServiceRefCredentialSelector

(Appears on:ServiceRefClusterSelector)

Field	Description
component string	The name of the Component where the credential resides in.
name string	The name of the credential (SystemAccount) to reference.

ServiceRefDeclaration

(Appears on:ComponentDefinitionSpec)

ServiceRefDeclaration represents a reference to a service that can be either provided by a KubeBlocks Cluster or an external service. It acts as a placeholder for the actual service reference, which is determined later when a Cluster is created.

The purpose of ServiceRefDeclaration is to declare a service dependency without specifying the concrete details of the service. It allows for flexibility and abstraction in defining service references within a Component. By using ServiceRefDeclaration, you can define service dependencies in a declarative manner, enabling loose coupling and easier management of service references across different components and clusters.

Upon Cluster creation, the ServiceRefDeclaration is bound to an actual service through the ServiceRef field, effectively resolving and connecting to the specified service.

Field	Description
name string	Specifies the name of the ServiceRefDeclaration.
serviceRefDeclarationSpecs []ServiceRefDeclarationSpec	Defines a list of constraints and requirements for services that can be bound to this ServiceRefDeclaration upon Cluster creation. Each ServiceRefDeclarationSpec defines a ServiceKind and ServiceVersion, outlining the acceptable service types and versions that are compatible. This flexibility allows a ServiceRefDeclaration to be fulfilled by any one of the provided specs. For example, if it requires an OLTP database, specs for both MySQL and PostgreSQL are listed, either MySQL or PostgreSQL services can be used when binding.
optional bool	(Optional) Specifies whether the service reference can be optional. For an optional service-ref, the component can still be created even if the service-ref is not provided.

ServiceRefDeclarationSpec

(Appears on:ServiceRefDeclaration)

Field	Description
serviceKind string	Specifies the type or nature of the service. This should be a well-known application cluster type, such as {mysql, redis, mongodb}. The field is case-insensitive and supports abbreviations for some well-known databases. For instance, both zk and zookeeper are considered as a ZooKeeper cluster, while pg, postgres, postgresql are all recognized as a PostgreSQL cluster.
serviceVersion string	Defines the service version of the service reference. This is a regular expression that matches a version number pattern. For instance, ^8.0.8$, 8.0.\d{1,2}$, ^[v\-]*?(\d{1,2}\.){0,3}\d{1,2}$ are all valid patterns.

ServiceRefPodFQDNsSelector

(Appears on:ServiceRefClusterSelector)

Field	Description
component string	The name of the Component where the pods reside in.
role string	(Optional) The role of the pods to reference.

ServiceRefServiceSelector

(Appears on:ServiceRefClusterSelector)

Field	Description
component string	(Optional) The name of the Component where the Service resides in. It is required when referencing a Component’s Service.
service string	The name of the Service to be referenced. Leave it empty to reference the default Service. Set it to “headless” to reference the default headless Service. If the referenced Service is of pod-service type (a Service per Pod), there will be multiple Service objects matched, and the resolved value will be presented in the following format: service1.name,service2.name…
port string	(Optional) The port name of the Service to be referenced. If there is a non-zero node-port exist for the matched Service port, the node-port will be selected first. If the referenced Service is of pod-service type (a Service per Pod), there will be multiple Service objects matched, and the resolved value will be presented in the following format: service1.name:port1,service2.name:port2…

ServiceRefVarSelector

(Appears on:VarSource)

ServiceRefVarSelector selects a var from a ServiceRefDeclaration.

Field	Description
ClusterObjectReference ClusterObjectReference	(Members of ClusterObjectReference are embedded into this type.) The ServiceRefDeclaration to select from.
ServiceRefVars ServiceRefVars	(Members of ServiceRefVars are embedded into this type.)

ServiceRefVars

(Appears on:ServiceRefVarSelector)

ServiceRefVars defines the vars that can be referenced from a ServiceRef.

Field	Description
endpoint VarOption	(Optional)
host VarOption	(Optional)
port VarOption	(Optional)
podFQDNs VarOption	(Optional)
CredentialVars CredentialVars	(Members of CredentialVars are embedded into this type.)

ServiceVarSelector

(Appears on:VarSource)

ServiceVarSelector selects a var from a Service.

Field	Description
ClusterObjectReference ClusterObjectReference	(Members of ClusterObjectReference are embedded into this type.) The Service to select from. It can be referenced from the default headless service by setting the name to “headless”.
ServiceVars ServiceVars	(Members of ServiceVars are embedded into this type.)

ServiceVars

(Appears on:ServiceVarSelector)

ServiceVars defines the vars that can be referenced from a Service.

Field	Description
serviceType VarOption	(Optional) ServiceType references the type of the service.
host VarOption	(Optional)
loadBalancer VarOption	(Optional) LoadBalancer represents the LoadBalancer ingress point of the service. If multiple ingress points are available, the first one will be used automatically, choosing between IP and Hostname.
port NamedVar	(Optional) Port references a port or node-port defined in the service. If the referenced service is a pod-service, there will be multiple service objects matched, and the value will be presented in the following format: service1.name:port1,service2.name:port2…

ShardingDefinitionSpec

(Appears on:ShardingDefinition)

ShardingDefinitionSpec defines the desired state of ShardingDefinition

Field	Description
template ShardingTemplate	This field is immutable.
shardsLimit ShardsLimit	(Optional) Defines the upper limit of the number of shards supported by the sharding. This field is immutable.
provisionStrategy UpdateStrategy	(Optional) Specifies the strategy for provisioning shards of the sharding. Only Serial and Parallel are supported. This field is immutable.
updateStrategy UpdateStrategy	(Optional) Specifies the strategy for updating shards of the sharding. Only Serial and Parallel are supported. This field is immutable.
lifecycleActions ShardingLifecycleActions	(Optional) Defines a set of hooks and procedures that customize the behavior of a sharding throughout its lifecycle. This field is immutable.
systemAccounts []ShardingSystemAccount	(Optional) Defines the system accounts for the sharding. This field is immutable.
tls ShardingTLS	(Optional) Defines the TLS for the sharding. This field is immutable.

ShardingDefinitionStatus

(Appears on:ShardingDefinition)

ShardingDefinitionStatus defines the observed state of ShardingDefinition

Field	Description
observedGeneration int64	(Optional) Refers to the most recent generation that has been observed for the ShardingDefinition.
phase Phase	(Optional) Represents the current status of the ShardingDefinition. Valid values include ``,Available, andUnavailable<code>. When the status is</code>Available, the ShardingDefinition is ready and can be utilized by related objects.
message string	(Optional) Provides additional information about the current phase.

ShardingLifecycleActions

(Appears on:ShardingDefinitionSpec)

ShardingLifecycleActions defines a collection of Actions for customizing the behavior of a sharding.

Field	Description
postProvision Action	(Optional) Specifies the hook to be executed after a sharding’s creation. By setting postProvision.preCondition, you can determine the specific lifecycle stage at which the action should trigger, available conditions for sharding include: Immediately, ComponentReady, and ClusterReady. For sharding, the ComponentReady condition means all components of the sharding are ready. With ComponentReady being the default. The PostProvision Action is intended to run only once. Note: This field is immutable once it has been set.
preTerminate Action	(Optional) Specifies the hook to be executed prior to terminating a sharding. The PreTerminate Action is intended to run only once. This action is executed immediately when a terminate operation for the sharding is initiated. The actual termination and cleanup of the sharding and its associated resources will not proceed until the PreTerminate action has completed successfully. Note: This field is immutable once it has been set.
shardAdd Action	(Optional) Specifies the hook to be executed after a shard added. Note: This field is immutable once it has been set.
shardRemove Action	(Optional) Specifies the hook to be executed prior to remove a shard. Note: This field is immutable once it has been set.

ShardingSystemAccount

(Appears on:ShardingDefinitionSpec)

Field	Description
name string	The name of the system account defined in the sharding template. This field is immutable once set.
shared bool	(Optional) Specifies whether the account is shared across all shards in the sharding.

ShardingTLS

(Appears on:ShardingDefinitionSpec)

Field	Description
shared bool	(Optional) Specifies whether the TLS configuration is shared across all shards in the sharding.

ShardingTemplate

(Appears on:ShardingDefinitionSpec)

Field	Description
compDef string	The component definition(s) that the sharding is based on. The component definition can be specified using one of the following: the full name the regular expression pattern (‘^’ will be added to the beginning of the pattern automatically) This field is immutable.

ShardsLimit

(Appears on:ShardingDefinitionSpec)

ShardsLimit defines the valid range of number of shards supported.

Field	Description
minShards int32	The minimum limit of shards.
maxShards int32	The maximum limit of replicas.

Sidecar

(Appears on:ComponentSpec)

Field	Description
name string	Name specifies the unique name of the sidecar. The name will be used as the name of the sidecar container in the Pod.
owner string	Specifies the exact component definition that the sidecar belongs to. A sidecar will be updated when the owner component definition is updated only.
sidecarDef string	Specifies the sidecar definition CR to be used to create the sidecar.

SidecarDefinitionSpec

(Appears on:SidecarDefinition)

SidecarDefinitionSpec defines the desired state of SidecarDefinition

Field	Description
name string	Specifies the name of the sidecar.
owner string	Specifies the component definition that the sidecar belongs to. For a specific cluster object, if there is any components provided by the component definition of @owner, the sidecar will be created and injected into the components which are provided by the component definition of @selectors automatically. This field is immutable.
selectors []string	Specifies the component definition of components that the sidecar along with. This field is immutable.
containers []Kubernetes core/v1.Container	List of containers for the sidecar. Cannot be updated.
vars []EnvVar	(Optional) Defines variables which are needed by the sidecar. This field is immutable.
configs []ComponentTemplateSpec	(Optional) Specifies the configuration file templates used by the Sidecar. This field is immutable.
scripts []ComponentTemplateSpec	(Optional) Specifies the scripts used by the Sidecar. This field is immutable.

SidecarDefinitionStatus

(Appears on:SidecarDefinition)

SidecarDefinitionStatus defines the observed state of SidecarDefinition

Field	Description
observedGeneration int64	(Optional) Refers to the most recent generation that has been observed for the SidecarDefinition.
phase Phase	(Optional) Represents the current status of the SidecarDefinition. Valid values include ``,Available, andUnavailable<code>. When the status is</code>Available, the SidecarDefinition is ready and can be utilized by related objects.
message string	(Optional) Provides additional information about the current phase.
owners string	(Optional) Resolved owners of the SidecarDefinition.
selectors string	(Optional) Resolved selectors of the SidecarDefinition.

SystemAccount

(Appears on:ComponentDefinitionSpec)

Field	Description
name string	Specifies the unique identifier for the account. This name is used by other entities to reference the account. This field is immutable once set.
initAccount bool	(Optional) Indicates if this account is a system initialization account (e.g., MySQL root). This field is immutable once set.
statement string	(Optional) Defines the statement used to create the account with the necessary privileges. This field is immutable once set.
passwordGenerationPolicy PasswordConfig	(Optional) Specifies the policy for generating the account’s password. This field is immutable once set.
secretRef ProvisionSecretRef	(Optional) Refers to the secret from which data will be copied to create the new account. This field is immutable once set.

TLS

(Appears on:ComponentDefinitionSpec)

Field	Description
volumeName string	Specifies the volume name for the TLS secret. The controller will create a volume object with the specified name and add it to the pod when the TLS is enabled. This field is immutable once set.
mountPath string	Specifies the mount path for the TLS secret to be mounted. Similar to the volume, the controller will mount the created volume to the specified path within containers when the TLS is enabled. This field is immutable once set.
defaultMode int32	(Optional) The permissions for the mounted path. Defaults to 0600. This field is immutable once set.
caFile string	(Optional) The CA file of the TLS. This field is immutable once set.
certFile string	(Optional) The certificate file of the TLS. This field is immutable once set.
keyFile string	(Optional) The key file of the TLS. This field is immutable once set.

TLSConfig

(Appears on:ComponentSpec)

Field	Description
enable bool	(Optional) A boolean flag that indicates whether the Component should use Transport Layer Security (TLS) for secure communication. When set to true, the Component will be configured to use TLS encryption for its network connections. This ensures that the data transmitted between the Component and its clients or other Components is encrypted and protected from unauthorized access. If TLS is enabled, the Component may require additional configuration, such as specifying TLS certificates and keys, to properly set up the secure communication channel.
issuer Issuer	(Optional) Specifies the configuration for the TLS certificates issuer. It allows defining the issuer name and the reference to the secret containing the TLS certificates and key. The secret should contain the CA certificate, TLS certificate, and private key in the specified keys. Required when TLS is enabled.

TLSSecretRef

(Appears on:Issuer)

TLSSecretRef defines Secret contains Tls certs

Field	Description
name string	Name of the Secret that contains user-provided certificates.
ca string	Key of CA cert in Secret
cert string	Key of Cert in Secret
key string	Key of TLS private key in Secret

TLSVarSelector

(Appears on:VarSource)

TLSVarSelector selects a var from the TLS.

Field	Description
ClusterObjectReference ClusterObjectReference	(Members of ClusterObjectReference are embedded into this type.) The Component to select from.
TLSVars TLSVars	(Members of TLSVars are embedded into this type.)

TLSVars

(Appears on:TLSVarSelector)

TLSVars defines the vars that can be referenced from the TLS.

Field	Description
enabled VarOption	(Optional)

TargetPodSelector (string alias)

(Appears on:ExecAction)

TargetPodSelector defines how to select pod(s) to execute an Action.

Value	Description
"All"
"Any"
"Ordinal"
"Role"

TerminationPolicyType (string alias)

(Appears on:ClusterSpec)

TerminationPolicyType defines termination policy types.

Value	Description
"Delete"	Delete will delete all runtime resources belong to the cluster.
"DoNotTerminate"	DoNotTerminate will block delete operation.
"WipeOut"	WipeOut is based on Delete and wipe out all volume snapshots and snapshot data from backup storage location.

UpdateStrategy (string alias)

(Appears on:ComponentDefinitionSpec, ShardingDefinitionSpec)

UpdateStrategy defines the update strategy for cluster components. This strategy determines how updates are applied across the cluster. The available strategies are Serial, BestEffortParallel, and Parallel.

Value	Description
"BestEffortParallel"	BestEffortParallelStrategy indicates that the replicas are updated in parallel, with the operator making a best-effort attempt to update as many replicas as possible concurrently while maintaining the component’s availability. Unlike the Parallel strategy, the BestEffortParallel strategy aims to ensure that a minimum number of replicas remain available during the update process to maintain the component’s quorum and functionality. For example, consider a component with 5 replicas. To maintain the component’s availability and quorum, the operator may allow a maximum of 2 replicas to be simultaneously updated. This ensures that at least 3 replicas (a quorum) remain available and functional during the update process. The BestEffortParallel strategy strikes a balance between update speed and component availability.
"Parallel"	ParallelStrategy indicates that updates are applied simultaneously to all Pods of a Component. The replicas are updated in parallel, with the operator updating all replicas concurrently. This strategy provides the fastest update time but may lead to a period of reduced availability or capacity during the update process.
"Serial"	SerialStrategy indicates that updates are applied one at a time in a sequential manner. The operator waits for each replica to be updated and ready before proceeding to the next one. This ensures that only one replica is unavailable at a time during the update process.

VarOption (string alias)

(Appears on:ClusterVars, ComponentVars, CredentialVars, NamedVar, RoledVar, ServiceRefVars, ServiceVars, TLSVars)

VarOption defines whether a variable is required or optional.

VarSource

(Appears on:EnvVar)

VarSource represents a source for the value of an EnvVar.

Field	Description
configMapKeyRef Kubernetes core/v1.ConfigMapKeySelector	(Optional) Selects a key of a ConfigMap.
secretKeyRef Kubernetes core/v1.SecretKeySelector	(Optional) Selects a key of a Secret.
hostNetworkVarRef HostNetworkVarSelector	(Optional) Selects a defined var of host-network resources.
serviceVarRef ServiceVarSelector	(Optional) Selects a defined var of a Service.
credentialVarRef CredentialVarSelector	(Optional) Selects a defined var of a Credential (SystemAccount).
tlsVarRef TLSVarSelector	(Optional) Selects a defined var of the TLS.
serviceRefVarRef ServiceRefVarSelector	(Optional) Selects a defined var of a ServiceRef.
componentVarRef ComponentVarSelector	(Optional) Selects a defined var of a Component.
clusterVarRef ClusterVarSelector	(Optional) Selects a defined var of a Cluster.

---

apps.kubeblocks.io/v1alpha1

Resource Types:

• Cluster
• ClusterDefinition
• Component
• ComponentDefinition
• ComponentVersion
• ConfigConstraint
• Configuration
• ServiceDescriptor

Cluster

Cluster offers a unified management interface for a wide variety of database and storage systems:

• Relational databases: MySQL, PostgreSQL, MariaDB

• NoSQL databases: Redis, MongoDB

• KV stores: ZooKeeper, etcd

• Analytics systems: ElasticSearch, OpenSearch, ClickHouse, Doris, StarRocks, Solr

• Message queues: Kafka, Pulsar

• Distributed SQL: TiDB, OceanBase

• Vector databases: Qdrant, Milvus, Weaviate

• Object storage: Minio

KubeBlocks utilizes an abstraction layer to encapsulate the characteristics of these diverse systems. A Cluster is composed of multiple Components, each defined by vendors or KubeBlocks Addon developers via ComponentDefinition, arranged in Directed Acyclic Graph (DAG) topologies. The topologies, defined in a ClusterDefinition, coordinate reconciliation across Cluster’s lifecycle phases: Creating, Running, Updating, Stopping, Stopped, Deleting. Lifecycle management ensures that each Component operates in harmony, executing appropriate actions at each lifecycle stage.

For sharded-nothing architecture, the Cluster supports managing multiple shards, each shard managed by a separate Component, supporting dynamic resharding.

The Cluster object is aimed to maintain the overall integrity and availability of a database cluster, serves as the central control point, abstracting the complexity of multiple-component management, and providing a unified interface for cluster-wide operations.

Field	Description
apiVersion string	apps.kubeblocks.io/v1alpha1
kind string	Cluster
metadata Kubernetes meta/v1.ObjectMeta	Refer to the Kubernetes API documentation for the fields of the metadata field.
spec ClusterSpec	clusterDefinitionRef string (Optional) Specifies the name of the ClusterDefinition to use when creating a Cluster. This field enables users to create a Cluster based on a specific ClusterDefinition. Which, in conjunction with the topology field, determine: The Components to be included in the Cluster. The sequences in which the Components are created, updated, and terminate. This facilitates multiple-components management with predefined ClusterDefinition. Users with advanced requirements can bypass this general setting and specify more precise control over the composition of the Cluster by directly referencing specific ComponentDefinitions for each component within componentSpecs[*].componentDef. If this field is not provided, each component must be explicitly defined in componentSpecs[*].componentDef. Note: Once set, this field cannot be modified; it is immutable. clusterVersionRef string (Optional) Refers to the ClusterVersion name. Deprecated since v0.9, use ComponentVersion instead. This field is maintained for backward compatibility and its use is discouraged. Existing usage should be updated to the current preferred approach to avoid compatibility issues in future releases. topology string (Optional) Specifies the name of the ClusterTopology to be used when creating the Cluster. This field defines which set of Components, as outlined in the ClusterDefinition, will be used to construct the Cluster based on the named topology. The ClusterDefinition may list multiple topologies under clusterdefinition.spec.topologies[*], each tailored to different use cases or environments. If topology is not specified, the Cluster will use the default topology defined in the ClusterDefinition. Note: Once set during the Cluster creation, the topology field cannot be modified. It establishes the initial composition and structure of the Cluster and is intended for one-time configuration. terminationPolicy TerminationPolicyType Specifies the behavior when a Cluster is deleted. It defines how resources, data, and backups associated with a Cluster are managed during termination. Choose a policy based on the desired level of resource cleanup and data preservation: DoNotTerminate: Prevents deletion of the Cluster. This policy ensures that all resources remain intact. Halt: Deletes Cluster resources like Pods and Services but retains Persistent Volume Claims (PVCs), allowing for data preservation while stopping other operations. Warning: Halt policy is deprecated in 0.9.1 and will have same meaning as DoNotTerminate. Delete: Extends the Halt policy by also removing PVCs, leading to a thorough cleanup while removing all persistent data. WipeOut: An aggressive policy that deletes all Cluster resources, including volume snapshots and backups in external storage. This results in complete data removal and should be used cautiously, primarily in non-production environments to avoid irreversible data loss. Warning: Choosing an inappropriate termination policy can result in data loss. The WipeOut policy is particularly risky in production environments due to its irreversible nature. shardingSpecs []ShardingSpec (Optional) Specifies a list of ShardingSpec objects that manage the sharding topology for Cluster Components. Each ShardingSpec organizes components into shards, with each shard corresponding to a Component. Components within a shard are all based on a common ClusterComponentSpec template, ensuring uniform configurations. This field supports dynamic resharding by facilitating the addition or removal of shards through the shards field in ShardingSpec. Note: shardingSpecs and componentSpecs cannot both be empty; at least one must be defined to configure a Cluster. componentSpecs []ClusterComponentSpec (Optional) Specifies a list of ClusterComponentSpec objects used to define the individual Components that make up a Cluster. This field allows for detailed configuration of each Component within the Cluster. Note: shardingSpecs and componentSpecs cannot both be empty; at least one must be defined to configure a Cluster. services []ClusterService (Optional) Defines a list of additional Services that are exposed by a Cluster. This field allows Services of selected Components, either from componentSpecs or shardingSpecs to be exposed, alongside Services defined with ComponentService. Services defined here can be referenced by other clusters using the ServiceRefClusterSelector. affinity Affinity (Optional) Defines a set of node affinity scheduling rules for the Cluster’s Pods. This field helps control the placement of Pods on nodes within the Cluster. Deprecated since v0.10. Use the schedulingPolicy field instead. tolerations []Kubernetes core/v1.Toleration (Optional) An array that specifies tolerations attached to the Cluster’s Pods, allowing them to be scheduled onto nodes with matching taints. Deprecated since v0.10. Use the schedulingPolicy field instead. schedulingPolicy SchedulingPolicy (Optional) Specifies the scheduling policy for the Cluster. runtimeClassName string (Optional) Specifies runtimeClassName for all Pods managed by this Cluster. backup ClusterBackup (Optional) Specifies the backup configuration of the Cluster. tenancy TenancyType (Optional) Describes how Pods are distributed across node. Deprecated since v0.9. This field is maintained for backward compatibility and its use is discouraged. Existing usage should be updated to the current preferred approach to avoid compatibility issues in future releases. availabilityPolicy AvailabilityPolicyType (Optional) Describes the availability policy, including zone, node, and none. Deprecated since v0.9. This field is maintained for backward compatibility and its use is discouraged. Existing usage should be updated to the current preferred approach to avoid compatibility issues in future releases. replicas int32 (Optional) Specifies the replicas of the first componentSpec, if the replicas of the first componentSpec is specified, this value will be ignored. Deprecated since v0.9. This field is maintained for backward compatibility and its use is discouraged. Existing usage should be updated to the current preferred approach to avoid compatibility issues in future releases. resources ClusterResources (Optional) Specifies the resources of the first componentSpec, if the resources of the first componentSpec is specified, this value will be ignored. Deprecated since v0.9. This field is maintained for backward compatibility and its use is discouraged. Existing usage should be updated to the current preferred approach to avoid compatibility issues in future releases. storage ClusterStorage (Optional) Specifies the storage of the first componentSpec, if the storage of the first componentSpec is specified, this value will be ignored. Deprecated since v0.9. This field is maintained for backward compatibility and its use is discouraged. Existing usage should be updated to the current preferred approach to avoid compatibility issues in future releases. network ClusterNetwork (Optional) The configuration of network. Deprecated since v0.9. This field is maintained for backward compatibility and its use is discouraged. Existing usage should be updated to the current preferred approach to avoid compatibility issues in future releases.
status ClusterStatus

ClusterDefinition

ClusterDefinition defines the topology for databases or storage systems, offering a variety of topological configurations to meet diverse deployment needs and scenarios.

It includes a list of Components, each linked to a ComponentDefinition, which enhances reusability and reduce redundancy. For example, widely used components such as etcd and Zookeeper can be defined once and reused across multiple ClusterDefinitions, simplifying the setup of new systems.

Additionally, ClusterDefinition also specifies the sequence of startup, upgrade, and shutdown for Components, ensuring a controlled and predictable management of component lifecycles.

Field	Description
apiVersion string	apps.kubeblocks.io/v1alpha1
kind string	ClusterDefinition
metadata Kubernetes meta/v1.ObjectMeta	Refer to the Kubernetes API documentation for the fields of the metadata field.
spec ClusterDefinitionSpec	type string (Optional) Specifies the well-known database type, such as mysql, redis, or mongodb. Deprecated since v0.9. This field is maintained for backward compatibility and its use is discouraged. Existing usage should be updated to the current preferred approach to avoid compatibility issues in future releases. componentDefs []ClusterComponentDefinition (Optional) Provides the definitions for the cluster components. Deprecated since v0.9. Components should now be individually defined using ComponentDefinition and collectively referenced via topology.components. This field is maintained for backward compatibility and its use is discouraged. Existing usage should be updated to the current preferred approach to avoid compatibility issues in future releases. connectionCredential map[string]string (Optional) Connection credential template used for creating a connection credential secret for cluster objects. Built-in objects are: $(RANDOM_PASSWD) random 8 characters. $(STRONG_RANDOM_PASSWD) random 16 characters, with mixed cases, digits and symbols. $(UUID) generate a random UUID v4 string. $(UUID_B64) generate a random UUID v4 BASE64 encoded string. $(UUID_STR_B64) generate a random UUID v4 string then BASE64 encoded. $(UUID_HEX) generate a random UUID v4 HEX representation. $(HEADLESS_SVC_FQDN) headless service FQDN placeholder, value pattern is $(CLUSTER_NAME)-$(1ST_COMP_NAME)-headless.$(NAMESPACE).svc, where 1ST_COMP_NAME is the 1st component that provide ClusterDefinition.spec.componentDefs[].service attribute; $(SVC_FQDN) service FQDN placeholder, value pattern is $(CLUSTER_NAME)-$(1ST_COMP_NAME).$(NAMESPACE).svc, where 1ST_COMP_NAME is the 1st component that provide ClusterDefinition.spec.componentDefs[].service attribute; $(SVC_PORT_{PORT-NAME}) is ServicePort’s port value with specified port name, i.e, a servicePort JSON struct: {"name": "mysql", "targetPort": "mysqlContainerPort", "port": 3306}, and $(SVC_PORT_mysql) in the connection credential value is 3306. Deprecated since v0.9. This field is maintained for backward compatibility and its use is discouraged. Existing usage should be updated to the current preferred approach to avoid compatibility issues in future releases. topologies []ClusterTopology (Optional) Topologies defines all possible topologies within the cluster.
status ClusterDefinitionStatus

Component

Component is a fundamental building block of a Cluster object. For example, a Redis Cluster can include Components like ‘redis’, ‘sentinel’, and potentially a proxy like ‘twemproxy’.

The Component object is responsible for managing the lifecycle of all replicas within a Cluster component, It supports a wide range of operations including provisioning, stopping, restarting, termination, upgrading, configuration changes, vertical and horizontal scaling, failover, switchover, cross-node migration, scheduling configuration, exposing Services, managing system accounts, enabling/disabling exporter, and configuring log collection.

Component is an internal sub-object derived from the user-submitted Cluster object. It is designed primarily to be used by the KubeBlocks controllers, users are discouraged from modifying Component objects directly and should use them only for monitoring Component statuses.

Field	Description
apiVersion string	apps.kubeblocks.io/v1alpha1
kind string	Component
metadata Kubernetes meta/v1.ObjectMeta	Refer to the Kubernetes API documentation for the fields of the metadata field.
spec ComponentSpec	compDef string Specifies the name of the referenced ComponentDefinition. serviceVersion string (Optional) ServiceVersion specifies the version of the Service expected to be provisioned by this Component. The version should follow the syntax and semantics of the “Semantic Versioning” specification (http://semver.org/). serviceRefs []ServiceRef (Optional) Defines a list of ServiceRef for a Component, enabling access to both external services and Services provided by other Clusters. Types of services: External services: Not managed by KubeBlocks or managed by a different KubeBlocks operator; Require a ServiceDescriptor for connection details. Services provided by a Cluster: Managed by the same KubeBlocks operator; identified using Cluster, Component and Service names. ServiceRefs with identical serviceRef.name in the same Cluster are considered the same. Example: serviceRefs: name: "redis-sentinel" serviceDescriptor: name: "external-redis-sentinel" name: "postgres-cluster" clusterServiceSelector: cluster: "my-postgres-cluster" service: component: "postgresql" The example above includes ServiceRefs to an external Redis Sentinel service and a PostgreSQL Cluster. labels map[string]string (Optional) Specifies Labels to override or add for underlying Pods, PVCs, Account & TLS Secrets, Services Owned by Component. annotations map[string]string (Optional) Specifies Annotations to override or add for underlying Pods, PVCs, Account & TLS Secrets, Services Owned by Component. env []Kubernetes core/v1.EnvVar (Optional) List of environment variables to add. resources Kubernetes core/v1.ResourceRequirements (Optional) Specifies the resources required by the Component. It allows defining the CPU, memory requirements and limits for the Component’s containers. volumeClaimTemplates []ClusterComponentVolumeClaimTemplate (Optional) Specifies a list of PersistentVolumeClaim templates that define the storage requirements for the Component. Each template specifies the desired characteristics of a persistent volume, such as storage class, size, and access modes. These templates are used to dynamically provision persistent volumes for the Component. volumes []Kubernetes core/v1.Volume (Optional) List of volumes to override. services []ComponentService (Optional) Overrides Services defined in referenced ComponentDefinition and exposes endpoints that can be accessed by clients. systemAccounts []ComponentSystemAccount (Optional) Overrides system accounts defined in referenced ComponentDefinition. replicas int32 Specifies the desired number of replicas in the Component for enhancing availability and durability, or load balancing. configs []ClusterComponentConfig (Optional) Specifies the configuration content of a config template. enabledLogs []string (Optional) Specifies which types of logs should be collected for the Cluster. The log types are defined in the componentDefinition.spec.logConfigs field with the LogConfig entries. The elements in the enabledLogs array correspond to the names of the LogConfig entries. For example, if the componentDefinition.spec.logConfigs defines LogConfig entries with names “slow_query_log” and “error_log”, you can enable the collection of these logs by including their names in the enabledLogs array: enabledLogs: slow_query_log error_log serviceAccountName string (Optional) Specifies the name of the ServiceAccount required by the running Component. This ServiceAccount is used to grant necessary permissions for the Component’s Pods to interact with other Kubernetes resources, such as modifying Pod labels or sending events. Defaults: If not specified, KubeBlocks automatically assigns a default ServiceAccount named “kb-{cluster.name}”, bound to a default role defined during KubeBlocks installation. Future Changes: Future versions might change the default ServiceAccount creation strategy to one per Component, potentially revising the naming to “kb-{cluster.name}-{component.name}”. Users can override the automatic ServiceAccount assignment by explicitly setting the name of an existed ServiceAccount in this field. instanceUpdateStrategy InstanceUpdateStrategy (Optional) Indicates the InstanceUpdateStrategy that will be employed to update Pods in the InstanceSet when a revision is made to Template. parallelPodManagementConcurrency Kubernetes api utils intstr.IntOrString (Optional) Controls the concurrency of pods during initial scale up, when replacing pods on nodes, or when scaling down. It only used when PodManagementPolicy is set to Parallel. The default Concurrency is 100%. podUpdatePolicy PodUpdatePolicyType (Optional) PodUpdatePolicy indicates how pods should be updated StrictInPlace indicates that only allows in-place upgrades. Any attempt to modify other fields will be rejected. PreferInPlace indicates that we will first attempt an in-place upgrade of the Pod. If that fails, it will fall back to the ReCreate, where pod will be recreated. Default value is “PreferInPlace” affinity Affinity (Optional) Specifies a group of affinity scheduling rules for the Component. It allows users to control how the Component’s Pods are scheduled onto nodes in the Cluster. Deprecated since v0.10, replaced by the schedulingPolicy field. tolerations []Kubernetes core/v1.Toleration (Optional) Allows Pods to be scheduled onto nodes with matching taints. Each toleration in the array allows the Pod to tolerate node taints based on specified key, value, effect, and operator. The key, value, and effect identify the taint that the toleration matches. The operator determines how the toleration matches the taint. Pods with matching tolerations are allowed to be scheduled on tainted nodes, typically reserved for specific purposes. Deprecated since v0.10, replaced by the schedulingPolicy field. schedulingPolicy SchedulingPolicy (Optional) Specifies the scheduling policy for the Component. tlsConfig TLSConfig (Optional) Specifies the TLS configuration for the Component, including: A boolean flag that indicates whether the Component should use Transport Layer Security (TLS) for secure communication. An optional field that specifies the configuration for the TLS certificates issuer when TLS is enabled. It allows defining the issuer name and the reference to the secret containing the TLS certificates and key. The secret should contain the CA certificate, TLS certificate, and private key in the specified keys. instances []InstanceTemplate (Optional) Allows for the customization of configuration values for each instance within a Component. An Instance represent a single replica (Pod and associated K8s resources like PVCs, Services, and ConfigMaps). While instances typically share a common configuration as defined in the ClusterComponentSpec, they can require unique settings in various scenarios: For example: A database Component might require different resource allocations for primary and secondary instances, with primaries needing more resources. During a rolling upgrade, a Component may first update the image for one or a few instances, and then update the remaining instances after verifying that the updated instances are functioning correctly. InstanceTemplate allows for specifying these unique configurations per instance. Each instance’s name is constructed using the pattern: $(component.name)-$(template.name)-$(ordinal), starting with an ordinal of 0. It is crucial to maintain unique names for each InstanceTemplate to avoid conflicts. The sum of replicas across all InstanceTemplates should not exceed the total number of Replicas specified for the Component. Any remaining replicas will be generated using the default template and will follow the default naming rules. offlineInstances []string (Optional) Specifies the names of instances to be transitioned to offline status. Marking an instance as offline results in the following: The associated Pod is stopped, and its PersistentVolumeClaim (PVC) is retained for potential future reuse or data recovery, but it is no longer actively used. The ordinal number assigned to this instance is preserved, ensuring it remains unique and avoiding conflicts with new instances. Setting instances to offline allows for a controlled scale-in process, preserving their data and maintaining ordinal consistency within the Cluster. Note that offline instances and their associated resources, such as PVCs, are not automatically deleted. The administrator must manually manage the cleanup and removal of these resources when they are no longer needed. runtimeClassName string (Optional) Defines runtimeClassName for all Pods managed by this Component. disableExporter bool (Optional) Determines whether metrics exporter information is annotated on the Component’s headless Service. If set to true, the following annotations will not be patched into the Service: “monitor.kubeblocks.io/path” “monitor.kubeblocks.io/port” “monitor.kubeblocks.io/scheme” These annotations allow the Prometheus installed by KubeBlocks to discover and scrape metrics from the exporter. stop bool (Optional) Stop the Component. If set, all the computing resources will be released.
status ComponentStatus

ComponentDefinition

ComponentDefinition serves as a reusable blueprint for creating Components, encapsulating essential static settings such as Component description, Pod templates, configuration file templates, scripts, parameter lists, injected environment variables and their sources, and event handlers. ComponentDefinition works in conjunction with dynamic settings from the ClusterComponentSpec, to instantiate Components during Cluster creation.

Key aspects that can be defined in a ComponentDefinition include:

• PodSpec template: Specifies the PodSpec template used by the Component.

• Configuration templates: Specify the configuration file templates required by the Component.

• Scripts: Provide the necessary scripts for Component management and operations.

• Storage volumes: Specify the storage volumes and their configurations for the Component.

• Pod roles: Outlines various roles of Pods within the Component along with their capabilities.

• Exposed Kubernetes Services: Specify the Services that need to be exposed by the Component.

• System accounts: Define the system accounts required for the Component.

• Monitoring and logging: Configure the exporter and logging settings for the Component.

ComponentDefinitions also enable defining reactive behaviors of the Component in response to events, such as member join/leave, Component addition/deletion, role changes, switch over, and more. This allows for automatic event handling, thus encapsulating complex behaviors within the Component.

Referencing a ComponentDefinition when creating individual Components ensures inheritance of predefined configurations, promoting reusability and consistency across different deployments and cluster topologies.

Field	Description
apiVersion string	apps.kubeblocks.io/v1alpha1
kind string	ComponentDefinition
metadata Kubernetes meta/v1.ObjectMeta	Refer to the Kubernetes API documentation for the fields of the metadata field.
spec ComponentDefinitionSpec	provider string (Optional) Specifies the name of the Component provider, typically the vendor or developer name. It identifies the entity responsible for creating and maintaining the Component. When specifying the provider name, consider the following guidelines: Keep the name concise and relevant to the Component. Use a consistent naming convention across Components from the same provider. Avoid using trademarked or copyrighted names without proper permission. description string (Optional) Provides a brief and concise explanation of the Component’s purpose, functionality, and any relevant details. It serves as a quick reference for users to understand the Component’s role and characteristics. serviceKind string (Optional) Defines the type of well-known service protocol that the Component provides. It specifies the standard or widely recognized protocol used by the Component to offer its Services. The serviceKind field allows users to quickly identify the type of Service provided by the Component based on common protocols or service types. This information helps in understanding the compatibility, interoperability, and usage of the Component within a system. Some examples of well-known service protocols include: “MySQL”: Indicates that the Component provides a MySQL database service. “PostgreSQL”: Indicates that the Component offers a PostgreSQL database service. “Redis”: Signifies that the Component functions as a Redis key-value store. “ETCD”: Denotes that the Component serves as an ETCD distributed key-value store. The serviceKind value is case-insensitive, allowing for flexibility in specifying the protocol name. When specifying the serviceKind, consider the following guidelines: Use well-established and widely recognized protocol names or service types. Ensure that the serviceKind accurately represents the primary service type offered by the Component. If the Component provides multiple services, choose the most prominent or commonly used protocol. Limit the serviceKind to a maximum of 32 characters for conciseness and readability. Note: The serviceKind field is optional and can be left empty if the Component does not fit into a well-known service category or if the protocol is not widely recognized. It is primarily used to convey information about the Component’s service type to users and facilitate discovery and integration. The serviceKind field is immutable and cannot be updated. serviceVersion string (Optional) Specifies the version of the Service provided by the Component. It follows the syntax and semantics of the “Semantic Versioning” specification (http://semver.org/). The Semantic Versioning specification defines a version number format of X.Y.Z (MAJOR.MINOR.PATCH), where: X represents the major version and indicates incompatible API changes. Y represents the minor version and indicates added functionality in a backward-compatible manner. Z represents the patch version and indicates backward-compatible bug fixes. Additional labels for pre-release and build metadata are available as extensions to the X.Y.Z format: Use pre-release labels (e.g., -alpha, -beta) for versions that are not yet stable or ready for production use. Use build metadata (e.g., +build.1) for additional version information if needed. Examples of valid ServiceVersion values: “1.0.0” “2.3.1” “3.0.0-alpha.1” “4.5.2+build.1” The serviceVersion field is immutable and cannot be updated. runtime Kubernetes core/v1.PodSpec Specifies the PodSpec template used in the Component. It includes the following elements: Init containers Containers Image Commands Args Envs Mounts Ports Security context Probes Lifecycle Volumes This field is intended to define static settings that remain consistent across all instantiated Components. Dynamic settings such as CPU and memory resource limits, as well as scheduling settings (affinity, toleration, priority), may vary among different instantiated Components. They should be specified in the cluster.spec.componentSpecs (ClusterComponentSpec). Specific instances of a Component may override settings defined here, such as using a different container image or modifying environment variable values. These instance-specific overrides can be specified in cluster.spec.componentSpecs[*].instances. This field is immutable and cannot be updated once set. monitor MonitorConfig (Optional) Deprecated since v0.9 monitor is monitoring config which provided by provider. exporter Exporter (Optional) Defines the built-in metrics exporter container. vars []EnvVar (Optional) Defines variables which are determined after Cluster instantiation and reflect dynamic or runtime attributes of instantiated Clusters. These variables serve as placeholders for setting environment variables in Pods and Actions, or for rendering configuration and script templates before actual values are finalized. These variables are placed in front of the environment variables declared in the Pod if used as environment variables. Variable values can be sourced from: ConfigMap: Select and extract a value from a specific key within a ConfigMap. Secret: Select and extract a value from a specific key within a Secret. HostNetwork: Retrieves values (including ports) from host-network resources. Service: Retrieves values (including address, port, NodePort) from a selected Service. Intended to obtain the address of a ComponentService within the same Cluster. Credential: Retrieves account name and password from a SystemAccount variable. ServiceRef: Retrieves address, port, account name and password from a selected ServiceRefDeclaration. Designed to obtain the address bound to a ServiceRef, such as a ClusterService or ComponentService of another cluster or an external service. Component: Retrieves values from a selected Component, including replicas and instance name list. This field is immutable. volumes []ComponentVolume (Optional) Defines the volumes used by the Component and some static attributes of the volumes. After defining the volumes here, user can reference them in the cluster.spec.componentSpecs[*].volumeClaimTemplates field to configure dynamic properties such as volume capacity and storage class. This field allows you to specify the following: Snapshot behavior: Determines whether a snapshot of the volume should be taken when performing a snapshot backup of the Component. Disk high watermark: Sets the high watermark for the volume’s disk usage. When the disk usage reaches the specified threshold, it triggers an alert or action. By configuring these volume behaviors, you can control how the volumes are managed and monitored within the Component. This field is immutable. hostNetwork HostNetwork (Optional) Specifies the host network configuration for the Component. When hostNetwork option is enabled, the Pods share the host’s network namespace and can directly access the host’s network interfaces. This means that if multiple Pods need to use the same port, they cannot run on the same host simultaneously due to port conflicts. The DNSPolicy field in the Pod spec determines how containers within the Pod perform DNS resolution. When using hostNetwork, the operator will set the DNSPolicy to ‘ClusterFirstWithHostNet’. With this policy, DNS queries will first go through the K8s cluster’s DNS service. If the query fails, it will fall back to the host’s DNS settings. If set, the DNS policy will be automatically set to “ClusterFirstWithHostNet”. This field is immutable. services []ComponentService (Optional) Defines additional Services to expose the Component’s endpoints. A default headless Service, named {cluster.name}-{component.name}-headless, is automatically created for internal Cluster communication. This field enables customization of additional Services to expose the Component’s endpoints to other Components within the same or different Clusters, and to external applications. Each Service entry in this list can include properties such as ports, type, and selectors. For intra-Cluster access, Components can reference Services using variables declared in componentDefinition.spec.vars[*].valueFrom.serviceVarRef. For inter-Cluster access, reference Services use variables declared in componentDefinition.spec.vars[*].valueFrom.serviceRefVarRef, and bind Services at Cluster creation time with clusterComponentSpec.ServiceRef[*].clusterServiceSelector. This field is immutable. configs []ComponentConfigSpec (Optional) Specifies the configuration file templates and volume mount parameters used by the Component. It also includes descriptions of the parameters in the ConfigMaps, such as value range limitations. This field specifies a list of templates that will be rendered into Component containers’ configuration files. Each template is represented as a ConfigMap and may contain multiple configuration files, with each file being a key in the ConfigMap. The rendered configuration files will be mounted into the Component’s containers according to the specified volume mount parameters. This field is immutable. logConfigs []LogConfig (Optional) Defines the types of logs generated by instances of the Component and their corresponding file paths. These logs can be collected for further analysis and monitoring. The logConfigs field is an optional list of LogConfig objects, where each object represents a specific log type and its configuration. It allows you to specify multiple log types and their respective file paths for the Component. Examples: logConfigs: filePathPattern: /data/mysql/log/mysqld-error.log name: error filePathPattern: /data/mysql/log/mysqld.log name: general filePathPattern: /data/mysql/log/mysqld-slowquery.log name: slow This field is immutable. scripts []ComponentTemplateSpec (Optional) Specifies groups of scripts, each provided via a ConfigMap, to be mounted as volumes in the container. These scripts can be executed during container startup or via specific actions. Each script group is encapsulated in a ComponentTemplateSpec that includes: The ConfigMap containing the scripts. The mount point where the scripts will be mounted inside the container. This field is immutable. policyRules []Kubernetes rbac/v1.PolicyRule (Optional) Defines the namespaced policy rules required by the Component. The policyRules field is an array of rbacv1.PolicyRule objects that define the policy rules needed by the Component to operate within a namespace. These policy rules determine the permissions and verbs the Component is allowed to perform on Kubernetes resources within the namespace. The purpose of this field is to automatically generate the necessary RBAC roles for the Component based on the specified policy rules. This ensures that the Pods in the Component has appropriate permissions to function. Note: This field is currently non-functional and is reserved for future implementation. This field is immutable. labels map[string]string (Optional) Specifies static labels that will be patched to all Kubernetes resources created for the Component. Note: If a label key in the labels field conflicts with any system labels or user-specified labels, it will be silently ignored to avoid overriding higher-priority labels. This field is immutable. annotations map[string]string (Optional) Specifies static annotations that will be patched to all Kubernetes resources created for the Component. Note: If an annotation key in the annotations field conflicts with any system annotations or user-specified annotations, it will be silently ignored to avoid overriding higher-priority annotations. This field is immutable. replicasLimit ReplicasLimit (Optional) Defines the upper limit of the number of replicas supported by the Component. It defines the maximum number of replicas that can be created for the Component. This field allows you to set a limit on the scalability of the Component, preventing it from exceeding a certain number of replicas. This field is immutable. systemAccounts []SystemAccount (Optional) An array of SystemAccount objects that define the system accounts needed for the management operations of the Component. Each SystemAccount includes: Account name. The SQL statement template: Used to create the system account. Password Source: Either generated based on certain rules or retrieved from a Secret. Use cases for system accounts typically involve tasks like system initialization, backups, monitoring, health checks, replication, and other system-level operations. System accounts are distinct from user accounts, although both are database accounts. System Accounts: Created during Cluster setup by the KubeBlocks operator, these accounts have higher privileges for system management and are fully managed through a declarative API by the operator. User Accounts: Managed by users or administrator. User account permissions should follow the principle of least privilege, granting only the necessary access rights to complete their required tasks. This field is immutable. updateStrategy UpdateStrategy (Optional) Specifies the concurrency strategy for updating multiple instances of the Component. Available strategies: Serial: Updates replicas one at a time, ensuring minimal downtime by waiting for each replica to become ready before updating the next. Parallel: Updates all replicas simultaneously, optimizing for speed but potentially reducing availability during the update. BestEffortParallel: Updates replicas concurrently with a limit on simultaneous updates to ensure a minimum number of operational replicas for maintaining quorum. For example, in a 5-replica component, updating a maximum of 2 replicas simultaneously keeps at least 3 operational for quorum. This field is immutable and defaults to ‘Serial’. podManagementPolicy Kubernetes apps/v1.PodManagementPolicyType (Optional) InstanceSet controls the creation of pods during initial scale up, replacement of pods on nodes, and scaling down. OrderedReady: Creates pods in increasing order (pod-0, then pod-1, etc). The controller waits until each pod is ready before continuing. Pods are removed in reverse order when scaling down. Parallel: Creates pods in parallel to match the desired scale without waiting. All pods are deleted at once when scaling down. roles []ReplicaRole (Optional) Enumerate all possible roles assigned to each replica of the Component, influencing its behavior. A replica can have zero to multiple roles. KubeBlocks operator determines the roles of each replica by invoking the lifecycleActions.roleProbe method. This action returns a list of roles for each replica, and the returned roles must be predefined in the roles field. The roles assigned to a replica can influence various aspects of the Component’s behavior, such as: Service selection: The Component’s exposed Services may target replicas based on their roles using roleSelector. Update order: The roles can determine the order in which replicas are updated during a Component update. For instance, replicas with a “follower” role can be updated first, while the replica with the “leader” role is updated last. This helps minimize the number of leader changes during the update process. This field is immutable. roleArbitrator RoleArbitrator (Optional) This field has been deprecated since v0.9. This field is maintained for backward compatibility and its use is discouraged. Existing usage should be updated to the current preferred approach to avoid compatibility issues in future releases. This field is immutable. lifecycleActions ComponentLifecycleActions (Optional) Defines a set of hooks and procedures that customize the behavior of a Component throughout its lifecycle. Actions are triggered at specific lifecycle stages: postProvision: Defines the hook to be executed after the creation of a Component, with preCondition specifying when the action should be fired relative to the Component’s lifecycle stages: Immediately, RuntimeReady, ComponentReady, and ClusterReady. preTerminate: Defines the hook to be executed before terminating a Component. roleProbe: Defines the procedure which is invoked regularly to assess the role of replicas. switchover: Defines the procedure for a controlled transition of leadership from the current leader to a new replica. This approach aims to minimize downtime and maintain availability in systems with a leader-follower topology, such as before planned maintenance or upgrades on the current leader node. memberJoin: Defines the procedure to add a new replica to the replication group. memberLeave: Defines the method to remove a replica from the replication group. readOnly: Defines the procedure to switch a replica into the read-only state. readWrite: transition a replica from the read-only state back to the read-write state. dataDump: Defines the procedure to export the data from a replica. dataLoad: Defines the procedure to import data into a replica. reconfigure: Defines the procedure that update a replica with new configuration file. accountProvision: Defines the procedure to generate a new database account. This field is immutable. serviceRefDeclarations []ServiceRefDeclaration (Optional) Lists external service dependencies of the Component, including services from other Clusters or outside the K8s environment. This field is immutable. minReadySeconds int32 (Optional) minReadySeconds is the minimum duration in seconds that a new Pod should remain in the ready state without any of its containers crashing to be considered available. This ensures the Pod’s stability and readiness to serve requests. A default value of 0 seconds means the Pod is considered available as soon as it enters the ready state.
status ComponentDefinitionStatus

ComponentVersion

ComponentVersion is the Schema for the componentversions API

Field	Description
apiVersion string	apps.kubeblocks.io/v1alpha1
kind string	ComponentVersion
metadata Kubernetes meta/v1.ObjectMeta	Refer to the Kubernetes API documentation for the fields of the metadata field.
spec ComponentVersionSpec	compatibilityRules []ComponentVersionCompatibilityRule CompatibilityRules defines compatibility rules between sets of component definitions and releases. releases []ComponentVersionRelease Releases represents different releases of component instances within this ComponentVersion.
status ComponentVersionStatus

ConfigConstraint

ConfigConstraint manages the parameters across multiple configuration files contained in a single configure template. These configuration files should have the same format (e.g. ini, xml, properties, json).

It provides the following functionalities:

1. Parameter Value Validation: Validates and ensures compliance of parameter values with defined constraints.

2. Dynamic Reload on Modification: Monitors parameter changes and triggers dynamic reloads to apply updates.

3. Parameter Rendering in Templates: Injects parameters into templates to generate up-to-date configuration files.

Field	Description
apiVersion string	apps.kubeblocks.io/v1alpha1
kind string	ConfigConstraint
metadata Kubernetes meta/v1.ObjectMeta	Refer to the Kubernetes API documentation for the fields of the metadata field.
spec ConfigConstraintSpec	reloadOptions ReloadOptions (Optional) Specifies the dynamic reload action supported by the engine. When set, the controller executes the method defined here to execute hot parameter updates. Dynamic reloading is triggered only if both of the following conditions are met: The modified parameters are listed in the dynamicParameters field. If reloadStaticParamsBeforeRestart is set to true, modifications to staticParameters can also trigger a reload. reloadOptions is set. If reloadOptions is not set or the modified parameters are not listed in dynamicParameters, dynamic reloading will not be triggered. Example: reloadOptions: tplScriptTrigger: namespace: kb-system scriptConfigMapRef: mysql-reload-script sync: true dynamicActionCanBeMerged bool (Optional) Indicates whether to consolidate dynamic reload and restart actions into a single restart. If true, updates requiring both actions will result in only a restart, merging the actions. If false, updates will trigger both actions executed sequentially: first dynamic reload, then restart. This flag allows for more efficient handling of configuration changes by potentially eliminating an unnecessary reload step. reloadStaticParamsBeforeRestart bool (Optional) Configures whether the dynamic reload specified in reloadOptions applies only to dynamic parameters or to all parameters (including static parameters). false (default): Only modifications to the dynamic parameters listed in dynamicParameters will trigger a dynamic reload. true: Modifications to both dynamic parameters listed in dynamicParameters and static parameters listed in staticParameters will trigger a dynamic reload. The “true” option is for certain engines that require static parameters to be set via SQL statements before they can take effect on restart. toolsImageSpec ToolsSetup (Optional) Specifies the tools container image used by ShellTrigger for dynamic reload. If the dynamic reload action is triggered by a ShellTrigger, this field is required. This image must contain all necessary tools for executing the ShellTrigger scripts. Usually the specified image is referenced by the init container, which is then responsible for copy the tools from the image to a bin volume. This ensures that the tools are available to the ‘config-manager’ sidecar. downwardAPIOptions []DownwardAPIChangeTriggeredAction (Optional) Specifies a list of actions to execute specified commands based on Pod labels. It utilizes the K8s Downward API to mount label information as a volume into the pod. The ‘config-manager’ sidecar container watches for changes in the role label and dynamically invoke registered commands (usually execute some SQL statements) when a change is detected. It is designed for scenarios where: Replicas with different roles have different configurations, such as Redis primary & secondary replicas. After a role switch (e.g., from secondary to primary), some changes in configuration are needed to reflect the new role. scriptConfigs []ScriptConfig (Optional) A list of ScriptConfig Object. Each ScriptConfig object specifies a ConfigMap that contains script files that should be mounted inside the pod. The scripts are mounted as volumes and can be referenced and executed by the dynamic reload and DownwardAction to perform specific tasks or configurations. cfgSchemaTopLevelName string (Optional) Specifies the top-level key in the ‘configurationSchema.cue’ that organizes the validation rules for parameters. This key must exist within the CUE script defined in ‘configurationSchema.cue’. configurationSchema CustomParametersValidation (Optional) Defines a list of parameters including their names, default values, descriptions, types, and constraints (permissible values or the range of valid values). staticParameters []string (Optional) List static parameters. Modifications to any of these parameters require a restart of the process to take effect. dynamicParameters []string (Optional) List dynamic parameters. Modifications to these parameters trigger a configuration reload without requiring a process restart. immutableParameters []string (Optional) Lists the parameters that cannot be modified once set. Attempting to change any of these parameters will be ignored. selector Kubernetes meta/v1.LabelSelector (Optional) Used to match labels on the pod to determine whether a dynamic reload should be performed. In some scenarios, only specific pods (e.g., primary replicas) need to undergo a dynamic reload. The selector allows you to specify label selectors to target the desired pods for the reload process. If the selector is not specified or is nil, all pods managed by the workload will be considered for the dynamic reload. formatterConfig FileFormatConfig Specifies the format of the configuration file and any associated parameters that are specific to the chosen format. Supported formats include ini, xml, yaml, json, hcl, dotenv, properties, and toml. Each format may have its own set of parameters that can be configured. For instance, when using the ini format, you can specify the section name. Example: formatterConfig: format: ini iniConfig: sectionName: mysqld
status ConfigConstraintStatus

Configuration

Configuration represents the complete set of configurations for a specific Component of a Cluster. This includes templates for each configuration file, their corresponding ConfigConstraints, volume mounts, and other relevant details.

Field	Description
apiVersion string	apps.kubeblocks.io/v1alpha1
kind string	Configuration
metadata Kubernetes meta/v1.ObjectMeta	Refer to the Kubernetes API documentation for the fields of the metadata field.
spec ConfigurationSpec	clusterRef string Specifies the name of the Cluster that this configuration is associated with. componentName string Represents the name of the Component that this configuration pertains to. configItemDetails []ConfigurationItemDetail (Optional) ConfigItemDetails is an array of ConfigurationItemDetail objects. Each ConfigurationItemDetail corresponds to a configuration template, which is a ConfigMap that contains multiple configuration files. Each configuration file is stored as a key-value pair within the ConfigMap. The ConfigurationItemDetail includes information such as: The configuration template (a ConfigMap) The corresponding ConfigConstraint (constraints and validation rules for the configuration) Volume mounts (for mounting the configuration files)
status ConfigurationStatus

ServiceDescriptor

ServiceDescriptor describes a service provided by external sources. It contains the necessary details such as the service’s address and connection credentials. To enable a Cluster to access this service, the ServiceDescriptor’s name should be specified in the Cluster configuration under clusterComponent.serviceRefs[*].serviceDescriptor.

Field	Description
apiVersion string	apps.kubeblocks.io/v1alpha1
kind string	ServiceDescriptor
metadata Kubernetes meta/v1.ObjectMeta	Refer to the Kubernetes API documentation for the fields of the metadata field.
spec ServiceDescriptorSpec	serviceKind string Describes the type of database service provided by the external service. For example, “mysql”, “redis”, “mongodb”. This field categorizes databases by their functionality, protocol and compatibility, facilitating appropriate service integration based on their unique capabilities. This field is case-insensitive. It also supports abbreviations for some well-known databases: “pg”, “pgsql”, “postgres”, “postgresql”: PostgreSQL service “zk”, “zookeeper”: ZooKeeper service “es”, “elasticsearch”: Elasticsearch service “mongo”, “mongodb”: MongoDB service “ch”, “clickhouse”: ClickHouse service serviceVersion string Describes the version of the service provided by the external service. This is crucial for ensuring compatibility between different components of the system, as different versions of a service may have varying features. endpoint CredentialVar (Optional) Specifies the endpoint of the external service. If the service is exposed via a cluster, the endpoint will be provided in the format of host:port. host CredentialVar (Optional) Specifies the service or IP address of the external service. port CredentialVar (Optional) Specifies the port of the external service. auth ConnectionCredentialAuth (Optional) Specifies the authentication credentials required for accessing an external service.
status ServiceDescriptorStatus

AccessMode (string alias)

(Appears on:ConsensusMember)

AccessMode defines the modes of access granted to the SVC. The modes can be None, Readonly, or ReadWrite.

Value	Description
"None"	None implies no access.
"ReadWrite"	ReadWrite permits both read and write operations.
"Readonly"	Readonly allows only read operations.

AccountName (string alias)

(Appears on:SystemAccountConfig)

AccountName defines system account names.

Value	Description
"kbadmin"
"kbdataprotection"
"kbmonitoring"
"kbprobe"
"kbreplicator"

Action

(Appears on:ComponentSwitchover, LifecycleActionHandler, Probe)

Action defines a customizable hook or procedure tailored for different database engines, designed to be invoked at predetermined points within the lifecycle of a Component instance. It provides a modular and extensible way to customize a Component’s behavior through the execution of defined actions.

Available Action triggers include:

• postProvision: Defines the hook to be executed after the creation of a Component, with preCondition specifying when the action should be fired relative to the Component’s lifecycle stages: Immediately, RuntimeReady, ComponentReady, and ClusterReady.

• preTerminate: Defines the hook to be executed before terminating a Component.

• roleProbe: Defines the procedure which is invoked regularly to assess the role of replicas.

• switchover: Defines the procedure for a controlled transition of leadership from the current leader to a new replica. This approach aims to minimize downtime and maintain availability in systems with a leader-follower topology, such as during planned maintenance or upgrades on the current leader node.

• memberJoin: Defines the procedure to add a new replica to the replication group.

• memberLeave: Defines the method to remove a replica from the replication group.

• readOnly: Defines the procedure to switch a replica into the read-only state.

• readWrite: Defines the procedure to transition a replica from the read-only state back to the read-write state.

• dataDump: Defines the procedure to export the data from a replica.

• dataLoad: Defines the procedure to import data into a replica.

• reconfigure: Defines the procedure that update a replica with new configuration.

• accountProvision: Defines the procedure to generate a new database account.

Actions can be executed in different ways:

• ExecAction: Executes a command inside a container. which may run as a K8s job or be executed inside the Lorry sidecar container, depending on the implementation. Future implementations will standardize execution within Lorry. A set of predefined environment variables are available and can be leveraged within the exec.command to access context information such as details about pods, components, the overall cluster state, or database connection credentials. These variables provide a dynamic and context-aware mechanism for script execution.

• HTTPAction: Performs an HTTP request. HTTPAction is to be implemented in future version.

• GRPCAction: In future version, Actions will support initiating gRPC calls. This allows developers to implement Actions using plugins written in programming language like Go, providing greater flexibility and extensibility.

An action is considered successful on returning 0, or HTTP 200 for status HTTP(s) Actions. Any other return value or HTTP status codes indicate failure, and the action may be retried based on the configured retry policy.

• If an action exceeds the specified timeout duration, it will be terminated, and the action is considered failed.

• If an action produces any data as output, it should be written to stdout, or included in the HTTP response payload for HTTP(s) actions.

• If an action encounters any errors, error messages should be written to stderr, or detailed in the HTTP response with the appropriate non-200 status code.

Field	Description
image string	(Optional) Specifies the container image to be used for running the Action. When specified, a dedicated container will be created using this image to execute the Action. This field is mutually exclusive with the container field; only one of them should be provided. This field cannot be updated.
exec ExecAction	(Optional) Defines the command to run. This field cannot be updated.
http HTTPAction	(Optional) Specifies the HTTP request to perform. This field cannot be updated. Note: HTTPAction is to be implemented in future version.
env []Kubernetes core/v1.EnvVar	(Optional) Represents a list of environment variables that will be injected into the container. These variables enable the container to adapt its behavior based on the environment it’s running in. This field cannot be updated.
targetPodSelector TargetPodSelector	(Optional) Defines the criteria used to select the target Pod(s) for executing the Action. This is useful when there is no default target replica identified. It allows for precise control over which Pod(s) the Action should run in. This field cannot be updated. Note: This field is reserved for future use and is not currently active.
matchingKey string	(Optional) Used in conjunction with the targetPodSelector field to refine the selection of target pod(s) for Action execution. The impact of this field depends on the targetPodSelector value: When targetPodSelector is set to Any or All, this field will be ignored. When targetPodSelector is set to Role, only those replicas whose role matches the matchingKey will be selected for the Action. This field cannot be updated. Note: This field is reserved for future use and is not currently active.
container string	(Optional) Defines the name of the container within the target Pod where the action will be executed. This name must correspond to one of the containers defined in componentDefinition.spec.runtime. If this field is not specified, the default behavior is to use the first container listed in componentDefinition.spec.runtime. This field cannot be updated. Note: This field is reserved for future use and is not currently active.
timeoutSeconds int32	(Optional) Specifies the maximum duration in seconds that the Action is allowed to run. If the Action does not complete within this time frame, it will be terminated. This field cannot be updated.
retryPolicy RetryPolicy	(Optional) Defines the strategy to be taken when retrying the Action after a failure. It specifies the conditions under which the Action should be retried and the limits to apply, such as the maximum number of retries and backoff strategy. This field cannot be updated.
preCondition PreConditionType	(Optional) Specifies the state that the cluster must reach before the Action is executed. Currently, this is only applicable to the postProvision action. The conditions are as follows: Immediately: Executed right after the Component object is created. The readiness of the Component and its resources is not guaranteed at this stage. RuntimeReady: The Action is triggered after the Component object has been created and all associated runtime resources (e.g. Pods) are in a ready state. ComponentReady: The Action is triggered after the Component itself is in a ready state. This process does not affect the readiness state of the Component or the Cluster. ClusterReady: The Action is executed after the Cluster is in a ready state. This execution does not alter the Component or the Cluster’s state of readiness. This field cannot be updated.

Affinity

(Appears on:ClusterComponentSpec, ClusterSpec, ComponentSpec)

Field	Description
podAntiAffinity PodAntiAffinity	(Optional) Specifies the anti-affinity level of Pods within a Component. It determines how pods should be spread across nodes to improve availability and performance. It can have the following values: Preferred and Required. The default value is Preferred.
topologyKeys []string	(Optional) Represents the key of node labels used to define the topology domain for Pod anti-affinity and Pod spread constraints. In K8s, a topology domain is a set of nodes that have the same value for a specific label key. Nodes with labels containing any of the specified TopologyKeys and identical values are considered to be in the same topology domain. Note: The concept of topology in the context of K8s TopologyKeys is different from the concept of topology in the ClusterDefinition. When a Pod has anti-affinity or spread constraints specified, Kubernetes will attempt to schedule the Pod on nodes with different values for the specified TopologyKeys. This ensures that Pods are spread across different topology domains, promoting high availability and reducing the impact of node failures. Some well-known label keys, such as kubernetes.io/hostname and topology.kubernetes.io/zone, are often used as TopologyKey. These keys represent the hostname and zone of a node, respectively. By including these keys in the TopologyKeys list, Pods will be spread across nodes with different hostnames or zones. In addition to the well-known keys, users can also specify custom label keys as TopologyKeys. This allows for more flexible and custom topology definitions based on the specific needs of the application or environment. The TopologyKeys field is a slice of strings, where each string represents a label key. The order of the keys in the slice does not matter.
nodeLabels map[string]string	(Optional) Indicates the node labels that must be present on nodes for pods to be scheduled on them. It is a map where the keys are the label keys and the values are the corresponding label values. Pods will only be scheduled on nodes that have all the specified labels with the corresponding values. For example, if NodeLabels is set to {“nodeType”: “ssd”, “environment”: “production”}, pods will only be scheduled on nodes that have both the “nodeType” label with value “ssd” and the “environment” label with value “production”. This field allows users to control Pod placement based on specific node labels. It can be used to ensure that Pods are scheduled on nodes with certain characteristics, such as specific hardware (e.g., SSD), environment (e.g., production, staging), or any other custom labels assigned to nodes.
tenancy TenancyType	(Optional) Determines the level of resource isolation between Pods. It can have the following values: SharedNode and DedicatedNode. SharedNode: Allow that multiple Pods may share the same node, which is the default behavior of K8s. DedicatedNode: Each Pod runs on a dedicated node, ensuring that no two Pods share the same node. In other words, if a Pod is already running on a node, no other Pods will be scheduled on that node. Which provides a higher level of isolation and resource guarantee for Pods. The default value is SharedNode.

AvailabilityPolicyType (string alias)

(Appears on:ClusterSpec)

AvailabilityPolicyType defines the type of availability policy to be applied for cluster affinity, influencing how resources are distributed across zones or nodes for high availability and resilience.

Value	Description
"node"	AvailabilityPolicyNode specifies that resources should be distributed across different nodes within the same zone. This policy aims to provide resilience against node failures, ensuring that the failure of a single node does not impact the overall service availability.
"none"	AvailabilityPolicyNone specifies that no specific availability policy is applied. Resources may not be explicitly distributed for high availability, potentially concentrating them in a single zone or node based on other scheduling decisions.
"zone"	AvailabilityPolicyZone specifies that resources should be distributed across different availability zones. This policy aims to ensure high availability and protect against zone failures, spreading the resources to reduce the risk of simultaneous downtime.

BackupStatusUpdateStage (string alias)

BackupStatusUpdateStage defines the stage of backup status update.

BaseBackupType (string alias)

BaseBackupType the base backup type, keep synchronized with the BaseBackupType of the data protection API.

BuiltinActionHandlerType (string alias)

(Appears on:LifecycleActionHandler)

BuiltinActionHandlerType defines build-in action handlers provided by Lorry, including:

• mysql

• wesql

• oceanbase

• redis

• mongodb

• etcd

• postgresql

• vanilla-postgresql

• apecloud-postgresql

• polardbx

• custom

• unknown

Value	Description
"apecloud-postgresql"
"custom"
"etcd"
"mongodb"
"mysql"
"oceanbase"
"polardbx"
"postgresql"
"redis"
"unknown"
"vanilla-postgresql"
"wesql"

ClassDefRef

(Appears on:ClusterComponentSpec)

ClassDefRef is deprecated since v0.9.

Field	Description
name string	(Optional) Specifies the name of the ComponentClassDefinition.
class string	Defines the name of the class that is defined in the ComponentClassDefinition.

ClusterBackup

(Appears on:ClusterSpec)

Field	Description
enabled bool	(Optional) Specifies whether automated backup is enabled for the Cluster.
retentionPeriod github.com/apecloud/kubeblocks/apis/dataprotection/v1alpha1.RetentionPeriod	(Optional) Determines the duration to retain backups. Backups older than this period are automatically removed. For example, RetentionPeriod of 30d will keep only the backups of last 30 days. Sample duration format: years: 2y months: 6mo days: 30d hours: 12h minutes: 30m You can also combine the above durations. For example: 30d12h30m. Default value is 7d.
method string	Specifies the backup method to use, as defined in backupPolicy.
cronExpression string	(Optional) The cron expression for the schedule. The timezone is in UTC. See https://en.wikipedia.org/wiki/Cron.
startingDeadlineMinutes int64	(Optional) Specifies the maximum time in minutes that the system will wait to start a missed backup job. If the scheduled backup time is missed for any reason, the backup job must start within this deadline. Values must be between 0 (immediate execution) and 1440 (one day).
repoName string	(Optional) Specifies the name of the backupRepo. If not set, the default backupRepo will be used.
pitrEnabled bool	(Optional) Specifies whether to enable point-in-time recovery.
incrementalBackupEnabled bool	(Optional) Specifies whether to enable incremental backup.
incrementalCronExpression string	(Optional) The cron expression for the incremental backup schedule. The timezone is in UTC. See https://en.wikipedia.org/wiki/Cron.

ClusterComponentConfig

(Appears on:ClusterComponentSpec, ComponentSpec)

ClusterComponentConfig represents a config with its source bound.

Field	Description
name string	(Optional) The name of the config.
ClusterComponentConfigSource ClusterComponentConfigSource	(Members of ClusterComponentConfigSource are embedded into this type.) The source of the config.

ClusterComponentConfigSource

(Appears on:ClusterComponentConfig)

ClusterComponentConfigSource represents the source of a config.

Field	Description
configMap Kubernetes core/v1.ConfigMapVolumeSource	(Optional) ConfigMap source for the config.

ClusterComponentDefinition

(Appears on:ClusterDefinitionSpec)

ClusterComponentDefinition defines a Component within a ClusterDefinition but is deprecated and has been replaced by ComponentDefinition.

Deprecated: Use ComponentDefinition instead. This type is deprecated as of version 0.8.

Field	Description
name string	This name could be used as default name of cluster.spec.componentSpecs.name, and needs to conform with same validation rules as cluster.spec.componentSpecs.name, currently complying with IANA Service Naming rule. This name will apply to cluster objects as the value of label “apps.kubeblocks.io/component-name”.
description string	(Optional) Description of the component definition.
workloadType WorkloadType	Defines the type of the workload. Stateless describes stateless applications. Stateful describes common stateful applications. Consensus describes applications based on consensus protocols, such as raft and paxos. Replication describes applications based on the primary-secondary data replication protocol.
characterType string	(Optional) Defines well-known database component name, such as mongos(mongodb), proxy(redis), mariadb(mysql).
configSpecs []ComponentConfigSpec	(Optional) Defines the template of configurations.
scriptSpecs []ComponentTemplateSpec	(Optional) Defines the template of scripts.
probes ClusterDefinitionProbes	(Optional) Settings for health checks.
logConfigs []LogConfig	(Optional) Specify the logging files which can be observed and configured by cluster users.
podSpec Kubernetes core/v1.PodSpec	(Optional) Defines the pod spec template of component.
service ServiceSpec	(Optional) Defines the service spec.
statelessSpec StatelessSetSpec	(Optional) Defines spec for Stateless workloads.
statefulSpec StatefulSetSpec	(Optional) Defines spec for Stateful workloads.
consensusSpec ConsensusSetSpec	(Optional) Defines spec for Consensus workloads. It’s required if the workload type is Consensus.
replicationSpec ReplicationSetSpec	(Optional) Defines spec for Replication workloads.
rsmSpec RSMSpec	(Optional) Defines workload spec of this component. From KB 0.7.0, RSM(InstanceSetSpec) will be the underlying CR which powers all kinds of workload in KB. RSM is an enhanced stateful workload extension dedicated for heavy-state workloads like databases.
horizontalScalePolicy HorizontalScalePolicy	(Optional) Defines the behavior of horizontal scale.
systemAccounts SystemAccountSpec	(Optional) Defines system accounts needed to manage the component, and the statement to create them.
volumeTypes []VolumeTypeSpec	(Optional) Used to describe the purpose of the volumes mapping the name of the VolumeMounts in the PodSpec.Container field, such as data volume, log volume, etc. When backing up the volume, the volume can be correctly backed up according to the volumeType. For example: name: data, type: data means that the volume named data is used to store data. name: binlog, type: log means that the volume named binlog is used to store log. NOTE: When volumeTypes is not defined, the backup function will not be supported, even if a persistent volume has been specified.
customLabelSpecs []CustomLabelSpec	(Optional) Used for custom label tags which you want to add to the component resources.
switchoverSpec SwitchoverSpec	(Optional) Defines command to do switchover. In particular, when workloadType=Replication, the command defined in switchoverSpec will only be executed under the condition of cluster.componentSpecs[x].SwitchPolicy.type=Noop.
postStartSpec PostStartAction	(Optional) Defines the command to be executed when the component is ready, and the command will only be executed once after the component becomes ready.
volumeProtectionSpec VolumeProtectionSpec	(Optional) Defines settings to do volume protect.
componentDefRef []ComponentDefRef	(Optional) Used to inject values from other components into the current component. Values will be saved and updated in a configmap and mounted to the current component.
serviceRefDeclarations []ServiceRefDeclaration	(Optional) Used to declare the service reference of the current component.
exporter Exporter	(Optional) Defines the metrics exporter.
monitor MonitorConfig	(Optional) Deprecated since v0.9 monitor is monitoring config which provided by provider.

ClusterComponentPhase (string alias)

(Appears on:ClusterComponentStatus, ComponentStatus)

ClusterComponentPhase defines the phase of a cluster component as represented in cluster.status.components.phase field.

Value	Description
"Abnormal"	AbnormalClusterCompPhase indicates the component has more than zero replicas, but there are some failed pods. The component is functioning, but it is in a fragile state.
"Creating"	CreatingClusterCompPhase indicates the component is being created.
"Deleting"	DeletingClusterCompPhase indicates the component is currently being deleted.
"Failed"	FailedClusterCompPhase indicates the component has more than zero replicas, but there are some failed pods. The component is not functioning.
"Running"	RunningClusterCompPhase indicates the component has more than zero replicas, and all pods are up-to-date and in a ‘Running’ state.
"Stopped"	StoppedClusterCompPhase indicates the component has zero replicas, and all pods have been deleted.
"Stopping"	StoppingClusterCompPhase indicates the component has zero replicas, and there are pods that are terminating.
"Updating"	UpdatingClusterCompPhase indicates the component has more than zero replicas, and there are no failed pods, it is currently being updated.

ClusterComponentService

(Appears on:ClusterComponentSpec)

Field	Description
name string	References the ComponentService name defined in the componentDefinition.spec.services[*].name.
serviceType Kubernetes core/v1.ServiceType	(Optional) Determines how the Service is exposed. Valid options are ClusterIP, NodePort, and LoadBalancer. ClusterIP allocates a Cluster-internal IP address for load-balancing to endpoints. Endpoints are determined by the selector or if that is not specified, they are determined by manual construction of an Endpoints object or EndpointSlice objects. NodePort builds on ClusterIP and allocates a port on every node which routes to the same endpoints as the ClusterIP. LoadBalancer builds on NodePort and creates an external load-balancer (if supported in the current cloud) which routes to the same endpoints as the ClusterIP. Note: although K8s Service type allows the ‘ExternalName’ type, it is not a valid option for ClusterComponentService. For more info, see: https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services-service-types.
annotations map[string]string	(Optional) If ServiceType is LoadBalancer, cloud provider related parameters can be put here. More info: https://kubernetes.io/docs/concepts/services-networking/service/#loadbalancer.
podService bool	(Optional) Indicates whether to generate individual Services for each Pod. If set to true, a separate Service will be created for each Pod in the Cluster.

ClusterComponentSpec

(Appears on:ClusterSpec, ShardingSpec)

ClusterComponentSpec defines the specification of a Component within a Cluster.

Field	Description
name string	(Optional) Specifies the Component’s name. It’s part of the Service DNS name and must comply with the IANA service naming rule. The name is optional when ClusterComponentSpec is used as a template (e.g., in shardingSpec), but required otherwise.
componentDefRef string	(Optional) References a ClusterComponentDefinition defined in the clusterDefinition.spec.componentDef field. Must comply with the IANA service naming rule. Deprecated since v0.9, because defining Components in clusterDefinition.spec.componentDef field has been deprecated. This field is replaced by the componentDef field, use componentDef instead. This field is maintained for backward compatibility and its use is discouraged. Existing usage should be updated to the current preferred approach to avoid compatibility issues in future releases.
componentDef string	(Optional) Specifies the exact name, name prefix, or regular expression pattern for matching the name of the ComponentDefinition custom resource (CR) that defines the Component’s characteristics and behavior. If both componentDefRef and componentDef are provided, the componentDef will take precedence over componentDefRef.
serviceVersion string	(Optional) ServiceVersion specifies the version of the Service expected to be provisioned by this Component. The version should follow the syntax and semantics of the “Semantic Versioning” specification (http://semver.org/). If no version is specified, the latest available version will be used.
classDefRef ClassDefRef	(Optional) References the class defined in ComponentClassDefinition. Deprecated since v0.9. This field is maintained for backward compatibility and its use is discouraged. Existing usage should be updated to the current preferred approach to avoid compatibility issues in future releases.
serviceRefs []ServiceRef	(Optional) Defines a list of ServiceRef for a Component, enabling access to both external services and Services provided by other Clusters. Types of services: External services: Not managed by KubeBlocks or managed by a different KubeBlocks operator; Require a ServiceDescriptor for connection details. Services provided by a Cluster: Managed by the same KubeBlocks operator; identified using Cluster, Component and Service names. ServiceRefs with identical serviceRef.name in the same Cluster are considered the same. Example: serviceRefs: name: "redis-sentinel" serviceDescriptor: name: "external-redis-sentinel" name: "postgres-cluster" clusterServiceSelector: cluster: "my-postgres-cluster" service: component: "postgresql" The example above includes ServiceRefs to an external Redis Sentinel service and a PostgreSQL Cluster.
enabledLogs []string	(Optional) Specifies which types of logs should be collected for the Component. The log types are defined in the componentDefinition.spec.logConfigs field with the LogConfig entries. The elements in the enabledLogs array correspond to the names of the LogConfig entries. For example, if the componentDefinition.spec.logConfigs defines LogConfig entries with names “slow_query_log” and “error_log”, you can enable the collection of these logs by including their names in the enabledLogs array: enabledLogs: slow_query_log error_log
labels map[string]string	(Optional) Specifies Labels to override or add for underlying Pods, PVCs, Account & TLS Secrets, Services Owned by Component.
annotations map[string]string	(Optional) Specifies Annotations to override or add for underlying Pods, PVCs, Account & TLS Secrets, Services Owned by Component.
env []Kubernetes core/v1.EnvVar	(Optional) List of environment variables to add. These environment variables will be placed after the environment variables declared in the Pod.
replicas int32	Specifies the desired number of replicas in the Component for enhancing availability and durability, or load balancing.
affinity Affinity	(Optional) Specifies a group of affinity scheduling rules for the Component. It allows users to control how the Component’s Pods are scheduled onto nodes in the K8s cluster. Deprecated since v0.10, replaced by the schedulingPolicy field.
tolerations []Kubernetes core/v1.Toleration	(Optional) Allows Pods to be scheduled onto nodes with matching taints. Each toleration in the array allows the Pod to tolerate node taints based on specified key, value, effect, and operator. The key, value, and effect identify the taint that the toleration matches. The operator determines how the toleration matches the taint. Pods with matching tolerations are allowed to be scheduled on tainted nodes, typically reserved for specific purposes. Deprecated since v0.10, replaced by the schedulingPolicy field.
schedulingPolicy SchedulingPolicy	(Optional) Specifies the scheduling policy for the Component.
resources Kubernetes core/v1.ResourceRequirements	(Optional) Specifies the resources required by the Component. It allows defining the CPU, memory requirements and limits for the Component’s containers.
volumeClaimTemplates []ClusterComponentVolumeClaimTemplate	(Optional) Specifies a list of PersistentVolumeClaim templates that represent the storage requirements for the Component. Each template specifies the desired characteristics of a persistent volume, such as storage class, size, and access modes. These templates are used to dynamically provision persistent volumes for the Component.
volumes []Kubernetes core/v1.Volume	(Optional) List of volumes to override.
services []ClusterComponentService	(Optional) Overrides services defined in referenced ComponentDefinition and expose endpoints that can be accessed by clients.
systemAccounts []ComponentSystemAccount	(Optional) Overrides system accounts defined in referenced ComponentDefinition.
configs []ClusterComponentConfig	(Optional) Specifies the configuration content of a config template.
switchPolicy ClusterSwitchPolicy	(Optional) Defines the strategy for switchover and failover. Deprecated since v0.9. This field is maintained for backward compatibility and its use is discouraged. Existing usage should be updated to the current preferred approach to avoid compatibility issues in future releases.
tls bool	(Optional) A boolean flag that indicates whether the Component should use Transport Layer Security (TLS) for secure communication. When set to true, the Component will be configured to use TLS encryption for its network connections. This ensures that the data transmitted between the Component and its clients or other Components is encrypted and protected from unauthorized access. If TLS is enabled, the Component may require additional configuration, such as specifying TLS certificates and keys, to properly set up the secure communication channel.
issuer Issuer	(Optional) Specifies the configuration for the TLS certificates issuer. It allows defining the issuer name and the reference to the secret containing the TLS certificates and key. The secret should contain the CA certificate, TLS certificate, and private key in the specified keys. Required when TLS is enabled.
serviceAccountName string	(Optional) Specifies the name of the ServiceAccount required by the running Component. This ServiceAccount is used to grant necessary permissions for the Component’s Pods to interact with other Kubernetes resources, such as modifying Pod labels or sending events. Defaults: To perform certain operational tasks, agent sidecars running in Pods require specific RBAC permissions. The service account will be bound to a default role named “kubeblocks-cluster-pod-role” which is installed together with KubeBlocks. If not specified, KubeBlocks automatically assigns a default ServiceAccount named “kb-{cluster.name}” Future Changes: Future versions might change the default ServiceAccount creation strategy to one per Component, potentially revising the naming to “kb-{cluster.name}-{component.name}”. Users can override the automatic ServiceAccount assignment by explicitly setting the name of an existed ServiceAccount in this field.
updateStrategy UpdateStrategy	(Optional) Defines the update strategy for the Component. Deprecated since v0.9. This field is maintained for backward compatibility and its use is discouraged. Existing usage should be updated to the current preferred approach to avoid compatibility issues in future releases.
instanceUpdateStrategy InstanceUpdateStrategy	(Optional) Indicates the InstanceUpdateStrategy that will be employed to update Pods in the InstanceSet when a revision is made to Template.
parallelPodManagementConcurrency Kubernetes api utils intstr.IntOrString	(Optional) Controls the concurrency of pods during initial scale up, when replacing pods on nodes, or when scaling down. It only used when PodManagementPolicy is set to Parallel. The default Concurrency is 100%.
podUpdatePolicy PodUpdatePolicyType	(Optional) PodUpdatePolicy indicates how pods should be updated StrictInPlace indicates that only allows in-place upgrades. Any attempt to modify other fields will be rejected. PreferInPlace indicates that we will first attempt an in-place upgrade of the Pod. If that fails, it will fall back to the ReCreate, where pod will be recreated. Default value is “PreferInPlace”
userResourceRefs UserResourceRefs	(Optional) Allows users to specify custom ConfigMaps and Secrets to be mounted as volumes in the Cluster’s Pods. This is useful in scenarios where users need to provide additional resources to the Cluster, such as: Mounting custom scripts or configuration files during Cluster startup. Mounting Secrets as volumes to provide sensitive information, like S3 AK/SK, to the Cluster.
instances []InstanceTemplate	(Optional) Allows for the customization of configuration values for each instance within a Component. An instance represent a single replica (Pod and associated K8s resources like PVCs, Services, and ConfigMaps). While instances typically share a common configuration as defined in the ClusterComponentSpec, they can require unique settings in various scenarios: For example: A database Component might require different resource allocations for primary and secondary instances, with primaries needing more resources. During a rolling upgrade, a Component may first update the image for one or a few instances, and then update the remaining instances after verifying that the updated instances are functioning correctly. InstanceTemplate allows for specifying these unique configurations per instance. Each instance’s name is constructed using the pattern: $(component.name)-$(template.name)-$(ordinal), starting with an ordinal of 0. It is crucial to maintain unique names for each InstanceTemplate to avoid conflicts. The sum of replicas across all InstanceTemplates should not exceed the total number of replicas specified for the Component. Any remaining replicas will be generated using the default template and will follow the default naming rules.
offlineInstances []string	(Optional) Specifies the names of instances to be transitioned to offline status. Marking an instance as offline results in the following: The associated Pod is stopped, and its PersistentVolumeClaim (PVC) is retained for potential future reuse or data recovery, but it is no longer actively used. The ordinal number assigned to this instance is preserved, ensuring it remains unique and avoiding conflicts with new instances. Setting instances to offline allows for a controlled scale-in process, preserving their data and maintaining ordinal consistency within the Cluster. Note that offline instances and their associated resources, such as PVCs, are not automatically deleted. The administrator must manually manage the cleanup and removal of these resources when they are no longer needed.
disableExporter bool	(Optional) Determines whether metrics exporter information is annotated on the Component’s headless Service. If set to true, the following annotations will not be patched into the Service: “monitor.kubeblocks.io/path” “monitor.kubeblocks.io/port” “monitor.kubeblocks.io/scheme” These annotations allow the Prometheus installed by KubeBlocks to discover and scrape metrics from the exporter.
monitor bool	(Optional) Deprecated since v0.9 Determines whether metrics exporter information is annotated on the Component’s headless Service. If set to true, the following annotations will be patched into the Service: “monitor.kubeblocks.io/path” “monitor.kubeblocks.io/port” “monitor.kubeblocks.io/scheme” These annotations allow the Prometheus installed by KubeBlocks to discover and scrape metrics from the exporter.
stop bool	(Optional) Stop the Component. If set, all the computing resources will be released.

ClusterComponentStatus

(Appears on:ClusterStatus)

ClusterComponentStatus records Component status.

Field	Description
phase ClusterComponentPhase	Specifies the current state of the Component.
message ComponentMessageMap	(Optional) Records detailed information about the Component in its current phase. The keys are either podName, deployName, or statefulSetName, formatted as ‘ObjectKind/Name’.
podsReady bool	(Optional) Checks if all Pods of the Component are ready.
podsReadyTime Kubernetes meta/v1.Time	(Optional) Indicates the time when all Component Pods became ready. This is the readiness time of the last Component Pod.
membersStatus []MemberStatus	(Optional) Represents the status of the members.

ClusterComponentVolumeClaimTemplate

(Appears on:ClusterComponentSpec, ComponentSpec, InstanceTemplate)

Field	Description
name string	Refers to the name of a volumeMount defined in either: componentDefinition.spec.runtime.containers[*].volumeMounts clusterDefinition.spec.componentDefs[*].podSpec.containers[*].volumeMounts (deprecated) The value of name must match the name field of a volumeMount specified in the corresponding volumeMounts array.
spec PersistentVolumeClaimSpec	(Optional) Defines the desired characteristics of a PersistentVolumeClaim that will be created for the volume with the mount name specified in the name field. When a Pod is created for this ClusterComponent, a new PVC will be created based on the specification defined in the spec field. The PVC will be associated with the volume mount specified by the name field. accessModes []Kubernetes core/v1.PersistentVolumeAccessMode (Optional) Contains the desired access modes the volume should have. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#access-modes-1. resources Kubernetes core/v1.VolumeResourceRequirements (Optional) Represents the minimum resources the volume should have. If the RecoverVolumeExpansionFailure feature is enabled, users are allowed to specify resource requirements that are lower than the previous value but must still be higher than the capacity recorded in the status field of the claim. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#resources. storageClassName string (Optional) The name of the StorageClass required by the claim. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#class-1. volumeMode Kubernetes core/v1.PersistentVolumeMode (Optional) Defines what type of volume is required by the claim, either Block or Filesystem.

ClusterDefinitionProbe

(Appears on:ClusterDefinitionProbes)

ClusterDefinitionProbe is deprecated since v0.8.

Field	Description
periodSeconds int32	How often (in seconds) to perform the probe.
timeoutSeconds int32	Number of seconds after which the probe times out. Defaults to 1 second.
failureThreshold int32	Minimum consecutive failures for the probe to be considered failed after having succeeded.
commands ClusterDefinitionProbeCMDs	(Optional) Commands used to execute for probe.

ClusterDefinitionProbeCMDs

(Appears on:ClusterDefinitionProbe)

ClusterDefinitionProbeCMDs is deprecated since v0.8.

Field	Description
writes []string	(Optional) Defines write checks that are executed on the probe sidecar.
queries []string	(Optional) Defines read checks that are executed on the probe sidecar.

ClusterDefinitionProbes

(Appears on:ClusterComponentDefinition)

ClusterDefinitionProbes is deprecated since v0.8.

Field	Description
runningProbe ClusterDefinitionProbe	(Optional) Specifies the probe used for checking the running status of the component.
statusProbe ClusterDefinitionProbe	(Optional) Specifies the probe used for checking the status of the component.
roleProbe ClusterDefinitionProbe	(Optional) Specifies the probe used for checking the role of the component.
roleProbeTimeoutAfterPodsReady int32	(Optional) Defines the timeout (in seconds) for the role probe after all pods of the component are ready. The system will check if the application is available in the pod. If pods exceed the InitializationTimeoutSeconds time without a role label, this component will enter the Failed/Abnormal phase. Note that this configuration will only take effect if the component supports RoleProbe and will not affect the life cycle of the pod. default values are 60 seconds.

ClusterDefinitionSpec

(Appears on:ClusterDefinition)

ClusterDefinitionSpec defines the desired state of ClusterDefinition.

Field	Description
type string	(Optional) Specifies the well-known database type, such as mysql, redis, or mongodb. Deprecated since v0.9. This field is maintained for backward compatibility and its use is discouraged. Existing usage should be updated to the current preferred approach to avoid compatibility issues in future releases.
componentDefs []ClusterComponentDefinition	(Optional) Provides the definitions for the cluster components. Deprecated since v0.9. Components should now be individually defined using ComponentDefinition and collectively referenced via topology.components. This field is maintained for backward compatibility and its use is discouraged. Existing usage should be updated to the current preferred approach to avoid compatibility issues in future releases.
connectionCredential map[string]string	(Optional) Connection credential template used for creating a connection credential secret for cluster objects. Built-in objects are: $(RANDOM_PASSWD) random 8 characters. $(STRONG_RANDOM_PASSWD) random 16 characters, with mixed cases, digits and symbols. $(UUID) generate a random UUID v4 string. $(UUID_B64) generate a random UUID v4 BASE64 encoded string. $(UUID_STR_B64) generate a random UUID v4 string then BASE64 encoded. $(UUID_HEX) generate a random UUID v4 HEX representation. $(HEADLESS_SVC_FQDN) headless service FQDN placeholder, value pattern is $(CLUSTER_NAME)-$(1ST_COMP_NAME)-headless.$(NAMESPACE).svc, where 1ST_COMP_NAME is the 1st component that provide ClusterDefinition.spec.componentDefs[].service attribute; $(SVC_FQDN) service FQDN placeholder, value pattern is $(CLUSTER_NAME)-$(1ST_COMP_NAME).$(NAMESPACE).svc, where 1ST_COMP_NAME is the 1st component that provide ClusterDefinition.spec.componentDefs[].service attribute; $(SVC_PORT_{PORT-NAME}) is ServicePort’s port value with specified port name, i.e, a servicePort JSON struct: {"name": "mysql", "targetPort": "mysqlContainerPort", "port": 3306}, and $(SVC_PORT_mysql) in the connection credential value is 3306. Deprecated since v0.9. This field is maintained for backward compatibility and its use is discouraged. Existing usage should be updated to the current preferred approach to avoid compatibility issues in future releases.
topologies []ClusterTopology	(Optional) Topologies defines all possible topologies within the cluster.

ClusterDefinitionStatus

(Appears on:ClusterDefinition)

ClusterDefinitionStatus defines the observed state of ClusterDefinition

Field	Description
observedGeneration int64	(Optional) Represents the most recent generation observed for this ClusterDefinition.
phase Phase	Specifies the current phase of the ClusterDefinition. Valid values are empty, Available, Unavailable. When Available, the ClusterDefinition is ready and can be referenced by related objects.
message string	(Optional) Provides additional information about the current phase.
topologies string	(Optional) Topologies this ClusterDefinition supported.
serviceRefs string	(Optional) The service references declared by this ClusterDefinition.

ClusterNetwork

(Appears on:ClusterSpec)

ClusterNetwork is deprecated since v0.9.

Field	Description
hostNetworkAccessible bool	(Optional) Indicates whether the host network can be accessed. By default, this is set to false.
publiclyAccessible bool	(Optional) Indicates whether the network is accessible to the public. By default, this is set to false.

ClusterObjectReference

(Appears on:ComponentVarSelector, CredentialVarSelector, HostNetworkVarSelector, ServiceRefVarSelector, ServiceVarSelector)

ClusterObjectReference defines information to let you locate the referenced object inside the same Cluster.

Field	Description
compDef string	(Optional) Specifies the exact name, name prefix, or regular expression pattern for matching the name of the ComponentDefinition custom resource (CR) used by the component that the referent object resident in. If not specified, the component itself will be used.
name string	(Optional) Name of the referent object.
optional bool	(Optional) Specify whether the object must be defined.
multipleClusterObjectOption MultipleClusterObjectOption	(Optional) This option defines the behavior when multiple component objects match the specified @CompDef. If not provided, an error will be raised when handling multiple matches.

ClusterPhase (string alias)

(Appears on:ClusterStatus)

ClusterPhase defines the phase of the Cluster within the .status.phase field.

Value	Description
"Abnormal"	AbnormalClusterPhase represents some components are in Failed or Abnormal phase, indicates that the cluster is in a fragile state and troubleshooting is required.
"Creating"	CreatingClusterPhase represents all components are in Creating phase.
"Deleting"	DeletingClusterPhase indicates the cluster is being deleted.
"Failed"	FailedClusterPhase represents all components are in Failed phase, indicates that the cluster is unavailable.
"Running"	RunningClusterPhase represents all components are in Running phase, indicates that the cluster is functioning properly.
"Stopped"	StoppedClusterPhase represents all components are in Stopped phase, indicates that the cluster has stopped and is not providing any functionality.
"Stopping"	StoppingClusterPhase represents at least one component is in Stopping phase, indicates that the cluster is in the process of stopping.
"Updating"	UpdatingClusterPhase represents all components are in Creating, Running or Updating phase, and at least one component is in Creating or Updating phase, indicates that the cluster is undergoing an update.

ClusterResources

(Appears on:ClusterSpec)

ClusterResources is deprecated since v0.9.

Field	Description
cpu Kubernetes resource.Quantity	(Optional) Specifies the amount of CPU resource the Cluster needs. For more information, refer to: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
memory Kubernetes resource.Quantity	(Optional) Specifies the amount of memory resource the Cluster needs. For more information, refer to: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/

ClusterService

(Appears on:ClusterSpec)

ClusterService defines a service that is exposed externally, allowing entities outside the cluster to access it. For example, external applications, or other Clusters. And another Cluster managed by the same KubeBlocks operator can resolve the address exposed by a ClusterService using the serviceRef field.

When a Component needs to access another Cluster’s ClusterService using the serviceRef field, it must also define the service type and version information in the componentDefinition.spec.serviceRefDeclarations section.

Field	Description
Service Service	(Members of Service are embedded into this type.)
shardingSelector string	(Optional) Extends the ServiceSpec.Selector by allowing the specification of a sharding name, which is defined in cluster.spec.shardingSpecs[*].name, to be used as a selector for the service. Note that this and the componentSelector are mutually exclusive and cannot be set simultaneously.
componentSelector string	(Optional) Extends the ServiceSpec.Selector by allowing the specification of a component, to be used as a selector for the service. Note that this and the shardingSelector are mutually exclusive and cannot be set simultaneously.

ClusterSpec

(Appears on:Cluster)

ClusterSpec defines the desired state of Cluster.

Field	Description
clusterDefinitionRef string	(Optional) Specifies the name of the ClusterDefinition to use when creating a Cluster. This field enables users to create a Cluster based on a specific ClusterDefinition. Which, in conjunction with the topology field, determine: The Components to be included in the Cluster. The sequences in which the Components are created, updated, and terminate. This facilitates multiple-components management with predefined ClusterDefinition. Users with advanced requirements can bypass this general setting and specify more precise control over the composition of the Cluster by directly referencing specific ComponentDefinitions for each component within componentSpecs[*].componentDef. If this field is not provided, each component must be explicitly defined in componentSpecs[*].componentDef. Note: Once set, this field cannot be modified; it is immutable.
clusterVersionRef string	(Optional) Refers to the ClusterVersion name. Deprecated since v0.9, use ComponentVersion instead. This field is maintained for backward compatibility and its use is discouraged. Existing usage should be updated to the current preferred approach to avoid compatibility issues in future releases.
topology string	(Optional) Specifies the name of the ClusterTopology to be used when creating the Cluster. This field defines which set of Components, as outlined in the ClusterDefinition, will be used to construct the Cluster based on the named topology. The ClusterDefinition may list multiple topologies under clusterdefinition.spec.topologies[*], each tailored to different use cases or environments. If topology is not specified, the Cluster will use the default topology defined in the ClusterDefinition. Note: Once set during the Cluster creation, the topology field cannot be modified. It establishes the initial composition and structure of the Cluster and is intended for one-time configuration.
terminationPolicy TerminationPolicyType	Specifies the behavior when a Cluster is deleted. It defines how resources, data, and backups associated with a Cluster are managed during termination. Choose a policy based on the desired level of resource cleanup and data preservation: DoNotTerminate: Prevents deletion of the Cluster. This policy ensures that all resources remain intact. Halt: Deletes Cluster resources like Pods and Services but retains Persistent Volume Claims (PVCs), allowing for data preservation while stopping other operations. Warning: Halt policy is deprecated in 0.9.1 and will have same meaning as DoNotTerminate. Delete: Extends the Halt policy by also removing PVCs, leading to a thorough cleanup while removing all persistent data. WipeOut: An aggressive policy that deletes all Cluster resources, including volume snapshots and backups in external storage. This results in complete data removal and should be used cautiously, primarily in non-production environments to avoid irreversible data loss. Warning: Choosing an inappropriate termination policy can result in data loss. The WipeOut policy is particularly risky in production environments due to its irreversible nature.
shardingSpecs []ShardingSpec	(Optional) Specifies a list of ShardingSpec objects that manage the sharding topology for Cluster Components. Each ShardingSpec organizes components into shards, with each shard corresponding to a Component. Components within a shard are all based on a common ClusterComponentSpec template, ensuring uniform configurations. This field supports dynamic resharding by facilitating the addition or removal of shards through the shards field in ShardingSpec. Note: shardingSpecs and componentSpecs cannot both be empty; at least one must be defined to configure a Cluster.
componentSpecs []ClusterComponentSpec	(Optional) Specifies a list of ClusterComponentSpec objects used to define the individual Components that make up a Cluster. This field allows for detailed configuration of each Component within the Cluster. Note: shardingSpecs and componentSpecs cannot both be empty; at least one must be defined to configure a Cluster.
services []ClusterService	(Optional) Defines a list of additional Services that are exposed by a Cluster. This field allows Services of selected Components, either from componentSpecs or shardingSpecs to be exposed, alongside Services defined with ComponentService. Services defined here can be referenced by other clusters using the ServiceRefClusterSelector.
affinity Affinity	(Optional) Defines a set of node affinity scheduling rules for the Cluster’s Pods. This field helps control the placement of Pods on nodes within the Cluster. Deprecated since v0.10. Use the schedulingPolicy field instead.
tolerations []Kubernetes core/v1.Toleration	(Optional) An array that specifies tolerations attached to the Cluster’s Pods, allowing them to be scheduled onto nodes with matching taints. Deprecated since v0.10. Use the schedulingPolicy field instead.
schedulingPolicy SchedulingPolicy	(Optional) Specifies the scheduling policy for the Cluster.
runtimeClassName string	(Optional) Specifies runtimeClassName for all Pods managed by this Cluster.
backup ClusterBackup	(Optional) Specifies the backup configuration of the Cluster.
tenancy TenancyType	(Optional) Describes how Pods are distributed across node. Deprecated since v0.9. This field is maintained for backward compatibility and its use is discouraged. Existing usage should be updated to the current preferred approach to avoid compatibility issues in future releases.
availabilityPolicy AvailabilityPolicyType	(Optional) Describes the availability policy, including zone, node, and none. Deprecated since v0.9. This field is maintained for backward compatibility and its use is discouraged. Existing usage should be updated to the current preferred approach to avoid compatibility issues in future releases.
replicas int32	(Optional) Specifies the replicas of the first componentSpec, if the replicas of the first componentSpec is specified, this value will be ignored. Deprecated since v0.9. This field is maintained for backward compatibility and its use is discouraged. Existing usage should be updated to the current preferred approach to avoid compatibility issues in future releases.
resources ClusterResources	(Optional) Specifies the resources of the first componentSpec, if the resources of the first componentSpec is specified, this value will be ignored. Deprecated since v0.9. This field is maintained for backward compatibility and its use is discouraged. Existing usage should be updated to the current preferred approach to avoid compatibility issues in future releases.
storage ClusterStorage	(Optional) Specifies the storage of the first componentSpec, if the storage of the first componentSpec is specified, this value will be ignored. Deprecated since v0.9. This field is maintained for backward compatibility and its use is discouraged. Existing usage should be updated to the current preferred approach to avoid compatibility issues in future releases.
network ClusterNetwork	(Optional) The configuration of network. Deprecated since v0.9. This field is maintained for backward compatibility and its use is discouraged. Existing usage should be updated to the current preferred approach to avoid compatibility issues in future releases.

ClusterStatus

(Appears on:Cluster)

ClusterStatus defines the observed state of the Cluster.

Field	Description
observedGeneration int64	(Optional) The most recent generation number of the Cluster object that has been observed by the controller.
phase ClusterPhase	(Optional) The current phase of the Cluster includes: Creating, Running, Updating, Stopping, Stopped, Deleting, Failed, Abnormal.
message string	(Optional) Provides additional information about the current phase.
components map[string]github.com/apecloud/kubeblocks/apis/apps/v1alpha1.ClusterComponentStatus	(Optional) Records the current status information of all Components within the Cluster.
clusterDefGeneration int64	(Optional) Represents the generation number of the referenced ClusterDefinition.
conditions []Kubernetes meta/v1.Condition	(Optional) Represents a list of detailed status of the Cluster object. Each condition in the list provides real-time information about certain aspect of the Cluster object. This field is crucial for administrators and developers to monitor and respond to changes within the Cluster. It provides a history of state transitions and a snapshot of the current state that can be used for automated logic or direct inspection.

ClusterStorage

(Appears on:ClusterSpec)

ClusterStorage is deprecated since v0.9.

Field	Description
size Kubernetes resource.Quantity	(Optional) Specifies the amount of storage the Cluster needs. For more information, refer to: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/

ClusterSwitchPolicy

(Appears on:ClusterComponentSpec)

ClusterSwitchPolicy defines the switch policy for a Cluster.

Deprecated since v0.9.

Field	Description
type SwitchPolicyType	(Optional) Type specifies the type of switch policy to be applied.

ClusterTopology

(Appears on:ClusterDefinitionSpec)

ClusterTopology represents the definition for a specific cluster topology.

Field	Description
name string	Name is the unique identifier for the cluster topology. Cannot be updated.
components []ClusterTopologyComponent	Components specifies the components in the topology.
orders ClusterTopologyOrders	(Optional) Specifies the sequence in which components within a cluster topology are started, stopped, and upgraded. This ordering is crucial for maintaining the correct dependencies and operational flow across components.
default bool	(Optional) Default indicates whether this topology serves as the default configuration. When set to true, this topology is automatically used unless another is explicitly specified.

ClusterTopologyComponent

(Appears on:ClusterTopology)

ClusterTopologyComponent defines a Component within a ClusterTopology.

Field	Description
name string	Defines the unique identifier of the component within the cluster topology. It follows IANA Service naming rules and is used as part of the Service’s DNS name. The name must start with a lowercase letter, can contain lowercase letters, numbers, and hyphens, and must end with a lowercase letter or number. Cannot be updated once set.
compDef string	Specifies the exact name, name prefix, or regular expression pattern for matching the name of the ComponentDefinition custom resource (CR) that defines the Component’s characteristics and behavior. The system selects the ComponentDefinition CR with the latest version that matches the pattern. This approach allows: Precise selection by providing the exact name of a ComponentDefinition CR. Flexible and automatic selection of the most up-to-date ComponentDefinition CR by specifying a name prefix or regular expression pattern. Once set, this field cannot be updated.

ClusterTopologyOrders

(Appears on:ClusterTopology)

ClusterTopologyOrders manages the lifecycle of components within a cluster by defining their provisioning, terminating, and updating sequences. It organizes components into stages or groups, where each group indicates a set of components that can be managed concurrently. These groups are processed sequentially, allowing precise control based on component dependencies and requirements.

Field	Description
provision []string	(Optional) Specifies the order for creating and initializing components. This is designed for components that depend on one another. Components without dependencies can be grouped together. Components that can be provisioned independently or have no dependencies can be listed together in the same stage, separated by commas.
terminate []string	(Optional) Outlines the order for stopping and deleting components. This sequence is designed for components that require a graceful shutdown or have interdependencies. Components that can be terminated independently or have no dependencies can be listed together in the same stage, separated by commas.
update []string	(Optional) Update determines the order for updating components’ specifications, such as image upgrades or resource scaling. This sequence is designed for components that have dependencies or require specific update procedures. Components that can be updated independently or have no dependencies can be listed together in the same stage, separated by commas.

CmdExecutorConfig

(Appears on:PostStartAction, SwitchoverAction, SystemAccountSpec)

CmdExecutorConfig specifies how to perform creation and deletion statements.

Deprecated since v0.8.

Field	Description
CommandExecutorEnvItem CommandExecutorEnvItem	(Members of CommandExecutorEnvItem are embedded into this type.)
CommandExecutorItem CommandExecutorItem	(Members of CommandExecutorItem are embedded into this type.)

CommandExecutorEnvItem

(Appears on:CmdExecutorConfig)

CommandExecutorEnvItem is deprecated since v0.8.

Field	Description
image string	Specifies the image used to execute the command.
env []Kubernetes core/v1.EnvVar	(Optional) A list of environment variables that will be injected into the command execution context.

CommandExecutorItem

(Appears on:CmdExecutorConfig)

CommandExecutorItem is deprecated since v0.8.

Field	Description
command []string	The command to be executed.
args []string	(Optional) Additional parameters used in the execution of the command.

ComponentConfigSpec

(Appears on:ClusterComponentDefinition, ComponentDefinitionSpec, ConfigurationItemDetail)

Field	Description
ComponentTemplateSpec ComponentTemplateSpec	(Members of ComponentTemplateSpec are embedded into this type.)
keys []string	(Optional) Specifies the configuration files within the ConfigMap that support dynamic updates. A configuration template (provided in the form of a ConfigMap) may contain templates for multiple configuration files. Each configuration file corresponds to a key in the ConfigMap. Some of these configuration files may support dynamic modification and reloading without requiring a pod restart. If empty or omitted, all configuration files in the ConfigMap are assumed to support dynamic updates, and ConfigConstraint applies to all keys.
legacyRenderedConfigSpec LegacyRenderedTemplateSpec	(Optional) Specifies the secondary rendered config spec for pod-specific customization. The template is rendered inside the pod (by the “config-manager” sidecar container) and merged with the main template’s render result to generate the final configuration file. This field is intended to handle scenarios where different pods within the same Component have varying configurations. It allows for pod-specific customization of the configuration. Note: This field will be deprecated in future versions, and the functionality will be moved to cluster.spec.componentSpecs[*].instances[*].
constraintRef string	(Optional) Specifies the name of the referenced configuration constraints object.
asEnvFrom []string	(Optional) Specifies the containers to inject the ConfigMap parameters as environment variables. This is useful when application images accept parameters through environment variables and generate the final configuration file in the startup script based on these variables. This field allows users to specify a list of container names, and KubeBlocks will inject the environment variables converted from the ConfigMap into these designated containers. This provides a flexible way to pass the configuration items from the ConfigMap to the container without modifying the image. Deprecated: asEnvFrom has been deprecated since 0.9.0 and will be removed in 0.10.0. Use injectEnvTo instead.
injectEnvTo []string	(Optional) Specifies the containers to inject the ConfigMap parameters as environment variables. This is useful when application images accept parameters through environment variables and generate the final configuration file in the startup script based on these variables. This field allows users to specify a list of container names, and KubeBlocks will inject the environment variables converted from the ConfigMap into these designated containers. This provides a flexible way to pass the configuration items from the ConfigMap to the container without modifying the image.
reRenderResourceTypes []RerenderResourceType	(Optional) Specifies whether the configuration needs to be re-rendered after v-scale or h-scale operations to reflect changes. In some scenarios, the configuration may need to be updated to reflect the changes in resource allocation or cluster topology. Examples: Redis: adjust maxmemory after v-scale operation. MySQL: increase max connections after v-scale operation. Zookeeper: update zoo.cfg with new node addresses after h-scale operation.
asSecret bool	(Optional) Whether to store the final rendered parameters as a secret.

ComponentDefRef

(Appears on:ClusterComponentDefinition)

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

Deprecated since v0.8.

Field	Description
componentDefName string	The name of the componentDef to be selected.
failurePolicy FailurePolicyType	(Optional) Defines the policy to be followed in case of a failure in finding the component.
componentRefEnv []ComponentRefEnv	(Optional) The values that are to be injected as environment variables into each component.

ComponentDefinitionSpec

(Appears on:ComponentDefinition)

Field	Description
provider string	(Optional) Specifies the name of the Component provider, typically the vendor or developer name. It identifies the entity responsible for creating and maintaining the Component. When specifying the provider name, consider the following guidelines: Keep the name concise and relevant to the Component. Use a consistent naming convention across Components from the same provider. Avoid using trademarked or copyrighted names without proper permission.
description string	(Optional) Provides a brief and concise explanation of the Component’s purpose, functionality, and any relevant details. It serves as a quick reference for users to understand the Component’s role and characteristics.
serviceKind string	(Optional) Defines the type of well-known service protocol that the Component provides. It specifies the standard or widely recognized protocol used by the Component to offer its Services. The serviceKind field allows users to quickly identify the type of Service provided by the Component based on common protocols or service types. This information helps in understanding the compatibility, interoperability, and usage of the Component within a system. Some examples of well-known service protocols include: “MySQL”: Indicates that the Component provides a MySQL database service. “PostgreSQL”: Indicates that the Component offers a PostgreSQL database service. “Redis”: Signifies that the Component functions as a Redis key-value store. “ETCD”: Denotes that the Component serves as an ETCD distributed key-value store. The serviceKind value is case-insensitive, allowing for flexibility in specifying the protocol name. When specifying the serviceKind, consider the following guidelines: Use well-established and widely recognized protocol names or service types. Ensure that the serviceKind accurately represents the primary service type offered by the Component. If the Component provides multiple services, choose the most prominent or commonly used protocol. Limit the serviceKind to a maximum of 32 characters for conciseness and readability. Note: The serviceKind field is optional and can be left empty if the Component does not fit into a well-known service category or if the protocol is not widely recognized. It is primarily used to convey information about the Component’s service type to users and facilitate discovery and integration. The serviceKind field is immutable and cannot be updated.
serviceVersion string	(Optional) Specifies the version of the Service provided by the Component. It follows the syntax and semantics of the “Semantic Versioning” specification (http://semver.org/). The Semantic Versioning specification defines a version number format of X.Y.Z (MAJOR.MINOR.PATCH), where: X represents the major version and indicates incompatible API changes. Y represents the minor version and indicates added functionality in a backward-compatible manner. Z represents the patch version and indicates backward-compatible bug fixes. Additional labels for pre-release and build metadata are available as extensions to the X.Y.Z format: Use pre-release labels (e.g., -alpha, -beta) for versions that are not yet stable or ready for production use. Use build metadata (e.g., +build.1) for additional version information if needed. Examples of valid ServiceVersion values: “1.0.0” “2.3.1” “3.0.0-alpha.1” “4.5.2+build.1” The serviceVersion field is immutable and cannot be updated.
runtime Kubernetes core/v1.PodSpec	Specifies the PodSpec template used in the Component. It includes the following elements: Init containers Containers Image Commands Args Envs Mounts Ports Security context Probes Lifecycle Volumes This field is intended to define static settings that remain consistent across all instantiated Components. Dynamic settings such as CPU and memory resource limits, as well as scheduling settings (affinity, toleration, priority), may vary among different instantiated Components. They should be specified in the cluster.spec.componentSpecs (ClusterComponentSpec). Specific instances of a Component may override settings defined here, such as using a different container image or modifying environment variable values. These instance-specific overrides can be specified in cluster.spec.componentSpecs[*].instances. This field is immutable and cannot be updated once set.
monitor MonitorConfig	(Optional) Deprecated since v0.9 monitor is monitoring config which provided by provider.
exporter Exporter	(Optional) Defines the built-in metrics exporter container.
vars []EnvVar	(Optional) Defines variables which are determined after Cluster instantiation and reflect dynamic or runtime attributes of instantiated Clusters. These variables serve as placeholders for setting environment variables in Pods and Actions, or for rendering configuration and script templates before actual values are finalized. These variables are placed in front of the environment variables declared in the Pod if used as environment variables. Variable values can be sourced from: ConfigMap: Select and extract a value from a specific key within a ConfigMap. Secret: Select and extract a value from a specific key within a Secret. HostNetwork: Retrieves values (including ports) from host-network resources. Service: Retrieves values (including address, port, NodePort) from a selected Service. Intended to obtain the address of a ComponentService within the same Cluster. Credential: Retrieves account name and password from a SystemAccount variable. ServiceRef: Retrieves address, port, account name and password from a selected ServiceRefDeclaration. Designed to obtain the address bound to a ServiceRef, such as a ClusterService or ComponentService of another cluster or an external service. Component: Retrieves values from a selected Component, including replicas and instance name list. This field is immutable.
volumes []ComponentVolume	(Optional) Defines the volumes used by the Component and some static attributes of the volumes. After defining the volumes here, user can reference them in the cluster.spec.componentSpecs[*].volumeClaimTemplates field to configure dynamic properties such as volume capacity and storage class. This field allows you to specify the following: Snapshot behavior: Determines whether a snapshot of the volume should be taken when performing a snapshot backup of the Component. Disk high watermark: Sets the high watermark for the volume’s disk usage. When the disk usage reaches the specified threshold, it triggers an alert or action. By configuring these volume behaviors, you can control how the volumes are managed and monitored within the Component. This field is immutable.
hostNetwork HostNetwork	(Optional) Specifies the host network configuration for the Component. When hostNetwork option is enabled, the Pods share the host’s network namespace and can directly access the host’s network interfaces. This means that if multiple Pods need to use the same port, they cannot run on the same host simultaneously due to port conflicts. The DNSPolicy field in the Pod spec determines how containers within the Pod perform DNS resolution. When using hostNetwork, the operator will set the DNSPolicy to ‘ClusterFirstWithHostNet’. With this policy, DNS queries will first go through the K8s cluster’s DNS service. If the query fails, it will fall back to the host’s DNS settings. If set, the DNS policy will be automatically set to “ClusterFirstWithHostNet”. This field is immutable.
services []ComponentService	(Optional) Defines additional Services to expose the Component’s endpoints. A default headless Service, named {cluster.name}-{component.name}-headless, is automatically created for internal Cluster communication. This field enables customization of additional Services to expose the Component’s endpoints to other Components within the same or different Clusters, and to external applications. Each Service entry in this list can include properties such as ports, type, and selectors. For intra-Cluster access, Components can reference Services using variables declared in componentDefinition.spec.vars[*].valueFrom.serviceVarRef. For inter-Cluster access, reference Services use variables declared in componentDefinition.spec.vars[*].valueFrom.serviceRefVarRef, and bind Services at Cluster creation time with clusterComponentSpec.ServiceRef[*].clusterServiceSelector. This field is immutable.
configs []ComponentConfigSpec	(Optional) Specifies the configuration file templates and volume mount parameters used by the Component. It also includes descriptions of the parameters in the ConfigMaps, such as value range limitations. This field specifies a list of templates that will be rendered into Component containers’ configuration files. Each template is represented as a ConfigMap and may contain multiple configuration files, with each file being a key in the ConfigMap. The rendered configuration files will be mounted into the Component’s containers according to the specified volume mount parameters. This field is immutable.
logConfigs []LogConfig	(Optional) Defines the types of logs generated by instances of the Component and their corresponding file paths. These logs can be collected for further analysis and monitoring. The logConfigs field is an optional list of LogConfig objects, where each object represents a specific log type and its configuration. It allows you to specify multiple log types and their respective file paths for the Component. Examples: logConfigs: filePathPattern: /data/mysql/log/mysqld-error.log name: error filePathPattern: /data/mysql/log/mysqld.log name: general filePathPattern: /data/mysql/log/mysqld-slowquery.log name: slow This field is immutable.
scripts []ComponentTemplateSpec	(Optional) Specifies groups of scripts, each provided via a ConfigMap, to be mounted as volumes in the container. These scripts can be executed during container startup or via specific actions. Each script group is encapsulated in a ComponentTemplateSpec that includes: The ConfigMap containing the scripts. The mount point where the scripts will be mounted inside the container. This field is immutable.
policyRules []Kubernetes rbac/v1.PolicyRule	(Optional) Defines the namespaced policy rules required by the Component. The policyRules field is an array of rbacv1.PolicyRule objects that define the policy rules needed by the Component to operate within a namespace. These policy rules determine the permissions and verbs the Component is allowed to perform on Kubernetes resources within the namespace. The purpose of this field is to automatically generate the necessary RBAC roles for the Component based on the specified policy rules. This ensures that the Pods in the Component has appropriate permissions to function. Note: This field is currently non-functional and is reserved for future implementation. This field is immutable.
labels map[string]string	(Optional) Specifies static labels that will be patched to all Kubernetes resources created for the Component. Note: If a label key in the labels field conflicts with any system labels or user-specified labels, it will be silently ignored to avoid overriding higher-priority labels. This field is immutable.
annotations map[string]string	(Optional) Specifies static annotations that will be patched to all Kubernetes resources created for the Component. Note: If an annotation key in the annotations field conflicts with any system annotations or user-specified annotations, it will be silently ignored to avoid overriding higher-priority annotations. This field is immutable.
replicasLimit ReplicasLimit	(Optional) Defines the upper limit of the number of replicas supported by the Component. It defines the maximum number of replicas that can be created for the Component. This field allows you to set a limit on the scalability of the Component, preventing it from exceeding a certain number of replicas. This field is immutable.
systemAccounts []SystemAccount	(Optional) An array of SystemAccount objects that define the system accounts needed for the management operations of the Component. Each SystemAccount includes: Account name. The SQL statement template: Used to create the system account. Password Source: Either generated based on certain rules or retrieved from a Secret. Use cases for system accounts typically involve tasks like system initialization, backups, monitoring, health checks, replication, and other system-level operations. System accounts are distinct from user accounts, although both are database accounts. System Accounts: Created during Cluster setup by the KubeBlocks operator, these accounts have higher privileges for system management and are fully managed through a declarative API by the operator. User Accounts: Managed by users or administrator. User account permissions should follow the principle of least privilege, granting only the necessary access rights to complete their required tasks. This field is immutable.
updateStrategy UpdateStrategy	(Optional) Specifies the concurrency strategy for updating multiple instances of the Component. Available strategies: Serial: Updates replicas one at a time, ensuring minimal downtime by waiting for each replica to become ready before updating the next. Parallel: Updates all replicas simultaneously, optimizing for speed but potentially reducing availability during the update. BestEffortParallel: Updates replicas concurrently with a limit on simultaneous updates to ensure a minimum number of operational replicas for maintaining quorum. For example, in a 5-replica component, updating a maximum of 2 replicas simultaneously keeps at least 3 operational for quorum. This field is immutable and defaults to ‘Serial’.
podManagementPolicy Kubernetes apps/v1.PodManagementPolicyType	(Optional) InstanceSet controls the creation of pods during initial scale up, replacement of pods on nodes, and scaling down. OrderedReady: Creates pods in increasing order (pod-0, then pod-1, etc). The controller waits until each pod is ready before continuing. Pods are removed in reverse order when scaling down. Parallel: Creates pods in parallel to match the desired scale without waiting. All pods are deleted at once when scaling down.
roles []ReplicaRole	(Optional) Enumerate all possible roles assigned to each replica of the Component, influencing its behavior. A replica can have zero to multiple roles. KubeBlocks operator determines the roles of each replica by invoking the lifecycleActions.roleProbe method. This action returns a list of roles for each replica, and the returned roles must be predefined in the roles field. The roles assigned to a replica can influence various aspects of the Component’s behavior, such as: Service selection: The Component’s exposed Services may target replicas based on their roles using roleSelector. Update order: The roles can determine the order in which replicas are updated during a Component update. For instance, replicas with a “follower” role can be updated first, while the replica with the “leader” role is updated last. This helps minimize the number of leader changes during the update process. This field is immutable.
roleArbitrator RoleArbitrator	(Optional) This field has been deprecated since v0.9. This field is maintained for backward compatibility and its use is discouraged. Existing usage should be updated to the current preferred approach to avoid compatibility issues in future releases. This field is immutable.
lifecycleActions ComponentLifecycleActions	(Optional) Defines a set of hooks and procedures that customize the behavior of a Component throughout its lifecycle. Actions are triggered at specific lifecycle stages: postProvision: Defines the hook to be executed after the creation of a Component, with preCondition specifying when the action should be fired relative to the Component’s lifecycle stages: Immediately, RuntimeReady, ComponentReady, and ClusterReady. preTerminate: Defines the hook to be executed before terminating a Component. roleProbe: Defines the procedure which is invoked regularly to assess the role of replicas. switchover: Defines the procedure for a controlled transition of leadership from the current leader to a new replica. This approach aims to minimize downtime and maintain availability in systems with a leader-follower topology, such as before planned maintenance or upgrades on the current leader node. memberJoin: Defines the procedure to add a new replica to the replication group. memberLeave: Defines the method to remove a replica from the replication group. readOnly: Defines the procedure to switch a replica into the read-only state. readWrite: transition a replica from the read-only state back to the read-write state. dataDump: Defines the procedure to export the data from a replica. dataLoad: Defines the procedure to import data into a replica. reconfigure: Defines the procedure that update a replica with new configuration file. accountProvision: Defines the procedure to generate a new database account. This field is immutable.
serviceRefDeclarations []ServiceRefDeclaration	(Optional) Lists external service dependencies of the Component, including services from other Clusters or outside the K8s environment. This field is immutable.
minReadySeconds int32	(Optional) minReadySeconds is the minimum duration in seconds that a new Pod should remain in the ready state without any of its containers crashing to be considered available. This ensures the Pod’s stability and readiness to serve requests. A default value of 0 seconds means the Pod is considered available as soon as it enters the ready state.

ComponentDefinitionStatus

(Appears on:ComponentDefinition)

ComponentDefinitionStatus defines the observed state of ComponentDefinition.

Field	Description
observedGeneration int64	(Optional) Refers to the most recent generation that has been observed for the ComponentDefinition.
phase Phase	(Optional) Represents the current status of the ComponentDefinition. Valid values include ``,Available, andUnavailable<code>. When the status is</code>Available, the ComponentDefinition is ready and can be utilized by related objects.
message string	(Optional) Provides additional information about the current phase.

ComponentLifecycleActions

(Appears on:ComponentDefinitionSpec)

ComponentLifecycleActions defines a collection of Actions for customizing the behavior of a Component.

Field	Description
postProvision LifecycleActionHandler	(Optional) Specifies the hook to be executed after a component’s creation. By setting postProvision.customHandler.preCondition, you can determine the specific lifecycle stage at which the action should trigger: Immediately, RuntimeReady, ComponentReady, and ClusterReady. with ComponentReady being the default. The PostProvision Action is intended to run only once. The container executing this action has access to following environment variables: KB_CLUSTER_POD_IP_LIST: Comma-separated list of the cluster’s pod IP addresses (e.g., “podIp1,podIp2”). KB_CLUSTER_POD_NAME_LIST: Comma-separated list of the cluster’s pod names (e.g., “pod1,pod2”). KB_CLUSTER_POD_HOST_NAME_LIST: Comma-separated list of host names, each corresponding to a pod in KB_CLUSTER_POD_NAME_LIST (e.g., “hostName1,hostName2”). KB_CLUSTER_POD_HOST_IP_LIST: Comma-separated list of host IP addresses, each corresponding to a pod in KB_CLUSTER_POD_NAME_LIST (e.g., “hostIp1,hostIp2”). KB_CLUSTER_COMPONENT_POD_NAME_LIST: Comma-separated list of all pod names within the component (e.g., “pod1,pod2”). KB_CLUSTER_COMPONENT_POD_IP_LIST: Comma-separated list of pod IP addresses, matching the order of pods in KB_CLUSTER_COMPONENT_POD_NAME_LIST (e.g., “podIp1,podIp2”). KB_CLUSTER_COMPONENT_POD_HOST_NAME_LIST: Comma-separated list of host names for each pod, matching the order of pods in KB_CLUSTER_COMPONENT_POD_NAME_LIST (e.g., “hostName1,hostName2”). KB_CLUSTER_COMPONENT_POD_HOST_IP_LIST: Comma-separated list of host IP addresses for each pod, matching the order of pods in KB_CLUSTER_COMPONENT_POD_NAME_LIST (e.g., “hostIp1,hostIp2”). KB_CLUSTER_COMPONENT_LIST: Comma-separated list of all cluster components (e.g., “comp1,comp2”). KB_CLUSTER_COMPONENT_DELETING_LIST: Comma-separated list of components that are currently being deleted (e.g., “comp1,comp2”). KB_CLUSTER_COMPONENT_UNDELETED_LIST: Comma-separated list of components that are not being deleted (e.g., “comp1,comp2”). Note: This field is immutable once it has been set.
preTerminate LifecycleActionHandler	(Optional) Specifies the hook to be executed prior to terminating a component. The PreTerminate Action is intended to run only once. This action is executed immediately when a scale-down operation for the Component is initiated. The actual termination and cleanup of the Component and its associated resources will not proceed until the PreTerminate action has completed successfully. The container executing this action has access to following environment variables: KB_CLUSTER_POD_IP_LIST: Comma-separated list of the cluster’s pod IP addresses (e.g., “podIp1,podIp2”). KB_CLUSTER_POD_NAME_LIST: Comma-separated list of the cluster’s pod names (e.g., “pod1,pod2”). KB_CLUSTER_POD_HOST_NAME_LIST: Comma-separated list of host names, each corresponding to a pod in KB_CLUSTER_POD_NAME_LIST (e.g., “hostName1,hostName2”). KB_CLUSTER_POD_HOST_IP_LIST: Comma-separated list of host IP addresses, each corresponding to a pod in KB_CLUSTER_POD_NAME_LIST (e.g., “hostIp1,hostIp2”). KB_CLUSTER_COMPONENT_POD_NAME_LIST: Comma-separated list of all pod names within the component (e.g., “pod1,pod2”). KB_CLUSTER_COMPONENT_POD_IP_LIST: Comma-separated list of pod IP addresses, matching the order of pods in KB_CLUSTER_COMPONENT_POD_NAME_LIST (e.g., “podIp1,podIp2”). KB_CLUSTER_COMPONENT_POD_HOST_NAME_LIST: Comma-separated list of host names for each pod, matching the order of pods in KB_CLUSTER_COMPONENT_POD_NAME_LIST (e.g., “hostName1,hostName2”). KB_CLUSTER_COMPONENT_POD_HOST_IP_LIST: Comma-separated list of host IP addresses for each pod, matching the order of pods in KB_CLUSTER_COMPONENT_POD_NAME_LIST (e.g., “hostIp1,hostIp2”). KB_CLUSTER_COMPONENT_LIST: Comma-separated list of all cluster components (e.g., “comp1,comp2”). KB_CLUSTER_COMPONENT_DELETING_LIST: Comma-separated list of components that are currently being deleted (e.g., “comp1,comp2”). KB_CLUSTER_COMPONENT_UNDELETED_LIST: Comma-separated list of components that are not being deleted (e.g., “comp1,comp2”). KB_CLUSTER_COMPONENT_IS_SCALING_IN: Indicates whether the component is currently scaling in. If this variable is present and set to “true”, it denotes that the component is undergoing a scale-in operation. During scale-in, data rebalancing is necessary to maintain cluster integrity. Contrast this with a cluster deletion scenario where data rebalancing is not required as the entire cluster is being cleaned up. Note: This field is immutable once it has been set.
roleProbe RoleProbe	(Optional) Defines the procedure which is invoked regularly to assess the role of replicas. This action is periodically triggered by Lorry at the specified interval to determine the role of each replica. Upon successful execution, the action’s output designates the role of the replica, which should match one of the predefined role names within componentDefinition.spec.roles. The output is then compared with the previous successful execution result. If a role change is detected, an event is generated to inform the controller, which initiates an update of the replica’s role. Defining a RoleProbe Action for a Component is required if roles are defined for the Component. It ensures replicas are correctly labeled with their respective roles. Without this, services that rely on roleSelectors might improperly direct traffic to wrong replicas. The container executing this action has access to following environment variables: KB_POD_FQDN: The FQDN of the Pod whose role is being assessed. KB_SERVICE_PORT: The port used by the database service. KB_SERVICE_USER: The username with the necessary permissions to interact with the database service. KB_SERVICE_PASSWORD: The corresponding password for KB_SERVICE_USER to authenticate with the database service. Expected output of this action: On Success: The determined role of the replica, which must align with one of the roles specified in the component definition. On Failure: An error message, if applicable, indicating why the action failed. Note: This field is immutable once it has been set.
switchover ComponentSwitchover	(Optional) Defines the procedure for a controlled transition of leadership from the current leader to a new replica. This approach aims to minimize downtime and maintain availability in systems with a leader-follower topology, during events such as planned maintenance or when performing stop, shutdown, restart, or upgrade operations involving the current leader node. The container executing this action has access to following environment variables: KB_SWITCHOVER_CANDIDATE_NAME: The name of the pod for the new leader candidate, which may not be specified (empty). KB_SWITCHOVER_CANDIDATE_FQDN: The FQDN of the new leader candidate’s pod, which may not be specified (empty). KB_LEADER_POD_IP: The IP address of the current leader’s pod prior to the switchover. KB_LEADER_POD_NAME: The name of the current leader’s pod prior to the switchover. KB_LEADER_POD_FQDN: The FQDN of the current leader’s pod prior to the switchover. The environment variables with the following prefixes are deprecated and will be removed in future releases: KB_REPLICATION_PRIMARYPOD KB_CONSENSUS_LEADERPOD Note: This field is immutable once it has been set.
memberJoin LifecycleActionHandler	(Optional) Defines the procedure to add a new replica to the replication group. This action is initiated after a replica pod becomes ready. The role of the replica (e.g., primary, secondary) will be determined and assigned as part of the action command implementation, or automatically by the database kernel or a sidecar utility like Patroni that implements a consensus algorithm. The container executing this action has access to following environment variables: KB_SERVICE_PORT: The port used by the database service. KB_SERVICE_USER: The username with the necessary permissions to interact with the database service. KB_SERVICE_PASSWORD: The corresponding password for KB_SERVICE_USER to authenticate with the database service. KB_PRIMARY_POD_FQDN: The FQDN of the primary Pod within the replication group. KB_MEMBER_ADDRESSES: A comma-separated list of Pod addresses for all replicas in the group. KB_NEW_MEMBER_POD_NAME: The pod name of the replica being added to the group. KB_NEW_MEMBER_POD_IP: The IP address of the replica being added to the group. Expected action output: On Failure: An error message detailing the reason for any failure encountered during the addition of the new member. For example, to add a new OBServer to an OceanBase Cluster in ‘zone1’, the following command may be used: command: bash -c | ADDRESS=$(KB_MEMBER_ADDRESSES%%,*) HOST=$(echo $ADDRESS | cut -d ':' -f 1) PORT=$(echo $ADDRESS | cut -d ':' -f 2) CLIENT="mysql -u $KB_SERVICE_USER -p$KB_SERVICE_PASSWORD -P $PORT -h $HOST -e" $CLIENT "ALTER SYSTEM ADD SERVER '$KB_NEW_MEMBER_POD_IP:$KB_SERVICE_PORT' ZONE 'zone1'" Note: This field is immutable once it has been set.
memberLeave LifecycleActionHandler	(Optional) Defines the procedure to remove a replica from the replication group. This action is initiated before remove a replica from the group. The operator will wait for MemberLeave to complete successfully before releasing the replica and cleaning up related Kubernetes resources. The process typically includes updating configurations and informing other group members about the removal. Data migration is generally not part of this action and should be handled separately if needed. The container executing this action has access to following environment variables: KB_SERVICE_PORT: The port used by the database service. KB_SERVICE_USER: The username with the necessary permissions to interact with the database service. KB_SERVICE_PASSWORD: The corresponding password for KB_SERVICE_USER to authenticate with the database service. KB_PRIMARY_POD_FQDN: The FQDN of the primary Pod within the replication group. KB_MEMBER_ADDRESSES: A comma-separated list of Pod addresses for all replicas in the group. KB_LEAVE_MEMBER_POD_NAME: The pod name of the replica being removed from the group. KB_LEAVE_MEMBER_POD_IP: The IP address of the replica being removed from the group. Expected action output: On Failure: An error message, if applicable, indicating why the action failed. For example, to remove an OBServer from an OceanBase Cluster in ‘zone1’, the following command can be executed: command: bash -c | ADDRESS=$(KB_MEMBER_ADDRESSES%%,*) HOST=$(echo $ADDRESS | cut -d ':' -f 1) PORT=$(echo $ADDRESS | cut -d ':' -f 2) CLIENT="mysql -u $KB_SERVICE_USER -p$KB_SERVICE_PASSWORD -P $PORT -h $HOST -e" $CLIENT "ALTER SYSTEM DELETE SERVER '$KB_LEAVE_MEMBER_POD_IP:$KB_SERVICE_PORT' ZONE 'zone1'" Note: This field is immutable once it has been set.
readonly LifecycleActionHandler	(Optional) Defines the procedure to switch a replica into the read-only state. Use Case: This action is invoked when the database’s volume capacity nears its upper limit and space is about to be exhausted. The container executing this action has access to following environment variables: KB_POD_FQDN: The FQDN of the replica pod whose role is being checked. KB_SERVICE_PORT: The port used by the database service. KB_SERVICE_USER: The username with the necessary permissions to interact with the database service. KB_SERVICE_PASSWORD: The corresponding password for KB_SERVICE_USER to authenticate with the database service. Expected action output: On Failure: An error message, if applicable, indicating why the action failed. Note: This field is immutable once it has been set.
readwrite LifecycleActionHandler	(Optional) Defines the procedure to transition a replica from the read-only state back to the read-write state. Use Case: This action is used to bring back a replica that was previously in a read-only state, which restricted write operations, to its normal operational state where it can handle both read and write operations. The container executing this action has access to following environment variables: KB_POD_FQDN: The FQDN of the replica pod whose role is being checked. KB_SERVICE_PORT: The port used by the database service. KB_SERVICE_USER: The username with the necessary permissions to interact with the database service. KB_SERVICE_PASSWORD: The corresponding password for KB_SERVICE_USER to authenticate with the database service. Expected action output: On Failure: An error message, if applicable, indicating why the action failed. Note: This field is immutable once it has been set.
dataDump LifecycleActionHandler	(Optional) Defines the procedure for exporting the data from a replica. Use Case: This action is intended for initializing a newly created replica with data. It involves exporting data from an existing replica and importing it into the new, empty replica. This is essential for synchronizing the state of replicas across the system. Applicability: Some database engines or associated sidecar applications (e.g., Patroni) may already provide this functionality. In such cases, this action may not be required. The output should be a valid data dump streamed to stdout. It must exclude any irrelevant information to ensure that only the necessary data is exported for import into the new replica. Note: This field is immutable once it has been set.
dataLoad LifecycleActionHandler	(Optional) Defines the procedure for importing data into a replica. Use Case: This action is intended for initializing a newly created replica with data. It involves exporting data from an existing replica and importing it into the new, empty replica. This is essential for synchronizing the state of replicas across the system. Some database engines or associated sidecar applications (e.g., Patroni) may already provide this functionality. In such cases, this action may not be required. Data should be received through stdin. If any error occurs during the process, the action must be able to guarantee idempotence to allow for retries from the beginning. Note: This field is immutable once it has been set.
reconfigure LifecycleActionHandler	(Optional) Defines the procedure that update a replica with new configuration. Note: This field is immutable once it has been set. This Action is reserved for future versions.
accountProvision LifecycleActionHandler	(Optional) Defines the procedure to generate a new database account. Use Case: This action is designed to create system accounts that are utilized for replication, monitoring, backup, and other administrative tasks. Note: This field is immutable once it has been set.

ComponentMessageMap (map[string]string alias)

(Appears on:ClusterComponentStatus, ComponentStatus)

ComponentRefEnv

(Appears on:ComponentDefRef)

ComponentRefEnv specifies name and value of an env.

Deprecated since v0.8.

Field	Description
name string	The name of the env, it must be a C identifier.
value string	(Optional) The value of the env.
valueFrom ComponentValueFrom	(Optional) The source from which the value of the env.

ComponentService

(Appears on:ComponentDefinitionSpec, ComponentSpec)

ComponentService defines a service that would be exposed as an inter-component service within a Cluster. A Service defined in the ComponentService is expected to be accessed by other Components within the same Cluster.

When a Component needs to use a ComponentService provided by another Component within the same Cluster, it can declare a variable in the componentDefinition.spec.vars section and bind it to the specific exposed address of the ComponentService using the serviceVarRef field.

Field	Description
Service Service	(Members of Service are embedded into this type.)
podService bool	(Optional) Indicates whether to create a corresponding Service for each Pod of the selected Component. When set to true, a set of Services will be automatically generated for each Pod, and the roleSelector field will be ignored. The names of the generated Services will follow the same suffix naming pattern: $(serviceName)-$(podOrdinal). The total number of generated Services will be equal to the number of replicas specified for the Component. Example usage: name: my-service serviceName: my-service podService: true disableAutoProvision: true spec: type: NodePort ports: name: http port: 80 targetPort: 8080 In this example, if the Component has 3 replicas, three Services will be generated: my-service-0: Points to the first Pod (podOrdinal: 0) my-service-1: Points to the second Pod (podOrdinal: 1) my-service-2: Points to the third Pod (podOrdinal: 2) Each generated Service will have the specified spec configuration and will target its respective Pod. This feature is useful when you need to expose each Pod of a Component individually, allowing external access to specific instances of the Component.
disableAutoProvision bool	(Optional) Indicates whether the automatic provisioning of the service should be disabled. If set to true, the service will not be automatically created at the component provisioning. Instead, you can enable the creation of this service by specifying it explicitly in the cluster API.

ComponentSpec

(Appears on:Component)

ComponentSpec defines the desired state of Component.

Field	Description
compDef string	Specifies the name of the referenced ComponentDefinition.
serviceVersion string	(Optional) ServiceVersion specifies the version of the Service expected to be provisioned by this Component. The version should follow the syntax and semantics of the “Semantic Versioning” specification (http://semver.org/).
serviceRefs []ServiceRef	(Optional) Defines a list of ServiceRef for a Component, enabling access to both external services and Services provided by other Clusters. Types of services: External services: Not managed by KubeBlocks or managed by a different KubeBlocks operator; Require a ServiceDescriptor for connection details. Services provided by a Cluster: Managed by the same KubeBlocks operator; identified using Cluster, Component and Service names. ServiceRefs with identical serviceRef.name in the same Cluster are considered the same. Example: serviceRefs: name: "redis-sentinel" serviceDescriptor: name: "external-redis-sentinel" name: "postgres-cluster" clusterServiceSelector: cluster: "my-postgres-cluster" service: component: "postgresql" The example above includes ServiceRefs to an external Redis Sentinel service and a PostgreSQL Cluster.
labels map[string]string	(Optional) Specifies Labels to override or add for underlying Pods, PVCs, Account & TLS Secrets, Services Owned by Component.
annotations map[string]string	(Optional) Specifies Annotations to override or add for underlying Pods, PVCs, Account & TLS Secrets, Services Owned by Component.
env []Kubernetes core/v1.EnvVar	(Optional) List of environment variables to add.
resources Kubernetes core/v1.ResourceRequirements	(Optional) Specifies the resources required by the Component. It allows defining the CPU, memory requirements and limits for the Component’s containers.
volumeClaimTemplates []ClusterComponentVolumeClaimTemplate	(Optional) Specifies a list of PersistentVolumeClaim templates that define the storage requirements for the Component. Each template specifies the desired characteristics of a persistent volume, such as storage class, size, and access modes. These templates are used to dynamically provision persistent volumes for the Component.
volumes []Kubernetes core/v1.Volume	(Optional) List of volumes to override.
services []ComponentService	(Optional) Overrides Services defined in referenced ComponentDefinition and exposes endpoints that can be accessed by clients.
systemAccounts []ComponentSystemAccount	(Optional) Overrides system accounts defined in referenced ComponentDefinition.
replicas int32	Specifies the desired number of replicas in the Component for enhancing availability and durability, or load balancing.
configs []ClusterComponentConfig	(Optional) Specifies the configuration content of a config template.
enabledLogs []string	(Optional) Specifies which types of logs should be collected for the Cluster. The log types are defined in the componentDefinition.spec.logConfigs field with the LogConfig entries. The elements in the enabledLogs array correspond to the names of the LogConfig entries. For example, if the componentDefinition.spec.logConfigs defines LogConfig entries with names “slow_query_log” and “error_log”, you can enable the collection of these logs by including their names in the enabledLogs array: enabledLogs: slow_query_log error_log
serviceAccountName string	(Optional) Specifies the name of the ServiceAccount required by the running Component. This ServiceAccount is used to grant necessary permissions for the Component’s Pods to interact with other Kubernetes resources, such as modifying Pod labels or sending events. Defaults: If not specified, KubeBlocks automatically assigns a default ServiceAccount named “kb-{cluster.name}”, bound to a default role defined during KubeBlocks installation. Future Changes: Future versions might change the default ServiceAccount creation strategy to one per Component, potentially revising the naming to “kb-{cluster.name}-{component.name}”. Users can override the automatic ServiceAccount assignment by explicitly setting the name of an existed ServiceAccount in this field.
instanceUpdateStrategy InstanceUpdateStrategy	(Optional) Indicates the InstanceUpdateStrategy that will be employed to update Pods in the InstanceSet when a revision is made to Template.
parallelPodManagementConcurrency Kubernetes api utils intstr.IntOrString	(Optional) Controls the concurrency of pods during initial scale up, when replacing pods on nodes, or when scaling down. It only used when PodManagementPolicy is set to Parallel. The default Concurrency is 100%.
podUpdatePolicy PodUpdatePolicyType	(Optional) PodUpdatePolicy indicates how pods should be updated StrictInPlace indicates that only allows in-place upgrades. Any attempt to modify other fields will be rejected. PreferInPlace indicates that we will first attempt an in-place upgrade of the Pod. If that fails, it will fall back to the ReCreate, where pod will be recreated. Default value is “PreferInPlace”
affinity Affinity	(Optional) Specifies a group of affinity scheduling rules for the Component. It allows users to control how the Component’s Pods are scheduled onto nodes in the Cluster. Deprecated since v0.10, replaced by the schedulingPolicy field.
tolerations []Kubernetes core/v1.Toleration	(Optional) Allows Pods to be scheduled onto nodes with matching taints. Each toleration in the array allows the Pod to tolerate node taints based on specified key, value, effect, and operator. The key, value, and effect identify the taint that the toleration matches. The operator determines how the toleration matches the taint. Pods with matching tolerations are allowed to be scheduled on tainted nodes, typically reserved for specific purposes. Deprecated since v0.10, replaced by the schedulingPolicy field.
schedulingPolicy SchedulingPolicy	(Optional) Specifies the scheduling policy for the Component.
tlsConfig TLSConfig	(Optional) Specifies the TLS configuration for the Component, including: A boolean flag that indicates whether the Component should use Transport Layer Security (TLS) for secure communication. An optional field that specifies the configuration for the TLS certificates issuer when TLS is enabled. It allows defining the issuer name and the reference to the secret containing the TLS certificates and key. The secret should contain the CA certificate, TLS certificate, and private key in the specified keys.
instances []InstanceTemplate	(Optional) Allows for the customization of configuration values for each instance within a Component. An Instance represent a single replica (Pod and associated K8s resources like PVCs, Services, and ConfigMaps). While instances typically share a common configuration as defined in the ClusterComponentSpec, they can require unique settings in various scenarios: For example: A database Component might require different resource allocations for primary and secondary instances, with primaries needing more resources. During a rolling upgrade, a Component may first update the image for one or a few instances, and then update the remaining instances after verifying that the updated instances are functioning correctly. InstanceTemplate allows for specifying these unique configurations per instance. Each instance’s name is constructed using the pattern: $(component.name)-$(template.name)-$(ordinal), starting with an ordinal of 0. It is crucial to maintain unique names for each InstanceTemplate to avoid conflicts. The sum of replicas across all InstanceTemplates should not exceed the total number of Replicas specified for the Component. Any remaining replicas will be generated using the default template and will follow the default naming rules.
offlineInstances []string	(Optional) Specifies the names of instances to be transitioned to offline status. Marking an instance as offline results in the following: The associated Pod is stopped, and its PersistentVolumeClaim (PVC) is retained for potential future reuse or data recovery, but it is no longer actively used. The ordinal number assigned to this instance is preserved, ensuring it remains unique and avoiding conflicts with new instances. Setting instances to offline allows for a controlled scale-in process, preserving their data and maintaining ordinal consistency within the Cluster. Note that offline instances and their associated resources, such as PVCs, are not automatically deleted. The administrator must manually manage the cleanup and removal of these resources when they are no longer needed.
runtimeClassName string	(Optional) Defines runtimeClassName for all Pods managed by this Component.
disableExporter bool	(Optional) Determines whether metrics exporter information is annotated on the Component’s headless Service. If set to true, the following annotations will not be patched into the Service: “monitor.kubeblocks.io/path” “monitor.kubeblocks.io/port” “monitor.kubeblocks.io/scheme” These annotations allow the Prometheus installed by KubeBlocks to discover and scrape metrics from the exporter.
stop bool	(Optional) Stop the Component. If set, all the computing resources will be released.

ComponentStatus

(Appears on:Component)

ComponentStatus represents the observed state of a Component within the Cluster.

Field	Description
observedGeneration int64	(Optional) Specifies the most recent generation observed for this Component object.
conditions []Kubernetes meta/v1.Condition	(Optional) Represents a list of detailed status of the Component object. Each condition in the list provides real-time information about certain aspect of the Component object. This field is crucial for administrators and developers to monitor and respond to changes within the Component. It provides a history of state transitions and a snapshot of the current state that can be used for automated logic or direct inspection.
phase ClusterComponentPhase	Indicates the current phase of the Component, with each phase indicating specific conditions: Creating: The initial phase for new Components, transitioning from ‘empty’(“”). Running: All Pods in a Running state. Updating: The Component is currently being updated, with no failed Pods present. Abnormal: Some Pods have failed, indicating a potentially unstable state. However, the cluster remains available as long as a quorum of members is functioning. Failed: A significant number of Pods or critical Pods have failed The cluster may be non-functional or may offer only limited services (e.g, read-only). Stopping: All Pods are being terminated, with current replica count at zero. Stopped: All associated Pods have been successfully deleted. Deleting: The Component is being deleted.
message ComponentMessageMap	(Optional) A map that stores detailed message about the Component. Each entry in the map provides insights into specific elements of the Component, such as Pods or workloads. Keys in this map are formatted as ObjectKind/Name, where ObjectKind could be a type like Pod, and Name is the specific name of the object.

ComponentSwitchover

(Appears on:ComponentLifecycleActions)

Field	Description
withCandidate Action	(Optional) Represents the switchover process for a specified candidate primary or leader instance. Note that only Action.Exec is currently supported, while Action.HTTP is not.
withoutCandidate Action	(Optional) Represents a switchover process that does not involve a specific candidate primary or leader instance. As with the previous field, only Action.Exec is currently supported, not Action.HTTP.
scriptSpecSelectors []ScriptSpecSelector	(Optional) Used to define the selectors for the scriptSpecs that need to be referenced. If this field is set, the scripts defined under the ‘scripts’ field can be invoked or referenced within an Action. This field is deprecated from v0.9. This field is maintained for backward compatibility and its use is discouraged. Existing usage should be updated to the current preferred approach to avoid compatibility issues in future releases.

ComponentSystemAccount

(Appears on:ClusterComponentSpec, ComponentSpec)

Field	Description
name string	The name of the system account.
passwordConfig PasswordConfig	(Optional) Specifies the policy for generating the account’s password. This field is immutable once set.
secretRef ProvisionSecretRef	(Optional) Refers to the secret from which data will be copied to create the new account. This field is immutable once set.

ComponentTemplateSpec

(Appears on:ClusterComponentDefinition, ComponentConfigSpec, ComponentDefinitionSpec)

Field	Description
name string	Specifies the name of the configuration template.
templateRef string	(Optional) Specifies the name of the referenced configuration template ConfigMap object.
namespace string	(Optional) Specifies the namespace of the referenced configuration template ConfigMap object. An empty namespace is equivalent to the “default” namespace.
volumeName string	(Optional) Refers to the volume name of PodTemplate. The configuration file produced through the configuration template will be mounted to the corresponding volume. Must be a DNS_LABEL name. The volume name must be defined in podSpec.containers[*].volumeMounts.
defaultMode int32	(Optional) The operator attempts to set default file permissions for scripts (0555) and configurations (0444). However, certain database engines may require different file permissions. You can specify the desired file permissions here. Must be specified as an octal value between 0000 and 0777 (inclusive), or as a decimal value between 0 and 511 (inclusive). YAML supports both octal and decimal values for file permissions. Please note that this setting only affects the permissions of the files themselves. Directories within the specified path are not impacted by this setting. It’s important to be aware that this setting might conflict with other options that influence the file mode, such as fsGroup. In such cases, the resulting file mode may have additional bits set. Refers to documents of k8s.ConfigMapVolumeSource.defaultMode for more information.

ComponentValueFrom

(Appears on:ComponentRefEnv)

ComponentValueFrom is deprecated since v0.8.

Field	Description
type ComponentValueFromType	Specifies the source to select. It can be one of three types: FieldRef, ServiceRef, HeadlessServiceRef.
fieldPath string	(Optional) The jsonpath of the source to select when the Type is FieldRef. Two objects are registered in the jsonpath: componentDef and components: componentDef is the component definition object specified in componentRef.componentDefName. components are the component list objects referring to the component definition object.
format string	(Optional) Defines the format of each headless service address. Three builtin variables can be used as placeholders: $POD_ORDINAL, $POD_FQDN, $POD_NAME $POD_ORDINAL represents the ordinal of the pod. $POD_FQDN represents the fully qualified domain name of the pod. $POD_NAME represents the name of the pod.
joinWith string	(Optional) The string used to join the values of headless service addresses.

ComponentValueFromType (string alias)

(Appears on:ComponentValueFrom)

ComponentValueFromType specifies the type of component value from which the data is derived.

Deprecated since v0.8.

Value	Description
"FieldRef"	FromFieldRef refers to the value of a specific field in the object.
"HeadlessServiceRef"	FromHeadlessServiceRef refers to a headless service within the same namespace as the object.
"ServiceRef"	FromServiceRef refers to a service within the same namespace as the object.

ComponentVarSelector

(Appears on:VarSource)

ComponentVarSelector selects a var from a Component.

Field	Description
ClusterObjectReference ClusterObjectReference	(Members of ClusterObjectReference are embedded into this type.) The Component to select from.
ComponentVars ComponentVars	(Members of ComponentVars are embedded into this type.)

ComponentVars

(Appears on:ComponentVarSelector)

Field	Description
componentName VarOption	(Optional) Reference to the name of the Component object.
replicas VarOption	(Optional) Reference to the replicas of the component.
instanceNames VarOption	(Optional) Reference to the pod name list of the component. and the value will be presented in the following format: name1,name2,…
podFQDNs VarOption	(Optional) Reference to the pod FQDN list of the component. The value will be presented in the following format: FQDN1,FQDN2,…

ComponentVersionCompatibilityRule

(Appears on:ComponentVersionSpec)

ComponentVersionCompatibilityRule defines the compatibility between a set of component definitions and a set of releases.

Field	Description
compDefs []string	CompDefs specifies names for the component definitions associated with this ComponentVersion. Each name in the list can represent an exact name, a name prefix, or a regular expression pattern. For example: “mysql-8.0.30-v1alpha1”: Matches the exact name “mysql-8.0.30-v1alpha1” “mysql-8.0.30”: Matches all names starting with “mysql-8.0.30” ”^mysql-8.0.\d{1,2}$“: Matches all names starting with “mysql-8.0.” followed by one or two digits.
releases []string	Releases is a list of identifiers for the releases.

ComponentVersionRelease

(Appears on:ComponentVersionSpec)

ComponentVersionRelease represents a release of component instances within a ComponentVersion.

Field	Description
name string	Name is a unique identifier for this release. Cannot be updated.
changes string	(Optional) Changes provides information about the changes made in this release.
serviceVersion string	ServiceVersion defines the version of the well-known service that the component provides. The version should follow the syntax and semantics of the “Semantic Versioning” specification (http://semver.org/). If the release is used, it will serve as the service version for component instances, overriding the one defined in the component definition. Cannot be updated.
images map[string]string	Images define the new images for different containers within the release.

ComponentVersionSpec

(Appears on:ComponentVersion)

ComponentVersionSpec defines the desired state of ComponentVersion

Field	Description
compatibilityRules []ComponentVersionCompatibilityRule	CompatibilityRules defines compatibility rules between sets of component definitions and releases.
releases []ComponentVersionRelease	Releases represents different releases of component instances within this ComponentVersion.

ComponentVersionStatus

(Appears on:ComponentVersion)

ComponentVersionStatus defines the observed state of ComponentVersion

Field	Description
observedGeneration int64	(Optional) ObservedGeneration is the most recent generation observed for this ComponentVersion.
phase Phase	(Optional) Phase valid values are ``,Available, 'Unavailable`. Available is ComponentVersion become available, and can be used for co-related objects.
message string	(Optional) Extra message for current phase.
serviceVersions string	(Optional) ServiceVersions represent the supported service versions of this ComponentVersion.

ComponentVolume

(Appears on:ComponentDefinitionSpec)

Field	Description
name string	Specifies the name of the volume. It must be a DNS_LABEL and unique within the pod. More info can be found at: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names Note: This field cannot be updated.
needSnapshot bool	(Optional) Specifies whether the creation of a snapshot of this volume is necessary when performing a backup of the Component. Note: This field cannot be updated.
highWatermark int	(Optional) Sets the critical threshold for volume space utilization as a percentage (0-100). Exceeding this percentage triggers the system to switch the volume to read-only mode as specified in componentDefinition.spec.lifecycleActions.readOnly. This precaution helps prevent space depletion while maintaining read-only access. If the space utilization later falls below this threshold, the system reverts the volume to read-write mode as defined in componentDefinition.spec.lifecycleActions.readWrite, restoring full functionality. Note: This field cannot be updated.

ConfigConstraintSpec

(Appears on:ConfigConstraint)

ConfigConstraintSpec defines the desired state of ConfigConstraint

Field	Description
reloadOptions ReloadOptions	(Optional) Specifies the dynamic reload action supported by the engine. When set, the controller executes the method defined here to execute hot parameter updates. Dynamic reloading is triggered only if both of the following conditions are met: The modified parameters are listed in the dynamicParameters field. If reloadStaticParamsBeforeRestart is set to true, modifications to staticParameters can also trigger a reload. reloadOptions is set. If reloadOptions is not set or the modified parameters are not listed in dynamicParameters, dynamic reloading will not be triggered. Example: reloadOptions: tplScriptTrigger: namespace: kb-system scriptConfigMapRef: mysql-reload-script sync: true
dynamicActionCanBeMerged bool	(Optional) Indicates whether to consolidate dynamic reload and restart actions into a single restart. If true, updates requiring both actions will result in only a restart, merging the actions. If false, updates will trigger both actions executed sequentially: first dynamic reload, then restart. This flag allows for more efficient handling of configuration changes by potentially eliminating an unnecessary reload step.
reloadStaticParamsBeforeRestart bool	(Optional) Configures whether the dynamic reload specified in reloadOptions applies only to dynamic parameters or to all parameters (including static parameters). false (default): Only modifications to the dynamic parameters listed in dynamicParameters will trigger a dynamic reload. true: Modifications to both dynamic parameters listed in dynamicParameters and static parameters listed in staticParameters will trigger a dynamic reload. The “true” option is for certain engines that require static parameters to be set via SQL statements before they can take effect on restart.
toolsImageSpec ToolsSetup	(Optional) Specifies the tools container image used by ShellTrigger for dynamic reload. If the dynamic reload action is triggered by a ShellTrigger, this field is required. This image must contain all necessary tools for executing the ShellTrigger scripts. Usually the specified image is referenced by the init container, which is then responsible for copy the tools from the image to a bin volume. This ensures that the tools are available to the ‘config-manager’ sidecar.
downwardAPIOptions []DownwardAPIChangeTriggeredAction	(Optional) Specifies a list of actions to execute specified commands based on Pod labels. It utilizes the K8s Downward API to mount label information as a volume into the pod. The ‘config-manager’ sidecar container watches for changes in the role label and dynamically invoke registered commands (usually execute some SQL statements) when a change is detected. It is designed for scenarios where: Replicas with different roles have different configurations, such as Redis primary & secondary replicas. After a role switch (e.g., from secondary to primary), some changes in configuration are needed to reflect the new role.
scriptConfigs []ScriptConfig	(Optional) A list of ScriptConfig Object. Each ScriptConfig object specifies a ConfigMap that contains script files that should be mounted inside the pod. The scripts are mounted as volumes and can be referenced and executed by the dynamic reload and DownwardAction to perform specific tasks or configurations.
cfgSchemaTopLevelName string	(Optional) Specifies the top-level key in the ‘configurationSchema.cue’ that organizes the validation rules for parameters. This key must exist within the CUE script defined in ‘configurationSchema.cue’.
configurationSchema CustomParametersValidation	(Optional) Defines a list of parameters including their names, default values, descriptions, types, and constraints (permissible values or the range of valid values).
staticParameters []string	(Optional) List static parameters. Modifications to any of these parameters require a restart of the process to take effect.
dynamicParameters []string	(Optional) List dynamic parameters. Modifications to these parameters trigger a configuration reload without requiring a process restart.
immutableParameters []string	(Optional) Lists the parameters that cannot be modified once set. Attempting to change any of these parameters will be ignored.
selector Kubernetes meta/v1.LabelSelector	(Optional) Used to match labels on the pod to determine whether a dynamic reload should be performed. In some scenarios, only specific pods (e.g., primary replicas) need to undergo a dynamic reload. The selector allows you to specify label selectors to target the desired pods for the reload process. If the selector is not specified or is nil, all pods managed by the workload will be considered for the dynamic reload.
formatterConfig FileFormatConfig	Specifies the format of the configuration file and any associated parameters that are specific to the chosen format. Supported formats include ini, xml, yaml, json, hcl, dotenv, properties, and toml. Each format may have its own set of parameters that can be configured. For instance, when using the ini format, you can specify the section name. Example: formatterConfig: format: ini iniConfig: sectionName: mysqld

ConfigConstraintStatus

(Appears on:ConfigConstraint)

ConfigConstraintStatus represents the observed state of a ConfigConstraint.

Field	Description
phase ConfigConstraintPhase	(Optional) Specifies the status of the configuration template. When set to CCAvailablePhase, the ConfigConstraint can be referenced by ClusterDefinition.
message string	(Optional) Provides descriptions for abnormal states.
observedGeneration int64	(Optional) Refers to the most recent generation observed for this ConfigConstraint. This value is updated by the API Server.

ConfigMapRef

(Appears on:UserResourceRefs)

ConfigMapRef defines a reference to a ConfigMap.

Field	Description
ResourceMeta ResourceMeta	(Members of ResourceMeta are embedded into this type.)
configMap Kubernetes core/v1.ConfigMapVolumeSource	ConfigMap specifies the ConfigMap to be mounted as a volume.

ConfigParams

(Appears on:ConfigurationItemDetail)

Field	Description
content string	(Optional) Holds the configuration keys and values. This field is a workaround for issues found in kubebuilder and code-generator. Refer to https://github.com/kubernetes-sigs/kubebuilder/issues/528 and https://github.com/kubernetes/code-generator/issues/50 for more details. Represents the content of the configuration file.
parameters map[string]*string	(Optional) Represents the updated parameters for a single configuration file.

ConfigTemplateExtension

(Appears on:ConfigurationItemDetail, LegacyRenderedTemplateSpec)

Field	Description
templateRef string	Specifies the name of the referenced configuration template ConfigMap object.
namespace string	(Optional) Specifies the namespace of the referenced configuration template ConfigMap object. An empty namespace is equivalent to the “default” namespace.
policy MergedPolicy	(Optional) Defines the strategy for merging externally imported templates into component templates.

ConfigurationItemDetail

(Appears on:ConfigurationSpec)

ConfigurationItemDetail corresponds to settings of a configuration template (a ConfigMap).

Field	Description
name string	Defines the unique identifier of the configuration template. It must be a string of maximum 63 characters, and can only include lowercase alphanumeric characters, hyphens, and periods. The name must start and end with an alphanumeric character.
version string	(Optional) Deprecated: No longer used. Please use ‘Payload’ instead. Previously represented the version of the configuration template.
payload Payload	(Optional) External controllers can trigger a configuration rerender by modifying this field. Note: Currently, the payload field is opaque and its content is not interpreted by the system. Modifying this field will cause a rerender, regardless of the specific content of this field.
configSpec ComponentConfigSpec	(Optional) Specifies the name of the configuration template (a ConfigMap), ConfigConstraint, and other miscellaneous options. The configuration template is a ConfigMap that contains multiple configuration files. Each configuration file is stored as a key-value pair within the ConfigMap. ConfigConstraint allows defining constraints and validation rules for configuration parameters. It ensures that the configuration adheres to certain requirements and limitations.
importTemplateRef ConfigTemplateExtension	(Optional) Specifies the user-defined configuration template. When provided, the importTemplateRef overrides the default configuration template specified in configSpec.templateRef. This allows users to customize the configuration template according to their specific requirements.
configFileParams map[string]github.com/apecloud/kubeblocks/apis/apps/v1alpha1.ConfigParams	(Optional) Specifies the user-defined configuration parameters. When provided, the parameter values in configFileParams override the default configuration parameters. This allows users to override the default configuration according to their specific needs.

ConfigurationItemDetailStatus

(Appears on:ConfigurationStatus)

Field	Description
name string	Specifies the name of the configuration template. It is a required field and must be a string of maximum 63 characters. The name should only contain lowercase alphanumeric characters, hyphens, or periods. It should start and end with an alphanumeric character.
phase ConfigurationPhase	(Optional) Indicates the current status of the configuration item. Possible values include “Creating”, “Init”, “Running”, “Pending”, “Merged”, “MergeFailed”, “FailedAndPause”, “Upgrading”, “Deleting”, “FailedAndRetry”, “Finished”.
lastDoneRevision string	(Optional) Represents the last completed revision of the configuration item. This field is optional.
updateRevision string	(Optional) Represents the updated revision of the configuration item. This field is optional.
message string	(Optional) Provides a description of any abnormal status. This field is optional.
reconcileDetail ReconcileDetail	(Optional) Provides detailed information about the execution of the configuration change. This field is optional.

ConfigurationPhase (string alias)

(Appears on:ConfigurationItemDetailStatus)

ConfigurationPhase defines the Configuration FSM phase

Value	Description
"Creating"
"Deleting"
"FailedAndPause"
"FailedAndRetry"
"Finished"
"Init"
"MergeFailed"
"Merged"
"Pending"
"Running"
"Upgrading"

ConfigurationSpec

(Appears on:Configuration)

ConfigurationSpec defines the desired state of a Configuration resource.

Field	Description
clusterRef string	Specifies the name of the Cluster that this configuration is associated with.
componentName string	Represents the name of the Component that this configuration pertains to.
configItemDetails []ConfigurationItemDetail	(Optional) ConfigItemDetails is an array of ConfigurationItemDetail objects. Each ConfigurationItemDetail corresponds to a configuration template, which is a ConfigMap that contains multiple configuration files. Each configuration file is stored as a key-value pair within the ConfigMap. The ConfigurationItemDetail includes information such as: The configuration template (a ConfigMap) The corresponding ConfigConstraint (constraints and validation rules for the configuration) Volume mounts (for mounting the configuration files)

ConfigurationStatus

(Appears on:Configuration)

ConfigurationStatus represents the observed state of a Configuration resource.

Field	Description
message string	(Optional) Provides a description of any abnormal status.
observedGeneration int64	(Optional) Represents the latest generation observed for this ClusterDefinition. It corresponds to the ConfigConstraint’s generation, which is updated by the API Server.
conditions []Kubernetes meta/v1.Condition	(Optional) Provides detailed status information for opsRequest.
configurationStatus []ConfigurationItemDetailStatus	Provides the status of each component undergoing reconfiguration.

ConnectionCredentialAuth

(Appears on:ServiceDescriptorSpec)

ConnectionCredentialAuth specifies the authentication credentials required for accessing an external service.

Field	Description
username CredentialVar	(Optional) Specifies the username for the external service.
password CredentialVar	(Optional) Specifies the password for the external service.

ConsensusMember

(Appears on:ConsensusSetSpec)

ConsensusMember is deprecated since v0.7.

Field	Description
name string	Specifies the name of the consensus member.
accessMode AccessMode	Specifies the services that this member is capable of providing.
replicas int32	(Optional) Indicates the number of Pods that perform this role. The default is 1 for Leader, 0 for Learner, others for Followers.

ConsensusSetSpec

(Appears on:ClusterComponentDefinition)

ConsensusSetSpec is deprecated since v0.7.

Field	Description
StatefulSetSpec StatefulSetSpec	(Members of StatefulSetSpec are embedded into this type.)
leader ConsensusMember	Represents a single leader in the consensus set.
followers []ConsensusMember	(Optional) Members of the consensus set that have voting rights but are not the leader.
learner ConsensusMember	(Optional) Represents a member of the consensus set that does not have voting rights.

ContainerVars

(Appears on:HostNetworkVars)

ContainerVars defines the vars that can be referenced from a Container.

Field	Description
name string	The name of the container.
port NamedVar	(Optional) Container port to reference.

CredentialVar

(Appears on:ConnectionCredentialAuth, ServiceDescriptorSpec)

CredentialVar represents a variable that retrieves its value either directly from a specified expression or from a source defined in valueFrom. Only one of these options may be used at a time.

Field	Description
value string	(Optional) Holds a direct string or an expression that can be evaluated to a string. It can include variables denoted by $(VAR_NAME). These variables are expanded to the value of the environment variables defined in the container. If a variable cannot be resolved, it remains unchanged in the output. To escape variable expansion and retain the literal value, use double $ characters. For example: ”$(VAR_NAME)” will be expanded to the value of the environment variable VAR_NAME. ”$$(VAR_NAME)” will result in “$(VAR_NAME)” in the output, without any variable expansion. Default value is an empty string.
valueFrom Kubernetes core/v1.EnvVarSource	(Optional) Specifies the source for the variable’s value.

CredentialVarSelector

(Appears on:VarSource)

CredentialVarSelector selects a var from a Credential (SystemAccount).

Field	Description
ClusterObjectReference ClusterObjectReference	(Members of ClusterObjectReference are embedded into this type.) The Credential (SystemAccount) to select from.
CredentialVars CredentialVars	(Members of CredentialVars are embedded into this type.)

CredentialVars

(Appears on:CredentialVarSelector, ServiceRefVars)

CredentialVars defines the vars that can be referenced from a Credential (SystemAccount). !!!!! CredentialVars will only be used as environment variables for Pods & Actions, and will not be used to render the templates.

Field	Description
username VarOption	(Optional)
password VarOption	(Optional)

CustomLabelSpec

(Appears on:ClusterComponentDefinition)

CustomLabelSpec is deprecated since v0.8.

Field	Description
key string	The key of the label.
value string	The value of the label.
resources []GVKResource	The resources that will be patched with the label.

CustomParametersValidation

(Appears on:ConfigConstraintSpec)

CustomParametersValidation Defines a list of configuration items with their names, default values, descriptions, types, and constraints.

Field	Description
cue string	(Optional) Hold a string that contains a script written in CUE language that defines a list of configuration items. Each item is detailed with its name, default value, description, type (e.g. string, integer, float), and constraints (permissible values or the valid range of values). CUE (Configure, Unify, Execute) is a declarative language designed for defining and validating complex data configurations. It is particularly useful in environments like K8s where complex configurations and validation rules are common. This script functions as a validator for user-provided configurations, ensuring compliance with the established specifications and constraints.
schema Kubernetes api extensions v1.JSONSchemaProps	Generated from the ‘cue’ field and transformed into a JSON format.

EnvVar

(Appears on:ComponentDefinitionSpec)

EnvVar represents a variable present in the env of Pod/Action or the template of config/script.

Field	Description
name string	Name of the variable. Must be a C_IDENTIFIER.
value string	(Optional) Variable references $(VAR_NAME) are expanded using the previously defined variables in the current context. If a variable cannot be resolved, the reference in the input string will be unchanged. Double $$ are reduced to a single $, which allows for escaping the $(VAR_NAME) syntax: i.e. $$(VAR_NAME) will produce the string literal $(VAR_NAME). Escaped references will never be expanded, regardless of whether the variable exists or not. Defaults to “”.
valueFrom VarSource	(Optional) Source for the variable’s value. Cannot be used if value is not empty.
expression string	(Optional) A Go template expression that will be applied to the resolved value of the var. The expression will only be evaluated if the var is successfully resolved to a non-credential value. The resolved value can be accessed by its name within the expression, system vars and other user-defined non-credential vars can be used within the expression in the same way. Notice that, when accessing vars by its name, you should replace all the “-” in the name with “_”, because of that “-” is not a valid identifier in Go. All expressions are evaluated in the order the vars are defined. If a var depends on any vars that also have expressions defined, be careful about the evaluation order as it may use intermediate values. The result of evaluation will be used as the final value of the var. If the expression fails to evaluate, the resolving of var will also be considered failed.

ExecAction

(Appears on:Action)

ExecAction describes an Action that executes a command inside a container. Which may run as a K8s job or be executed inside the Lorry sidecar container, depending on the implementation. Future implementations will standardize execution within Lorry.

Field	Description
command []string	(Optional) Specifies the command to be executed inside the container. The working directory for this command is the container’s root directory(‘/’). Commands are executed directly without a shell environment, meaning shell-specific syntax (‘|’, etc.) is not supported. If the shell is required, it must be explicitly invoked in the command. A successful execution is indicated by an exit status of 0; any non-zero status signifies a failure.
args []string	(Optional) Args represents the arguments that are passed to the command for execution.

Exporter

(Appears on:ClusterComponentDefinition, ComponentDefinitionSpec)

Field	Description
containerName string	(Optional) Specifies the name of the built-in metrics exporter container.
scrapePath string	(Optional) Specifies the http/https url path to scrape for metrics. If empty, Prometheus uses the default value (e.g. /metrics).
scrapePort string	(Optional) Specifies the port name to scrape for metrics.
scrapeScheme PrometheusScheme	(Optional) Specifies the schema to use for scraping. http and https are the expected values unless you rewrite the __scheme__ label via relabeling. If empty, Prometheus uses the default value http.

ExporterConfig

(Appears on:MonitorConfig)

Field	Description
scrapePort Kubernetes api utils intstr.IntOrString	scrapePort is exporter port for Time Series Database to scrape metrics.
scrapePath string	(Optional) scrapePath is exporter url path for Time Series Database to scrape metrics.

FailurePolicyType (string alias)

(Appears on:ComponentDefRef)

FailurePolicyType specifies the type of failure policy.

Value	Description
"Fail"	FailurePolicyFail means that an error will be reported.
"Ignore"	FailurePolicyIgnore means that an error will be ignored but logged.

GVKResource

(Appears on:CustomLabelSpec)

GVKResource is deprecated since v0.8.

Field	Description
gvk string	Represents the GVK of a resource, such as “v1/Pod”, “apps/v1/StatefulSet”, etc. When a resource matching this is found by the selector, a custom label will be added if it doesn’t already exist, or updated if it does.
selector map[string]string	(Optional) A label query used to filter a set of resources.

HScaleDataClonePolicyType (string alias)

(Appears on:HorizontalScalePolicy)

HScaleDataClonePolicyType defines the data clone policy to be used during horizontal scaling. This policy determines how data is handled when new nodes are added to the cluster. The policy can be set to None, CloneVolume, or Snapshot.

Value	Description
"CloneVolume"	HScaleDataClonePolicyCloneVolume indicates that data will be cloned from existing volumes during horizontal scaling.
"Snapshot"	HScaleDataClonePolicyFromSnapshot indicates that data will be cloned from a snapshot during horizontal scaling.
"None"	HScaleDataClonePolicyNone indicates that no data cloning will occur during horizontal scaling.

HTTPAction

(Appears on:Action)

HTTPAction describes an Action that triggers HTTP requests. HTTPAction is to be implemented in future version.

Field	Description
path string	(Optional) Specifies the endpoint to be requested on the HTTP server.
port Kubernetes api utils intstr.IntOrString	Specifies the target port for the HTTP request. It can be specified either as a numeric value in the range of 1 to 65535, or as a named port that meets the IANA_SVC_NAME specification.
host string	(Optional) Indicates the server’s domain name or IP address. Defaults to the Pod’s IP. Prefer setting the “Host” header in httpHeaders when needed.
scheme Kubernetes core/v1.URIScheme	(Optional) Designates the protocol used to make the request, such as HTTP or HTTPS. If not specified, HTTP is used by default.
method string	(Optional) Represents the type of HTTP request to be made, such as “GET,” “POST,” “PUT,” etc. If not specified, “GET” is the default method.
httpHeaders []Kubernetes core/v1.HTTPHeader	(Optional) Allows for the inclusion of custom headers in the request. HTTP permits the use of repeated headers.

HorizontalScalePolicy

(Appears on:ClusterComponentDefinition)

HorizontalScalePolicy is deprecated since v0.8.

Field	Description
type HScaleDataClonePolicyType	(Optional) Determines the data synchronization method when a component scales out. The policy can be one of the following: {None, CloneVolume}. The default policy is None. None: This is the default policy. It creates an empty volume without data cloning. CloneVolume: This policy clones data to newly scaled pods. It first tries to use a volume snapshot. If volume snapshot is not enabled, it will attempt to use a backup tool. If neither method works, it will report an error. Snapshot: This policy is deprecated and is an alias for CloneVolume.
backupPolicyTemplateName string	(Optional) Refers to the backup policy template.
volumeMountsName string	(Optional) Specifies the volumeMount of the container to backup. This only works if Type is not None. If not specified, the first volumeMount will be selected.

HostNetwork

(Appears on:ComponentDefinitionSpec)

Field	Description
containerPorts []HostNetworkContainerPort	(Optional) The list of container ports that are required by the component.

HostNetworkContainerPort

(Appears on:HostNetwork)

Field	Description
container string	Container specifies the target container within the Pod.
ports []string	Ports are named container ports within the specified container. These container ports must be defined in the container for proper port allocation.

HostNetworkVarSelector

(Appears on:VarSource)

HostNetworkVarSelector selects a var from host-network resources.

Field	Description
ClusterObjectReference ClusterObjectReference	(Members of ClusterObjectReference are embedded into this type.) The component to select from.
HostNetworkVars HostNetworkVars	(Members of HostNetworkVars are embedded into this type.)

HostNetworkVars

(Appears on:HostNetworkVarSelector)

HostNetworkVars defines the vars that can be referenced from host-network resources.

Field	Description
container ContainerVars	(Optional)

InstanceTemplate

(Appears on:ClusterComponentSpec, ComponentSpec)

InstanceTemplate allows customization of individual replica configurations in a Component.

Field	Description
name string	Name specifies the unique name of the instance Pod created using this InstanceTemplate. This name is constructed by concatenating the Component’s name, the template’s name, and the instance’s ordinal using the pattern: $(cluster.name)-$(component.name)-$(template.name)-$(ordinal). Ordinals start from 0. The specified name overrides any default naming conventions or patterns.
replicas int32	(Optional) Specifies the number of instances (Pods) to create from this InstanceTemplate. This field allows setting how many replicated instances of the Component, with the specific overrides in the InstanceTemplate, are created. The default value is 1. A value of 0 disables instance creation.
annotations map[string]string	(Optional) Specifies a map of key-value pairs to be merged into the Pod’s existing annotations. Existing keys will have their values overwritten, while new keys will be added to the annotations.
labels map[string]string	(Optional) Specifies a map of key-value pairs that will be merged into the Pod’s existing labels. Values for existing keys will be overwritten, and new keys will be added.
image string	(Optional) Specifies an override for the first container’s image in the Pod.
schedulingPolicy SchedulingPolicy	(Optional) Specifies the scheduling policy for the Component.
resources Kubernetes core/v1.ResourceRequirements	(Optional) Specifies an override for the resource requirements of the first container in the Pod. This field allows for customizing resource allocation (CPU, memory, etc.) for the container.
env []Kubernetes core/v1.EnvVar	(Optional) Defines Env to override. Add new or override existing envs.
volumes []Kubernetes core/v1.Volume	(Optional) Defines Volumes to override. Add new or override existing volumes.
volumeMounts []Kubernetes core/v1.VolumeMount	(Optional) Defines VolumeMounts to override. Add new or override existing volume mounts of the first container in the Pod.
volumeClaimTemplates []ClusterComponentVolumeClaimTemplate	(Optional) Defines VolumeClaimTemplates to override. Add new or override existing volume claim templates.

InstanceUpdateStrategy

(Appears on:ClusterComponentSpec, ComponentSpec)

InstanceUpdateStrategy indicates the strategy that the InstanceSet controller will use to perform updates.

Field	Description
partition int32	(Optional) Partition indicates the number of pods that should be updated during a rolling update. The remaining pods will remain untouched. This is helpful in defining how many pods should participate in the update process. The update process will follow the order of pod names in descending lexicographical (dictionary) order. The default value is ComponentSpec.Replicas (i.e., update all pods).
maxUnavailable Kubernetes api utils intstr.IntOrString	(Optional) The maximum number of pods that can be unavailable during the update. Value can be an absolute number (ex: 5) or a percentage of desired pods (ex: 10%). Absolute number is calculated from percentage by rounding up. This can not be 0. Defaults to 1. The field applies to all pods. That means if there is any unavailable pod, it will be counted towards MaxUnavailable.

Issuer

(Appears on:ClusterComponentSpec, TLSConfig)

Issuer defines the TLS certificates issuer for the Cluster.

Field	Description
name IssuerName	The issuer for TLS certificates. It only allows two enum values: KubeBlocks and UserProvided. KubeBlocks indicates that the self-signed TLS certificates generated by the KubeBlocks Operator will be used. UserProvided means that the user is responsible for providing their own CA, Cert, and Key. In this case, the user-provided CA certificate, server certificate, and private key will be used for TLS communication.
secretRef TLSSecretRef	(Optional) SecretRef is the reference to the secret that contains user-provided certificates. It is required when the issuer is set to UserProvided.

IssuerName (string alias)

(Appears on:Issuer)

IssuerName defines the name of the TLS certificates issuer.

Value	Description
"KubeBlocks"	IssuerKubeBlocks represents certificates that are signed by the KubeBlocks Operator.
"UserProvided"	IssuerUserProvided indicates that the user has provided their own CA-signed certificates.

LegacyRenderedTemplateSpec

(Appears on:ComponentConfigSpec)

LegacyRenderedTemplateSpec describes the configuration extension for the lazy rendered template. Deprecated: LegacyRenderedTemplateSpec has been deprecated since 0.9.0 and will be removed in 0.10.0

Field	Description
ConfigTemplateExtension ConfigTemplateExtension	(Members of ConfigTemplateExtension are embedded into this type.) Extends the configuration template.

LetterCase (string alias)

(Appears on:PasswordConfig)

LetterCase defines the available cases to be used in password generation.

Value	Description
"LowerCases"	LowerCases represents the use of lower case letters only.
"MixedCases"	MixedCases represents the use of a mix of both lower and upper case letters.
"UpperCases"	UpperCases represents the use of upper case letters only.

LifecycleActionHandler

(Appears on:ComponentLifecycleActions, RoleProbe)

LifecycleActionHandler describes the implementation of a specific lifecycle action.

Each action is deemed successful if it returns an exit code of 0 for command executions, or an HTTP 200 status for HTTP(s) actions. Any other exit code or HTTP status is considered an indication of failure.

Field	Description
builtinHandler BuiltinActionHandlerType	(Optional) Specifies the name of the predefined action handler to be invoked for lifecycle actions. Lorry, as a sidecar agent co-located with the database container in the same Pod, includes a suite of built-in action implementations that are tailored to different database engines. These are known as “builtin” handlers, includes: mysql, redis, mongodb, etcd, postgresql, vanilla-postgresql, apecloud-postgresql, wesql, oceanbase, polardbx. If the builtinHandler field is specified, it instructs Lorry to utilize its internal built-in action handler to execute the specified lifecycle actions. The builtinHandler field is of type BuiltinActionHandlerType, which represents the name of the built-in handler. The builtinHandler specified within the same ComponentLifecycleActions should be consistent across all actions. This means that if you specify a built-in handler for one action, you should use the same handler for all other actions throughout the entire ComponentLifecycleActions collection. If you need to define lifecycle actions for database engines not covered by the existing built-in support, or when the pre-existing built-in handlers do not meet your specific needs, you can use the customHandler field to define your own action implementation. Deprecation Notice: In the future, the builtinHandler field will be deprecated in favor of using the customHandler field for configuring all lifecycle actions. Instead of using a name to indicate the built-in action implementations in Lorry, the recommended approach will be to explicitly invoke the desired action implementation through a gRPC interface exposed by the sidecar agent. Developers will have the flexibility to either use the built-in action implementations provided by Lorry or develop their own sidecar agent to implement custom actions and expose them via gRPC interfaces. This change will allow for greater customization and extensibility of lifecycle actions, as developers can create their own “builtin” implementations tailored to their specific requirements.
customHandler Action	(Optional) Specifies a user-defined hook or procedure that is called to perform the specific lifecycle action. It offers a flexible and expandable approach for customizing the behavior of a Component by leveraging tailored actions. An Action can be implemented as either an ExecAction or an HTTPAction, with future versions planning to support GRPCAction, thereby accommodating unique logic for different database systems within the Action’s framework. In future iterations, all built-in handlers are expected to transition to GRPCAction. This change means that Lorry or other sidecar agents will expose the implementation of actions through a GRPC interface for external invocation. Then the controller will interact with these actions via GRPCAction calls.

LogConfig

(Appears on:ClusterComponentDefinition, ComponentDefinitionSpec)

Field	Description
name string	Specifies a descriptive label for the log type, such as ‘slow’ for a MySQL slow log file. It provides a clear identification of the log’s purpose and content.
filePathPattern string	Specifies the paths or patterns identifying where the log files are stored. This field allows the system to locate and manage log files effectively. Examples: /home/postgres/pgdata/pgroot/data/log/postgresql-* /data/mysql/log/mysqld-error.log

MergedPolicy (string alias)

(Appears on:ConfigTemplateExtension)

MergedPolicy defines how to merge external imported templates into component templates.

Value	Description
"none"
"add"
"patch"
"replace"

MonitorConfig

(Appears on:ClusterComponentDefinition, ComponentDefinitionSpec)

Field	Description
builtIn bool	(Optional) builtIn is a switch to enable KubeBlocks builtIn monitoring. If BuiltIn is set to true, monitor metrics will be scraped automatically. If BuiltIn is set to false, the provider should set ExporterConfig and Sidecar container own.
exporterConfig ExporterConfig	(Optional) exporterConfig provided by provider, which specify necessary information to Time Series Database. exporterConfig is valid when builtIn is false.

MultipleClusterObjectCombinedOption

(Appears on:MultipleClusterObjectOption)

MultipleClusterObjectCombinedOption defines options for handling combined variables.

Field	Description
newVarSuffix string	(Optional) If set, the existing variable will be kept, and a new variable will be defined with the specified suffix in pattern: $(var.name)_$(suffix). The new variable will be auto-created and placed behind the existing one. If not set, the existing variable will be reused with the value format defined below.
valueFormat MultipleClusterObjectValueFormat	(Optional) The format of the value that the operator will use to compose values from multiple components.
flattenFormat MultipleClusterObjectValueFormatFlatten	(Optional) The flatten format, default is: $(comp-name-1):value,$(comp-name-2):value.

MultipleClusterObjectOption

(Appears on:ClusterObjectReference)

MultipleClusterObjectOption defines the options for handling multiple cluster objects matched.

Field	Description
strategy MultipleClusterObjectStrategy	Define the strategy for handling multiple cluster objects.
combinedOption MultipleClusterObjectCombinedOption	(Optional) Define the options for handling combined variables. Valid only when the strategy is set to “combined”.

MultipleClusterObjectStrategy (string alias)

(Appears on:MultipleClusterObjectOption)

MultipleClusterObjectStrategy defines the strategy for handling multiple cluster objects.

Value	Description
"combined"	MultipleClusterObjectStrategyCombined - the values from all matched components will be combined into a single variable using the specified option.
"individual"	MultipleClusterObjectStrategyIndividual - each matched component will have its individual variable with its name as the suffix. This is required when referencing credential variables that cannot be passed by values.

MultipleClusterObjectValueFormat (string alias)

(Appears on:MultipleClusterObjectCombinedOption)

MultipleClusterObjectValueFormat defines the format details for the value.

Value	Description
"Flatten"

MultipleClusterObjectValueFormatFlatten

(Appears on:MultipleClusterObjectCombinedOption)

MultipleClusterObjectValueFormatFlatten defines the flatten format for the value.

Field	Description
delimiter string	Pair delimiter.
keyValueDelimiter string	Key-value delimiter.

NamedVar

(Appears on:ContainerVars, ServiceVars)

Field	Description
name string	(Optional)
option VarOption	(Optional)

PasswordConfig

(Appears on:ComponentSystemAccount, SystemAccount, SystemAccountSpec)

PasswordConfig helps provide to customize complexity of password generation pattern.

Field	Description
length int32	(Optional) The length of the password.
numDigits int32	(Optional) The number of digits in the password.
numSymbols int32	(Optional) The number of symbols in the password.
letterCase LetterCase	(Optional) The case of the letters in the password.
seed string	(Optional) Seed to generate the account’s password. Cannot be updated.

Payload

(Appears on:ConfigurationItemDetail)

Field	Description
- map[string]any	(Optional) Holds the payload data. This field is optional and can contain any type of data. Not included in the JSON representation of the object.

PersistentVolumeClaimSpec

(Appears on:ClusterComponentVolumeClaimTemplate)

Field	Description
accessModes []Kubernetes core/v1.PersistentVolumeAccessMode	(Optional) Contains the desired access modes the volume should have. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#access-modes-1.
resources Kubernetes core/v1.VolumeResourceRequirements	(Optional) Represents the minimum resources the volume should have. If the RecoverVolumeExpansionFailure feature is enabled, users are allowed to specify resource requirements that are lower than the previous value but must still be higher than the capacity recorded in the status field of the claim. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#resources.
storageClassName string	(Optional) The name of the StorageClass required by the claim. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#class-1.
volumeMode Kubernetes core/v1.PersistentVolumeMode	(Optional) Defines what type of volume is required by the claim, either Block or Filesystem.

Phase (string alias)

(Appears on:ClusterDefinitionStatus, ComponentDefinitionStatus, ComponentVersionStatus, ServiceDescriptorStatus)

Phase represents the current status of the ClusterDefinition CR.

Value	Description
"Available"	AvailablePhase indicates that the object is in an available state.
"Unavailable"	UnavailablePhase indicates that the object is in an unavailable state.

PodAntiAffinity (string alias)

(Appears on:Affinity)

PodAntiAffinity defines the pod anti-affinity strategy.

This strategy determines how pods are scheduled in relation to other pods, with the aim of either spreading pods across nodes (Preferred) or ensuring that certain pods do not share a node (Required).

Value	Description
"Preferred"	Preferred indicates that the scheduler will try to enforce the anti-affinity rules, but it will not guarantee it.
"Required"	Required indicates that the scheduler must enforce the anti-affinity rules and will not schedule the pods unless the rules are met.

PodAvailabilityPolicy (string alias)

PodAvailabilityPolicy pod availability strategy.

Value	Description
"Available"
"None"
"UnAvailable"

PostStartAction

(Appears on:ClusterComponentDefinition)

PostStartAction is deprecated since v0.8.

Field	Description
cmdExecutorConfig CmdExecutorConfig	Specifies the post-start command to be executed.
scriptSpecSelectors []ScriptSpecSelector	(Optional) Used to select the script that need to be referenced. When defined, the scripts defined in scriptSpecs can be referenced within the CmdExecutorConfig.

PreConditionType (string alias)

(Appears on:Action)

PreConditionType defines the preCondition type of the action execution.

Value	Description
"ClusterReady"
"ComponentReady"
"Immediately"
"RuntimeReady"

Probe

Field	Description
Action Action	(Members of Action are embedded into this type.)
initialDelaySeconds int32	(Optional) Specifies the number of seconds to wait after the container has started before the RoleProbe begins to detect the container’s role.
periodSeconds int32	(Optional) Specifies the frequency at which the probe is conducted. This value is expressed in seconds. Default to 10 seconds. Minimum value is 1.
successThreshold int32	(Optional) Minimum consecutive successes for the probe to be considered successful after having failed. Defaults to 1. Minimum value is 1.
failureThreshold int32	(Optional) Minimum consecutive failures for the probe to be considered failed after having succeeded. Defaults to 3. Minimum value is 1.

PrometheusScheme (string alias)

(Appears on:Exporter)

PrometheusScheme defines the protocol of prometheus scrape metrics.

Value	Description
"http"
"https"

ProtectedVolume

(Appears on:VolumeProtectionSpec)

Field	Description
name string	(Optional) The Name of the volume to protect.
highWatermark int	(Optional) Defines the high watermark threshold for the volume, it will override the component level threshold. If the value is invalid, it will be ignored and the component level threshold will be used.

ProvisionPolicy

(Appears on:SystemAccountConfig)

ProvisionPolicy defines the policy details for creating accounts.

Deprecated since v0.9.

Field	Description
type ProvisionPolicyType	Specifies the method to provision an account.
scope ProvisionScope	Defines the scope within which the account is provisioned.
statements ProvisionStatements	(Optional) The statement to provision an account.
secretRef ProvisionSecretRef	(Optional) The external secret to refer.

ProvisionPolicyType (string alias)

(Appears on:ProvisionPolicy)

ProvisionPolicyType defines the policy for creating accounts.

Value	Description
"CreateByStmt"	CreateByStmt will create account w.r.t. deletion and creation statement given by provider.
"ReferToExisting"	ReferToExisting will not create account, but create a secret by copying data from referred secret file.

ProvisionScope (string alias)

(Appears on:ProvisionPolicy)

ProvisionScope defines the scope of provision within a component.

Value	Description
"AllPods"	AllPods indicates that accounts will be created for all pods within the component.
"AnyPods"	AnyPods indicates that accounts will be created only on a single pod within the component.

ProvisionSecretRef

(Appears on:ComponentSystemAccount, ProvisionPolicy, SystemAccount)

ProvisionSecretRef represents the reference to a secret.

Field	Description
name string	The unique identifier of the secret.
namespace string	The namespace where the secret is located.

ProvisionStatements

(Appears on:ProvisionPolicy)

ProvisionStatements defines the statements used to create accounts.

Deprecated since v0.9.

Field	Description
creation string	Specifies the statement required to create a new account with the necessary privileges.
update string	(Optional) Defines the statement required to update the password of an existing account.
deletion string	(Optional) Defines the statement required to delete an existing account. Typically used in conjunction with the creation statement to delete an account before recreating it. For example, one might use a drop user if exists statement followed by a create user statement to ensure a fresh account. Deprecated: This field is deprecated and the update statement should be used instead.

RSMSpec

(Appears on:ClusterComponentDefinition)

RSMSpec is deprecated since v0.8.

Field	Description
roles []ReplicaRole	(Optional) Specifies a list of roles defined within the system.
roleProbe RoleProbe	(Optional) Defines the method used to probe a role.
membershipReconfiguration MembershipReconfiguration	(Optional) Indicates the actions required for dynamic membership reconfiguration.
memberUpdateStrategy MemberUpdateStrategy	(Optional) Describes the strategy for updating Members (Pods). Serial: Updates Members sequentially to ensure minimum component downtime. BestEffortParallel: Updates Members in parallel to ensure minimum component write downtime. Parallel: Forces parallel updates.

ReconcileDetail

(Appears on:ConfigurationItemDetailStatus)

Field	Description
policy string	(Optional) Represents the policy applied during the most recent execution.
execResult string	(Optional) Represents the outcome of the most recent execution.
currentRevision string	(Optional) Represents the current revision of the configuration item.
succeedCount int32	(Optional) Represents the number of pods where configuration changes were successfully applied.
expectedCount int32	(Optional) Represents the total number of pods that require execution of configuration changes.
errMessage string	(Optional) Represents the error message generated when the execution of configuration changes fails.

ReloadOptions

(Appears on:ConfigConstraintSpec)

ReloadOptions defines the mechanisms available for dynamically reloading a process within K8s without requiring a restart.

Only one of the mechanisms can be specified at a time.

Field	Description
unixSignalTrigger UnixSignalTrigger	(Optional) Used to trigger a reload by sending a specific Unix signal to the process.
shellTrigger ShellTrigger	(Optional) Allows to execute a custom shell script to reload the process.
tplScriptTrigger TPLScriptTrigger	(Optional) Enables reloading process using a Go template script.
autoTrigger AutoTrigger	(Optional) Automatically perform the reload when specified conditions are met.

ReplicaRole

(Appears on:ComponentDefinitionSpec)

ReplicaRole represents a role that can be assumed by a component instance.

Field	Description
name string	Defines the role’s identifier. It is used to set the “apps.kubeblocks.io/role” label value on the corresponding object. This field is immutable once set.
serviceable bool	(Optional) Indicates whether a replica assigned this role is capable of providing services. This field is immutable once set.
writable bool	(Optional) Determines if a replica in this role has the authority to perform write operations. A writable replica can modify data, handle update operations. This field is immutable once set.
votable bool	(Optional) Specifies whether a replica with this role has voting rights. In distributed systems, this typically means the replica can participate in consensus decisions, configuration changes, or other processes that require a quorum. This field is immutable once set.

ReplicasLimit

(Appears on:ComponentDefinitionSpec)

ReplicasLimit defines the valid range of number of replicas supported.

Field	Description
minReplicas int32	The minimum limit of replicas.
maxReplicas int32	The maximum limit of replicas.

ReplicationSetSpec

(Appears on:ClusterComponentDefinition)

ReplicationSetSpec is deprecated since v0.7.

Field	Description
StatefulSetSpec StatefulSetSpec	(Members of StatefulSetSpec are embedded into this type.)

RerenderResourceType (string alias)

(Appears on:ComponentConfigSpec)

RerenderResourceType defines the resource requirements for a component.

Value	Description
"hscale"
"vscale"

ResourceMeta

(Appears on:ConfigMapRef, SecretRef)

ResourceMeta encapsulates metadata and configuration for referencing ConfigMaps and Secrets as volumes.

Field	Description
name string	Name is the name of the referenced ConfigMap or Secret object. It must conform to DNS label standards.
mountPoint string	MountPoint is the filesystem path where the volume will be mounted.
subPath string	(Optional) SubPath specifies a path within the volume from which to mount.
asVolumeFrom []string	(Optional) AsVolumeFrom lists the names of containers in which the volume should be mounted.

RetryPolicy

(Appears on:Action)

Field	Description
maxRetries int	(Optional) Defines the maximum number of retry attempts that should be made for a given Action. This value is set to 0 by default, indicating that no retries will be made.
retryInterval time.Duration	(Optional) Indicates the duration of time to wait between each retry attempt. This value is set to 0 by default, indicating that there will be no delay between retry attempts.

RoleArbitrator (string alias)

(Appears on:ComponentDefinitionSpec)

RoleArbitrator defines how to arbitrate the role of replicas.

Deprecated since v0.9

Value	Description
"External"
"Lorry"

RoleProbe

(Appears on:ComponentLifecycleActions)

Field	Description
LifecycleActionHandler LifecycleActionHandler	(Members of LifecycleActionHandler are embedded into this type.)
initialDelaySeconds int32	(Optional) Specifies the number of seconds to wait after the container has started before the RoleProbe begins to detect the container’s role.
timeoutSeconds int32	(Optional) Specifies the number of seconds after which the probe times out. Defaults to 1 second. Minimum value is 1.
periodSeconds int32	(Optional) Specifies the frequency at which the probe is conducted. This value is expressed in seconds. Default to 10 seconds. Minimum value is 1.

SchedulingPolicy

(Appears on:ClusterComponentSpec, ClusterSpec, ComponentSpec, InstanceTemplate)

Field	Description
schedulerName string	(Optional) If specified, the Pod will be dispatched by specified scheduler. If not specified, the Pod will be dispatched by default scheduler.
nodeSelector map[string]string	(Optional) NodeSelector is a selector which must be true for the Pod to fit on a node. Selector which must match a node’s labels for the Pod to be scheduled on that node. More info: https://kubernetes.io/docs/concepts/configuration/assign-pod-node/
nodeName string	(Optional) NodeName is a request to schedule this Pod onto a specific node. If it is non-empty, the scheduler simply schedules this Pod onto that node, assuming that it fits resource requirements.
affinity Kubernetes core/v1.Affinity	(Optional) Specifies a group of affinity scheduling rules of the Cluster, including NodeAffinity, PodAffinity, and PodAntiAffinity.
tolerations []Kubernetes core/v1.Toleration	(Optional) Allows Pods to be scheduled onto nodes with matching taints. Each toleration in the array allows the Pod to tolerate node taints based on specified key, value, effect, and operator. The key, value, and effect identify the taint that the toleration matches. The operator determines how the toleration matches the taint. Pods with matching tolerations are allowed to be scheduled on tainted nodes, typically reserved for specific purposes.
topologySpreadConstraints []Kubernetes core/v1.TopologySpreadConstraint	(Optional) TopologySpreadConstraints describes how a group of Pods ought to spread across topology domains. Scheduler will schedule Pods in a way which abides by the constraints. All topologySpreadConstraints are ANDed.

ScriptSpecSelector

(Appears on:ComponentSwitchover, PostStartAction, SwitchoverAction)

Field	Description
name string	Represents the name of the ScriptSpec referent.

SecretRef

(Appears on:UserResourceRefs)

SecretRef defines a reference to a Secret.

Field	Description
ResourceMeta ResourceMeta	(Members of ResourceMeta are embedded into this type.)
secret Kubernetes core/v1.SecretVolumeSource	Secret specifies the Secret to be mounted as a volume.

Service

(Appears on:ClusterService, ComponentService)

Field	Description
name string	Name defines the name of the service. otherwise, it indicates the name of the service. Others can refer to this service by its name. (e.g., connection credential) Cannot be updated.
serviceName string	(Optional) ServiceName defines the name of the underlying service object. If not specified, the default service name with different patterns will be used: CLUSTER_NAME: for cluster-level services CLUSTER_NAME-COMPONENT_NAME: for component-level services Only one default service name is allowed. Cannot be updated.
annotations map[string]string	(Optional) If ServiceType is LoadBalancer, cloud provider related parameters can be put here More info: https://kubernetes.io/docs/concepts/services-networking/service/#loadbalancer.
spec Kubernetes core/v1.ServiceSpec	(Optional) Spec defines the behavior of a service. https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status ports []Kubernetes core/v1.ServicePort The list of ports that are exposed by this service. More info: https://kubernetes.io/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies selector map[string]string (Optional) Route service traffic to pods with label keys and values matching this selector. If empty or not present, the service is assumed to have an external process managing its endpoints, which Kubernetes will not modify. Only applies to types ClusterIP, NodePort, and LoadBalancer. Ignored if type is ExternalName. More info: https://kubernetes.io/docs/concepts/services-networking/service/ clusterIP string (Optional) clusterIP is the IP address of the service and is usually assigned randomly. If an address is specified manually, is in-range (as per system configuration), and is not in use, it will be allocated to the service; otherwise creation of the service will fail. This field may not be changed through updates unless the type field is also being changed to ExternalName (which requires this field to be blank) or the type field is being changed from ExternalName (in which case this field may optionally be specified, as describe above). Valid values are “None”, empty string (“”), or a valid IP address. Setting this to “None” makes a “headless service” (no virtual IP), which is useful when direct endpoint connections are preferred and proxying is not required. Only applies to types ClusterIP, NodePort, and LoadBalancer. If this field is specified when creating a Service of type ExternalName, creation will fail. This field will be wiped when updating a Service to type ExternalName. More info: https://kubernetes.io/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies clusterIPs []string (Optional) ClusterIPs is a list of IP addresses assigned to this service, and are usually assigned randomly. If an address is specified manually, is in-range (as per system configuration), and is not in use, it will be allocated to the service; otherwise creation of the service will fail. This field may not be changed through updates unless the type field is also being changed to ExternalName (which requires this field to be empty) or the type field is being changed from ExternalName (in which case this field may optionally be specified, as describe above). Valid values are “None”, empty string (“”), or a valid IP address. Setting this to “None” makes a “headless service” (no virtual IP), which is useful when direct endpoint connections are preferred and proxying is not required. Only applies to types ClusterIP, NodePort, and LoadBalancer. If this field is specified when creating a Service of type ExternalName, creation will fail. This field will be wiped when updating a Service to type ExternalName. If this field is not specified, it will be initialized from the clusterIP field. If this field is specified, clients must ensure that clusterIPs[0] and clusterIP have the same value. This field may hold a maximum of two entries (dual-stack IPs, in either order). These IPs must correspond to the values of the ipFamilies field. Both clusterIPs and ipFamilies are governed by the ipFamilyPolicy field. More info: https://kubernetes.io/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies type Kubernetes core/v1.ServiceType (Optional) type determines how the Service is exposed. Defaults to ClusterIP. Valid options are ExternalName, ClusterIP, NodePort, and LoadBalancer. “ClusterIP” allocates a cluster-internal IP address for load-balancing to endpoints. Endpoints are determined by the selector or if that is not specified, by manual construction of an Endpoints object or EndpointSlice objects. If clusterIP is “None”, no virtual IP is allocated and the endpoints are published as a set of endpoints rather than a virtual IP. “NodePort” builds on ClusterIP and allocates a port on every node which routes to the same endpoints as the clusterIP. “LoadBalancer” builds on NodePort and creates an external load-balancer (if supported in the current cloud) which routes to the same endpoints as the clusterIP. “ExternalName” aliases this service to the specified externalName. Several other fields do not apply to ExternalName services. More info: https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services-service-types externalIPs []string (Optional) externalIPs is a list of IP addresses for which nodes in the cluster will also accept traffic for this service. These IPs are not managed by Kubernetes. The user is responsible for ensuring that traffic arrives at a node with this IP. A common example is external load-balancers that are not part of the Kubernetes system. sessionAffinity Kubernetes core/v1.ServiceAffinity (Optional) Supports “ClientIP” and “None”. Used to maintain session affinity. Enable client IP based session affinity. Must be ClientIP or None. Defaults to None. More info: https://kubernetes.io/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies loadBalancerIP string (Optional) Only applies to Service Type: LoadBalancer. This feature depends on whether the underlying cloud-provider supports specifying the loadBalancerIP when a load balancer is created. This field will be ignored if the cloud-provider does not support the feature. Deprecated: This field was under-specified and its meaning varies across implementations. Using it is non-portable and it may not support dual-stack. Users are encouraged to use implementation-specific annotations when available. loadBalancerSourceRanges []string (Optional) If specified and supported by the platform, this will restrict traffic through the cloud-provider load-balancer will be restricted to the specified client IPs. This field will be ignored if the cloud-provider does not support the feature.” More info: https://kubernetes.io/docs/tasks/access-application-cluster/create-external-load-balancer/ externalName string (Optional) externalName is the external reference that discovery mechanisms will return as an alias for this service (e.g. a DNS CNAME record). No proxying will be involved. Must be a lowercase RFC-1123 hostname (https://tools.ietf.org/html/rfc1123) and requires type to be “ExternalName”. externalTrafficPolicy Kubernetes core/v1.ServiceExternalTrafficPolicy (Optional) externalTrafficPolicy describes how nodes distribute service traffic they receive on one of the Service’s “externally-facing” addresses (NodePorts, ExternalIPs, and LoadBalancer IPs). If set to “Local”, the proxy will configure the service in a way that assumes that external load balancers will take care of balancing the service traffic between nodes, and so each node will deliver traffic only to the node-local endpoints of the service, without masquerading the client source IP. (Traffic mistakenly sent to a node with no endpoints will be dropped.) The default value, “Cluster”, uses the standard behavior of routing to all endpoints evenly (possibly modified by topology and other features). Note that traffic sent to an External IP or LoadBalancer IP from within the cluster will always get “Cluster” semantics, but clients sending to a NodePort from within the cluster may need to take traffic policy into account when picking a node. healthCheckNodePort int32 (Optional) healthCheckNodePort specifies the healthcheck nodePort for the service. This only applies when type is set to LoadBalancer and externalTrafficPolicy is set to Local. If a value is specified, is in-range, and is not in use, it will be used. If not specified, a value will be automatically allocated. External systems (e.g. load-balancers) can use this port to determine if a given node holds endpoints for this service or not. If this field is specified when creating a Service which does not need it, creation will fail. This field will be wiped when updating a Service to no longer need it (e.g. changing type). This field cannot be updated once set. publishNotReadyAddresses bool (Optional) publishNotReadyAddresses indicates that any agent which deals with endpoints for this Service should disregard any indications of ready/not-ready. The primary use case for setting this field is for a StatefulSet’s Headless Service to propagate SRV DNS records for its Pods for the purpose of peer discovery. The Kubernetes controllers that generate Endpoints and EndpointSlice resources for Services interpret this to mean that all endpoints are considered “ready” even if the Pods themselves are not. Agents which consume only Kubernetes generated endpoints through the Endpoints or EndpointSlice resources can safely assume this behavior. sessionAffinityConfig Kubernetes core/v1.SessionAffinityConfig (Optional) sessionAffinityConfig contains the configurations of session affinity. ipFamilies []Kubernetes core/v1.IPFamily (Optional) IPFamilies is a list of IP families (e.g. IPv4, IPv6) assigned to this service. This field is usually assigned automatically based on cluster configuration and the ipFamilyPolicy field. If this field is specified manually, the requested family is available in the cluster, and ipFamilyPolicy allows it, it will be used; otherwise creation of the service will fail. This field is conditionally mutable: it allows for adding or removing a secondary IP family, but it does not allow changing the primary IP family of the Service. Valid values are “IPv4” and “IPv6”. This field only applies to Services of types ClusterIP, NodePort, and LoadBalancer, and does apply to “headless” services. This field will be wiped when updating a Service to type ExternalName. This field may hold a maximum of two entries (dual-stack families, in either order). These families must correspond to the values of the clusterIPs field, if specified. Both clusterIPs and ipFamilies are governed by the ipFamilyPolicy field. ipFamilyPolicy Kubernetes core/v1.IPFamilyPolicy (Optional) IPFamilyPolicy represents the dual-stack-ness requested or required by this Service. If there is no value provided, then this field will be set to SingleStack. Services can be “SingleStack” (a single IP family), “PreferDualStack” (two IP families on dual-stack configured clusters or a single IP family on single-stack clusters), or “RequireDualStack” (two IP families on dual-stack configured clusters, otherwise fail). The ipFamilies and clusterIPs fields depend on the value of this field. This field will be wiped when updating a service to type ExternalName. allocateLoadBalancerNodePorts bool (Optional) allocateLoadBalancerNodePorts defines if NodePorts will be automatically allocated for services with type LoadBalancer. Default is “true”. It may be set to “false” if the cluster load-balancer does not rely on NodePorts. If the caller requests specific NodePorts (by specifying a value), those requests will be respected, regardless of this field. This field may only be set for services with type LoadBalancer and will be cleared if the type is changed to any other type. loadBalancerClass string (Optional) loadBalancerClass is the class of the load balancer implementation this Service belongs to. If specified, the value of this field must be a label-style identifier, with an optional prefix, e.g. “internal-vip” or “example.com/internal-vip”. Unprefixed names are reserved for end-users. This field can only be set when the Service type is ‘LoadBalancer’. If not set, the default load balancer implementation is used, today this is typically done through the cloud provider integration, but should apply for any default implementation. If set, it is assumed that a load balancer implementation is watching for Services with a matching class. Any default load balancer implementation (e.g. cloud providers) should ignore Services that set this field. This field can only be set when creating or updating a Service to type ‘LoadBalancer’. Once set, it can not be changed. This field will be wiped when a service is updated to a non ‘LoadBalancer’ type. internalTrafficPolicy Kubernetes core/v1.ServiceInternalTrafficPolicy (Optional) InternalTrafficPolicy describes how nodes distribute service traffic they receive on the ClusterIP. If set to “Local”, the proxy will assume that pods only want to talk to endpoints of the service on the same node as the pod, dropping the traffic if there are no local endpoints. The default value, “Cluster”, uses the standard behavior of routing to all endpoints evenly (possibly modified by topology and other features).
roleSelector string	(Optional) Extends the above serviceSpec.selector by allowing you to specify defined role as selector for the service. When roleSelector is set, it adds a label selector “kubeblocks.io/role: {roleSelector}” to the serviceSpec.selector. Example usage: roleSelector: "leader" In this example, setting roleSelector to “leader” will add a label selector “kubeblocks.io/role: leader” to the serviceSpec.selector. This means that the service will select and route traffic to Pods with the label “kubeblocks.io/role” set to “leader”. Note that if podService sets to true, RoleSelector will be ignored. The podService flag takes precedence over roleSelector and generates a service for each Pod.

ServiceDescriptorSpec

(Appears on:ServiceDescriptor)

ServiceDescriptorSpec defines the desired state of ServiceDescriptor.

Field	Description
serviceKind string	Describes the type of database service provided by the external service. For example, “mysql”, “redis”, “mongodb”. This field categorizes databases by their functionality, protocol and compatibility, facilitating appropriate service integration based on their unique capabilities. This field is case-insensitive. It also supports abbreviations for some well-known databases: “pg”, “pgsql”, “postgres”, “postgresql”: PostgreSQL service “zk”, “zookeeper”: ZooKeeper service “es”, “elasticsearch”: Elasticsearch service “mongo”, “mongodb”: MongoDB service “ch”, “clickhouse”: ClickHouse service
serviceVersion string	Describes the version of the service provided by the external service. This is crucial for ensuring compatibility between different components of the system, as different versions of a service may have varying features.
endpoint CredentialVar	(Optional) Specifies the endpoint of the external service. If the service is exposed via a cluster, the endpoint will be provided in the format of host:port.
host CredentialVar	(Optional) Specifies the service or IP address of the external service.
port CredentialVar	(Optional) Specifies the port of the external service.
auth ConnectionCredentialAuth	(Optional) Specifies the authentication credentials required for accessing an external service.

ServiceDescriptorStatus

(Appears on:ServiceDescriptor)

ServiceDescriptorStatus defines the observed state of ServiceDescriptor

Field	Description
phase Phase	(Optional) Indicates the current lifecycle phase of the ServiceDescriptor. This can be either ‘Available’ or ‘Unavailable’.
message string	(Optional) Provides a human-readable explanation detailing the reason for the current phase of the ServiceConnectionCredential.
observedGeneration int64	(Optional) Represents the generation number that has been processed by the controller.

ServicePort

(Appears on:ServiceSpec)

ServicePort is deprecated since v0.8.

Field	Description
name string	The name of this port within the service. This must be a DNS_LABEL. All ports within a ServiceSpec must have unique names. When considering the endpoints for a Service, this must match the ‘name’ field in the EndpointPort.
protocol Kubernetes core/v1.Protocol	(Optional) The IP protocol for this port. Supports “TCP”, “UDP”, and “SCTP”. Default is TCP.
appProtocol string	(Optional) The application protocol for this port. This field follows standard Kubernetes label syntax. Un-prefixed names are reserved for IANA standard service names (as per RFC-6335 and https://www.iana.org/assignments/service-names). Non-standard protocols should use prefixed names such as mycompany.com/my-custom-protocol.
port int32	The port that will be exposed by this service.
targetPort Kubernetes api utils intstr.IntOrString	(Optional) Number or name of the port to access on the pods targeted by the service. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME. If this is a string, it will be looked up as a named port in the target Pod’s container ports. If this is not specified, the value of the port field is used (an identity map). This field is ignored for services with clusterIP=None, and should be omitted or set equal to the port field. More info: https://kubernetes.io/docs/concepts/services-networking/service/#defining-a-service

ServiceRef

(Appears on:ClusterComponentSpec, ComponentSpec)

Field	Description
name string	Specifies the identifier of the service reference declaration. It corresponds to the serviceRefDeclaration name defined in either: componentDefinition.spec.serviceRefDeclarations[*].name clusterDefinition.spec.componentDefs[*].serviceRefDeclarations[*].name (deprecated)
namespace string	(Optional) Specifies the namespace of the referenced Cluster or the namespace of the referenced ServiceDescriptor object. If not provided, the referenced Cluster and ServiceDescriptor will be searched in the namespace of the current Cluster by default.
cluster string	(Optional) Specifies the name of the KubeBlocks Cluster being referenced. This is used when services from another KubeBlocks Cluster are consumed. By default, the referenced KubeBlocks Cluster’s clusterDefinition.spec.connectionCredential will be utilized to bind to the current Component. This credential should include: endpoint, port, username, and password. Note: The ServiceKind and ServiceVersion specified in the service reference within the ClusterDefinition are not validated when using this approach. If both cluster and serviceDescriptor are present, cluster will take precedence. Deprecated since v0.9 since clusterDefinition.spec.connectionCredential is deprecated, use clusterServiceSelector instead. This field is maintained for backward compatibility and its use is discouraged. Existing usage should be updated to the current preferred approach to avoid compatibility issues in future releases.
clusterServiceSelector ServiceRefClusterSelector	(Optional) References a service provided by another KubeBlocks Cluster. It specifies the ClusterService and the account credentials needed for access.
serviceDescriptor string	(Optional) Specifies the name of the ServiceDescriptor object that describes a service provided by external sources. When referencing a service provided by external sources, a ServiceDescriptor object is required to establish the service binding. The serviceDescriptor.spec.serviceKind and serviceDescriptor.spec.serviceVersion should match the serviceKind and serviceVersion declared in the definition. If both cluster and serviceDescriptor are specified, the cluster takes precedence.

ServiceRefClusterSelector

(Appears on:ServiceRef)

Field	Description
cluster string	The name of the Cluster being referenced.
service ServiceRefServiceSelector	(Optional) Identifies a ClusterService from the list of Services defined in cluster.spec.services of the referenced Cluster.
credential ServiceRefCredentialSelector	(Optional) Specifies the SystemAccount to authenticate and establish a connection with the referenced Cluster. The SystemAccount should be defined in componentDefinition.spec.systemAccounts of the Component providing the service in the referenced Cluster.

ServiceRefCredentialSelector

(Appears on:ServiceRefClusterSelector)

Field	Description
component string	The name of the Component where the credential resides in.
name string	The name of the credential (SystemAccount) to reference.

ServiceRefDeclaration

(Appears on:ClusterComponentDefinition, ComponentDefinitionSpec)

ServiceRefDeclaration represents a reference to a service that can be either provided by a KubeBlocks Cluster or an external service. It acts as a placeholder for the actual service reference, which is determined later when a Cluster is created.

The purpose of ServiceRefDeclaration is to declare a service dependency without specifying the concrete details of the service. It allows for flexibility and abstraction in defining service references within a Component. By using ServiceRefDeclaration, you can define service dependencies in a declarative manner, enabling loose coupling and easier management of service references across different components and clusters.

Upon Cluster creation, the ServiceRefDeclaration is bound to an actual service through the ServiceRef field, effectively resolving and connecting to the specified service.

Field	Description
name string	Specifies the name of the ServiceRefDeclaration.
serviceRefDeclarationSpecs []ServiceRefDeclarationSpec	Defines a list of constraints and requirements for services that can be bound to this ServiceRefDeclaration upon Cluster creation. Each ServiceRefDeclarationSpec defines a ServiceKind and ServiceVersion, outlining the acceptable service types and versions that are compatible. This flexibility allows a ServiceRefDeclaration to be fulfilled by any one of the provided specs. For example, if it requires an OLTP database, specs for both MySQL and PostgreSQL are listed, either MySQL or PostgreSQL services can be used when binding.
optional bool	(Optional) Specifies whether the service reference can be optional. For an optional service-ref, the component can still be created even if the service-ref is not provided.

ServiceRefDeclarationSpec

(Appears on:ServiceRefDeclaration)

Field	Description
serviceKind string	Specifies the type or nature of the service. This should be a well-known application cluster type, such as {mysql, redis, mongodb}. The field is case-insensitive and supports abbreviations for some well-known databases. For instance, both zk and zookeeper are considered as a ZooKeeper cluster, while pg, postgres, postgresql are all recognized as a PostgreSQL cluster.
serviceVersion string	Defines the service version of the service reference. This is a regular expression that matches a version number pattern. For instance, ^8.0.8$, 8.0.\d{1,2}$, ^[v\-]*?(\d{1,2}\.){0,3}\d{1,2}$ are all valid patterns.

ServiceRefServiceSelector

(Appears on:ServiceRefClusterSelector)

Field	Description
component string	(Optional) The name of the Component where the Service resides in. It is required when referencing a Component’s Service.
service string	The name of the Service to be referenced. Leave it empty to reference the default Service. Set it to “headless” to reference the default headless Service. If the referenced Service is of pod-service type (a Service per Pod), there will be multiple Service objects matched, and the resolved value will be presented in the following format: service1.name,service2.name…
port string	(Optional) The port name of the Service to be referenced. If there is a non-zero node-port exist for the matched Service port, the node-port will be selected first. If the referenced Service is of pod-service type (a Service per Pod), there will be multiple Service objects matched, and the resolved value will be presented in the following format: service1.name:port1,service2.name:port2…

ServiceRefVarSelector

(Appears on:VarSource)

ServiceRefVarSelector selects a var from a ServiceRefDeclaration.

Field	Description
ClusterObjectReference ClusterObjectReference	(Members of ClusterObjectReference are embedded into this type.) The ServiceRefDeclaration to select from.
ServiceRefVars ServiceRefVars	(Members of ServiceRefVars are embedded into this type.)

ServiceRefVars

(Appears on:ServiceRefVarSelector)

ServiceRefVars defines the vars that can be referenced from a ServiceRef.

Field	Description
endpoint VarOption	(Optional)
host VarOption	(Optional)
port VarOption	(Optional)
CredentialVars CredentialVars	(Members of CredentialVars are embedded into this type.)

ServiceSpec

(Appears on:ClusterComponentDefinition)

ServiceSpec is deprecated since v0.8.

Field	Description
ports []ServicePort	(Optional) The list of ports that are exposed by this service. More info: https://kubernetes.io/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies

ServiceVarSelector

(Appears on:VarSource)

ServiceVarSelector selects a var from a Service.

Field	Description
ClusterObjectReference ClusterObjectReference	(Members of ClusterObjectReference are embedded into this type.) The Service to select from. It can be referenced from the default headless service by setting the name to “headless”.
ServiceVars ServiceVars	(Members of ServiceVars are embedded into this type.)

ServiceVars

(Appears on:ServiceVarSelector)

ServiceVars defines the vars that can be referenced from a Service.

Field	Description
host VarOption	(Optional)
loadBalancer VarOption	(Optional) LoadBalancer represents the LoadBalancer ingress point of the service. If multiple ingress points are available, the first one will be used automatically, choosing between IP and Hostname.
port NamedVar	(Optional) Port references a port or node-port defined in the service. If the referenced service is a pod-service, there will be multiple service objects matched, and the value will be presented in the following format: service1.name:port1,service2.name:port2…

ShardingSpec

(Appears on:ClusterSpec)

ShardingSpec defines how KubeBlocks manage dynamic provisioned shards. A typical design pattern for distributed databases is to distribute data across multiple shards, with each shard consisting of multiple replicas. Therefore, KubeBlocks supports representing a shard with a Component and dynamically instantiating Components using a template when shards are added. When shards are removed, the corresponding Components are also deleted.

Field	Description
name string	Represents the common parent part of all shard names. This identifier is included as part of the Service DNS name and must comply with IANA service naming rules. It is used to generate the names of underlying Components following the pattern $(shardingSpec.name)-$(ShardID). ShardID is a random string that is appended to the Name to generate unique identifiers for each shard. For example, if the sharding specification name is “my-shard” and the ShardID is “abc”, the resulting Component name would be “my-shard-abc”. Note that the name defined in Component template(shardingSpec.template.name) will be disregarded when generating the Component names of the shards. The shardingSpec.name field takes precedence.
template ClusterComponentSpec	The template for generating Components for shards, where each shard consists of one Component. This field is of type ClusterComponentSpec, which encapsulates all the required details and definitions for creating and managing the Components. KubeBlocks uses this template to generate a set of identical Components or shards. All the generated Components will have the same specifications and definitions as specified in the template field. This allows for the creation of multiple Components with consistent configurations, enabling sharding and distribution of workloads across Components.
shards int32	Specifies the desired number of shards. Users can declare the desired number of shards through this field. KubeBlocks dynamically creates and deletes Components based on the difference between the desired and actual number of shards. KubeBlocks provides lifecycle management for sharding, including: Executing the postProvision Action defined in the ComponentDefinition when the number of shards increases. This allows for custom actions to be performed after a new shard is provisioned. Executing the preTerminate Action defined in the ComponentDefinition when the number of shards decreases. This enables custom cleanup or data migration tasks to be executed before a shard is terminated. Resources and data associated with the corresponding Component will also be deleted.

StatefulSetSpec

(Appears on:ClusterComponentDefinition, ConsensusSetSpec, ReplicationSetSpec)

StatefulSetSpec is deprecated since v0.7.

Field	Description
updateStrategy UpdateStrategy	(Optional) Specifies the strategy for updating Pods. For workloadType=Consensus, the update strategy can be one of the following: Serial: Updates Members sequentially to minimize component downtime. BestEffortParallel: Updates Members in parallel to minimize component write downtime. Majority remains online at all times. Parallel: Forces parallel updates.
llPodManagementPolicy Kubernetes apps/v1.PodManagementPolicyType	(Optional) Controls the creation of pods during initial scale up, replacement of pods on nodes, and scaling down. OrderedReady: Creates pods in increasing order (pod-0, then pod-1, etc). The controller waits until each pod is ready before continuing. Pods are removed in reverse order when scaling down. Parallel: Creates pods in parallel to match the desired scale without waiting. All pods are deleted at once when scaling down.
llUpdateStrategy Kubernetes apps/v1.StatefulSetUpdateStrategy	(Optional) Specifies the low-level StatefulSetUpdateStrategy to be used when updating Pods in the StatefulSet upon a revision to the Template. UpdateStrategy will be ignored if this is provided.

StatefulSetWorkload

StatefulSetWorkload interface

StatelessSetSpec

(Appears on:ClusterComponentDefinition)

StatelessSetSpec is deprecated since v0.7.

Field	Description
updateStrategy Kubernetes apps/v1.DeploymentStrategy	(Optional) Specifies the deployment strategy that will be used to replace existing pods with new ones.

SwitchPolicyType (string alias)

(Appears on:ClusterSwitchPolicy)

SwitchPolicyType defines the types of switch policies that can be applied to a cluster.

Currently, only the Noop policy is supported. Support for MaximumAvailability and MaximumDataProtection policies is planned for future releases.

Value	Description
"MaximumAvailability"	MaximumAvailability represents a switch policy that aims for maximum availability. This policy will switch if the primary is active and the synchronization delay is 0 according to the user-defined lagProbe data delay detection logic. If the primary is down, it will switch immediately. This policy is intended for future support.
"MaximumDataProtection"	MaximumDataProtection represents a switch policy focused on maximum data protection. This policy will only switch if the primary is active and the synchronization delay is 0, based on the user-defined lagProbe data lag detection logic. If the primary is down, it will switch only if it can be confirmed that the primary and secondary data are consistent. Otherwise, it will not switch. This policy is planned for future implementation.
"Noop"	Noop indicates that KubeBlocks will not perform any high-availability switching for the components. Users are required to implement their own HA solution or integrate an existing open-source HA solution.

SwitchoverAction

(Appears on:SwitchoverSpec)

SwitchoverAction is deprecated since v0.8.

Field	Description
cmdExecutorConfig CmdExecutorConfig	Specifies the switchover command.
scriptSpecSelectors []ScriptSpecSelector	(Optional) Used to select the script that need to be referenced. When defined, the scripts defined in scriptSpecs can be referenced within the SwitchoverAction.CmdExecutorConfig.

SwitchoverSpec

(Appears on:ClusterComponentDefinition)

SwitchoverSpec is deprecated since v0.8.

Field	Description
withCandidate SwitchoverAction	(Optional) Represents the action of switching over to a specified candidate primary or leader instance.
withoutCandidate SwitchoverAction	(Optional) Represents the action of switching over without specifying a candidate primary or leader instance.

SystemAccount

(Appears on:ComponentDefinitionSpec)

Field	Description
name string	Specifies the unique identifier for the account. This name is used by other entities to reference the account. This field is immutable once set.
initAccount bool	(Optional) Indicates if this account is a system initialization account (e.g., MySQL root). This field is immutable once set.
statement string	(Optional) Defines the statement used to create the account with the necessary privileges. This field is immutable once set.
passwordGenerationPolicy PasswordConfig	(Optional) Specifies the policy for generating the account’s password. This field is immutable once set.
secretRef ProvisionSecretRef	(Optional) Refers to the secret from which data will be copied to create the new account. This field is immutable once set.

SystemAccountConfig

(Appears on:SystemAccountSpec)

SystemAccountConfig specifies how to create and delete system accounts.

Deprecated since v0.9.

Field	Description
name AccountName	The unique identifier of a system account.
provisionPolicy ProvisionPolicy	Outlines the strategy for creating the account.

SystemAccountSpec

(Appears on:ClusterComponentDefinition)

SystemAccountSpec specifies information to create system accounts.

Deprecated since v0.8, be replaced by componentDefinition.spec.systemAccounts and componentDefinition.spec.lifecycleActions.accountProvision.

Field	Description
cmdExecutorConfig CmdExecutorConfig	Configures how to obtain the client SDK and execute statements.
passwordConfig PasswordConfig	Defines the pattern used to generate passwords for system accounts.
accounts []SystemAccountConfig	Defines the configuration settings for system accounts.

TLSConfig

(Appears on:ComponentSpec)

Field	Description
enable bool	(Optional) A boolean flag that indicates whether the Component should use Transport Layer Security (TLS) for secure communication. When set to true, the Component will be configured to use TLS encryption for its network connections. This ensures that the data transmitted between the Component and its clients or other Components is encrypted and protected from unauthorized access. If TLS is enabled, the Component may require additional configuration, such as specifying TLS certificates and keys, to properly set up the secure communication channel.
issuer Issuer	(Optional) Specifies the configuration for the TLS certificates issuer. It allows defining the issuer name and the reference to the secret containing the TLS certificates and key. The secret should contain the CA certificate, TLS certificate, and private key in the specified keys. Required when TLS is enabled.

TLSSecretRef

(Appears on:Issuer)

TLSSecretRef defines Secret contains Tls certs

Field	Description
name string	Name of the Secret that contains user-provided certificates.
ca string	Key of CA cert in Secret
cert string	Key of Cert in Secret
key string	Key of TLS private key in Secret

TargetPodSelector (string alias)

(Appears on:Action)

TargetPodSelector defines how to select pod(s) to execute an Action.

Value	Description
"All"
"Any"
"Ordinal"
"Role"

TenancyType (string alias)

(Appears on:Affinity, ClusterSpec)

TenancyType defines the type of tenancy for cluster tenant resources.

Value	Description
"DedicatedNode"	DedicatedNode means each pod runs on their own dedicated node.
"SharedNode"	SharedNode means multiple pods may share the same node.

TerminationPolicyType (string alias)

(Appears on:ClusterSpec)

TerminationPolicyType defines termination policy types.

Value	Description
"Delete"	Delete is based on Halt and deletes PVCs.
"DoNotTerminate"	DoNotTerminate will block delete operation.
"Halt"	Halt will delete workload resources such as statefulset, deployment workloads but keep PVCs.
"WipeOut"	WipeOut is based on Delete and wipe out all volume snapshots and snapshot data from backup storage location.

UpdateStrategy (string alias)

(Appears on:ClusterComponentSpec, ComponentDefinitionSpec, StatefulSetSpec)

UpdateStrategy defines the update strategy for cluster components. This strategy determines how updates are applied across the cluster. The available strategies are Serial, BestEffortParallel, and Parallel.

Value	Description
"BestEffortParallel"	BestEffortParallelStrategy indicates that the replicas are updated in parallel, with the operator making a best-effort attempt to update as many replicas as possible concurrently while maintaining the component’s availability. Unlike the Parallel strategy, the BestEffortParallel strategy aims to ensure that a minimum number of replicas remain available during the update process to maintain the component’s quorum and functionality. For example, consider a component with 5 replicas. To maintain the component’s availability and quorum, the operator may allow a maximum of 2 replicas to be simultaneously updated. This ensures that at least 3 replicas (a quorum) remain available and functional during the update process. The BestEffortParallel strategy strikes a balance between update speed and component availability.
"Parallel"	ParallelStrategy indicates that updates are applied simultaneously to all Pods of a Component. The replicas are updated in parallel, with the operator updating all replicas concurrently. This strategy provides the fastest update time but may lead to a period of reduced availability or capacity during the update process.
"Serial"	SerialStrategy indicates that updates are applied one at a time in a sequential manner. The operator waits for each replica to be updated and ready before proceeding to the next one. This ensures that only one replica is unavailable at a time during the update process.

UpgradePolicy (string alias)

UpgradePolicy defines the policy of reconfiguring.

Value	Description
"autoReload"
"dynamicReloadBeginRestart"
"none"
"simple"
"parallel"
"rolling"
"operatorSyncUpdate"

UserResourceRefs

(Appears on:ClusterComponentSpec)

UserResourceRefs defines references to user-defined Secrets and ConfigMaps.

Field	Description
secretRefs []SecretRef	(Optional) SecretRefs defines the user-defined Secrets.
configMapRefs []ConfigMapRef	(Optional) ConfigMapRefs defines the user-defined ConfigMaps.

VarOption (string alias)

(Appears on:ComponentVars, CredentialVars, NamedVar, ServiceRefVars, ServiceVars)

VarOption defines whether a variable is required or optional.

VarSource

(Appears on:EnvVar)

VarSource represents a source for the value of an EnvVar.

Field	Description
configMapKeyRef Kubernetes core/v1.ConfigMapKeySelector	(Optional) Selects a key of a ConfigMap.
secretKeyRef Kubernetes core/v1.SecretKeySelector	(Optional) Selects a key of a Secret.
hostNetworkVarRef HostNetworkVarSelector	(Optional) Selects a defined var of host-network resources.
serviceVarRef ServiceVarSelector	(Optional) Selects a defined var of a Service.
credentialVarRef CredentialVarSelector	(Optional) Selects a defined var of a Credential (SystemAccount).
serviceRefVarRef ServiceRefVarSelector	(Optional) Selects a defined var of a ServiceRef.
componentVarRef ComponentVarSelector	(Optional) Selects a defined var of a Component.

VolumeProtectionSpec

(Appears on:ClusterComponentDefinition)

VolumeProtectionSpec is deprecated since v0.9, replaced with ComponentVolume.HighWatermark.

Field	Description
highWatermark int	(Optional) The high watermark threshold for volume space usage. If there is any specified volumes who’s space usage is over the threshold, the pre-defined “LOCK” action will be triggered to degrade the service to protect volume from space exhaustion, such as to set the instance as read-only. And after that, if all volumes’ space usage drops under the threshold later, the pre-defined “UNLOCK” action will be performed to recover the service normally.
volumes []ProtectedVolume	(Optional) The Volumes to be protected.

VolumeType (string alias)

(Appears on:VolumeTypeSpec)

VolumeType defines the type of volume, specifically distinguishing between volumes used for backup data and those used for logs.

Value	Description
"data"	VolumeTypeData indicates a volume designated for storing backup data. This type of volume is optimized for the storage and retrieval of data backups, ensuring data persistence and reliability.
"log"	VolumeTypeLog indicates a volume designated for storing logs. This type of volume is optimized for log data, facilitating efficient log storage, retrieval, and management.

VolumeTypeSpec

(Appears on:ClusterComponentDefinition)

VolumeTypeSpec is deprecated since v0.9, replaced with ComponentVolume.

Field	Description
name string	Corresponds to the name of the VolumeMounts field in PodSpec.Container.
type VolumeType	(Optional) Type of data the volume will persistent.

WorkloadType (string alias)

(Appears on:ClusterComponentDefinition)

WorkloadType defines the type of workload for the components of the ClusterDefinition. It can be one of the following: Stateless, Stateful, Consensus, or Replication.

Deprecated since v0.8.

Value	Description
"Consensus"	Consensus represents a workload type involving distributed consensus algorithms for coordinated decision-making.
"Replication"	Replication represents a workload type that involves replication, typically used for achieving high availability and fault tolerance.
"Stateful"	Stateful represents a workload type where components maintain state, and each instance has a unique identity.
"Stateless"	Stateless represents a workload type where components do not maintain state, and instances are interchangeable.

---

apps.kubeblocks.io/v1beta1

Resource Types:

• ConfigConstraint

ConfigConstraint

ConfigConstraint manages the parameters across multiple configuration files contained in a single configure template. These configuration files should have the same format (e.g. ini, xml, properties, json).

It provides the following functionalities:

1. Parameter Value Validation: Validates and ensures compliance of parameter values with defined constraints.

2. Dynamic Reload on Modification: Monitors parameter changes and triggers dynamic reloads to apply updates.

3. Parameter Rendering in Templates: Injects parameters into templates to generate up-to-date configuration files.

Field	Description
apiVersion string	apps.kubeblocks.io/v1beta1
kind string	ConfigConstraint
metadata Kubernetes meta/v1.ObjectMeta	Refer to the Kubernetes API documentation for the fields of the metadata field.
spec ConfigConstraintSpec	reloadAction ReloadAction (Optional) Specifies the dynamic reload (dynamic reconfiguration) actions supported by the engine. When set, the controller executes the scripts defined in these actions to handle dynamic parameter updates. Dynamic reloading is triggered only if both of the following conditions are met: The modified parameters are listed in the dynamicParameters field. If dynamicParameterSelectedPolicy is set to “all”, modifications to staticParameters can also trigger a reload. reloadAction is set. If reloadAction is not set or the modified parameters are not listed in dynamicParameters, dynamic reloading will not be triggered. Example: dynamicReloadAction: tplScriptTrigger: namespace: kb-system scriptConfigMapRef: mysql-reload-script sync: true mergeReloadAndRestart bool (Optional) Indicates whether to consolidate dynamic reload and restart actions into a single restart. If true, updates requiring both actions will result in only a restart, merging the actions. If false, updates will trigger both actions executed sequentially: first dynamic reload, then restart. This flag allows for more efficient handling of configuration changes by potentially eliminating an unnecessary reload step. reloadStaticParamsBeforeRestart bool (Optional) Configures whether the dynamic reload specified in reloadAction applies only to dynamic parameters or to all parameters (including static parameters). false (default): Only modifications to the dynamic parameters listed in dynamicParameters will trigger a dynamic reload. true: Modifications to both dynamic parameters listed in dynamicParameters and static parameters listed in staticParameters will trigger a dynamic reload. The “all” option is for certain engines that require static parameters to be set via SQL statements before they can take effect on restart. downwardAPIChangeTriggeredActions []DownwardAPIChangeTriggeredAction (Optional) Specifies a list of actions to execute specified commands based on Pod labels. It utilizes the K8s Downward API to mount label information as a volume into the pod. The ‘config-manager’ sidecar container watches for changes in the role label and dynamically invoke registered commands (usually execute some SQL statements) when a change is detected. It is designed for scenarios where: Replicas with different roles have different configurations, such as Redis primary & secondary replicas. After a role switch (e.g., from secondary to primary), some changes in configuration are needed to reflect the new role. parametersSchema ParametersSchema (Optional) Defines a list of parameters including their names, default values, descriptions, types, and constraints (permissible values or the range of valid values). staticParameters []string (Optional) List static parameters. Modifications to any of these parameters require a restart of the process to take effect. dynamicParameters []string (Optional) List dynamic parameters. Modifications to these parameters trigger a configuration reload without requiring a process restart. immutableParameters []string (Optional) Lists the parameters that cannot be modified once set. Attempting to change any of these parameters will be ignored. fileFormatConfig FileFormatConfig Specifies the format of the configuration file and any associated parameters that are specific to the chosen format. Supported formats include ini, xml, yaml, json, hcl, dotenv, properties, and toml. Each format may have its own set of parameters that can be configured. For instance, when using the ini format, you can specify the section name. Example: fileFormatConfig: format: ini iniConfig: sectionName: mysqld
status ConfigConstraintStatus

AutoTrigger

(Appears on:ReloadOptions, ReloadAction)

AutoTrigger automatically perform the reload when specified conditions are met.

Field	Description
processName string	(Optional) The name of the process.

CfgFileFormat (string alias)

(Appears on:FileFormatConfig)

CfgFileFormat defines formatter of configuration files.

Value	Description
"dotenv"
"hcl"
"ini"
"json"
"properties"
"props-plus"
"redis"
"toml"
"xml"
"yaml"

ConfigConstraintPhase (string alias)

(Appears on:ConfigConstraintStatus, ConfigConstraintStatus)

ConfigConstraintPhase defines the ConfigConstraint CR .status.phase

Value	Description
"Available"
"Deleting"
"Unavailable"

ConfigConstraintSpec

(Appears on:ConfigConstraint)

ConfigConstraintSpec defines the desired state of ConfigConstraint

Field	Description
reloadAction ReloadAction	(Optional) Specifies the dynamic reload (dynamic reconfiguration) actions supported by the engine. When set, the controller executes the scripts defined in these actions to handle dynamic parameter updates. Dynamic reloading is triggered only if both of the following conditions are met: The modified parameters are listed in the dynamicParameters field. If dynamicParameterSelectedPolicy is set to “all”, modifications to staticParameters can also trigger a reload. reloadAction is set. If reloadAction is not set or the modified parameters are not listed in dynamicParameters, dynamic reloading will not be triggered. Example: dynamicReloadAction: tplScriptTrigger: namespace: kb-system scriptConfigMapRef: mysql-reload-script sync: true
mergeReloadAndRestart bool	(Optional) Indicates whether to consolidate dynamic reload and restart actions into a single restart. If true, updates requiring both actions will result in only a restart, merging the actions. If false, updates will trigger both actions executed sequentially: first dynamic reload, then restart. This flag allows for more efficient handling of configuration changes by potentially eliminating an unnecessary reload step.
reloadStaticParamsBeforeRestart bool	(Optional) Configures whether the dynamic reload specified in reloadAction applies only to dynamic parameters or to all parameters (including static parameters). false (default): Only modifications to the dynamic parameters listed in dynamicParameters will trigger a dynamic reload. true: Modifications to both dynamic parameters listed in dynamicParameters and static parameters listed in staticParameters will trigger a dynamic reload. The “all” option is for certain engines that require static parameters to be set via SQL statements before they can take effect on restart.
downwardAPIChangeTriggeredActions []DownwardAPIChangeTriggeredAction	(Optional) Specifies a list of actions to execute specified commands based on Pod labels. It utilizes the K8s Downward API to mount label information as a volume into the pod. The ‘config-manager’ sidecar container watches for changes in the role label and dynamically invoke registered commands (usually execute some SQL statements) when a change is detected. It is designed for scenarios where: Replicas with different roles have different configurations, such as Redis primary & secondary replicas. After a role switch (e.g., from secondary to primary), some changes in configuration are needed to reflect the new role.
parametersSchema ParametersSchema	(Optional) Defines a list of parameters including their names, default values, descriptions, types, and constraints (permissible values or the range of valid values).
staticParameters []string	(Optional) List static parameters. Modifications to any of these parameters require a restart of the process to take effect.
dynamicParameters []string	(Optional) List dynamic parameters. Modifications to these parameters trigger a configuration reload without requiring a process restart.
immutableParameters []string	(Optional) Lists the parameters that cannot be modified once set. Attempting to change any of these parameters will be ignored.
fileFormatConfig FileFormatConfig	Specifies the format of the configuration file and any associated parameters that are specific to the chosen format. Supported formats include ini, xml, yaml, json, hcl, dotenv, properties, and toml. Each format may have its own set of parameters that can be configured. For instance, when using the ini format, you can specify the section name. Example: fileFormatConfig: format: ini iniConfig: sectionName: mysqld

ConfigConstraintStatus

(Appears on:ConfigConstraint)

ConfigConstraintStatus represents the observed state of a ConfigConstraint.

Field	Description
phase ConfigConstraintPhase	(Optional) Specifies the status of the configuration template. When set to CCAvailablePhase, the ConfigConstraint can be referenced by ClusterDefinition.
message string	(Optional) Provides descriptions for abnormal states.
observedGeneration int64	(Optional) Refers to the most recent generation observed for this ConfigConstraint. This value is updated by the API Server.

DownwardAPIChangeTriggeredAction

(Appears on:ConfigConstraintSpec, ConfigConstraintSpec)

DownwardAPIChangeTriggeredAction defines an action that triggers specific commands in response to changes in Pod labels. For example, a command might be executed when the ‘role’ label of the Pod is updated.

Field	Description
name string	Specifies the name of the field. It must be a string of maximum length 63. The name should match the regex pattern ^[a-z0-9]([a-z0-9\.\-]*[a-z0-9])?$.
mountPoint string	Specifies the mount point of the Downward API volume.
items []Kubernetes core/v1.DownwardAPIVolumeFile	Represents a list of files under the Downward API volume.
command []string	(Optional) Specifies the command to be triggered when changes are detected in Downward API volume files. It relies on the inotify mechanism in the config-manager sidecar to monitor file changes.
scriptConfig ScriptConfig	(Optional) ScriptConfig object specifies a ConfigMap that contains script files that should be mounted inside the pod. The scripts are mounted as volumes and can be referenced and executed by the DownwardAction to perform specific tasks or configurations.

DynamicParameterSelectedPolicy (string alias)

DynamicParameterSelectedPolicy determines how to select the parameters of dynamic reload actions

Value	Description
"all"
"dynamic"

DynamicReloadType (string alias)

DynamicReloadType defines reload method.

Value	Description
"auto"
"http"
"sql"
"exec"
"tpl"
"signal"

FileFormatConfig

(Appears on:ConfigConstraintSpec, ConfigConstraintSpec)

FileFormatConfig specifies the format of the configuration file and any associated parameters that are specific to the chosen format.

Field	Description
FormatterAction FormatterAction	(Members of FormatterAction are embedded into this type.) (Optional) Each format may have its own set of parameters that can be configured. For instance, when using the ini format, you can specify the section name.
format CfgFileFormat	The config file format. Valid values are ini, xml, yaml, json, hcl, dotenv, properties and toml. Each format has its own characteristics and use cases. ini: is a text-based content with a structure and syntax comprising key–value pairs for properties, reference wiki: https://en.wikipedia.org/wiki/INI_file xml: refers to wiki: https://en.wikipedia.org/wiki/XML yaml: supports for complex data types and structures. json: refers to wiki: https://en.wikipedia.org/wiki/JSON hcl: The HashiCorp Configuration Language (HCL) is a configuration language authored by HashiCorp, reference url: https://www.linode.com/docs/guides/introduction-to-hcl/ dotenv: is a plain text file with simple key–value pairs, reference wiki: https://en.wikipedia.org/wiki/Configuration_file#MS-DOS properties: a file extension mainly used in Java, reference wiki: https://en.wikipedia.org/wiki/.properties toml: refers to wiki: https://en.wikipedia.org/wiki/TOML props-plus: a file extension mainly used in Java, supports CamelCase(e.g: brokerMaxConnectionsPerIp)

FormatterAction

(Appears on:FileFormatConfig)

FormatterAction configures format-specific options for different configuration file format. Note: Only one of its members should be specified at any given time.

Field	Description
iniConfig IniConfig	(Optional) Holds options specific to the ‘ini’ file format.

IniConfig

(Appears on:FormatterAction)

IniConfig holds options specific to the ‘ini’ file format.

Field	Description
sectionName string	(Optional) A string that describes the name of the ini section.

ParametersSchema

(Appears on:ConfigConstraintSpec)

ParametersSchema Defines a list of configuration items with their names, default values, descriptions, types, and constraints.

Field	Description
topLevelKey string	(Optional) Specifies the top-level key in the ‘configSchema.cue’ that organizes the validation rules for parameters. This key must exist within the CUE script defined in ‘configSchema.cue’.
cue string	(Optional) Hold a string that contains a script written in CUE language that defines a list of configuration items. Each item is detailed with its name, default value, description, type (e.g. string, integer, float), and constraints (permissible values or the valid range of values). CUE (Configure, Unify, Execute) is a declarative language designed for defining and validating complex data configurations. It is particularly useful in environments like K8s where complex configurations and validation rules are common. This script functions as a validator for user-provided configurations, ensuring compliance with the established specifications and constraints.
schemaInJSON Kubernetes api extensions v1.JSONSchemaProps	Generated from the ‘cue’ field and transformed into a JSON format.

ReloadAction

(Appears on:ConfigConstraintSpec)

ReloadAction defines the mechanisms available for dynamically reloading a process within K8s without requiring a restart.

Only one of the mechanisms can be specified at a time.

Field	Description
unixSignalTrigger UnixSignalTrigger	(Optional) Used to trigger a reload by sending a specific Unix signal to the process.
shellTrigger ShellTrigger	(Optional) Allows to execute a custom shell script to reload the process.
tplScriptTrigger TPLScriptTrigger	(Optional) Enables reloading process using a Go template script.
autoTrigger AutoTrigger	(Optional) Automatically perform the reload when specified conditions are met.
targetPodSelector Kubernetes meta/v1.LabelSelector	(Optional) Used to match labels on the pod to determine whether a dynamic reload should be performed. In some scenarios, only specific pods (e.g., primary replicas) need to undergo a dynamic reload. The reloadedPodSelector allows you to specify label selectors to target the desired pods for the reload process. If the reloadedPodSelector is not specified or is nil, all pods managed by the workload will be considered for the dynamic reload.

ScriptConfig

(Appears on:ConfigConstraintSpec, DownwardAPIChangeTriggeredAction, ShellTrigger, TPLScriptTrigger)

Field	Description
scriptConfigMapRef string	Specifies the reference to the ConfigMap containing the scripts.
namespace string	(Optional) Specifies the namespace for the ConfigMap. If not specified, it defaults to the “default” namespace.

ShellTrigger

(Appears on:ReloadOptions, ReloadAction)

ShellTrigger allows to execute a custom shell script to reload the process.

Field	Description
command []string	Specifies the command to execute in order to reload the process. It should be a valid shell command.
sync bool	(Optional) Determines the synchronization mode of parameter updates with “config-manager”. ‘True’: Executes reload actions synchronously, pausing until completion. ‘False’: Executes reload actions asynchronously, without waiting for completion.
batchReload bool	(Optional) Controls whether parameter updates are processed individually or collectively in a batch: ‘True’: Processes all changes in one batch reload. ‘False’: Processes each change individually. Defaults to ‘False’ if unspecified.
batchParamsFormatterTemplate string	(Optional) Specifies a Go template string for formatting batch input data. It’s used when batchReload is ‘True’ to format data passed into STDIN of the script. The template accesses key-value pairs of updated parameters via the ‘$’ variable. This allows for custom formatting of the input data. Example template: batchParamsFormatterTemplate: |- {{- range $pKey, $pValue := $ }} {{ printf "%s:%s" $pKey $pValue }} {{- end }} This example generates batch input data in a key:value format, sorted by keys. key1:value1 key2:value2 key3:value3 If not specified, the default format is key=value, sorted by keys, for each updated parameter. key1=value1 key2=value2 key3=value3
toolsSetup ToolsSetup	(Optional) Specifies the tools container image used by ShellTrigger for dynamic reload. If the dynamic reload action is triggered by a ShellTrigger, this field is required. This image must contain all necessary tools for executing the ShellTrigger scripts. Usually the specified image is referenced by the init container, which is then responsible for copy the tools from the image to a bin volume. This ensures that the tools are available to the ‘config-manager’ sidecar.
scriptConfig ScriptConfig	(Optional) ScriptConfig object specifies a ConfigMap that contains script files that should be mounted inside the pod. The scripts are mounted as volumes and can be referenced and executed by the dynamic reload.

SignalType (string alias)

(Appears on:UnixSignalTrigger)

SignalType defines which signals are valid.

Value	Description
"SIGABRT"
"SIGALRM"
"SIGBUS"
"SIGCHLD"
"SIGCONT"
"SIGFPE"
"SIGHUP"
"SIGILL"
"SIGINT"
"SIGIO"
"SIGKILL"
"SIGPIPE"
"SIGPROF"
"SIGPWR"
"SIGQUIT"
"SIGSEGV"
"SIGSTKFLT"
"SIGSTOP"
"SIGSYS"
"SIGTERM"
"SIGTRAP"
"SIGTSTP"
"SIGTTIN"
"SIGTTOU"
"SIGURG"
"SIGUSR1"
"SIGUSR2"
"SIGVTALRM"
"SIGWINCH"
"SIGXCPU"
"SIGXFSZ"

TPLScriptTrigger

(Appears on:ReloadOptions, ReloadAction)

TPLScriptTrigger Enables reloading process using a Go template script.

Field	Description
ScriptConfig ScriptConfig	(Members of ScriptConfig are embedded into this type.) Specifies the ConfigMap that contains the script to be executed for reload.
sync bool	(Optional) Determines whether parameter updates should be synchronized with the “config-manager”. Specifies the controller’s reload strategy: If set to ‘True’, the controller executes the reload action in synchronous mode, pausing execution until the reload completes. If set to ‘False’, the controller executes the reload action in asynchronous mode, updating the ConfigMap without waiting for the reload process to finish.

ToolConfig

(Appears on:ToolsSetup)

ToolConfig specifies the settings of an init container that prepare tools for dynamic reload.

Field	Description
name string	Specifies the name of the init container.
asContainerImage bool	(Optional) Indicates whether the tool image should be used as the container image for a sidecar. This is useful for large tool images, such as those for C++ tools, which may depend on numerous libraries (e.g., *.so files). If enabled, the tool image is deployed as a sidecar container image. Examples: toolsSetup:: mountPoint: /kb_tools toolConfigs: name: kb-tools asContainerImage: true image: apecloud/oceanbase:4.2.0.0-100010032023083021 generated containers: initContainers: name: install-config-manager-tool image: apecloud/kubeblocks-tools:${version} command: cp /bin/config_render /opt/tools volumemounts: name: kb-tools mountpath: /opt/tools containers: name: config-manager image: apecloud/oceanbase:4.2.0.0-100010032023083021 imagePullPolicy: IfNotPresent command: /opt/tools/reloader --log-level info --operator-update-enable --tcp "9901" --config /opt/config-manager/config-manager.yaml volumemounts: name: kb-tools mountpath: /opt/tools
image string	(Optional) Specifies the tool container image.
command []string	(Optional) Specifies the command to be executed by the init container.

ToolsSetup

(Appears on:ConfigConstraintSpec, ShellTrigger)

ToolsSetup prepares the tools for dynamic reloads used in ShellTrigger from a specified container image.

Example:

toolsSetup:
mountPoint: /kb_tools
toolConfigs:

name: kb-tools
command:

cp
/bin/ob-tools
/kb_tools/obtools
image: docker.io/apecloud/obtools

This example copies the “/bin/ob-tools” binary from the image to “/kb_tools/obtools”.

Field	Description
mountPoint string	Specifies the directory path in the container where the tools-related files are to be copied. This field is typically used with an emptyDir volume to ensure a temporary, empty directory is provided at pod creation.
toolConfigs []ToolConfig	(Optional) Specifies a list of settings of init containers that prepare tools for dynamic reload.

UnixSignalTrigger

(Appears on:ReloadOptions, ReloadAction)

UnixSignalTrigger is used to trigger a reload by sending a specific Unix signal to the process.

Field	Description
signal SignalType	Specifies a valid Unix signal to be sent. For a comprehensive list of all Unix signals, see: ../../pkg/configuration/configmap/handler.go:allUnixSignals
processName string	Identifies the name of the process to which the Unix signal will be sent.

---

workloads.kubeblocks.io/v1

Resource Types:

• InstanceSet

InstanceSet

InstanceSet is the Schema for the instancesets API.

Field	Description
apiVersion string	workloads.kubeblocks.io/v1
kind string	InstanceSet
metadata Kubernetes meta/v1.ObjectMeta	Contains the metadata for the particular object, such as name, namespace, labels, and annotations. Refer to the Kubernetes API documentation for the fields of the metadata field.
spec InstanceSetSpec	Defines the desired state of the state machine. It includes the configuration details for the state machine. replicas int32 (Optional) Specifies the desired number of replicas of the given Template. These replicas are instantiations of the same Template, with each having a consistent identity. Defaults to 1 if unspecified. defaultTemplateOrdinals Ordinals Specifies the desired Ordinals of the default template. The Ordinals used to specify the ordinal of the instance (pod) names to be generated under the default template. For example, if Ordinals is {ranges: [{start: 0, end: 1}], discrete: [7]}, then the instance names generated under the default template would be $(cluster.name)-$(component.name)-0、$(cluster.name)-$(component.name)-1 and $(cluster.name)-$(component.name)-7 minReadySeconds int32 (Optional) Defines the minimum number of seconds a newly created pod should be ready without any of its container crashing to be considered available. Defaults to 0, meaning the pod will be considered available as soon as it is ready. selector Kubernetes meta/v1.LabelSelector Represents a label query over pods that should match the desired replica count indicated by the replica field. It must match the labels defined in the pod template. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors template Kubernetes core/v1.PodTemplateSpec instances []InstanceTemplate (Optional) Overrides values in default Template. Instance is the fundamental unit managed by KubeBlocks. It represents a Pod with additional objects such as PVCs, Services, ConfigMaps, etc. An InstanceSet manages instances with a total count of Replicas, and by default, all these instances are generated from the same template. The InstanceTemplate provides a way to override values in the default template, allowing the InstanceSet to manage instances from different templates. The naming convention for instances (pods) based on the InstanceSet Name, InstanceTemplate Name, and ordinal. The constructed instance name follows the pattern: $(instance_set.name)-$(template.name)-$(ordinal). By default, the ordinal starts from 0 for each InstanceTemplate. It is important to ensure that the Name of each InstanceTemplate is unique. The sum of replicas across all InstanceTemplates should not exceed the total number of Replicas specified for the InstanceSet. Any remaining replicas will be generated using the default template and will follow the default naming rules. offlineInstances []string (Optional) Specifies the names of instances to be transitioned to offline status. Marking an instance as offline results in the following: The associated pod is stopped, and its PersistentVolumeClaim (PVC) is retained for potential future reuse or data recovery, but it is no longer actively used. The ordinal number assigned to this instance is preserved, ensuring it remains unique and avoiding conflicts with new instances. Setting instances to offline allows for a controlled scale-in process, preserving their data and maintaining ordinal consistency within the cluster. Note that offline instances and their associated resources, such as PVCs, are not automatically deleted. The cluster administrator must manually manage the cleanup and removal of these resources when they are no longer needed. volumeClaimTemplates []Kubernetes core/v1.PersistentVolumeClaim (Optional) Specifies a list of PersistentVolumeClaim templates that define the storage requirements for each replica. Each template specifies the desired characteristics of a persistent volume, such as storage class, size, and access modes. These templates are used to dynamically provision persistent volumes for replicas upon their creation. The final name of each PVC is generated by appending the pod’s identifier to the name specified in volumeClaimTemplates[*].name. podManagementPolicy Kubernetes apps/v1.PodManagementPolicyType (Optional) Controls how pods are created during initial scale up, when replacing pods on nodes, or when scaling down. The default policy is OrderedReady, where pods are created in increasing order and the controller waits until each pod is ready before continuing. When scaling down, the pods are removed in the opposite order. The alternative policy is Parallel which will create pods in parallel to match the desired scale without waiting, and on scale down will delete all pods at once. Note: This field will be removed in future version. parallelPodManagementConcurrency Kubernetes api utils intstr.IntOrString (Optional) Controls the concurrency of pods during initial scale up, when replacing pods on nodes, or when scaling down. It only used when PodManagementPolicy is set to Parallel. The default Concurrency is 100%. podUpdatePolicy PodUpdatePolicyType (Optional) PodUpdatePolicy indicates how pods should be updated StrictInPlace indicates that only allows in-place upgrades. Any attempt to modify other fields will be rejected. PreferInPlace indicates that we will first attempt an in-place upgrade of the Pod. If that fails, it will fall back to the ReCreate, where pod will be recreated. Default value is “PreferInPlace” updateStrategy Kubernetes apps/v1.StatefulSetUpdateStrategy Indicates the StatefulSetUpdateStrategy that will be employed to update Pods in the InstanceSet when a revision is made to Template. UpdateStrategy.Type will be set to appsv1.OnDeleteStatefulSetStrategyType if MemberUpdateStrategy is not nil Note: This field will be removed in future version. roles []ReplicaRole (Optional) A list of roles defined in the system. Instanceset obtains role through pods’ role label kubeblocks.io/role. membershipReconfiguration MembershipReconfiguration (Optional) Provides actions to do membership dynamic reconfiguration. templateVars map[string]string (Optional) Provides variables which are used to call Actions. memberUpdateStrategy MemberUpdateStrategy (Optional) Members(Pods) update strategy. serial: update Members one by one that guarantee minimum component unavailable time. bestEffortParallel: update Members in parallel that guarantee minimum component un-writable time. parallel: force parallel paused bool (Optional) Indicates that the InstanceSet is paused, meaning the reconciliation of this InstanceSet object will be paused. credential Credential (Optional) Credential used to connect to DB engine
status InstanceSetStatus	Represents the current information about the state machine. This data may be out of date.

AccessMode (string alias)

AccessMode defines SVC access mode enums.

Value	Description
"None"
"ReadWrite"
"Readonly"

Action

(Appears on:MembershipReconfiguration)

Field	Description
image string	(Optional) Refers to the utility image that contains the command which can be utilized to retrieve or process role information.
command []string	A set of instructions that will be executed within the Container to retrieve or process role information. This field is required.
args []string	(Optional) Additional parameters used to perform specific statements. This field is optional.

ConditionType (string alias)

Value	Description
"InstanceAvailable"	InstanceAvailable ConditionStatus will be True if all instances(pods) are in the ready condition and continue for “MinReadySeconds” seconds. Otherwise, it will be set to False.
"InstanceFailure"	InstanceFailure is added in an instance set when at least one of its instances(pods) is in a Failed phase.
"InstanceReady"	InstanceReady is added in an instance set when at least one of its instances(pods) is in a Ready condition. ConditionStatus will be True if all its instances(pods) are in a Ready condition. Or, a NotReady reason with not ready instances encoded in the Message filed will be set.
"InstanceUpdateRestricted"	InstanceUpdateRestricted represents a ConditionType that indicates updates to an InstanceSet are blocked(when the PodUpdatePolicy is set to StrictInPlace but the pods cannot be updated in-place).

Credential

(Appears on:InstanceSetSpec)

Field	Description
username CredentialVar	Defines the user’s name for the credential. The corresponding environment variable will be KB_ITS_USERNAME.
password CredentialVar	Represents the user’s password for the credential. The corresponding environment variable will be KB_ITS_PASSWORD.

CredentialVar

(Appears on:Credential)

Field	Description
value string	(Optional) Specifies the value of the environment variable. This field is optional and defaults to an empty string. The value can include variable references in the format $(VAR_NAME) which will be expanded using previously defined environment variables in the container and any service environment variables. If a variable cannot be resolved, the reference in the input string will remain unchanged. Double $$ can be used to escape the $(VAR_NAME) syntax, resulting in a single $ and producing the string literal “$(VAR_NAME)”. Escaped references will not be expanded, regardless of whether the variable exists or not.
valueFrom Kubernetes core/v1.EnvVarSource	(Optional) Defines the source for the environment variable’s value. This field is optional and cannot be used if the ‘Value’ field is not empty.

InstanceSetSpec

(Appears on:InstanceSet)

InstanceSetSpec defines the desired state of InstanceSet

Field	Description
replicas int32	(Optional) Specifies the desired number of replicas of the given Template. These replicas are instantiations of the same Template, with each having a consistent identity. Defaults to 1 if unspecified.
defaultTemplateOrdinals Ordinals	Specifies the desired Ordinals of the default template. The Ordinals used to specify the ordinal of the instance (pod) names to be generated under the default template. For example, if Ordinals is {ranges: [{start: 0, end: 1}], discrete: [7]}, then the instance names generated under the default template would be $(cluster.name)-$(component.name)-0、$(cluster.name)-$(component.name)-1 and $(cluster.name)-$(component.name)-7
minReadySeconds int32	(Optional) Defines the minimum number of seconds a newly created pod should be ready without any of its container crashing to be considered available. Defaults to 0, meaning the pod will be considered available as soon as it is ready.
selector Kubernetes meta/v1.LabelSelector	Represents a label query over pods that should match the desired replica count indicated by the replica field. It must match the labels defined in the pod template. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors
template Kubernetes core/v1.PodTemplateSpec
instances []InstanceTemplate	(Optional) Overrides values in default Template. Instance is the fundamental unit managed by KubeBlocks. It represents a Pod with additional objects such as PVCs, Services, ConfigMaps, etc. An InstanceSet manages instances with a total count of Replicas, and by default, all these instances are generated from the same template. The InstanceTemplate provides a way to override values in the default template, allowing the InstanceSet to manage instances from different templates. The naming convention for instances (pods) based on the InstanceSet Name, InstanceTemplate Name, and ordinal. The constructed instance name follows the pattern: $(instance_set.name)-$(template.name)-$(ordinal). By default, the ordinal starts from 0 for each InstanceTemplate. It is important to ensure that the Name of each InstanceTemplate is unique. The sum of replicas across all InstanceTemplates should not exceed the total number of Replicas specified for the InstanceSet. Any remaining replicas will be generated using the default template and will follow the default naming rules.
offlineInstances []string	(Optional) Specifies the names of instances to be transitioned to offline status. Marking an instance as offline results in the following: The associated pod is stopped, and its PersistentVolumeClaim (PVC) is retained for potential future reuse or data recovery, but it is no longer actively used. The ordinal number assigned to this instance is preserved, ensuring it remains unique and avoiding conflicts with new instances. Setting instances to offline allows for a controlled scale-in process, preserving their data and maintaining ordinal consistency within the cluster. Note that offline instances and their associated resources, such as PVCs, are not automatically deleted. The cluster administrator must manually manage the cleanup and removal of these resources when they are no longer needed.
volumeClaimTemplates []Kubernetes core/v1.PersistentVolumeClaim	(Optional) Specifies a list of PersistentVolumeClaim templates that define the storage requirements for each replica. Each template specifies the desired characteristics of a persistent volume, such as storage class, size, and access modes. These templates are used to dynamically provision persistent volumes for replicas upon their creation. The final name of each PVC is generated by appending the pod’s identifier to the name specified in volumeClaimTemplates[*].name.
podManagementPolicy Kubernetes apps/v1.PodManagementPolicyType	(Optional) Controls how pods are created during initial scale up, when replacing pods on nodes, or when scaling down. The default policy is OrderedReady, where pods are created in increasing order and the controller waits until each pod is ready before continuing. When scaling down, the pods are removed in the opposite order. The alternative policy is Parallel which will create pods in parallel to match the desired scale without waiting, and on scale down will delete all pods at once. Note: This field will be removed in future version.
parallelPodManagementConcurrency Kubernetes api utils intstr.IntOrString	(Optional) Controls the concurrency of pods during initial scale up, when replacing pods on nodes, or when scaling down. It only used when PodManagementPolicy is set to Parallel. The default Concurrency is 100%.
podUpdatePolicy PodUpdatePolicyType	(Optional) PodUpdatePolicy indicates how pods should be updated StrictInPlace indicates that only allows in-place upgrades. Any attempt to modify other fields will be rejected. PreferInPlace indicates that we will first attempt an in-place upgrade of the Pod. If that fails, it will fall back to the ReCreate, where pod will be recreated. Default value is “PreferInPlace”
updateStrategy Kubernetes apps/v1.StatefulSetUpdateStrategy	Indicates the StatefulSetUpdateStrategy that will be employed to update Pods in the InstanceSet when a revision is made to Template. UpdateStrategy.Type will be set to appsv1.OnDeleteStatefulSetStrategyType if MemberUpdateStrategy is not nil Note: This field will be removed in future version.
roles []ReplicaRole	(Optional) A list of roles defined in the system. Instanceset obtains role through pods’ role label kubeblocks.io/role.
membershipReconfiguration MembershipReconfiguration	(Optional) Provides actions to do membership dynamic reconfiguration.
templateVars map[string]string	(Optional) Provides variables which are used to call Actions.
memberUpdateStrategy MemberUpdateStrategy	(Optional) Members(Pods) update strategy. serial: update Members one by one that guarantee minimum component unavailable time. bestEffortParallel: update Members in parallel that guarantee minimum component un-writable time. parallel: force parallel
paused bool	(Optional) Indicates that the InstanceSet is paused, meaning the reconciliation of this InstanceSet object will be paused.
credential Credential	(Optional) Credential used to connect to DB engine

InstanceSetStatus

(Appears on:InstanceSet)

InstanceSetStatus defines the observed state of InstanceSet

Field	Description
observedGeneration int64	(Optional) observedGeneration is the most recent generation observed for this InstanceSet. It corresponds to the InstanceSet’s generation, which is updated on mutation by the API Server.
replicas int32	replicas is the number of instances created by the InstanceSet controller.
readyReplicas int32	readyReplicas is the number of instances created for this InstanceSet with a Ready Condition.
currentReplicas int32	currentReplicas is the number of instances created by the InstanceSet controller from the InstanceSet version indicated by CurrentRevisions.
updatedReplicas int32	updatedReplicas is the number of instances created by the InstanceSet controller from the InstanceSet version indicated by UpdateRevisions.
currentRevision string	currentRevision, if not empty, indicates the version of the InstanceSet used to generate instances in the sequence [0,currentReplicas).
updateRevision string	updateRevision, if not empty, indicates the version of the InstanceSet used to generate instances in the sequence [replicas-updatedReplicas,replicas)
conditions []Kubernetes meta/v1.Condition	(Optional) Represents the latest available observations of an instanceset’s current state. Known .status.conditions.type are: “InstanceFailure”, “InstanceReady”
availableReplicas int32	(Optional) Total number of available instances (ready for at least minReadySeconds) targeted by this InstanceSet.
initReplicas int32	(Optional) Defines the initial number of instances when the cluster is first initialized. This value is set to spec.Replicas at the time of object creation and remains constant thereafter. Used only when spec.roles set.
readyInitReplicas int32	(Optional) Represents the number of instances that have already reached the MembersStatus during the cluster initialization stage. This value remains constant once it equals InitReplicas. Used only when spec.roles set.
membersStatus []MemberStatus	(Optional) Provides the status of each member in the cluster.
currentRevisions map[string]string	(Optional) currentRevisions, if not empty, indicates the old version of the InstanceSet used to generate the underlying workload. key is the pod name, value is the revision.
updateRevisions map[string]string	(Optional) updateRevisions, if not empty, indicates the new version of the InstanceSet used to generate the underlying workload. key is the pod name, value is the revision.
templatesStatus []InstanceTemplateStatus	(Optional) TemplatesStatus represents status of each instance generated by InstanceTemplates

InstanceTemplateStatus

(Appears on:InstanceSetStatus)

InstanceTemplateStatus aggregates the status of replicas for each InstanceTemplate

Field	Description
name string	Name, the name of the InstanceTemplate.
replicas int32	(Optional) Replicas is the number of replicas of the InstanceTemplate.
readyReplicas int32	(Optional) ReadyReplicas is the number of Pods that have a Ready Condition.
availableReplicas int32	(Optional) AvailableReplicas is the number of Pods that ready for at least minReadySeconds.
currentReplicas int32	currentReplicas is the number of instances created by the InstanceSet controller from the InstanceSet version indicated by CurrentRevisions.
updatedReplicas int32	(Optional) UpdatedReplicas is the number of Pods created by the InstanceSet controller from the InstanceSet version indicated by UpdateRevisions.

MemberStatus

(Appears on:InstanceSetStatus)

Field	Description
podName string	Represents the name of the pod.
role ReplicaRole	(Optional) Defines the role of the replica in the cluster.

MemberUpdateStrategy (string alias)

(Appears on:InstanceSetSpec)

MemberUpdateStrategy defines Cluster Component update strategy.

Value	Description
"BestEffortParallel"
"Parallel"
"Serial"

MembershipReconfiguration

(Appears on:InstanceSetSpec)

Field	Description
switchoverAction Action	(Optional) Specifies the environment variables that can be used in all following Actions: KB_ITS_USERNAME: Represents the username part of the credential KB_ITS_PASSWORD: Represents the password part of the credential KB_ITS_LEADER_HOST: Represents the leader host KB_ITS_TARGET_HOST: Represents the target host KB_ITS_SERVICE_PORT: Represents the service port Defines the action to perform a switchover. If the Image is not configured, the latest BusyBox image will be used.
memberJoinAction Action	(Optional) Defines the action to add a member. If the Image is not configured, the Image from the previous non-nil action will be used.
memberLeaveAction Action	(Optional) Defines the action to remove a member. If the Image is not configured, the Image from the previous non-nil action will be used.
logSyncAction Action	(Optional) Defines the action to trigger the new member to start log syncing. If the Image is not configured, the Image from the previous non-nil action will be used.
promoteAction Action	(Optional) Defines the action to inform the cluster that the new member can join voting now. If the Image is not configured, the Image from the previous non-nil action will be used.
switchover Action	(Optional) Defines the procedure for a controlled transition of a role to a new replica.

PodUpdatePolicyType (string alias)

(Appears on:InstanceSetSpec)

Value	Description
"PreferInPlace"	PreferInPlacePodUpdatePolicyType indicates that we will first attempt an in-place upgrade of the Pod. If that fails, it will fall back to the ReCreate, where pod will be recreated.
"StrictInPlace"	StrictInPlacePodUpdatePolicyType indicates that only allows in-place upgrades. Any attempt to modify other fields will be rejected.

RoleUpdateMechanism (string alias)

RoleUpdateMechanism defines the way how pod role label being updated.

Value	Description
"DirectAPIServerEventUpdate"
"ReadinessProbeEventUpdate"

---

workloads.kubeblocks.io/v1alpha1

Resource Types:

• InstanceSet

InstanceSet

InstanceSet is the Schema for the instancesets API.

Field	Description
apiVersion string	workloads.kubeblocks.io/v1alpha1
kind string	InstanceSet
metadata Kubernetes meta/v1.ObjectMeta	Contains the metadata for the particular object, such as name, namespace, labels, and annotations. Refer to the Kubernetes API documentation for the fields of the metadata field.
spec InstanceSetSpec	Defines the desired state of the state machine. It includes the configuration details for the state machine. replicas int32 (Optional) Specifies the desired number of replicas of the given Template. These replicas are instantiations of the same Template, with each having a consistent identity. Defaults to 1 if unspecified. defaultTemplateOrdinals Ordinals Specifies the desired Ordinals of the default template. The Ordinals used to specify the ordinal of the instance (pod) names to be generated under the default template. For example, if Ordinals is {ranges: [{start: 0, end: 1}], discrete: [7]}, then the instance names generated under the default template would be $(cluster.name)-$(component.name)-0、$(cluster.name)-$(component.name)-1 and $(cluster.name)-$(component.name)-7 minReadySeconds int32 (Optional) Defines the minimum number of seconds a newly created pod should be ready without any of its container crashing to be considered available. Defaults to 0, meaning the pod will be considered available as soon as it is ready. selector Kubernetes meta/v1.LabelSelector Represents a label query over pods that should match the desired replica count indicated by the replica field. It must match the labels defined in the pod template. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors service Kubernetes core/v1.Service (Optional) Defines the behavior of a service spec. Provides read-write service. https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status Note: This field will be removed in future version. template Kubernetes core/v1.PodTemplateSpec instances []InstanceTemplate (Optional) Overrides values in default Template. Instance is the fundamental unit managed by KubeBlocks. It represents a Pod with additional objects such as PVCs, Services, ConfigMaps, etc. An InstanceSet manages instances with a total count of Replicas, and by default, all these instances are generated from the same template. The InstanceTemplate provides a way to override values in the default template, allowing the InstanceSet to manage instances from different templates. The naming convention for instances (pods) based on the InstanceSet Name, InstanceTemplate Name, and ordinal. The constructed instance name follows the pattern: $(instance_set.name)-$(template.name)-$(ordinal). By default, the ordinal starts from 0 for each InstanceTemplate. It is important to ensure that the Name of each InstanceTemplate is unique. The sum of replicas across all InstanceTemplates should not exceed the total number of Replicas specified for the InstanceSet. Any remaining replicas will be generated using the default template and will follow the default naming rules. offlineInstances []string (Optional) Specifies the names of instances to be transitioned to offline status. Marking an instance as offline results in the following: The associated pod is stopped, and its PersistentVolumeClaim (PVC) is retained for potential future reuse or data recovery, but it is no longer actively used. The ordinal number assigned to this instance is preserved, ensuring it remains unique and avoiding conflicts with new instances. Setting instances to offline allows for a controlled scale-in process, preserving their data and maintaining ordinal consistency within the cluster. Note that offline instances and their associated resources, such as PVCs, are not automatically deleted. The cluster administrator must manually manage the cleanup and removal of these resources when they are no longer needed. volumeClaimTemplates []Kubernetes core/v1.PersistentVolumeClaim (Optional) Specifies a list of PersistentVolumeClaim templates that define the storage requirements for each replica. Each template specifies the desired characteristics of a persistent volume, such as storage class, size, and access modes. These templates are used to dynamically provision persistent volumes for replicas upon their creation. The final name of each PVC is generated by appending the pod’s identifier to the name specified in volumeClaimTemplates[*].name. podManagementPolicy Kubernetes apps/v1.PodManagementPolicyType (Optional) Controls how pods are created during initial scale up, when replacing pods on nodes, or when scaling down. The default policy is OrderedReady, where pods are created in increasing order and the controller waits until each pod is ready before continuing. When scaling down, the pods are removed in the opposite order. The alternative policy is Parallel which will create pods in parallel to match the desired scale without waiting, and on scale down will delete all pods at once. Note: This field will be removed in future version. parallelPodManagementConcurrency Kubernetes api utils intstr.IntOrString (Optional) Controls the concurrency of pods during initial scale up, when replacing pods on nodes, or when scaling down. It only used when PodManagementPolicy is set to Parallel. The default Concurrency is 100%. podUpdatePolicy PodUpdatePolicyType (Optional) PodUpdatePolicy indicates how pods should be updated StrictInPlace indicates that only allows in-place upgrades. Any attempt to modify other fields will be rejected. PreferInPlace indicates that we will first attempt an in-place upgrade of the Pod. If that fails, it will fall back to the ReCreate, where pod will be recreated. Default value is “PreferInPlace” updateStrategy InstanceUpdateStrategy Indicates the StatefulSetUpdateStrategy that will be employed to update Pods in the InstanceSet when a revision is made to Template. Note: This field will be removed in future version. roles []ReplicaRole (Optional) A list of roles defined in the system. roleProbe RoleProbe (Optional) Provides method to probe role. membershipReconfiguration MembershipReconfiguration (Optional) Provides actions to do membership dynamic reconfiguration. memberUpdateStrategy MemberUpdateStrategy (Optional) Members(Pods) update strategy. serial: update Members one by one that guarantee minimum component unavailable time. bestEffortParallel: update Members in parallel that guarantee minimum component un-writable time. parallel: force parallel paused bool (Optional) Indicates that the InstanceSet is paused, meaning the reconciliation of this InstanceSet object will be paused. credential Credential (Optional) Credential used to connect to DB engine
status InstanceSetStatus	Represents the current information about the state machine. This data may be out of date.

AccessMode (string alias)

(Appears on:ReplicaRole)

AccessMode defines SVC access mode enums.

Value	Description
"None"
"ReadWrite"
"Readonly"

Action

(Appears on:MembershipReconfiguration, RoleProbe)

Field	Description
image string	(Optional) Refers to the utility image that contains the command which can be utilized to retrieve or process role information.
command []string	A set of instructions that will be executed within the Container to retrieve or process role information. This field is required.
args []string	(Optional) Additional parameters used to perform specific statements. This field is optional.

ConditionType (string alias)

Value	Description
"InstanceAvailable"	InstanceAvailable ConditionStatus will be True if all instances(pods) are in the ready condition and continue for “MinReadySeconds” seconds. Otherwise, it will be set to False.
"InstanceFailure"	InstanceFailure is added in an instance set when at least one of its instances(pods) is in a Failed phase.
"InstanceReady"	InstanceReady is added in an instance set when at least one of its instances(pods) is in a Ready condition. ConditionStatus will be True if all its instances(pods) are in a Ready condition. Or, a NotReady reason with not ready instances encoded in the Message filed will be set.
"InstanceUpdateRestricted"	InstanceUpdateRestricted represents a ConditionType that indicates updates to an InstanceSet are blocked(when the PodUpdatePolicy is set to StrictInPlace but the pods cannot be updated in-place).

Credential

(Appears on:InstanceSetSpec)

Field	Description
username CredentialVar	Defines the user’s name for the credential. The corresponding environment variable will be KB_ITS_USERNAME.
password CredentialVar	Represents the user’s password for the credential. The corresponding environment variable will be KB_ITS_PASSWORD.

CredentialVar

(Appears on:Credential)

Field	Description
value string	(Optional) Specifies the value of the environment variable. This field is optional and defaults to an empty string. The value can include variable references in the format $(VAR_NAME) which will be expanded using previously defined environment variables in the container and any service environment variables. If a variable cannot be resolved, the reference in the input string will remain unchanged. Double $$ can be used to escape the $(VAR_NAME) syntax, resulting in a single $ and producing the string literal “$(VAR_NAME)”. Escaped references will not be expanded, regardless of whether the variable exists or not.
valueFrom Kubernetes core/v1.EnvVarSource	(Optional) Defines the source for the environment variable’s value. This field is optional and cannot be used if the ‘Value’ field is not empty.

InstanceSetSpec

(Appears on:InstanceSet)

InstanceSetSpec defines the desired state of InstanceSet

Field	Description
replicas int32	(Optional) Specifies the desired number of replicas of the given Template. These replicas are instantiations of the same Template, with each having a consistent identity. Defaults to 1 if unspecified.
defaultTemplateOrdinals Ordinals	Specifies the desired Ordinals of the default template. The Ordinals used to specify the ordinal of the instance (pod) names to be generated under the default template. For example, if Ordinals is {ranges: [{start: 0, end: 1}], discrete: [7]}, then the instance names generated under the default template would be $(cluster.name)-$(component.name)-0、$(cluster.name)-$(component.name)-1 and $(cluster.name)-$(component.name)-7
minReadySeconds int32	(Optional) Defines the minimum number of seconds a newly created pod should be ready without any of its container crashing to be considered available. Defaults to 0, meaning the pod will be considered available as soon as it is ready.
selector Kubernetes meta/v1.LabelSelector	Represents a label query over pods that should match the desired replica count indicated by the replica field. It must match the labels defined in the pod template. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors
service Kubernetes core/v1.Service	(Optional) Defines the behavior of a service spec. Provides read-write service. https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status Note: This field will be removed in future version.
template Kubernetes core/v1.PodTemplateSpec
instances []InstanceTemplate	(Optional) Overrides values in default Template. Instance is the fundamental unit managed by KubeBlocks. It represents a Pod with additional objects such as PVCs, Services, ConfigMaps, etc. An InstanceSet manages instances with a total count of Replicas, and by default, all these instances are generated from the same template. The InstanceTemplate provides a way to override values in the default template, allowing the InstanceSet to manage instances from different templates. The naming convention for instances (pods) based on the InstanceSet Name, InstanceTemplate Name, and ordinal. The constructed instance name follows the pattern: $(instance_set.name)-$(template.name)-$(ordinal). By default, the ordinal starts from 0 for each InstanceTemplate. It is important to ensure that the Name of each InstanceTemplate is unique. The sum of replicas across all InstanceTemplates should not exceed the total number of Replicas specified for the InstanceSet. Any remaining replicas will be generated using the default template and will follow the default naming rules.
offlineInstances []string	(Optional) Specifies the names of instances to be transitioned to offline status. Marking an instance as offline results in the following: The associated pod is stopped, and its PersistentVolumeClaim (PVC) is retained for potential future reuse or data recovery, but it is no longer actively used. The ordinal number assigned to this instance is preserved, ensuring it remains unique and avoiding conflicts with new instances. Setting instances to offline allows for a controlled scale-in process, preserving their data and maintaining ordinal consistency within the cluster. Note that offline instances and their associated resources, such as PVCs, are not automatically deleted. The cluster administrator must manually manage the cleanup and removal of these resources when they are no longer needed.
volumeClaimTemplates []Kubernetes core/v1.PersistentVolumeClaim	(Optional) Specifies a list of PersistentVolumeClaim templates that define the storage requirements for each replica. Each template specifies the desired characteristics of a persistent volume, such as storage class, size, and access modes. These templates are used to dynamically provision persistent volumes for replicas upon their creation. The final name of each PVC is generated by appending the pod’s identifier to the name specified in volumeClaimTemplates[*].name.
podManagementPolicy Kubernetes apps/v1.PodManagementPolicyType	(Optional) Controls how pods are created during initial scale up, when replacing pods on nodes, or when scaling down. The default policy is OrderedReady, where pods are created in increasing order and the controller waits until each pod is ready before continuing. When scaling down, the pods are removed in the opposite order. The alternative policy is Parallel which will create pods in parallel to match the desired scale without waiting, and on scale down will delete all pods at once. Note: This field will be removed in future version.
parallelPodManagementConcurrency Kubernetes api utils intstr.IntOrString	(Optional) Controls the concurrency of pods during initial scale up, when replacing pods on nodes, or when scaling down. It only used when PodManagementPolicy is set to Parallel. The default Concurrency is 100%.
podUpdatePolicy PodUpdatePolicyType	(Optional) PodUpdatePolicy indicates how pods should be updated StrictInPlace indicates that only allows in-place upgrades. Any attempt to modify other fields will be rejected. PreferInPlace indicates that we will first attempt an in-place upgrade of the Pod. If that fails, it will fall back to the ReCreate, where pod will be recreated. Default value is “PreferInPlace”
updateStrategy InstanceUpdateStrategy	Indicates the StatefulSetUpdateStrategy that will be employed to update Pods in the InstanceSet when a revision is made to Template. Note: This field will be removed in future version.
roles []ReplicaRole	(Optional) A list of roles defined in the system.
roleProbe RoleProbe	(Optional) Provides method to probe role.
membershipReconfiguration MembershipReconfiguration	(Optional) Provides actions to do membership dynamic reconfiguration.
memberUpdateStrategy MemberUpdateStrategy	(Optional) Members(Pods) update strategy. serial: update Members one by one that guarantee minimum component unavailable time. bestEffortParallel: update Members in parallel that guarantee minimum component un-writable time. parallel: force parallel
paused bool	(Optional) Indicates that the InstanceSet is paused, meaning the reconciliation of this InstanceSet object will be paused.
credential Credential	(Optional) Credential used to connect to DB engine

InstanceSetStatus

(Appears on:InstanceSet)

InstanceSetStatus defines the observed state of InstanceSet

Field	Description
observedGeneration int64	(Optional) observedGeneration is the most recent generation observed for this InstanceSet. It corresponds to the InstanceSet’s generation, which is updated on mutation by the API Server.
replicas int32	replicas is the number of instances created by the InstanceSet controller.
readyReplicas int32	readyReplicas is the number of instances created for this InstanceSet with a Ready Condition.
currentReplicas int32	currentReplicas is the number of instances created by the InstanceSet controller from the InstanceSet version indicated by CurrentRevisions.
updatedReplicas int32	updatedReplicas is the number of instances created by the InstanceSet controller from the InstanceSet version indicated by UpdateRevisions.
currentRevision string	currentRevision, if not empty, indicates the version of the InstanceSet used to generate instances in the sequence [0,currentReplicas).
updateRevision string	updateRevision, if not empty, indicates the version of the InstanceSet used to generate instances in the sequence [replicas-updatedReplicas,replicas)
conditions []Kubernetes meta/v1.Condition	(Optional) Represents the latest available observations of an instanceset’s current state. Known .status.conditions.type are: “InstanceFailure”, “InstanceReady”
availableReplicas int32	(Optional) Total number of available instances (ready for at least minReadySeconds) targeted by this InstanceSet.
initReplicas int32	(Optional) Defines the initial number of instances when the cluster is first initialized. This value is set to spec.Replicas at the time of object creation and remains constant thereafter. Used only when spec.roles set.
readyInitReplicas int32	(Optional) Represents the number of instances that have already reached the MembersStatus during the cluster initialization stage. This value remains constant once it equals InitReplicas. Used only when spec.roles set.
membersStatus []MemberStatus	(Optional) Provides the status of each member in the cluster.
readyWithoutPrimary bool	(Optional) Indicates whether it is required for the InstanceSet to have at least one primary instance ready.
currentRevisions map[string]string	(Optional) currentRevisions, if not empty, indicates the old version of the InstanceSet used to generate the underlying workload. key is the pod name, value is the revision.
updateRevisions map[string]string	(Optional) updateRevisions, if not empty, indicates the new version of the InstanceSet used to generate the underlying workload. key is the pod name, value is the revision.
templatesStatus []InstanceTemplateStatus	(Optional) TemplatesStatus represents status of each instance generated by InstanceTemplates

InstanceTemplate

(Appears on:InstanceSetSpec)

InstanceTemplate allows customization of individual replica configurations within a Component, without altering the base component template defined in ClusterComponentSpec. It enables the application of distinct settings to specific instances (replicas), providing flexibility while maintaining a common configuration baseline.

Field	Description
name string	Name specifies the unique name of the instance Pod created using this InstanceTemplate. This name is constructed by concatenating the component’s name, the template’s name, and the instance’s ordinal using the pattern: $(cluster.name)-$(component.name)-$(template.name)-$(ordinal). Ordinals start from 0. The specified name overrides any default naming conventions or patterns.
replicas int32	(Optional) Specifies the number of instances (Pods) to create from this InstanceTemplate. This field allows setting how many replicated instances of the component, with the specific overrides in the InstanceTemplate, are created. The default value is 1. A value of 0 disables instance creation.
ordinals Ordinals	Specifies the desired Ordinals of this InstanceTemplate. The Ordinals used to specify the ordinal of the instance (pod) names to be generated under this InstanceTemplate. For example, if Ordinals is {ranges: [{start: 0, end: 1}], discrete: [7]}, then the instance names generated under this InstanceTemplate would be $(cluster.name)-$(component.name)-$(template.name)-0、$(cluster.name)-$(component.name)-$(template.name)-1 and $(cluster.name)-$(component.name)-$(template.name)-7
annotations map[string]string	(Optional) Specifies a map of key-value pairs to be merged into the Pod’s existing annotations. Existing keys will have their values overwritten, while new keys will be added to the annotations.
labels map[string]string	(Optional) Specifies a map of key-value pairs that will be merged into the Pod’s existing labels. Values for existing keys will be overwritten, and new keys will be added.
image string	(Optional) Specifies an override for the first container’s image in the pod.
schedulingPolicy SchedulingPolicy	(Optional) Specifies the scheduling policy for the Component.
resources Kubernetes core/v1.ResourceRequirements	(Optional) Specifies an override for the resource requirements of the first container in the Pod. This field allows for customizing resource allocation (CPU, memory, etc.) for the container.
env []Kubernetes core/v1.EnvVar	(Optional) Defines Env to override. Add new or override existing envs.
volumes []Kubernetes core/v1.Volume	(Optional) Defines Volumes to override. Add new or override existing volumes.
volumeMounts []Kubernetes core/v1.VolumeMount	(Optional) Defines VolumeMounts to override. Add new or override existing volume mounts of the first container in the pod.
volumeClaimTemplates []Kubernetes core/v1.PersistentVolumeClaim	(Optional) Defines VolumeClaimTemplates to override. Add new or override existing volume claim templates.

InstanceTemplateStatus

(Appears on:InstanceSetStatus)

InstanceTemplateStatus aggregates the status of replicas for each InstanceTemplate

Field	Description
name string	Name, the name of the InstanceTemplate.
replicas int32	(Optional) Replicas is the number of replicas of the InstanceTemplate.
readyReplicas int32	(Optional) ReadyReplicas is the number of Pods that have a Ready Condition.
availableReplicas int32	(Optional) AvailableReplicas is the number of Pods that ready for at least minReadySeconds.
currentReplicas int32	currentReplicas is the number of instances created by the InstanceSet controller from the InstanceSet version indicated by CurrentRevisions.
updatedReplicas int32	(Optional) UpdatedReplicas is the number of Pods created by the InstanceSet controller from the InstanceSet version indicated by UpdateRevisions.

InstanceUpdateStrategy

(Appears on:InstanceSetSpec)

InstanceUpdateStrategy indicates the strategy that the InstanceSet controller will use to perform updates. It includes any additional parameters necessary to perform the update for the indicated strategy.

Field	Description
partition int32	(Optional) Partition indicates the number of pods that should be updated during a rolling update. The remaining pods will remain untouched. This is helpful in defining how many pods should participate in the update process. The update process will follow the order of pod names in descending lexicographical (dictionary) order. The default value is Replicas (i.e., update all pods).
maxUnavailable Kubernetes api utils intstr.IntOrString	(Optional) The maximum number of pods that can be unavailable during the update. Value can be an absolute number (ex: 5) or a percentage of desired pods (ex: 10%). Absolute number is calculated from percentage by rounding up. This can not be 0. Defaults to 1. The field applies to all pods. That means if there is any unavailable pod, it will be counted towards MaxUnavailable.
memberUpdateStrategy MemberUpdateStrategy	(Optional) Members(Pods) update strategy. serial: update Members one by one that guarantee minimum component unavailable time. bestEffortParallel: update Members in parallel that guarantee minimum component un-writable time. parallel: force parallel

MemberStatus

(Appears on:ClusterComponentStatus, InstanceSetStatus)

Field	Description
podName string	Represents the name of the pod.
role ReplicaRole	(Optional) Defines the role of the replica in the cluster.

MemberUpdateStrategy (string alias)

(Appears on:RSMSpec, InstanceSetSpec, InstanceUpdateStrategy)

MemberUpdateStrategy defines Cluster Component update strategy.

Value	Description
"BestEffortParallel"
"Parallel"
"Serial"

MembershipReconfiguration

(Appears on:RSMSpec, InstanceSetSpec)

Field	Description
switchoverAction Action	(Optional) Specifies the environment variables that can be used in all following Actions: KB_ITS_USERNAME: Represents the username part of the credential KB_ITS_PASSWORD: Represents the password part of the credential KB_ITS_LEADER_HOST: Represents the leader host KB_ITS_TARGET_HOST: Represents the target host KB_ITS_SERVICE_PORT: Represents the service port Defines the action to perform a switchover. If the Image is not configured, the latest BusyBox image will be used.
memberJoinAction Action	(Optional) Defines the action to add a member. If the Image is not configured, the Image from the previous non-nil action will be used.
memberLeaveAction Action	(Optional) Defines the action to remove a member. If the Image is not configured, the Image from the previous non-nil action will be used.
logSyncAction Action	(Optional) Defines the action to trigger the new member to start log syncing. If the Image is not configured, the Image from the previous non-nil action will be used.
promoteAction Action	(Optional) Defines the action to inform the cluster that the new member can join voting now. If the Image is not configured, the Image from the previous non-nil action will be used.

Ordinals

(Appears on:InstanceSetSpec, InstanceTemplate)

Ordinals represents a combination of continuous segments and individual values.

Field	Description
ranges []Range
discrete []int32

PodUpdatePolicyType (string alias)

(Appears on:ClusterComponentSpec, ComponentSpec, InstanceSetSpec)

Value	Description
"PreferInPlace"	PreferInPlacePodUpdatePolicyType indicates that we will first attempt an in-place upgrade of the Pod. If that fails, it will fall back to the ReCreate, where pod will be recreated.
"StrictInPlace"	StrictInPlacePodUpdatePolicyType indicates that only allows in-place upgrades. Any attempt to modify other fields will be rejected.

Range

(Appears on:Ordinals)

Range represents a range with a start and an end value. It is used to define a continuous segment.

Field	Description
start int32
end int32

ReplicaRole

(Appears on:RSMSpec, InstanceSetSpec, MemberStatus)

Field	Description
name string	Defines the role name of the replica.
accessMode AccessMode	Specifies the service capabilities of this member.
canVote bool	(Optional) Indicates if this member has voting rights.
isLeader bool	(Optional) Determines if this member is the leader.

RoleProbe

(Appears on:RSMSpec, InstanceSetSpec)

RoleProbe defines how to observe role

Field	Description
builtinHandlerName string	(Optional) Specifies the builtin handler name to use to probe the role of the main container. Available handlers include: mysql, postgres, mongodb, redis, etcd, kafka. Use CustomHandler to define a custom role probe function if none of the built-in handlers meet the requirement.
customHandler []Action	(Optional) Defines a custom method for role probing. Actions defined here are executed in series. Upon completion of all actions, the final output should be a single string representing the role name defined in spec.Roles. The latest BusyBox image will be used if Image is not configured. Environment variables can be used in Command: v_KB_ITS_LASTSTDOUT: stdout from the last action, watch for ‘v’ prefix KB_ITS_USERNAME: username part of the credential KB_ITS_PASSWORD: password part of the credential
initialDelaySeconds int32	(Optional) Specifies the number of seconds to wait after the container has started before initiating role probing.
timeoutSeconds int32	(Optional) Specifies the number of seconds after which the probe times out.
periodSeconds int32	(Optional) Specifies the frequency (in seconds) of probe execution.
successThreshold int32	(Optional) Specifies the minimum number of consecutive successes for the probe to be considered successful after having failed.
failureThreshold int32	(Optional) Specifies the minimum number of consecutive failures for the probe to be considered failed after having succeeded.
roleUpdateMechanism RoleUpdateMechanism	(Optional) Specifies the method for updating the pod role label.

RoleUpdateMechanism (string alias)

(Appears on:RoleProbe)

RoleUpdateMechanism defines the way how pod role label being updated.

Value	Description
"DirectAPIServerEventUpdate"
"ReadinessProbeEventUpdate"

SchedulingPolicy

(Appears on:InstanceTemplate)

SchedulingPolicy the scheduling policy. Deprecated: Unify with apps/v1alpha1.SchedulingPolicy

Field	Description
schedulerName string	(Optional) If specified, the Pod will be dispatched by specified scheduler. If not specified, the Pod will be dispatched by default scheduler.
nodeSelector map[string]string	(Optional) NodeSelector is a selector which must be true for the Pod to fit on a node. Selector which must match a node’s labels for the Pod to be scheduled on that node. More info: https://kubernetes.io/docs/concepts/configuration/assign-pod-node/
nodeName string	(Optional) NodeName is a request to schedule this Pod onto a specific node. If it is non-empty, the scheduler simply schedules this Pod onto that node, assuming that it fits resource requirements.
affinity Kubernetes core/v1.Affinity	(Optional) Specifies a group of affinity scheduling rules of the Cluster, including NodeAffinity, PodAffinity, and PodAntiAffinity.
tolerations []Kubernetes core/v1.Toleration	(Optional) Allows Pods to be scheduled onto nodes with matching taints. Each toleration in the array allows the Pod to tolerate node taints based on specified key, value, effect, and operator. The key, value, and effect identify the taint that the toleration matches. The operator determines how the toleration matches the taint. Pods with matching tolerations are allowed to be scheduled on tainted nodes, typically reserved for specific purposes.
topologySpreadConstraints []Kubernetes core/v1.TopologySpreadConstraint	(Optional) TopologySpreadConstraints describes how a group of Pods ought to spread across topology domains. Scheduler will schedule Pods in a way which abides by the constraints. All topologySpreadConstraints are ANDed.

---

Generated with gen-crd-api-reference-docs