Cluster API Reference
Packages:
apps.kubeblocks.io/v1alpha1
Resource Types:- Cluster
- ClusterDefinition
- Component
- ComponentDefinition
- ComponentVersion
- ConfigConstraint
- Configuration
- OpsDefinition
- OpsRequest
- 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 themetadata field. | ||||||||||||||||||||||||||||||||||||
spec ClusterSpec |
| ||||||||||||||||||||||||||||||||||||
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 themetadata field. | ||
spec ClusterDefinitionSpec |
| ||
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 themetadata field. | ||||||||||||||||||||||||||||||||||||||||||||||||||||
spec ComponentSpec |
| ||||||||||||||||||||||||||||||||||||||||||||||||||||
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 themetadata field. | ||||||||||||||||||||||||||||||||||||||||||||||||
spec ComponentDefinitionSpec |
| ||||||||||||||||||||||||||||||||||||||||||||||||
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 themetadata field. | ||||
spec ComponentVersionSpec |
| ||||
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:
- Parameter Value Validation: Validates and ensures compliance of parameter values with defined constraints.
- Dynamic Reload on Modification: Monitors parameter changes and triggers dynamic reloads to apply updates.
- 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 themetadata field. | ||||||||||||||||||||||||||
spec ConfigConstraintSpec |
| ||||||||||||||||||||||||||
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 themetadata field. | ||||||
spec ConfigurationSpec |
| ||||||
status ConfigurationStatus |
OpsDefinition
OpsDefinition is the Schema for the OpsDefinitions API.
Field | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
apiVersion string | apps.kubeblocks.io/v1alpha1 | ||||||||||
kind string | OpsDefinition | ||||||||||
metadata Kubernetes meta/v1.ObjectMeta | Refer to the Kubernetes API documentation for the fields of themetadata field. | ||||||||||
spec OpsDefinitionSpec |
| ||||||||||
status OpsDefinitionStatus |
OpsRequest
OpsRequest is the Schema for the opsrequests API
Field | Description | ||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
apiVersion string | apps.kubeblocks.io/v1alpha1 | ||||||||||||||||||||||
kind string | OpsRequest | ||||||||||||||||||||||
metadata Kubernetes meta/v1.ObjectMeta | Refer to the Kubernetes API documentation for the fields of themetadata field. | ||||||||||||||||||||||
spec OpsRequestSpec |
| ||||||||||||||||||||||
status OpsRequestStatus |
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 themetadata field. | ||||||||||||
spec ServiceDescriptorSpec |
| ||||||||||||
status ServiceDescriptorStatus |
AccessMode (string
alias)
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. |
Action
(Appears on:ComponentLifecycleActions, 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, withpreCondition
specifying when the action should be fired relative to the Component’s lifecycle stages:Immediately
,RuntimeReady
,ComponentReady
, andClusterReady
.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. 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 The conditions are as follows:
This field cannot be updated. |
ActionTask
(Appears on:ProgressStatusDetail)
Field | Description |
---|---|
objectKey string | Represents the name of the task. |
namespace string | Represents the namespace where the task is deployed. |
status ActionTaskStatus | Indicates the current status of the task, including “Processing”, “Failed”, “Succeed”. |
targetPodName string | (Optional) The name of the Pod that the task is associated with or operates on. |
retries int32 | (Optional) The count of retry attempts made for this task. |
ActionTaskStatus (string
alias)
(Appears on:ActionTask)
ActionTaskStatus defines the status of the task.
Value | Description |
---|---|
"Failed" | |
"Processing" | |
"Succeed" |
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: |
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 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:
The default value is |
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. |
Backup
(Appears on:SpecificOpsRequest)
Field | Description |
---|---|
backupName string | (Optional) Specifies the name of the Backup custom resource. |
backupPolicyName string | (Optional) Indicates the name of the BackupPolicy applied to perform this Backup. |
backupMethod string | (Optional) Specifies the name of BackupMethod. The specified BackupMethod must be defined in the BackupPolicy. |
deletionPolicy string | (Optional) Determines whether the backup contents stored in backup repository should be deleted when the Backup custom resource is deleted. Supported values are |
retentionPeriod string | (Optional) Determines the duration for which the Backup custom resources should be retained. The controller will automatically remove all Backup objects that are older than the specified RetentionPeriod. For example, RetentionPeriod of
You can also combine the above durations. For example: 30d12h30m. If not set, the Backup objects will be kept forever. If the |
parentBackupName string | (Optional) If the specified BackupMethod is incremental, |
BackupMethod
(Appears on:BackupPolicy)
Field | Description |
---|---|
BackupMethod github.com/apecloud/kubeblocks/apis/dataprotection/v1alpha1.BackupMethod | (Members of Specifies the name of dataprotection.BackupMethod. |
target TargetInstance | (Optional) If set, specifies the method for selecting the replica to be backed up using the criteria defined here. If this field is not set, the selection method specified in This field provides a way to override the global |
envMapping []EnvMappingVar | (Optional) Specifies a mapping of an environment variable key to the appropriate version of the tool image required for backups, as determined by ClusterVersion and ComponentDefinition. The environment variable is then injected into the container executing the backup task. |
BackupPolicy
(Appears on:BackupPolicyTemplateSpec)
BackupPolicy is the template corresponding to a specified ComponentDefinition or to a group of ComponentDefinitions that are different versions of definitions of the same component.
Field | Description |
---|---|
componentDefs []string | (Optional) Specifies a list of names of ComponentDefinitions that the specified ClusterDefinition references. They should be different versions of definitions of the same component, thus allowing them to share a single BackupPolicy. Each name must adhere to the IANA Service Naming rule. |
target TargetInstance | (Optional) Defines the selection criteria of instance to be backed up, and the connection credential to be used during the backup process. |
schedules []SchedulePolicy | (Optional) Defines the execution plans for backup tasks, specifying when and how backups should occur, and the retention period of backup files. |
backupMethods []BackupMethod | Defines an array of BackupMethods to be used. |
backoffLimit int32 | (Optional) Specifies the maximum number of retry attempts for a backup before it is considered a failure. |
BackupPolicyTemplate
BackupPolicyTemplate should be provided by addon developers and is linked to a ClusterDefinition and its associated ComponentDefinitions. It is responsible for generating BackupPolicies for Components that require backup operations, also determining the suitable backup methods and strategies. This template is automatically selected based on the specified ClusterDefinition and ComponentDefinitions when a Cluster is created.
Field | Description | ||||
---|---|---|---|---|---|
metadata Kubernetes meta/v1.ObjectMeta | The metadata for the BackupPolicyTemplate object, including name, namespace, labels, and annotations. Refer to the Kubernetes API documentation for the fields of themetadata field. | ||||
spec BackupPolicyTemplateSpec | Defines the desired state of the BackupPolicyTemplate.
| ||||
status BackupPolicyTemplateStatus | Populated by the system, it represents the current information about the BackupPolicyTemplate. |
BackupPolicyTemplateSpec
(Appears on:BackupPolicyTemplate)
BackupPolicyTemplateSpec contains the settings in a BackupPolicyTemplate.
Field | Description |
---|---|
backupPolicies []BackupPolicy | Represents an array of BackupPolicy templates, with each template corresponding to a specified ComponentDefinition or to a group of ComponentDefinitions that are different versions of definitions of the same component. |
identifier string | (Optional) Specifies a unique identifier for the BackupPolicyTemplate. This identifier will be used as the suffix of the name of automatically generated BackupPolicy. This prevents unintended overwriting of BackupPolicies due to name conflicts when multiple BackupPolicyTemplates are present. For instance, using “backup-policy” for regular backups and “backup-policy-hscale” for horizontal-scale ops can differentiate the policies. |
BackupPolicyTemplateStatus
(Appears on:BackupPolicyTemplate)
BackupPolicyTemplateStatus defines the observed state of BackupPolicyTemplate.
BackupRefSpec
Field | Description |
---|---|
ref RefNamespaceName | (Optional) Refers to a reference backup that needs to be restored. |
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.
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
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. |
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 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. |
ClusterComponentPhase (string
alias)
(Appears on:ClusterComponentStatus, ComponentStatus, OpsRequestComponentStatus)
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, LastComponentConfiguration)
Field | Description |
---|---|
name string | References the ComponentService name defined in the |
serviceType Kubernetes core/v1.ServiceType | (Optional) Determines how the Service is exposed. Valid options are
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 |
componentDefRef string | (Optional) References a ClusterComponentDefinition defined in the Deprecated since v0.9, because defining Components in |
componentDef string | (Optional) References the name of a ComponentDefinition object. The ComponentDefinition specifies the behavior and characteristics of the Component. If both |
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:
ServiceRefs with identical Example:
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 The elements in the
|
labels map[string]string | (Optional) Specifies Labels to override or add for underlying Pods. |
annotations map[string]string | (Optional) Specifies Annotations to override or add for underlying Pods. |
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 |
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
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 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. |
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 |
podUpdatePolicy PodUpdatePolicyType | (Optional) PodUpdatePolicy indicates how pods should be updated
|
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:
|
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:
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:
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:
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:
The value of | ||||||||
spec PersistentVolumeClaimSpec | (Optional) Defines the desired characteristics of a PersistentVolumeClaim that will be created for the volume with the mount name specified in the When a Pod is created for this ClusterComponent, a new PVC will be created based on the specification defined in the
|
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 |
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) CompDef specifies the definition 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, OpsRequestBehaviour)
ClusterPhase defines the phase of the Cluster within the .status.phase field.
Value | Description |
---|---|
"Abnormal" | AbnormalClusterPhase represents some components are in |
"Creating" | CreatingClusterPhase represents all components are in |
"Deleting" | DeletingClusterPhase indicates the cluster is being deleted. |
"Failed" | FailedClusterPhase represents all components are in |
"Running" | RunningClusterPhase represents all components are in |
"Stopped" | StoppedClusterPhase represents all components are in |
"Stopping" | StoppingClusterPhase represents at least one component is in |
"Updating" | UpdatingClusterPhase represents all components are in |
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 |
shardingSelector string | (Optional) Extends the ServiceSpec.Selector by allowing the specification of a sharding name, which is defined in |
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 |
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
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 If this field is not provided, each component must be explicitly defined in 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 If Note: Once set during the Cluster creation, the |
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:
Warning: Choosing an inappropriate termination policy can result in data loss. The |
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 Note: |
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: |
services []ClusterService | (Optional) Defines a list of additional Services that are exposed by a Cluster. This field allows Services of selected Components, either from 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 |
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 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: |
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 name or prefix of the ComponentDefinition custom resource(CR) that defines the Component’s characteristics and behavior. When a prefix is used, the system selects the ComponentDefinition CR with the latest version that matches the prefix. This approach allows:
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. |
ClusterVarSelector
(Appears on:VarSource)
ClusterVarSelector selects a var from a Cluster.
Field | Description |
---|---|
ClusterVars ClusterVars | (Members of |
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. |
CompletionProbe
(Appears on:OpsResourceModifierAction)
Field | Description |
---|---|
initialDelaySeconds int32 | (Optional) Specifies the number of seconds to wait after the resource has been patched before initiating completion probes. The default value is 5 seconds, with a minimum value of 1. |
timeoutSeconds int32 | (Optional) Specifies the number of seconds after which the probe times out. The default value is 60 seconds, with a minimum value of 1. |
periodSeconds int32 | (Optional) Specifies the frequency (in seconds) at which the probe should be performed. The default value is 5 seconds, with a minimum value of 1. |
matchExpressions MatchExpressions | Executes expressions regularly, based on the value of PeriodSeconds, to determine if the action has been completed. |
ComponentConfigSpec
(Appears on:ComponentDefinitionSpec, ConfigurationItemDetail)
Field | Description |
---|---|
ComponentTemplateSpec ComponentTemplateSpec | (Members of |
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 |
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: |
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:
|
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:
|
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 Some examples of well-known service protocols include:
The When specifying the
Note: The The |
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:
Additional labels for pre-release and build metadata are available as extensions to the X.Y.Z format:
Examples of valid ServiceVersion values:
The |
runtime Kubernetes core/v1.PodSpec | Specifies the PodSpec template used in the Component. It includes the following elements:
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 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 This field is immutable and cannot be updated once set. |
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:
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 This field allows you to specify the following:
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 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 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.
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 Examples:
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:
This field is immutable. |
policyRules []Kubernetes rbac/v1.PolicyRule | (Optional) Defines the namespaced policy rules required by the Component. The 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 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 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 Each
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.
This field is immutable. |
updateStrategy UpdateStrategy | (Optional) Specifies the concurrency strategy for updating multiple instances of the Component. Available strategies:
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.
|
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 The roles assigned to a replica can influence various aspects of the Component’s behavior, such as:
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:
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)
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 ` |
message string | (Optional) Provides additional information about the current phase. |
ComponentInfo
(Appears on:OpsDefinitionSpec)
Field | Description |
---|---|
componentDefinitionName string | Specifies the name of the ComponentDefinition. |
accountName string | (Optional) Specifies the account name associated with the Component. If set, the corresponding account username and password are injected into containers’ environment variables |
serviceName string | (Optional) Specifies the name of the Service. If set, the service name is injected as the |
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 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 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:
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 Action | (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 variables:
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:
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:
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:
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:
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:
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:
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. 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:
Note: This field is immutable once it has been set. |
ComponentMessageMap (map[string]string
alias)
(Appears on:ClusterComponentStatus, ComponentStatus)
ComponentOps
(Appears on:CustomOpsComponent, HorizontalScaling, RebuildInstance, Reconfigure, SpecificOpsRequest, Switchover, UpgradeComponent, VerticalScaling, VolumeExpansion)
ComponentOps specifies the Component to be operated on.
Field | Description |
---|---|
componentName string | Specifies the name of the Component. |
ComponentResourceKey (string
alias)
ComponentResourceKey defines the resource key of component, such as pod/pvc.
Value | Description |
---|---|
"pods" |
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 |
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 The names of the generated Services will follow the same suffix naming pattern: Example usage:
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:
ServiceRefs with identical Example:
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. |
annotations map[string]string | (Optional) Specifies Annotations to override or add for underlying Pods. |
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 The elements in the
|
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. |
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 |
podUpdatePolicy PodUpdatePolicyType | (Optional) PodUpdatePolicy indicates how pods should be updated
|
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 |
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
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 SchedulingPolicy | (Optional) Specifies the scheduling policy for the Component. |
tlsConfig TLSConfig | (Optional) Specifies the TLS configuration for the Component, including:
|
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:
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:
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:
|
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 |
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)
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 | 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 The Component to select from. |
ComponentVars ComponentVars | (Members of |
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, or a name prefix. For example:
|
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 ` |
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/#namesNote: 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 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:
If Example:
|
dynamicActionCanBeMerged bool | (Optional) Indicates whether to consolidate dynamic reload and restart actions into a single 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
|
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:
|
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 If the |
formatterConfig FileFormatConfig | Specifies the format of the configuration file and any associated parameters that are specific to the chosen format. Supported formats include Each format may have its own set of parameters that can be configured. For instance, when using the Example:
|
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 |
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. |
ConfigurationItem
(Appears on:Reconfigure)
Field | Description |
---|---|
name string | Specifies the name of the configuration template. |
policy UpgradePolicy | (Optional) Defines the upgrade policy for the configuration. |
keys []ParameterConfig | Sets the configuration files and their associated parameters that need to be updated. It should contain at least one item. |
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 |
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 |
configFileParams map[string]github.com/apecloud/kubeblocks/apis/apps/v1alpha1.ConfigParams | (Optional) Specifies the user-defined configuration parameters. When provided, the parameter values in |
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. |
ConfigurationItemStatus
(Appears on:ReconfiguringStatus)
Field | Description |
---|---|
name string | Indicates the name of the configuration template (as ConfigMap). |
updatePolicy UpgradePolicy | (Optional) Records the UpgradePolicy of the configuration change operation. |
status string | (Optional) Represents the current state of the reconfiguration state machine. Possible values include “Creating”, “Init”, “Running”, “Pending”, “Merged”, “MergeFailed”, “FailedAndPause”, “Upgrading”, “Deleting”, “FailedAndRetry”, “Finished”, “ReconfigurePersisting”, “ReconfigurePersisted”. |
message string | (Optional) Provides details about the operation. |
succeedCount int32 | (Optional) Records the number of pods successfully updated following a configuration change. |
expectedCount int32 | (Optional) Represents the total count of pods intended to be updated by a configuration change. |
lastStatus string | (Optional) Records the last state of the reconfiguration finite state machine. Possible values include “None”, “Retry”, “Failed”, “NotSupport”, “FailedAndRetry”.
|
lastAppliedConfiguration map[string]string | (Optional) Stores the last applied configuration. |
updatedParameters UpdatedParameters | (Optional) Contains the updated parameters. |
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:
|
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. |
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:
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 The Credential (SystemAccount) to select from. |
CredentialVars CredentialVars | (Members of |
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) |
CustomOps
(Appears on:SpecificOpsRequest)
Field | Description |
---|---|
opsDefinitionName string | Specifies the name of the OpsDefinition. |
serviceAccountName string | Specifies the name of the ServiceAccount to be used for executing the custom operation. |
maxConcurrentComponents Kubernetes api utils intstr.IntOrString | (Optional) Specifies the maximum number of components to be operated on concurrently to mitigate performance impact on clusters with multiple components. It accepts an absolute number (e.g., 5) or a percentage of components to execute in parallel (e.g., “10%”). Percentages are rounded up to the nearest whole number of components. For example, if “10%” results in less than one, it rounds up to 1. When unspecified, all components are processed simultaneously by default. Note: This feature is not implemented yet. |
components []CustomOpsComponent | Specifies the components and their parameters for executing custom actions as defined in OpsDefinition. Requires at least one component. |
CustomOpsComponent
(Appears on:CustomOps)
Field | Description |
---|---|
ComponentOps ComponentOps | (Members of Specifies the name of the Component. |
parameters []Parameter | (Optional) Specifies the parameters that match the schema specified in the |
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. |
EnvMappingVar
(Appears on:BackupMethod)
Field | Description |
---|---|
key string | Specifies the environment variable key in the mapping. |
valueFrom ValueFrom | Specifies the source used to derive the value of the environment variable, which typically represents the tool image required for backup operation. |
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 If a variable cannot be resolved, the reference in the input string will be unchanged. Double
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. |
EnvVarRef
(Appears on:OpsVarSource)
Field | Description |
---|---|
targetContainerName string | (Optional) Specifies the container name in the target Pod. If not specified, the first container will be used by default. |
envName string | Defines the name of the environment variable. This name can originate from an ‘env’ entry or be a data key from an ‘envFrom’ source. |
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 |
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
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 The resources that can be shared are included:
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. |
scrapePort string | (Optional) Specifies the port name to scrape for metrics. |
scrapeScheme PrometheusScheme | (Optional) Specifies the schema to use for scraping. |
Expose
(Appears on:SpecificOpsRequest)
Field | Description |
---|---|
componentName string | Specifies the name of the Component. |
switch ExposeSwitch | Indicates whether the services will be exposed. ‘Enable’ exposes the services. while ‘Disable’ removes the exposed Service. |
services []OpsService | Specifies a list of OpsService. When an OpsService is exposed, a corresponding ClusterService will be added to Note: If |
ExposeSwitch (string
alias)
(Appears on:Expose)
ExposeSwitch Specifies the switch for the expose operation. This switch can be used to enable or disable the expose operation.
Value | Description |
---|---|
"Disable" | |
"Enable" |
FailurePolicyType (string
alias)
(Appears on:OpsAction)
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. |
HorizontalScaling
(Appears on:SpecificOpsRequest)
HorizontalScaling defines the parameters of a horizontal scaling operation.
Field | Description |
---|---|
ComponentOps ComponentOps | (Members of Specifies the name of the Component. |
replicas int32 | (Optional) Deprecated: since v0.9, use scaleOut and scaleIn instead. Specifies the number of replicas for the component. Cannot be used with “scaleIn” and “scaleOut”. |
scaleOut ScaleOut | (Optional) Specifies the replica changes for scaling out components and instance templates, and brings offline instances back online. Can be used in conjunction with the “scaleIn” operation. Note: Any configuration that deletes instances is considered invalid. |
scaleIn ScaleIn | (Optional) Specifies the replica changes for scaling in components and instance templates, and takes specified instances offline. Can be used in conjunction with the “scaleOut” operation. Note: Any configuration that creates instances is considered invalid. |
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 The component to select from. |
HostNetworkVars HostNetworkVars | (Members of |
HostNetworkVars
(Appears on:HostNetworkVarSelector)
HostNetworkVars defines the vars that can be referenced from host-network resources.
Field | Description |
---|---|
container ContainerVars | (Optional) |
Instance
(Appears on:RebuildInstance)
Field | Description |
---|---|
name string | Pod name of the instance. |
targetNodeName string | (Optional) The instance will rebuild on the specified node when the instance uses local PersistentVolume as the storage disk. If not set, it will rebuild on a random node. |
InstanceReplicasTemplate
(Appears on:ReplicaChanger)
InstanceReplicasTemplate defines the template for instance replicas.
Field | Description |
---|---|
name string | Specifies the name of the instance template. |
replicaChanges int32 | Specifies the replica changes for the instance template. |
InstanceResourceTemplate
(Appears on:VerticalScaling)
Field | Description |
---|---|
name string | Refer to the instance template name of the component or sharding. |
ResourceRequirements Kubernetes core/v1.ResourceRequirements | (Members of Defines the computational resource size for vertical scaling. |
InstanceTemplate
(Appears on:ClusterComponentSpec, ComponentSpec, LastComponentConfiguration, ScaleOut)
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. |
InstanceVolumeClaimTemplate
(Appears on:VolumeExpansion)
Field | Description |
---|---|
name string | Refer to the instance template name of the component or sharding. |
volumeClaimTemplates []OpsRequestVolumeClaimTemplate | volumeClaimTemplates specifies the storage size and volumeClaimTemplate name. |
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:
|
secretRef TLSSecretRef | (Optional) SecretRef is the reference to the secret that contains user-provided certificates. It is required when the issuer is set to |
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. |
JSONPatchOperation
(Appears on:OpsResourceModifierAction)
Field | Description |
---|---|
op string | Specifies the type of JSON patch operation. It supports the following values: ‘add’, ‘remove’, ‘replace’. |
path string | Specifies the json patch path. |
value string | Specifies the value to be used in the JSON patch operation. |
LastComponentConfiguration
(Appears on:LastConfiguration, OverrideBy)
LastComponentConfiguration can be used to track and compare the desired state of the Component over time.
Field | Description |
---|---|
replicas int32 | (Optional) Records the |
ResourceRequirements Kubernetes core/v1.ResourceRequirements | (Members of Records the resources of the Component prior to any changes. |
volumeClaimTemplates []OpsRequestVolumeClaimTemplate | (Optional) Records volumes’ storage size of the Component prior to any changes. |
services []ClusterComponentService | (Optional) Records the ClusterComponentService list of the Component prior to any changes. |
targetResources map[github.com/apecloud/kubeblocks/apis/apps/v1alpha1.ComponentResourceKey][]string | (Optional) Records the information about various types of resources associated with the Component prior to any changes. Currently, only one type of resource is supported: “pods”. The “pods” key maps to a list of names of all Pods of the Component. |
instances []InstanceTemplate | (Optional) Records the InstanceTemplate list of the Component prior to any changes. |
offlineInstances []string | (Optional) Records the offline instances of the Component prior to any changes. |
serviceVersion string | (Optional) Records the version of the Service expected to be provisioned by this Component prior to any changes. |
componentDefinitionName string | (Optional) Records the name of the ComponentDefinition prior to any changes. |
LastConfiguration
(Appears on:OpsRequestStatus)
Field | Description |
---|---|
clusterVersionRef string | (Optional) Specifies the name of the ClusterVersion. Deprecated and should be removed in the future version. |
components map[string]github.com/apecloud/kubeblocks/apis/apps/v1alpha1.LastComponentConfiguration | (Optional) Records the configuration of each Component prior to any changes. |
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 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. |
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:
|
MatchExpressions
(Appears on:CompletionProbe)
Field | Description |
---|---|
failure string | (Optional) Specifies a failure condition for an action using a Go template expression. Should evaluate to either |
success string | Specifies a success condition for an action using a Go template expression. Should evaluate to either |
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) |
OpsAction
(Appears on:OpsDefinitionSpec)
OpsAction specifies a custom action defined in OpsDefinition for execution in a “Custom” OpsRequest.
OpsAction can be of three types:
- workload: Creates a Job or Pod to run custom scripts, ideal for isolated or long-running tasks.
- exec: Executes commands directly within an existing container using the kubectl exec interface, suitable for immediate, short-lived operations.
- resourceModifier: Modifies a K8s object using JSON patches, useful for updating the spec of some resource.
Field | Description |
---|---|
name string | Specifies the name of the OpsAction. |
failurePolicy FailurePolicyType | (Optional) Specifies the failure policy of the OpsAction. Valid values are:
|
parameters []string | (Optional) Specifies the parameters for the OpsAction. Their usage varies based on the action type:
|
workload OpsWorkloadAction | (Optional) Specifies the configuration for a ‘workload’ action. This action leads to the creation of a K8s workload, such as a Pod or Job, to execute specified tasks. |
exec OpsExecAction | (Optional) Specifies the configuration for a ‘exec’ action. It creates a Pod and invokes a ‘kubectl exec’ to run command inside a specified container with the target Pod. |
resourceModifier OpsResourceModifierAction | (Optional) Specifies the configuration for a ‘resourceModifier’ action. This action allows for modifications to existing K8s objects. Note: This feature has not been implemented yet. |
OpsDefinitionSpec
(Appears on:OpsDefinition)
OpsDefinitionSpec defines the desired state of OpsDefinition.
Field | Description |
---|---|
preConditions []PreCondition | (Optional) Specifies the preconditions that must be met to run the actions for the operation. if set, it will check the condition before the Component runs this operation. Example:
|
podInfoExtractors []PodInfoExtractor | (Optional) Specifies a list of PodInfoExtractor, each designed to select a specific Pod and extract selected runtime info from its PodSpec. The extracted information, such as environment variables, volumes and tolerations, are then injected into Jobs or Pods that execute the OpsActions defined in |
componentInfos []ComponentInfo | (Optional) Specifies a list of ComponentDefinition for Components associated with this OpsDefinition. It also includes connection credentials (address and account) for each Component. |
parametersSchema ParametersSchema | (Optional) Specifies the schema for validating the data types and value ranges of parameters in OpsActions before their usage. |
actions []OpsAction | Specifies a list of OpsAction where each customized action is executed sequentially. |
OpsDefinitionStatus
(Appears on:OpsDefinition)
OpsDefinitionStatus defines the observed state of OpsDefinition
Field | Description |
---|---|
observedGeneration int64 | (Optional) Represents the most recent generation observed of this OpsDefinition. |
phase Phase | (Optional) Represents the current state of the OpsDefinition. Valid values are “”, “Available”, “Unavailable”. When it equals to “Available”, the OpsDefinition is ready and can be used in a “Custom” OpsRequest. |
message string | (Optional) Provides additional information about the current phase. |
OpsEnvVar
(Appears on:PodInfoExtractor)
Field | Description |
---|---|
name string | Specifies the name of the environment variable to be injected into Pods executing OpsActions. It must conform to the C_IDENTIFIER format, which includes only alphanumeric characters and underscores, and cannot begin with a digit. |
valueFrom OpsVarSource | Specifies the source of the environment variable’s value. |
OpsExecAction
(Appears on:OpsAction)
Field | Description |
---|---|
podInfoExtractorName string | Specifies a PodInfoExtractor defined in the |
backoffLimit int32 | (Optional) Specifies the number of retries allowed before marking the action as failed. |
command []string | The command to be executed via ‘kubectl exec –’. |
containerName string | (Optional) The name of the container in the target pod where the command should be executed. This corresponds to the If not set, the first container is used. |
OpsPhase (string
alias)
(Appears on:OpsRequestStatus)
OpsPhase defines opsRequest phase.
Value | Description |
---|---|
"Aborted" | |
"Cancelled" | |
"Cancelling" | |
"Creating" | |
"Failed" | |
"Pending" | |
"Running" | |
"Succeed" |
OpsRecorder
Field | Description |
---|---|
name string | name OpsRequest name |
type OpsType | opsRequest type |
inQueue bool | indicates whether the current opsRequest is in the queue |
queueBySelf bool | indicates that the operation is queued for execution within its own-type scope. |
OpsRequestBehaviour
Field | Description |
---|---|
FromClusterPhases []ClusterPhase | |
ToClusterPhase ClusterPhase |
OpsRequestComponentStatus
(Appears on:OpsRequestStatus)
Field | Description |
---|---|
phase ClusterComponentPhase | (Optional) Records the current phase of the Component, mirroring |
lastFailedTime Kubernetes meta/v1.Time | (Optional) Records the timestamp when the Component last transitioned to a “Failed” or “Abnormal” phase. |
preCheck PreCheckResult | (Optional) Records the result of the preConditions check of the opsRequest, which determines subsequent steps. |
progressDetails []ProgressStatusDetail | (Optional) Describes the progress details of objects or actions associated with the Component. |
reason string | (Optional) Provides an explanation for the Component being in its current state. |
message string | (Optional) Provides a human-readable message indicating details about this operation. |
OpsRequestSpec
(Appears on:OpsRequest)
OpsRequestSpec defines the desired state of OpsRequest
Field | Description |
---|---|
clusterName string | Specifies the name of the Cluster resource that this operation is targeting. |
clusterRef string | Deprecated: since v0.9, use clusterName instead. Specifies the name of the Cluster resource that this operation is targeting. |
cancel bool | (Optional) Indicates whether the current operation should be canceled and terminated gracefully if it’s in the “Pending”, “Creating”, or “Running” state. This field applies only to “VerticalScaling” and “HorizontalScaling” opsRequests. Note: Setting |
force bool | (Optional) Instructs the system to bypass pre-checks (including cluster state checks and customized pre-conditions hooks) and immediately execute the opsRequest, except for the opsRequest of ‘Start’ type, which will still undergo pre-checks even if This is useful for concurrent execution of ‘VerticalScaling’ and ‘HorizontalScaling’ opsRequests. By setting Note: Once set, the |
enqueueOnForce bool | (Optional) Indicates whether opsRequest should continue to queue when ‘force’ is set to true. |
type OpsType | Specifies the type of this operation. Supported types include “Start”, “Stop”, “Restart”, “Switchover”, “VerticalScaling”, “HorizontalScaling”, “VolumeExpansion”, “Reconfiguring”, “Upgrade”, “Backup”, “Restore”, “Expose”, “RebuildInstance”, “Custom”. Note: This field is immutable once set. |
ttlSecondsAfterSucceed int32 | (Optional) Specifies the duration in seconds that an OpsRequest will remain in the system after successfully completing (when |
ttlSecondsAfterUnsuccessfulCompletion int32 | (Optional) Specifies the duration in seconds that an OpsRequest will remain in the system after completion for any phase other than “Succeed” (e.g., “Failed”, “Cancelled”, “Aborted”) before automatic deletion. |
preConditionDeadlineSeconds int32 | (Optional) Specifies the maximum time in seconds that the OpsRequest will wait for its pre-conditions to be met before it aborts the operation. If set to 0 (default), pre-conditions must be satisfied immediately for the OpsRequest to proceed. |
timeoutSeconds int32 | (Optional) Specifies the maximum duration (in seconds) that an opsRequest is allowed to run. If the opsRequest runs longer than this duration, its phase will be marked as Aborted. If this value is not set or set to 0, the timeout will be ignored and the opsRequest will run indefinitely. |
SpecificOpsRequest SpecificOpsRequest | (Members of Exactly one of its members must be set. |
OpsRequestStatus
(Appears on:OpsRequest)
OpsRequestStatus represents the observed state of an OpsRequest.
Field | Description |
---|---|
clusterGeneration int64 | (Optional) Records the cluster generation after the OpsRequest action has been handled. |
phase OpsPhase | Represents the phase of the OpsRequest. Possible values include “Pending”, “Creating”, “Running”, “Cancelling”, “Cancelled”, “Failed”, “Succeed”. |
progress string | Represents the progress of the OpsRequest. |
lastConfiguration LastConfiguration | (Optional) Records the configuration prior to any changes. |
components map[string]github.com/apecloud/kubeblocks/apis/apps/v1alpha1.OpsRequestComponentStatus | (Optional) Records the status information of Components changed due to the OpsRequest. |
extras []string | A collection of additional key-value pairs that provide supplementary information for the OpsRequest. |
startTimestamp Kubernetes meta/v1.Time | (Optional) Records the time when the OpsRequest started processing. |
completionTimestamp Kubernetes meta/v1.Time | (Optional) Records the time when the OpsRequest was completed. |
cancelTimestamp Kubernetes meta/v1.Time | (Optional) Records the time when the OpsRequest was cancelled. |
reconfiguringStatus ReconfiguringStatus | (Optional) Deprecated: Replaced by ReconfiguringStatusAsComponent. Defines the status information of reconfiguring. |
reconfiguringStatusAsComponent map[string]*github.com/apecloud/kubeblocks/apis/apps/v1alpha1.ReconfiguringStatus | (Optional) Records the status of a reconfiguring operation if |
conditions []Kubernetes meta/v1.Condition | (Optional) Describes the detailed status of the OpsRequest. Possible condition types include “Cancelled”, “WaitForProgressing”, “Validated”, “Succeed”, “Failed”, “Restarting”, “VerticalScaling”, “HorizontalScaling”, “VolumeExpanding”, “Reconfigure”, “Switchover”, “Stopping”, “Starting”, “VersionUpgrading”, “Exposing”, “Backup”, “InstancesRebuilding”, “CustomOperation”. |
OpsRequestVolumeClaimTemplate
(Appears on:InstanceVolumeClaimTemplate, LastComponentConfiguration, VolumeExpansion)
Field | Description |
---|---|
storage Kubernetes resource.Quantity | Specifies the desired storage size for the volume. |
name string | Specify the name of the volumeClaimTemplate in the Component. The specified name must match one of the volumeClaimTemplates defined in the |
OpsResourceModifierAction
(Appears on:OpsAction)
Field | Description |
---|---|
resource TypedObjectRef | Specifies the K8s object that is to be updated. |
jsonPatches []JSONPatchOperation | Specifies a list of patches for modifying the object. |
completionProbe CompletionProbe | Specifies a method to determine if the action has been completed. Note: This feature has not been implemented yet. |
OpsService
(Appears on:Expose)
OpsService represents the parameters to dynamically create or remove a ClusterService in the cluster.spec.services
array.
Field | Description |
---|---|
name string | Specifies the name of the Service. This name is used to set Note: This field cannot be updated. |
annotations map[string]string | (Optional) Contains cloud provider related parameters if ServiceType is LoadBalancer. More info: https://kubernetes.io/docs/concepts/services-networking/service/#loadbalancer. |
ports []Kubernetes core/v1.ServicePort | (Optional) Specifies Port definitions that are to be exposed by a ClusterService. If not specified, the Port definitions from non-NodePort and non-LoadBalancer type ComponentService defined in the ComponentDefinition ( More info: https://kubernetes.io/docs/concepts/services-networking/service/#field-spec-ports |
roleSelector string | (Optional) Specifies a role to target with the service. If specified, the service will only be exposed to pods with the matching role. Note: If the component has roles, at least one of ‘roleSelector’ or ‘podSelector’ must be specified. If both are specified, a pod must match both conditions to be selected. |
podSelector map[string]string | (Optional) Routes service traffic to pods with matching label keys and values. If specified, the service will only be exposed to pods matching the selector. Note: If the component has roles, at least one of ‘roleSelector’ or ‘podSelector’ must be specified. If both are specified, a pod must match both conditions to be selected. |
serviceType Kubernetes core/v1.ServiceType | (Optional) Determines how the Service is exposed. Defaults to ‘ClusterIP’. Valid options are
Note: although K8s Service type allows the ‘ExternalName’ type, it is not a valid option for the expose operation. For more info, see:https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services-service-types. |
ipFamilies []Kubernetes core/v1.IPFamily | (Optional) A list of IP families (e.g., IPv4, IPv6) assigned to this Service. Usually assigned automatically based on the cluster configuration and the Valid values:
This field may hold a maximum of two entries (dual-stack families, in either order). Common combinations of
|
ipFamilyPolicy Kubernetes core/v1.IPFamilyPolicy | (Optional) Specifies whether the Service should use a single IP family (SingleStack) or two IP families (DualStack). Possible values:
|
OpsType (string
alias)
(Appears on:OpsRecorder, OpsRequestSpec)
OpsType defines operation types.
Value | Description |
---|---|
"Backup" | |
"Custom" | RebuildInstance rebuilding an instance is very useful when a node is offline or an instance is unrecoverable. |
"Expose" | StartType the start operation will start the pods which is deleted in stop operation. |
"HorizontalScaling" | |
"RebuildInstance" | |
"Reconfiguring" | |
"Restart" | |
"Restore" | |
"Start" | StopType the stop operation will delete all pods in a cluster concurrently. |
"Stop" | RestartType the restart operation is a special case of the rolling update operation. |
"Switchover" | |
"Upgrade" | |
"VerticalScaling" | |
"VolumeExpansion" |
OpsVarSource
(Appears on:OpsEnvVar)
Field | Description |
---|---|
envRef EnvVarRef | (Optional) Specifies a reference to a specific environment variable within a container. Used to specify the source of the variable, which can be either “env” or “envFrom”. |
fieldPath Kubernetes core/v1.ObjectFieldSelector | (Optional) Represents the JSONPath expression pointing to the specific data within the JSON structure of the target Pod. It is used to extract precise data locations for operations on the Pod. |
OpsWorkloadAction
(Appears on:OpsAction)
Field | Description |
---|---|
type OpsWorkloadType | Defines the workload type of the action. Valid values include “Job” and “Pod”.
|
podInfoExtractorName string | Specifies a PodInfoExtractor defined in the |
backoffLimit int32 | (Optional) Specifies the number of retries allowed before marking the action as failed. |
podSpec Kubernetes core/v1.PodSpec | Specifies the PodSpec of the ‘workload’ action. |
OpsWorkloadType (string
alias)
(Appears on:OpsWorkloadAction)
OpsWorkloadType policy after action failure.
Value | Description |
---|---|
"Job" | |
"Pod" |
OverrideBy
Field | Description |
---|---|
opsName string | (Optional) Indicates the name of the OpsRequest. |
LastComponentConfiguration LastComponentConfiguration | (Members of |
Parameter
(Appears on:CustomOpsComponent)
Field | Description |
---|---|
name string | Specifies the identifier of the parameter as defined in the OpsDefinition. |
value string | Holds the data associated with the parameter. If the parameter type is an array, the format should be “v1,v2,v3”. |
ParameterConfig
(Appears on:ConfigurationItem)
Field | Description |
---|---|
key string | Represents a key in the configuration template(as ConfigMap). Each key in the ConfigMap corresponds to a specific configuration file. |
parameters []ParameterPair | (Optional) Specifies a list of key-value pairs representing parameters and their corresponding values within a single configuration file. This field is used to override or set the values of parameters without modifying the entire configuration file. Either the |
fileContent string | (Optional) Specifies the content of the entire configuration file. This field is used to update the complete configuration file. Either the |
ParameterPair
(Appears on:ParameterConfig)
Field | Description |
---|---|
key string | Represents the name of the parameter that is to be updated. |
value string | (Optional) Represents the parameter values that are to be updated. If set to nil, the parameter defined by the Key field will be removed from the configuration file. |
ParametersSchema
(Appears on:OpsDefinitionSpec)
Field | Description |
---|---|
openAPIV3Schema Kubernetes api extensions v1.JSONSchemaProps | (Optional) Defines the schema for parameters using the OpenAPI v3. The supported property types include: - string - number - integer - array: Note that only items of string type are supported. |
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. |
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, OpsDefinitionStatus, 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" |
PodInfoExtractor
(Appears on:OpsDefinitionSpec)
Field | Description |
---|---|
name string | Specifies the name of the PodInfoExtractor. |
env []OpsEnvVar | (Optional) Specifies a list of environment variables to be extracted from a selected Pod, and injected into the containers executing each OpsAction. |
podSelector PodSelector | Used to select the target Pod from which environment variables and volumes are extracted from its PodSpec. |
volumeMounts []Kubernetes core/v1.VolumeMount | (Optional) Specifies a list of volumes, along with their respective mount points, that are to be extracted from a selected Pod, and mounted onto the containers executing each OpsAction. This allows the containers to access shared or persistent data necessary for the operation. |
PodSelectionPolicy (string
alias)
(Appears on:PodSelector)
PodSelectionPolicy pod selection strategy.
Value | Description |
---|---|
"All" | |
"Any" |
PodSelector
(Appears on:PodInfoExtractor)
PodSelector selects the target Pod from which environment variables and volumes are extracted from its PodSpec.
Field | Description |
---|---|
role string | (Optional) Specifies the role of the target Pod. |
multiPodSelectionPolicy PodSelectionPolicy | Defines the policy for selecting the target pod when multiple pods match the podSelector. It can be either ‘Any’ (select any one pod that matches the podSelector) or ‘All’ (select all pods that match the podSelector). |
PointInTimeRefSpec
Field | Description |
---|---|
time Kubernetes meta/v1.Time | (Optional) Refers to the specific time point for restoration, with UTC as the time zone. |
ref RefNamespaceName | (Optional) Refers to a reference source cluster that needs to be restored. |
PreCheckResult
(Appears on:OpsRequestComponentStatus)
Field | Description |
---|---|
pass bool | Indicates whether the preCheck operation passed or failed. |
message string | (Optional) Provides explanations related to the preCheck result in a human-readable format. |
PreCondition
(Appears on:OpsDefinitionSpec)
Field | Description |
---|---|
rule Rule | Specifies the conditions that must be met for the operation to execute. |
PreConditionExec
PreConditionExec is deprecated.
Field | Description |
---|---|
image string | Specifies the name of the image used for execution. |
env []Kubernetes core/v1.EnvVar | (Optional) Specifies a list of environment variables to be set in the container. |
command []string | (Optional) Specifies the command to be executed in the container. |
args []string | (Optional) Specifies the arguments to be passed to the command in the container. |
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 |
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. |
ProgressStatus (string
alias)
(Appears on:ProgressStatusDetail)
ProgressStatus defines the status of the opsRequest progress.
Value | Description |
---|---|
"Failed" | |
"Pending" | |
"Processing" | |
"Succeed" |
ProgressStatusDetail
(Appears on:OpsRequestComponentStatus)
Field | Description |
---|---|
group string | (Optional) Specifies the group to which the current object belongs to. |
objectKey string | (Optional)
|
actionName string | (Optional) Indicates the name of an OpsAction, as defined in |
actionTasks []ActionTask | (Optional) Lists the tasks, such as Jobs or Pods, that carry out the action. |
status ProgressStatus | Represents the current processing state of the object, including “Processing”, “Pending”, “Failed”, “Succeed” |
message string | (Optional) Provides a human-readable explanation of the object’s condition. |
startTime Kubernetes meta/v1.Time | (Optional) Records the start time of object processing. |
endTime Kubernetes meta/v1.Time | (Optional) Records the completion time of object processing. |
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. |
RebuildInstance
(Appears on:SpecificOpsRequest)
Field | Description |
---|---|
ComponentOps ComponentOps | (Members of Specifies the name of the Component. |
instances []Instance | Specifies the instances (Pods) that need to be rebuilt, typically operating as standbys. |
inPlace bool | When it is set to true, the instance will be rebuilt in-place. By default, a new pod will be created. Once the new pod is ready to serve, the instance that require rebuilding will be taken offline. |
backupName string | (Optional) Indicates the name of the Backup custom resource from which to recover the instance. Defaults to an empty PersistentVolume if unspecified. Note: - Only full physical backups are supported for multi-replica Components (e.g., ‘xtrabackup’ for MySQL). - Logical backups (e.g., ‘mysqldump’ for MySQL) are unsupported in the current version. |
restoreEnv []Kubernetes core/v1.EnvVar | (Optional) Defines container environment variables for the restore process. merged with the ones specified in the Backup and ActionSet resources. Merge priority: Restore env > Backup env > ActionSet env. Purpose: Some databases require different configurations when being restored as a standby compared to being restored as a primary. For example, when restoring MySQL as a replica, you need to set |
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. |
Reconfigure
(Appears on:SpecificOpsRequest)
Reconfigure defines the parameters for updating a Component’s configuration.
Field | Description |
---|---|
ComponentOps ComponentOps | (Members of Specifies the name of the Component. |
configurations []ConfigurationItem | Contains a list of ConfigurationItem objects, specifying the Component’s configuration template name, upgrade policy, and parameter key-value pairs to be updated. |
ReconfiguringStatus
(Appears on:OpsRequestStatus)
Field | Description |
---|---|
conditions []Kubernetes meta/v1.Condition | (Optional) Describes the reconfiguring detail status. Possible condition types include “Creating”, “Init”, “Running”, “Pending”, “Merged”, “MergeFailed”, “FailedAndPause”, “Upgrading”, “Deleting”, “FailedAndRetry”, “Finished”, “ReconfigurePersisting”, “ReconfigurePersisted”. |
configurationStatus []ConfigurationItemStatus | Describes the status of the component reconfiguring. |
RefNamespaceName
(Appears on:BackupRefSpec, PointInTimeRefSpec)
Field | Description |
---|---|
name string | (Optional) Refers to the specific name of the resource. |
namespace string | (Optional) Refers to the specific namespace of the resource. |
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. |
ReplicaChanger
(Appears on:ScaleIn, ScaleOut)
ReplicaChanger defines the parameters for changing the number of replicas.
Field | Description |
---|---|
replicaChanges int32 | Specifies the replica changes for the component. |
instances []InstanceReplicasTemplate | (Optional) Modifies the desired replicas count for existing InstanceTemplate. if the inst |
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. |
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. |
Restore
(Appears on:SpecificOpsRequest)
Field | Description |
---|---|
backupName string | Specifies the name of the Backup custom resource. |
restorePointInTime string | Specifies the point in time to which the restore should be performed. Supported time formats:
|
volumeRestorePolicy string | Specifies the policy for restoring volume claims of a Component’s Pods. It determines whether the volume claims should be restored sequentially (one by one) or in parallel (all at once). Support values:
|
deferPostReadyUntilClusterRunning bool | Controls the timing of PostReady actions during the recovery process. If false (default), PostReady actions execute when the Component reaches the “Running” state. If true, PostReady actions are delayed until the entire Cluster is “Running,” ensuring the cluster’s overall stability before proceeding. This setting is useful for coordinating PostReady operations across the Cluster for optimal cluster conditions. |
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) |
Rule
(Appears on:PreCondition)
Field | Description |
---|---|
expression string | Specifies a Go template expression that determines how the operation can be executed. The return value must be either
|
message string | Specifies the error or status message reported if the |
ScaleIn
(Appears on:HorizontalScaling)
ScaleIn defines the configuration for a scale-in operation.
Field | Description |
---|---|
ReplicaChanger ReplicaChanger | (Members of Modifies the replicas of the component and instance templates. |
onlineInstancesToOffline []string | (Optional) Specifies the instance names that need to be taken offline. |
ScaleOut
(Appears on:HorizontalScaling)
ScaleOut defines the configuration for a scale-out operation.
Field | Description |
---|---|
ReplicaChanger ReplicaChanger | (Members of Modifies the replicas of the component and instance templates. |
newInstances []InstanceTemplate | (Optional) Defines the configuration for new instances added during scaling, including resource requirements, labels, annotations, etc. New instances are created based on the provided instance templates. |
offlineInstancesToOnline []string | (Optional) Specifies the instances in the offline list to bring back online. |
SchedulePolicy
(Appears on:BackupPolicy)
Field | Description |
---|---|
enabled bool | (Optional) Specifies whether the backup schedule is enabled or not. |
backupMethod string | Defines the backup method name that is defined in backupPolicy. |
cronExpression string | Represents the cron expression for schedule, with the timezone set in UTC. Refer to https://en.wikipedia.org/wiki/Cron for more details. |
retentionPeriod github.com/apecloud/kubeblocks/apis/dataprotection/v1alpha1.RetentionPeriod | (Optional) Determines the duration for which the backup should be retained. The controller will remove all backups that are older than the RetentionPeriod. For instance, a RetentionPeriod of
These durations can also be combined, for example: 30d12h30m. |
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
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. |
SecretRef
(Appears on:UserResourceRefs)
SecretRef defines a reference to a Secret.
Field | Description |
---|---|
ResourceMeta ResourceMeta | (Members of |
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:
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
| ||||||||||||||||||||||||||||||||||||||
roleSelector string | (Optional) Extends the above
In this example, setting Note that if |
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 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. |
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:
|
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 Note:
Deprecated since v0.9 since |
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 If both |
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 |
credential ServiceRefCredentialSelector | (Optional) Specifies the SystemAccount to authenticate and establish a connection with the referenced Cluster. The SystemAccount should be defined in |
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 |
serviceVersion string | Defines the service version of the service reference. This is a regular expression that matches a version number pattern. For instance, |
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 The ServiceRefDeclaration to select from. |
ServiceRefVars ServiceRefVars | (Members of |
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 |
ServiceVarSelector
(Appears on:VarSource)
ServiceVarSelector selects a var from a Service.
Field | Description |
---|---|
ClusterObjectReference ClusterObjectReference | (Members of 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
(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… |
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 Note that the name defined in Component template( |
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 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:
|
SpecificOpsRequest
(Appears on:OpsRequestSpec)
Field | Description |
---|---|
upgrade Upgrade | (Optional) Specifies the desired new version of the Cluster. Note: This field is immutable once set. |
horizontalScaling []HorizontalScaling | (Optional) Lists HorizontalScaling objects, each specifying scaling requirements for a Component, including desired replica changes, configurations for new instances, modifications for existing instances, and take offline/online the specified instances. |
volumeExpansion []VolumeExpansion | (Optional) Lists VolumeExpansion objects, each specifying a component and its corresponding volumeClaimTemplates that requires storage expansion. |
restart []ComponentOps | (Optional) Lists Components to be restarted. |
switchover []Switchover | (Optional) Lists Switchover objects, each specifying a Component to perform the switchover operation. |
verticalScaling []VerticalScaling | (Optional) Lists VerticalScaling objects, each specifying a component and its desired compute resources for vertical scaling. |
reconfigure Reconfigure | (Optional) Specifies a component and its configuration updates. This field is deprecated and replaced by |
reconfigures []Reconfigure | (Optional) Lists Reconfigure objects, each specifying a Component and its configuration updates. |
expose []Expose | (Optional) Lists Expose objects, each specifying a Component and its services to be exposed. |
backup Backup | (Optional) Specifies the parameters to backup a Cluster. |
backupSpec Backup | (Optional) Deprecated: since v0.9, use backup instead. Specifies the parameters to backup a Cluster. |
restore Restore | (Optional) Specifies the parameters to restore a Cluster. Note that this restore operation will roll back cluster services. |
restoreSpec Restore | (Optional) Deprecated: since v0.9, use restore instead. Specifies the parameters to restore a Cluster. Note that this restore operation will roll back cluster services. |
rebuildFrom []RebuildInstance | (Optional) Specifies the parameters to rebuild some instances. Rebuilding an instance involves restoring its data from a backup or another database replica. The instances being rebuilt usually serve as standby in the cluster. Hence rebuilding instances is often also referred to as “standby reconstruction”. |
custom CustomOps | (Optional) Specifies a custom operation defined by OpsDefinition. |
StatefulSetWorkload
StatefulSetWorkload interface
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. |
Switchover
(Appears on:SpecificOpsRequest)
Field | Description |
---|---|
ComponentOps ComponentOps | (Members of Specifies the name of the Component. |
instanceName string | Specifies the instance to become the primary or leader during a switchover operation. The value of
|
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. |
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 |
TargetInstance
(Appears on:BackupMethod, BackupPolicy)
Field | Description |
---|---|
role string | Specifies the role to select one or more replicas for backup.
|
fallbackRole string | (Optional) Specifies the fallback role to select one replica for backup, this only takes effect when the |
account string | (Optional) If |
strategy github.com/apecloud/kubeblocks/apis/dataprotection/v1alpha1.PodSelectionStrategy | (Optional) Specifies the PodSelectionStrategy to use when multiple pods are selected for the backup target. Valid values are:
|
containerPort github.com/apecloud/kubeblocks/apis/dataprotection/v1alpha1.ContainerPort | (Optional) Specifies the container port in the target pod. If not specified, the first container and its first port will be used. |
TargetPodSelector (string
alias)
(Appears on:ExecAction)
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. |
TypedObjectRef
(Appears on:OpsResourceModifierAction)
Field | Description |
---|---|
apiGroup string | Specifies the group for the resource being referenced. If not specified, the referenced Kind must belong to the core API group. For all third-party types, this is mandatory. |
kind string | Specifies the type of resource being referenced. |
name string | Indicates the name of the resource being referenced. |
UpdateStrategy (string
alias)
(Appears on:ClusterComponentSpec, ComponentDefinitionSpec)
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 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 |
"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. |
UpdatedParameters
(Appears on:ConfigurationItemStatus)
UpdatedParameters holds details about the modifications made to configuration parameters. Example:
updatedParameters: updatedKeys: my.cnf: '{"mysqld":{"max_connections":"100"}}'
Field | Description |
---|---|
addedKeys map[string]string | (Optional) Maps newly added configuration files to their content. |
deletedKeys map[string]string | (Optional) Lists the name of configuration files that have been deleted. |
updatedKeys map[string]string | (Optional) Maps the name of configuration files to their updated content, detailing the changes made. |
Upgrade
(Appears on:SpecificOpsRequest)
Upgrade defines the parameters for an upgrade operation.
Field | Description |
---|---|
clusterVersionRef string | Deprecated: since v0.9 because ClusterVersion is deprecated. Specifies the name of the target ClusterVersion for the upgrade. |
components []UpgradeComponent | (Optional) Lists components to be upgrade based on desired ComponentDefinition and ServiceVersion. From the perspective of cluster API, the reasonable combinations should be: 1. (comp-def, service-ver) - upgrade to the specified service version and component definition, the user takes the responsibility to ensure that they are compatible. 2. (“”, service-ver) - upgrade to the specified service version, let the operator choose the latest compatible component definition. 3. (comp-def, “”) - upgrade to the specified component definition, let the operator choose the latest compatible service version. 4. (“”, “”) - upgrade to the latest service version and component definition, the operator will ensure the compatibility between the selected versions. |
UpgradeComponent
(Appears on:Upgrade)
Field | Description |
---|---|
ComponentOps ComponentOps | (Members of Specifies the name of the Component. |
componentDefinitionName string | (Optional) Specifies the name of the ComponentDefinition. |
serviceVersion string | (Optional) Specifies the version of the Service expected to be provisioned by this Component. Referring to the ServiceVersion defined by the ComponentDefinition and ComponentVersion. And ServiceVersion in ClusterComponentSpec is optional, when no version is specified, use the latest available version in ComponentVersion. |
UpgradePolicy (string
alias)
(Appears on:ConfigurationItem, ConfigurationItemStatus)
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. |
ValueFrom
(Appears on:EnvMappingVar)
Field | Description |
---|---|
clusterVersionRef []ValueMapping | (Optional) Determine the appropriate version of the backup tool image from ClusterVersion. Deprecated since v0.9, since ClusterVersion is deprecated. |
componentDef []ValueMapping | (Optional) Determine the appropriate version of the backup tool image from ComponentDefinition. |
ValueMapping
(Appears on:ValueFrom)
Field | Description |
---|---|
names []string | Represents an array of names of ComponentDefinition that can be mapped to the appropriate version of the backup tool image. This mapping allows different versions of component images to correspond to specific versions of backup tool images. |
mappingValue string | Specifies the appropriate version of the backup tool image. |
VarOption (string
alias)
(Appears on:ClusterVars, ComponentVars, CredentialVars, NamedVar, RoledVar, 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. |
clusterVarRef ClusterVarSelector | (Optional) Selects a defined var of a Cluster. |
VerticalScaling
(Appears on:SpecificOpsRequest)
VerticalScaling refers to the process of adjusting compute resources (e.g., CPU, memory) allocated to a Component. It defines the parameters required for the operation.
Field | Description |
---|---|
ComponentOps ComponentOps | (Members of Specifies the name of the Component. |
ResourceRequirements Kubernetes core/v1.ResourceRequirements | (Members of Defines the desired compute resources of the Component’s instances. |
instances []InstanceResourceTemplate | (Optional) Specifies the desired compute resources of the instance template that need to vertical scale. |
VolumeExpansion
(Appears on:SpecificOpsRequest)
VolumeExpansion encapsulates the parameters required for a volume expansion operation.
Field | Description |
---|---|
ComponentOps ComponentOps | (Members of Specifies the name of the Component. |
volumeClaimTemplates []OpsRequestVolumeClaimTemplate | Specifies a list of OpsRequestVolumeClaimTemplate objects, defining the volumeClaimTemplates that are used to expand the storage and the desired storage size for each one. |
instances []InstanceVolumeClaimTemplate | (Optional) Specifies the desired storage size of the instance template that need to volume expand. |
apps.kubeblocks.io/v1beta1
Resource Types: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:
- Parameter Value Validation: Validates and ensures compliance of parameter values with defined constraints.
- Dynamic Reload on Modification: Monitors parameter changes and triggers dynamic reloads to apply updates.
- 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 themetadata field. | ||||||||||||||||||
spec ConfigConstraintSpec |
| ||||||||||||||||||
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:
If Example:
|
mergeReloadAndRestart bool | (Optional) Indicates whether to consolidate dynamic reload and restart actions into a single 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
|
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:
|
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 Each format may have its own set of parameters that can be configured. For instance, when using the Example:
|
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 |
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 Each format may have its own set of parameters that can be configured. For instance, when using the |
format CfgFileFormat | The config file format. Valid values are
|
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 If the |
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”.
|
batchReload bool | (Optional) Controls whether parameter updates are processed individually or collectively in a batch:
Defaults to ‘False’ if unspecified. |
batchParamsFormatterTemplate string | (Optional) Specifies a Go template string for formatting batch input data. It’s used when Example template:
This example generates batch input data in a key:value format, sorted by keys.
If not specified, the default format is key=value, sorted by keys, for each updated parameter.
|
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 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:
|
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:
generated containers:
|
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/v1alpha1
Resource Types: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 themetadata field. | ||||||||||||||||||||||||||||||||||||||
spec InstanceSetSpec | Defines the desired state of the state machine. It includes the configuration details for the state machine.
| ||||||||||||||||||||||||||||||||||||||
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 |
"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 |
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:
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 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 |
podUpdatePolicy PodUpdatePolicyType | (Optional) PodUpdatePolicy indicates how pods should be updated
|
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. |
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.
|
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. |
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: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. |
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: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:InstanceSetSpec)
RoleProbe defines how to observe role
Field | Description |
---|---|
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
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