Skip to main content
Version: release-0.8

Cluster API Reference


Packages:

apps.kubeblocks.io/v1alpha1

Resource Types:

BackupPolicyTemplate

BackupPolicyTemplate is the Schema for the BackupPolicyTemplates API (defined by provider)

FieldDescription
apiVersion
string
apps.kubeblocks.io/v1alpha1
kind
string
BackupPolicyTemplate
metadata
Kubernetes meta/v1.ObjectMeta
Refer to the Kubernetes API documentation for the fields of themetadata field.
spec
BackupPolicyTemplateSpec


clusterDefinitionRef
string

clusterDefinitionRef references ClusterDefinition name, this is an immutable attribute.

backupPolicies
[]BackupPolicy

backupPolicies is a list of backup policy template for the specified componentDefinition.

identifier
string
(Optional)

Identifier is a unique identifier for this BackupPolicyTemplate. this identifier will be the suffix of the automatically generated backupPolicy name. and must be added when multiple BackupPolicyTemplates exist, otherwise the generated backupPolicy override will occur.

status
BackupPolicyTemplateStatus

Cluster

Cluster is the Schema for the clusters API.

FieldDescription
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


clusterDefinitionRef
string
(Optional)

Cluster referencing ClusterDefinition name. This is an immutable attribute. If ClusterDefRef is not specified, ComponentDef must be specified for each Component in ComponentSpecs.

clusterVersionRef
string
(Optional)

Cluster referencing ClusterVersion name.

terminationPolicy
TerminationPolicyType

Cluster termination policy. Valid values are DoNotTerminate, Halt, Delete, WipeOut.

  • DoNotTerminate will block delete operation.
  • Halt will delete workload resources such as statefulset, deployment workloads but keep PVCs.
  • Delete is based on Halt and deletes PVCs.
  • WipeOut is based on Delete and wipe out all volume snapshots and snapshot data from backup storage location.
shardingSpecs
[]ShardingSpec
(Optional)

List of ShardingSpec which is used to define components with a sharding topology structure that make up a cluster. ShardingSpecs and ComponentSpecs cannot both be empty at the same time.

componentSpecs
[]ClusterComponentSpec
(Optional)

List of componentSpec which is used to define the components that make up a cluster. ComponentSpecs and ShardingSpecs cannot both be empty at the same time.

services
[]ClusterService
(Optional)

services defines the services to access a cluster.

affinity
Affinity
(Optional)

affinity is a group of affinity scheduling rules.

tolerations
[]Kubernetes core/v1.Toleration
(Optional)

tolerations are attached to tolerate any taint that matches the triple key,value,effect using the matching operator operator.

tenancy
TenancyType
(Optional)

tenancy describes how pods are distributed across node. SharedNode means multiple pods may share the same node. DedicatedNode means each pod runs on their own dedicated node.

availabilityPolicy
AvailabilityPolicyType
(Optional)

availabilityPolicy describes the availability policy, including zone, node, and none.

replicas
int32
(Optional)

replicas specifies the replicas of the first componentSpec, if the replicas of the first componentSpec is specified, this value will be ignored.

resources
ClusterResources
(Optional)

resources specifies the resources of the first componentSpec, if the resources of the first componentSpec is specified, this value will be ignored.

storage
ClusterStorage
(Optional)

storage specifies the storage of the first componentSpec, if the storage of the first componentSpec is specified, this value will be ignored.

monitor
ClusterMonitor
(Optional)

monitor specifies the configuration of monitor

network
ClusterNetwork
(Optional)

network specifies the configuration of network

backup
ClusterBackup
(Optional)

cluster backup configuration.

status
ClusterStatus

ClusterDefinition

ClusterDefinition is the Schema for the clusterdefinitions API

FieldDescription
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


type
string
(Optional)

Cluster definition type defines well known application cluster type, e.g. mysql/redis/mongodb

componentDefs
[]ClusterComponentDefinition

componentDefs provides cluster components definitions.

connectionCredential
map[string]string
(Optional)

Connection credential template used for creating a connection credential secret for cluster.apps.kubeblocks.io object.

Built-in objects are:

  • $(RANDOM_PASSWD) random 8 characters. dfjksgks
  • $(STRONG_RANDOM_PASSWD) random 16 characters, with mixed cases, digits and symbols.
  • $(UUID) generate a random UUID v4 string.
  • $(UUID_B64) generate a random UUID v4 BASE64 encoded string.
  • $(UUID_STR_B64) generate a random UUID v4 string then BASE64 encoded.
  • $(UUID_HEX) generate a random UUID v4 HEX representation.
  • $(HEADLESS_SVC_FQDN) headless service FQDN placeholder, value pattern is $(CLUSTER_NAME)-$(1ST_COMP_NAME)-headless.$(NAMESPACE).svc, where 1ST_COMP_NAME is the 1st component that provide ClusterDefinition.spec.componentDefs[].service attribute;
  • $(SVC_FQDN) service FQDN placeholder, value pattern is $(CLUSTER_NAME)-$(1ST_COMP_NAME).$(NAMESPACE).svc, where 1ST_COMP_NAME is the 1st component that provide ClusterDefinition.spec.componentDefs[].service attribute;
  • $(SVC_PORT_{PORT-NAME}) is ServicePort’s port value with specified port name, i.e, a servicePort JSON struct:{"name": "mysql", "targetPort": "mysqlContainerPort", "port": 3306}, and $(SVC_PORT_mysql) in the connection credential value is 3306.
status
ClusterDefinitionStatus

ClusterVersion

ClusterVersion is the Schema for the ClusterVersions API

FieldDescription
apiVersion
string
apps.kubeblocks.io/v1alpha1
kind
string
ClusterVersion
metadata
Kubernetes meta/v1.ObjectMeta
Refer to the Kubernetes API documentation for the fields of themetadata field.
spec
ClusterVersionSpec


clusterDefinitionRef
string

ref ClusterDefinition.

componentVersions
[]ClusterComponentVersion

List of components’ containers versioning context, i.e., container image ID, container commands, args, and environments.

status
ClusterVersionStatus

Component

Component is the Schema for the components API

FieldDescription
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


compDef
string

compDef is the name of the referenced componentDefinition.

classDefRef
ClassDefRef
(Optional)

classDefRef references the class defined in ComponentClassDefinition.

serviceRefs
[]ServiceRef
(Optional)

serviceRefs define service references for the current component. Based on the referenced services, they can be categorized into two types:

  • Service provided by external sources: These services are provided by external sources and are not managed by KubeBlocks. They can be Kubernetes-based or non-Kubernetes services. For external services, you need to provide an additional ServiceDescriptor object to establish the service binding.
  • Service provided by other KubeBlocks clusters: These services are provided by other KubeBlocks clusters. You can bind to these services by specifying the name of the hosting cluster.

Each type of service reference requires specific configurations and bindings to establish the connection and interaction with the respective services. It should be noted that the ServiceRef has cluster-level semantic consistency, meaning that within the same Cluster, service references with the same ServiceRef.Name are considered to be the same service. It is only allowed to bind to the same Cluster or ServiceDescriptor.

resources
Kubernetes core/v1.ResourceRequirements
(Optional)

Resources requests and limits of workload.

volumeClaimTemplates
[]ClusterComponentVolumeClaimTemplate
(Optional)

VolumeClaimTemplates information for statefulset.spec.volumeClaimTemplates.

replicas
int32

Component replicas. The default value is used in ClusterDefinition spec if not specified.

configs
[]ComponentConfigSpec
(Optional)
monitor
bool
(Optional)

monitor is a switch to enable monitoring and is set as false by default. KubeBlocks provides an extension mechanism to support component level monitoring, which will scrape metrics auto or manually from servers in component and export metrics to Time Series Database.

enabledLogs
[]string
(Optional)

enabledLogs indicates which log file takes effect in the database cluster. element is the log type which is defined in ComponentDefinition logConfig.name, and will set relative variables about this log type in database kernel.

updateStrategy
UpdateStrategy
(Optional)
serviceAccountName
string
(Optional)

serviceAccountName is the name of the ServiceAccount that running component depends on.

affinity
Affinity
(Optional)
tolerations
[]Kubernetes core/v1.Toleration
(Optional)
tlsConfig
TLSConfig
(Optional)
rsmTransformPolicy
RsmTransformPolicy
(Optional)

RsmTransformPolicy defines the policy generate sts using rsm. ToSts: rsm transform to statefulSet ToPod: rsm transform to pods

nodes
[]k8s.io/apimachinery/pkg/types.NodeName
(Optional)

Nodes defines the list of nodes that pods can schedule If the RsmTransformPolicy is specified as OneToMul,the list of nodes will be used. If the list of nodes is empty, no specific node will be assigned. However, if the list of node is filled, all pods will be evenly scheduled across the nodes in the list.

instances
[]string
(Optional)

Instances defines the list of instance to be deleted priorly

status
ComponentStatus

ComponentClassDefinition

ComponentClassDefinition is the Schema for the componentclassdefinitions API

FieldDescription
apiVersion
string
apps.kubeblocks.io/v1alpha1
kind
string
ComponentClassDefinition
metadata
Kubernetes meta/v1.ObjectMeta
Refer to the Kubernetes API documentation for the fields of themetadata field.
spec
ComponentClassDefinitionSpec


groups
[]ComponentClassGroup
(Optional)

group defines a list of class series that conform to the same constraint.

status
ComponentClassDefinitionStatus

ComponentDefinition

ComponentDefinition is the Schema for the componentdefinitions API

FieldDescription
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


provider
string
(Optional)

Provider is the name of the component provider.

description
string
(Optional)

Description is a brief description of the component.

serviceKind
string
(Optional)

ServiceKind defines what kind of well-known service that the component provides (e.g., MySQL, Redis, ETCD, case insensitive). Cannot be updated.

serviceVersion
string
(Optional)

ServiceVersion defines the version of the well-known service that the component provides. Cannot be updated.

runtime
Kubernetes core/v1.PodSpec

Runtime defines primarily runtime information for the component, including:

  • Init containers
  • Containers
    • Image
    • Commands
    • Args
    • Envs
    • Mounts
    • Ports
    • Security context
    • Probes
    • Lifecycle
  • Volumes

CPU and memory resource limits, as well as scheduling settings (affinity, toleration, priority), should not be configured within this structure. Cannot be updated.

vars
[]EnvVar
(Optional)

Vars represents user-defined variables.

These variables can be utilized as environment variables for Pods and Actions, or to render the templates of config and script. When used as environment variables, these variables are placed in front of the environment variables declared in the Pod. Cannot be updated.

volumes
[]ComponentVolume
(Optional)

Volumes defines the persistent volumes needed by the component. The users are responsible for providing these volumes when creating a component instance. Cannot be updated.

services
[]ComponentService
(Optional)

Services defines endpoints that can be used to access the component service to manage the component.

In addition, a reserved headless service will be created by default, with the name pattern {clusterName}-{componentName}-headless. Cannot be updated.

configs
[]ComponentConfigSpec
(Optional)

The configs field provided by provider, and finally this configTemplateRefs will be rendered into the user’s own configuration file according to the user’s cluster. Cannot be updated.

logConfigs
[]LogConfig
(Optional)

LogConfigs is detail log file config which provided by provider. Cannot be updated.

monitor
MonitorConfig
(Optional)

Monitor is monitoring config which provided by provider. Cannot be updated.

scripts
[]ComponentTemplateSpec
(Optional)

The scripts field provided by provider, and finally this configTemplateRefs will be rendered into the user’s own configuration file according to the user’s cluster. Cannot be updated.

policyRules
[]Kubernetes rbac/v1.PolicyRule
(Optional)

PolicyRules defines the namespaced policy rules required by the component. If any rule application fails (e.g., due to lack of permissions), the provisioning of the component instance will also fail. Cannot be updated.

labels
map[string]string
(Optional)

Labels defines static labels that will be patched to all k8s resources created for the component. If a label key conflicts with any other system labels or user-specified labels, it will be silently ignored. Cannot be updated.

replicasLimit
ReplicasLimit
(Optional)

ReplicasLimit defines the limit of valid replicas supported. Cannot be updated.

systemAccounts
[]SystemAccount
(Optional)

SystemAccounts defines the pre-defined system accounts required to manage the component. Cannot be updated.

updateStrategy
UpdateStrategy
(Optional)

UpdateStrategy defines the strategy for updating the component instance. Cannot be updated.

roles
[]ReplicaRole
(Optional)

Roles defines all the roles that the component can assume. Cannot be updated.

roleArbitrator
RoleArbitrator
(Optional)

RoleArbitrator defines the strategy for electing the component’s active role. Cannot be updated.

lifecycleActions
ComponentLifecycleActions
(Optional)

LifecycleActions defines the operational actions that needed to interoperate with the component service and processes for lifecycle management. Cannot be updated.

serviceRefDeclarations
[]ServiceRefDeclaration
(Optional)

ServiceRefDeclarations is used to declare the service reference of the current component. Cannot be updated.

status
ComponentDefinitionStatus

ComponentResourceConstraint

ComponentResourceConstraint is the Schema for the componentresourceconstraints API

FieldDescription
apiVersion
string
apps.kubeblocks.io/v1alpha1
kind
string
ComponentResourceConstraint
metadata
Kubernetes meta/v1.ObjectMeta
Refer to the Kubernetes API documentation for the fields of themetadata field.
spec
ComponentResourceConstraintSpec


rules
[]ResourceConstraintRule

Component resource constraint rules.

selector
[]ClusterResourceConstraintSelector
(Optional)

selector is used to bind the resource constraint to cluster definitions based on ClusterDefinition API.

componentSelector
[]ComponentResourceConstraintSelector
(Optional)

componentSelector is used to bind the resource constraint to components based on ComponentDefinition API.

ConfigConstraint

ConfigConstraint is the Schema for the configconstraint API

FieldDescription
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


reloadOptions
ReloadOptions
(Optional)

reloadOptions indicates whether the process supports reload.

if set, the controller will determine the behavior of the engine instance based on the configuration templates, restart or reload depending on whether any parameters in the StaticParameters have been modified.

toolsImageSpec
ToolsImageSpec
(Optional)

toolConfig used to config init container.

downwardAPIOptions
[]DownwardAPIOption
(Optional)

downwardAPIOptions is used to watch pod fields.

scriptConfigs
[]ScriptConfig
(Optional)

scriptConfigs, list of ScriptConfig, witch these scripts can be used by volume trigger,downward trigger, or tool image

cfgSchemaTopLevelName
string
(Optional)

cfgSchemaTopLevelName is cue type name, which generates openapi schema.

configurationSchema
CustomParametersValidation
(Optional)

configurationSchema imposes restrictions on database parameter’s rule.

staticParameters
[]string
(Optional)

staticParameters, list of StaticParameter, modifications of them trigger a process restart.

dynamicParameters
[]string
(Optional)

dynamicParameters, list of DynamicParameter, modifications of them trigger a config dynamic reload without process restart.

immutableParameters
[]string
(Optional)

immutableParameters describes parameters that prohibit user from modification.

selector
Kubernetes meta/v1.LabelSelector

selector is used to match the label on the pod, for example, a pod of the primary is match on the patroni cluster.

formatterConfig
FormatterConfig

formatterConfig describes the format of the configuration file, the controller will:

  1. parses configuration file
  2. analyzes the modified parameters
  3. applies corresponding policies.
status
ConfigConstraintStatus

Configuration

Configuration is the Schema for the configurations API

FieldDescription
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


clusterRef
string

clusterRef references Cluster name.

componentName
string

componentName is cluster component name.

configItemDetails
[]ConfigurationItemDetail
(Optional)

customConfigurationItems describes user-defined config template.

status
ConfigurationStatus

OpsDefinition

OpsDefinition is the Schema for the opsdefinitions API

FieldDescription
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


componentDefinitionRefs
[]ComponentDefinitionRef

componentDefinitionRefs indicates which types of componentDefinitions are supported by the operation, and can refer some vars of the componentDefinition. if it is set, the component that does not meet the conditions will be intercepted.

varsRef
VarsRef
(Optional)

varsRef defines the envs that need to be referenced from the target component pod, and will inject to job’s containers.

parametersSchema
ParametersSchema
(Optional)

parametersSchema describes the schema used for validation, pruning, and defaulting.

jobSpec
Kubernetes batch/v1.JobSpec

jobSpec describes the job spec for the operation.

preConditions
[]PreCondition
(Optional)

preCondition if it meets the requirements to run the job for the operation.

status
OpsDefinitionStatus

OpsRequest

OpsRequest is the Schema for the opsrequests API

FieldDescription
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


clusterRef
string

clusterRef references cluster object.

cancel
bool
(Optional)

cancel defines the action to cancel the Pending/Creating/Running opsRequest, supported types: VerticalScaling/HorizontalScaling. once cancel is set to true, this opsRequest will be canceled and modifying this property again will not take effect.

type
OpsType

type defines the operation type.

ttlSecondsAfterSucceed
int32
(Optional)

ttlSecondsAfterSucceed OpsRequest will be deleted after TTLSecondsAfterSucceed second when OpsRequest.status.phase is Succeed.

upgrade
Upgrade
(Optional)

upgrade specifies the cluster version by specifying clusterVersionRef.

horizontalScaling
[]HorizontalScaling
(Optional)

horizontalScaling defines what component need to horizontal scale the specified replicas.

volumeExpansion
[]VolumeExpansion
(Optional)

volumeExpansion defines what component and volumeClaimTemplate need to expand the specified storage.

restart
[]ComponentOps
(Optional)

restart the specified components.

switchover
[]Switchover
(Optional)

switchover the specified components.

verticalScaling
[]VerticalScaling
(Optional)

verticalScaling defines what component need to vertical scale the specified compute resources.

reconfigure
Reconfigure
(Optional)

reconfigure defines the variables that need to input when updating configuration.

reconfigures
[]Reconfigure
(Optional)

reconfigure defines the variables that need to input when updating configuration.

expose
[]Expose
(Optional)

expose defines services the component needs to expose.

restoreFrom
RestoreFromSpec
(Optional)

cluster RestoreFrom backup or point in time

ttlSecondsBeforeAbort
int32
(Optional)

ttlSecondsBeforeAbort OpsRequest will wait at most TTLSecondsBeforeAbort seconds for start-conditions to be met. If not specified, the default value is 0, which means that the start-conditions must be met immediately.

scriptSpec
ScriptSpec
(Optional)

scriptSpec defines the script to be executed.

backupSpec
BackupSpec
(Optional)

backupSpec defines how to backup the cluster.

restoreSpec
RestoreSpec
(Optional)

restoreSpec defines how to restore the cluster. note that this restore operation will roll back cluster services.

customSpec
CustomOpsSpec
status
OpsRequestStatus

ServiceDescriptor

ServiceDescriptor is the Schema for the servicedescriptors API

FieldDescription
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


serviceKind
string

service kind, indicating the type or nature of the service. It should be well-known application cluster type, e.g. {mysql, redis, mongodb}. The serviceKind is case-insensitive and supports abbreviations for some well-known databases. For example, both zk and zookeeper will be considered as a ZooKeeper cluster, and pg, postgres, postgresql will all be considered as a PostgreSQL cluster.

serviceVersion
string

The version of the service reference.

endpoint
CredentialVar
(Optional)

endpoint is the endpoint of the service connection credential.

auth
ConnectionCredentialAuth
(Optional)

auth is the auth of the service connection credential.

port
CredentialVar
(Optional)

port is the port of the service connection credential.

status
ServiceDescriptorStatus

AccessMode (string alias)

(Appears on:ConsensusMember, ConsensusMemberStatus)

AccessMode defines SVC access mode enums.

ValueDescription

"None"

"ReadWrite"

"Readonly"

AccountName (string alias)

(Appears on:SystemAccountConfig)

AccountName defines system account names.

ValueDescription

"kbadmin"

"kbdataprotection"

"kbmonitoring"

"kbprobe"

"kbreplicator"

Action

(Appears on:ComponentSwitchover, LifecycleActionHandler)

Action defines an operational action that can be performed by a component instance. There are some pre-defined environment variables that can be used when writing action commands, check @BuiltInVars for reference.

An action is considered successful if it returns 0 (or HTTP 200 for HTTP(s) actions). Any other return value or HTTP status code is considered as a 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 included in the HTTP response payload with a non-200 HTTP status code).
FieldDescription
image
string
(Optional)

Image defines the container image to run the action. Cannot be updated.

exec
ExecAction
(Optional)

Exec specifies the action to take. Cannot be updated.

http
HTTPAction
(Optional)

HTTP specifies the http request to perform. Cannot be updated.

env
[]Kubernetes core/v1.EnvVar
(Optional)

List of environment variables to set in the container. Cannot be updated.

targetPodSelector
TargetPodSelector
(Optional)

TargetPodSelector defines the way that how to select the target Pod where the action will be performed, if there may not have a target replica by default. Cannot be updated.

matchingKey
string
(Optional)

MatchingKey uses to select the target pod(s) actually. If the selector is AnyReplica or AllReplicas, the matchingKey will be ignored. If the selector is RoleSelector, any replica which has the same role with matchingKey will be chosen. Cannot be updated.

container
string
(Optional)

Container defines the name of the container within the target Pod where the action will be executed. If specified, it must be one of container declared in @Runtime. If not specified, the first container declared in @Runtime will be used. Cannot be updated.

timeoutSeconds:omitempty
int32
(Optional)

TimeoutSeconds defines the timeout duration for the action in seconds. Cannot be updated.

retryPolicy
RetryPolicy
(Optional)

RetryPolicy defines the strategy for retrying the action in case of failure. Cannot be updated.

preCondition
PreConditionType
(Optional)

PreCondition defines the condition when the action will be executed.

  • Immediately: The Action is executed immediately after the Component object is created, without guaranteeing the availability of the Component and its underlying resources. only after the action is successfully executed will the Component’s state turn to ready.
  • RuntimeReady: The Action is executed after the Component object is created and once all underlying Runtimes are ready. only after the action is successfully executed will the Component’s state turn to ready.
  • ComponentReady: The Action is executed after the Component object is created and once the Component is ready. the execution process does not impact the state of the Component and the Cluster.
  • ClusterReady: The Action is executed after the Cluster object is created and once the Cluster is ready.

the execution process does not impact the state of the Component and the Cluster. Cannot be updated.

Affinity

(Appears on:ClusterComponentSpec, ClusterSpec, ComponentSpec)

FieldDescription
podAntiAffinity
PodAntiAffinity
(Optional)

podAntiAffinity describes the anti-affinity level of pods within a component. Preferred means try spread pods by TopologyKeys. Required means must spread pods by TopologyKeys.

topologyKeys
[]string
(Optional)

topologyKey is the key of node labels. Nodes that have a label with this key and identical values are considered to be in the same topology. It’s used as the topology domain for pod anti-affinity and pod spread constraint. Some well-known label keys, such as kubernetes.io/hostname and topology.kubernetes.io/zoneare often used as TopologyKey, as well as any other custom label key.

nodeLabels
map[string]string
(Optional)

nodeLabels describes that pods must be scheduled to the nodes with the specified node labels.

tenancy
TenancyType
(Optional)

tenancy describes how pods are distributed across node. SharedNode means multiple pods may share the same node. DedicatedNode means each pod runs on their own dedicated node.

AutoTrigger

(Appears on:ReloadOptions)

FieldDescription
processName
string
(Optional)

processName is process name

AvailabilityPolicyType (string alias)

(Appears on:ClusterSpec)

AvailabilityPolicyType for cluster affinity policy.

ValueDescription

"node"

"none"

"zone"

BackupMethod

(Appears on:BackupPolicy)

FieldDescription
BackupMethod
github.com/apecloud/kubeblocks/apis/dataprotection/v1alpha1.BackupMethod

(Members of BackupMethod are embedded into this type.)

target
TargetInstance
(Optional)

target instance for backup.

envMapping
[]EnvMappingVar
(Optional)

envMapping defines the variables of cluster mapped to env values’ keys.

BackupPolicy

(Appears on:BackupPolicyTemplateSpec)

FieldDescription
componentDefRef
string
(Optional)

componentDefRef references componentDef defined in ClusterDefinition spec. Need to comply with IANA Service Naming rule.

componentDefs
[]string
(Optional)

componentDef references componentDefinition. Need to comply with IANA Service Naming rule.

target
TargetInstance
(Optional)

target instance for backup.

schedules
[]SchedulePolicy
(Optional)

schedule policy for backup.

backupMethods
[]BackupMethod

backupMethods defines the backup methods.

backoffLimit
int32
(Optional)

Specifies the number of retries before marking the backup failed.

BackupPolicyTemplateSpec

(Appears on:BackupPolicyTemplate)

BackupPolicyTemplateSpec defines the desired state of BackupPolicyTemplate

FieldDescription
clusterDefinitionRef
string

clusterDefinitionRef references ClusterDefinition name, this is an immutable attribute.

backupPolicies
[]BackupPolicy

backupPolicies is a list of backup policy template for the specified componentDefinition.

identifier
string
(Optional)

Identifier is a unique identifier for this BackupPolicyTemplate. this identifier will be the suffix of the automatically generated backupPolicy name. and must be added when multiple BackupPolicyTemplates exist, otherwise the generated backupPolicy override will occur.

BackupPolicyTemplateStatus

(Appears on:BackupPolicyTemplate)

BackupPolicyTemplateStatus defines the observed state of BackupPolicyTemplate

BackupRefSpec

(Appears on:RestoreFromSpec)

FieldDescription
ref
RefNamespaceName
(Optional)

specify a reference backup to restore

BackupSpec

(Appears on:OpsRequestSpec)

FieldDescription
backupName
string
(Optional)

backupName is the name of the backup.

backupPolicyName
string
(Optional)

Which backupPolicy is applied to perform this backup

backupMethod
string
(Optional)

Backup method name that is defined in backupPolicy.

deletionPolicy
string
(Optional)

deletionPolicy determines whether the backup contents stored in backup repository should be deleted when the backup custom resource is deleted. Supported values are Retain and Delete.

  • Retain means that the backup content and its physical snapshot on backup repository are kept.
  • Delete means that the backup content and its physical snapshot on backup repository are deleted.
retentionPeriod
string
(Optional)

retentionPeriod determines a duration up to which the backup should be kept. Controller will remove all backups that are older than the RetentionPeriod. For example, RetentionPeriod of 30d will keep only the backups of last 30 days. Sample duration format:

  • years: 2y
  • months: 6mo
  • days: 30d
  • hours: 12h
  • minutes: 30m

You can also combine the above durations. For example: 30d12h30m. If not set, the backup will be kept forever.

parentBackupName
string
(Optional)

if backupType is incremental, parentBackupName is required.

BackupStatusUpdateStage (string alias)

BackupStatusUpdateStage defines the stage of backup status update.

BaseBackupType (string alias)

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

BuiltinActionHandlerType (string alias)

(Appears on:LifecycleActionHandler)

BuiltinActionHandlerType defines build-in action handlers provided by Lorry.

ValueDescription

"apecloud-postgresql"

"etcd"

"mongodb"

"mysql"

"oceanbase"

"official-postgresql"

"polardbx"

"postgresql"

"redis"

"unknown"

"wesql"

CPUConstraint

(Appears on:ResourceConstraintRule)

FieldDescription
max
Kubernetes resource.Quantity
(Optional)

The maximum count of vcpu cores, [Min, Max] defines a range for valid vcpu cores, and the value in this range must be multiple times of Step. It’s useful to define a large number of valid values without defining them one by one. Please see the documentation for Step for some examples. If Slots is specified, Max, Min, and Step are ignored

min
Kubernetes resource.Quantity
(Optional)

The minimum count of vcpu cores, [Min, Max] defines a range for valid vcpu cores, and the value in this range must be multiple times of Step. It’s useful to define a large number of valid values without defining them one by one. Please see the documentation for Step for some examples. If Slots is specified, Max, Min, and Step are ignored

step
Kubernetes resource.Quantity
(Optional)

The minimum granularity of vcpu cores, [Min, Max] defines a range for valid vcpu cores and the value in this range must be multiple times of Step. For example: 1. Min is 2, Max is 8, Step is 2, and the valid vcpu core is {2, 4, 6, 8}. 2. Min is 0.5, Max is 2, Step is 0.5, and the valid vcpu core is {0.5, 1, 1.5, 2}.

slots
[]Kubernetes resource.Quantity
(Optional)

The valid vcpu cores, it’s useful if you want to define valid vcpu cores explicitly. If Slots is specified, Max, Min, and Step are ignored

CfgFileFormat (string alias)

(Appears on:FormatterConfig)

CfgFileFormat defines formatter of configuration files.

ValueDescription

"dotenv"

"hcl"

"ini"

"json"

"properties"

"props-plus"

"redis"

"toml"

"xml"

"yaml"

CfgReloadType (string alias)

CfgReloadType defines reload method.

ValueDescription

"auto"

"http"

"sql"

"exec"

"tpl"

"signal"

ClassDefRef

(Appears on:ClusterComponentSpec, ComponentSpec, LastComponentConfiguration, VerticalScaling)

FieldDescription
name
string
(Optional)

Name refers to the name of the ComponentClassDefinition.

class
string

Class refers to the name of the class that is defined in the ComponentClassDefinition.

ClusterBackup

(Appears on:ClusterSpec)

FieldDescription
enabled
bool
(Optional)

enabled defines whether to enable automated backup.

retentionPeriod
github.com/apecloud/kubeblocks/apis/dataprotection/v1alpha1.RetentionPeriod
(Optional)

retentionPeriod determines a duration up to which the backup should be kept. controller will remove all backups that are older than the RetentionPeriod. For example, RetentionPeriod of 30d will keep only the backups of last 30 days. Sample duration format:

  • years: 2y
  • months: 6mo
  • days: 30d
  • hours: 12h
  • minutes: 30m

You can also combine the above durations. For example: 30d12h30m

method
string
(Optional)

backup method name to use, that is defined in backupPolicy.

cronExpression
string
(Optional)

the cron expression for schedule, the timezone is in UTC. see https://en.wikipedia.org/wiki/Cron.

startingDeadlineMinutes
int64
(Optional)

startingDeadlineMinutes defines the deadline in minutes for starting the backup job if it misses scheduled time for any reason.

repoName
string
(Optional)

repoName is the name of the backupRepo, if not set, will use the default backupRepo.

pitrEnabled
bool
(Optional)

pitrEnabled defines whether to enable point-in-time recovery.

ClusterComponentDefinition

(Appears on:ClusterDefinitionSpec)

ClusterComponentDefinition provides a workload component specification template, with attributes that strongly work with stateful workloads and day-2 operations behaviors.

FieldDescription
name
string

A component definition name, this name could be used as default name of Cluster.spec.componentSpecs.name, and so this name is need to conform with same validation rules as Cluster.spec.componentSpecs.name, that is currently comply with IANA Service Naming rule. This name will apply to “apps.kubeblocks.io/component-name” object label value.

description
string
(Optional)

The description of component definition.

workloadType
WorkloadType

workloadType defines type of the workload.

  • Stateless is a stateless workload type used to describe stateless applications.
  • Stateful is a stateful workload type used to describe common stateful applications.
  • Consensus is a stateful workload type used to describe applications based on consensus protocols, common consensus protocols such as raft and paxos.
  • Replication is a stateful workload type used to describe applications based on the primary-secondary data replication protocol.
characterType
string
(Optional)

characterType defines well-known database component name, such as mongos(mongodb), proxy(redis), mariadb(mysql). KubeBlocks will generate proper monitor configs for well-known characterType when builtIn is true.

It will also be used in role probe to decide which probe engine to use. current available candidates are: mysql, postgres, mongodb, redis, etcd, kafka.

configSpecs
[]ComponentConfigSpec
(Optional)

The configSpec field provided by provider, and finally this configTemplateRefs will be rendered into the user’s own configuration file according to the user’s cluster.

scriptSpecs
[]ComponentTemplateSpec
(Optional)

The scriptSpec field provided by provider, and finally this configTemplateRefs will be rendered into the user’s own configuration file according to the user’s cluster.

probes
ClusterDefinitionProbes
(Optional)

probes setting for healthy checks.

monitor
MonitorConfig
(Optional)

monitor is monitoring config which provided by provider.

logConfigs
[]LogConfig
(Optional)

logConfigs is detail log file config which provided by provider.

podSpec
Kubernetes core/v1.PodSpec
(Optional)

podSpec define pod spec template of the cluster component.

service
ServiceSpec
(Optional)

service defines the behavior of a service spec. provide read-write service when WorkloadType is Consensus.

statelessSpec
StatelessSetSpec
(Optional)

statelessSpec defines stateless related spec if workloadType is Stateless.

statefulSpec
StatefulSetSpec
(Optional)

statefulSpec defines stateful related spec if workloadType is Stateful.

consensusSpec
ConsensusSetSpec
(Optional)

consensusSpec defines consensus related spec if workloadType is Consensus, required if workloadType is Consensus.

replicationSpec
ReplicationSetSpec
(Optional)

replicationSpec defines replication related spec if workloadType is Replication.

rsmSpec
RSMSpec
(Optional)

RSMSpec defines workload related spec of this component. start from KB 0.7.0, RSM(ReplicatedStateMachineSpec) will be the underlying CR which powers all kinds of workload in KB. RSM is an enhanced stateful workload extension dedicated for heavy-state workloads like databases.

horizontalScalePolicy
HorizontalScalePolicy
(Optional)

horizontalScalePolicy controls the behavior of horizontal scale.

systemAccounts
SystemAccountSpec
(Optional)

Statement to create system account.

volumeTypes
[]VolumeTypeSpec
(Optional)

volumeTypes is used to describe the purpose of the volumes mapping the name of the VolumeMounts in the PodSpec.Container field, such as data volume, log volume, etc. When backing up the volume, the volume can be correctly backed up according to the volumeType.

For example:

  • name: data, type: data means that the volume named data is used to store data.
  • name: binlog, type: log means that the volume named binlog is used to store log.

NOTE: When volumeTypes is not defined, the backup function will not be supported, even if a persistent volume has been specified.

customLabelSpecs
[]CustomLabelSpec
(Optional)

customLabelSpecs is used for custom label tags which you want to add to the component resources.

switchoverSpec
SwitchoverSpec
(Optional)

switchoverSpec defines command to do switchover. in particular, when workloadType=Replication, the command defined in switchoverSpec will only be executed under the condition of cluster.componentSpecs[x].SwitchPolicy.type=Noop.

postStartSpec
PostStartAction
(Optional)

postStartSpec defines the command to be executed when the component is ready, and the command will only be executed once after the component becomes ready.

volumeProtectionSpec
VolumeProtectionSpec
(Optional)
componentDefRef
[]ComponentDefRef
(Optional)

componentDefRef is used to inject values from other components into the current component. values will be saved and updated in a configmap and mounted to the current component.

serviceRefDeclarations
[]ServiceRefDeclaration
(Optional)

serviceRefDeclarations is used to declare the service reference of the current component.

ClusterComponentPhase (string alias)

(Appears on:ClusterComponentStatus, ComponentStatus, OpsRequestComponentStatus)

ClusterComponentPhase defines the Cluster CR .status.components.phase

ValueDescription

"Abnormal"

"Creating"

"Deleting"

"Failed"

"Running"

"Stopped"

"Stopping"

"Updating"

ClusterComponentService

(Appears on:ClusterComponentSpec, LastComponentConfiguration)

FieldDescription
name
string

Service name

serviceType
Kubernetes core/v1.ServiceType
(Optional)

serviceType determines how the Service is exposed. Valid options are ClusterIP, NodePort, and LoadBalancer.

  • ClusterIP allocates a cluster-internal IP address for load-balancing to endpoints. Endpoints are determined by the selector or if that is not specified, they are determined by manual construction of an Endpoints object or EndpointSlice objects. If clusterIP is “None”, no virtual IP is allocated and the endpoints are published as a set of endpoints rather than a virtual IP.
  • NodePort builds on ClusterIP and allocates a port on every node which routes to the same endpoints as the clusterIP.
  • LoadBalancer builds on NodePort and creates an external load-balancer (if supported in the current cloud) which routes to the same endpoints as the clusterIP.

More info: 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.

ClusterComponentSpec

(Appears on:ClusterSpec, ShardingSpec)

ClusterComponentSpec defines the cluster component spec.

FieldDescription
name
string
(Optional)

name defines cluster’s component name, this name is also part of Service DNS name, so this name will comply with IANA Service Naming rule. When ClusterComponentSpec is referenced as a template, name is optional. Otherwise, it is required.

componentDefRef
string
(Optional)

componentDefRef references componentDef defined in ClusterDefinition spec. Need to comply with IANA Service Naming rule.

componentDef
string
(Optional)

componentDef references the name of the ComponentDefinition. If both componentDefRef and componentDef are provided, the componentDef will take precedence over componentDefRef.

classDefRef
ClassDefRef
(Optional)

classDefRef references the class defined in ComponentClassDefinition.

serviceRefs
[]ServiceRef
(Optional)

serviceRefs define service references for the current component. Based on the referenced services, they can be categorized into two types:

  • Service provided by external sources: These services are provided by external sources and are not managed by KubeBlocks. They can be Kubernetes-based or non-Kubernetes services. For external services, you need to provide an additional ServiceDescriptor object to establish the service binding.
  • Service provided by other KubeBlocks clusters: These services are provided by other KubeBlocks clusters. You can bind to these services by specifying the name of the hosting cluster.

Each type of service reference requires specific configurations and bindings to establish the connection and interaction with the respective services. It should be noted that the ServiceRef has cluster-level semantic consistency, meaning that within the same Cluster, service references with the same ServiceRef.Name are considered to be the same service. It is only allowed to bind to the same Cluster or ServiceDescriptor.

monitor
bool
(Optional)

monitor is a switch to enable monitoring and is set as false by default. KubeBlocks provides an extension mechanism to support component level monitoring, which will scrape metrics auto or manually from servers in component and export metrics to Time Series Database.

enabledLogs
[]string
(Optional)

enabledLogs indicates which log file takes effect in the database cluster. element is the log type which is defined in cluster definition logConfig.name, and will set relative variables about this log type in database kernel.

replicas
int32

Component replicas.

affinity
Affinity
(Optional)

affinity describes affinities specified by users.

tolerations
[]Kubernetes core/v1.Toleration
(Optional)

Component tolerations will override ClusterSpec.Tolerations if specified.

resources
Kubernetes core/v1.ResourceRequirements
(Optional)

Resources requests and limits of workload.

volumeClaimTemplates
[]ClusterComponentVolumeClaimTemplate
(Optional)

volumeClaimTemplates information for statefulset.spec.volumeClaimTemplates.

services
[]ClusterComponentService
(Optional)

Services expose endpoints that can be accessed by clients.

switchPolicy
ClusterSwitchPolicy
(Optional)

switchPolicy defines the strategy for switchover and failover when workloadType is Replication.

tls
bool
(Optional)

Enables or disables TLS certs.

issuer
Issuer
(Optional)

issuer defines provider context for TLS certs. required when TLS enabled

serviceAccountName
string
(Optional)

serviceAccountName is the name of the ServiceAccount that running component depends on.

noCreatePDB
bool
(Optional)

noCreatePDB defines the PodDisruptionBudget creation behavior and is set to true if creation of PodDisruptionBudget for this component is not needed. It defaults to false.

updateStrategy
UpdateStrategy
(Optional)

updateStrategy defines the update strategy for the component.

userResourceRefs
UserResourceRefs
(Optional)

userResourceRefs defines the user-defined volumes.

rsmTransformPolicy
RsmTransformPolicy
(Optional)

RsmTransformPolicy defines the policy generate sts using rsm. ToSts: rsm transforms to statefulSet ToPod: rsm transforms to pods

nodes
[]k8s.io/apimachinery/pkg/types.NodeName
(Optional)

Nodes defines the list of nodes that pods can schedule If the RsmTransformPolicy is specified as ToPod,the list of nodes will be used. If the list of nodes is empty, no specific node will be assigned. However, if the list of node is filled, all pods will be evenly scheduled across the nodes in the list.

instances
[]string
(Optional)

Instances defines the list of instance to be deleted priorly If the RsmTransformPolicy is specified as ToPod,the list of instances will be used.

ClusterComponentStatus

(Appears on:ClusterStatus)

ClusterComponentStatus records components status.

FieldDescription
phase
ClusterComponentPhase

phase describes the phase of the component and the detail information of the phases are as following:

  • Creating: Creating is a special Updating with previous phase empty(means “”) or Creating.
  • Running: component replicas > 0 and all pod specs are latest with a Running state.
  • Updating: component replicas > 0 and has no failed pods. the component is being updated.
  • Abnormal: component replicas > 0 but having some failed pods. the component basically works but in a fragile state.
  • Failed: component replicas > 0 but having some failed pods. the component doesn’t work anymore.
  • Stopping: component replicas = 0 and has terminating pods.
  • Stopped: component replicas = 0 and all pods have been deleted.
  • Deleting: the component is being deleted.
message
ComponentMessageMap
(Optional)

message records the component details message in current phase. Keys are podName or deployName or statefulSetName. The format is ObjectKind/Name.

podsReady
bool
(Optional)

podsReady checks if all pods of the component are ready.

podsReadyTime
Kubernetes meta/v1.Time
(Optional)

podsReadyTime what time point of all component pods are ready, this time is the ready time of the last component pod.

consensusSetStatus
ConsensusSetStatus
(Optional)

consensusSetStatus specifies the mapping of role and pod name.

replicationSetStatus
ReplicationSetStatus
(Optional)

replicationSetStatus specifies the mapping of role and pod name.

membersStatus
[]MemberStatus
(Optional)

members’ status.

ClusterComponentVersion

(Appears on:ClusterVersionSpec)

ClusterComponentVersion is an application version component spec.

FieldDescription
componentDefRef
string

componentDefRef reference one of the cluster component definition names in ClusterDefinition API (spec.componentDefs.name).

configSpecs
[]ComponentConfigSpec
(Optional)

configSpecs defines a configuration extension mechanism to handle configuration differences between versions, the configTemplateRefs field, together with configTemplateRefs in the ClusterDefinition, determines the final configuration file.

systemAccountSpec
SystemAccountShortSpec
(Optional)

systemAccountSpec define image for the component to connect database or engines. It overrides image and env attributes defined in ClusterDefinition.spec.componentDefs.systemAccountSpec.cmdExecutorConfig. To clean default envs settings, set SystemAccountSpec.CmdExecutorConfig.Env to empty list.

versionsContext
VersionsContext

versionContext defines containers images’ context for component versions, this value replaces ClusterDefinition.spec.componentDefs.podSpec.[initContainers | containers]

switchoverSpec
SwitchoverShortSpec
(Optional)

switchoverSpec defines images for the component to do switchover. It overrides image and env attributes defined in ClusterDefinition.spec.componentDefs.SwitchoverSpec.CommandExecutorEnvItem.

ClusterComponentVolumeClaimTemplate

(Appears on:ClusterComponentSpec, ComponentSpec)

FieldDescription
name
string

Reference ClusterDefinition.spec.componentDefs.containers.volumeMounts.name.

spec
PersistentVolumeClaimSpec
(Optional)

spec defines the desired characteristics of a volume requested by a pod author.



accessModes
[]Kubernetes core/v1.PersistentVolumeAccessMode
(Optional)

accessModes 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.ResourceRequirements
(Optional)

resources represents the minimum resources the volume should have. If RecoverVolumeExpansionFailure feature is enabled users are allowed to specify resource requirements that are lower than previous value but must still be higher than capacity recorded in the status field of the claim. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#resources.

storageClassName
string
(Optional)

storageClassName is 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)

volumeMode defines what type of volume is required by the claim.

ClusterDefinitionProbe

(Appears on:ClusterDefinitionProbes)

FieldDescription
periodSeconds
int32

How often (in seconds) to perform the probe.

timeoutSeconds
int32

Number of seconds after which the probe times out. Defaults to 1 second.

failureThreshold
int32

Minimum consecutive failures for the probe to be considered failed after having succeeded.

commands
ClusterDefinitionProbeCMDs
(Optional)

commands used to execute for probe.

ClusterDefinitionProbeCMDs

(Appears on:ClusterDefinitionProbe)

FieldDescription
writes
[]string
(Optional)

Write check executed on probe sidecar, used to check workload’s allow write access.

queries
[]string
(Optional)

Read check executed on probe sidecar, used to check workload’s readonly access.

ClusterDefinitionProbes

(Appears on:ClusterComponentDefinition)

FieldDescription
runningProbe
ClusterDefinitionProbe
(Optional)

Probe for DB running check.

statusProbe
ClusterDefinitionProbe
(Optional)

Probe for DB status check.

roleProbe
ClusterDefinitionProbe
(Optional)

Probe for DB role changed check.

roleProbeTimeoutAfterPodsReady
int32
(Optional)

roleProbeTimeoutAfterPodsReady(in seconds), when all pods of the component are ready, it will detect whether the application is available in the pod. if pods exceed the InitializationTimeoutSeconds time without a role label, this component will enter the Failed/Abnormal phase.

Note that this configuration will only take effect if the component supports RoleProbe and will not affect the life cycle of the pod. default values are 60 seconds.

ClusterDefinitionSpec

(Appears on:ClusterDefinition)

ClusterDefinitionSpec defines the desired state of ClusterDefinition

FieldDescription
type
string
(Optional)

Cluster definition type defines well known application cluster type, e.g. mysql/redis/mongodb

componentDefs
[]ClusterComponentDefinition

componentDefs provides cluster components definitions.

connectionCredential
map[string]string
(Optional)

Connection credential template used for creating a connection credential secret for cluster.apps.kubeblocks.io object.

Built-in objects are:

  • $(RANDOM_PASSWD) random 8 characters. dfjksgks
  • $(STRONG_RANDOM_PASSWD) random 16 characters, with mixed cases, digits and symbols.
  • $(UUID) generate a random UUID v4 string.
  • $(UUID_B64) generate a random UUID v4 BASE64 encoded string.
  • $(UUID_STR_B64) generate a random UUID v4 string then BASE64 encoded.
  • $(UUID_HEX) generate a random UUID v4 HEX representation.
  • $(HEADLESS_SVC_FQDN) headless service FQDN placeholder, value pattern is $(CLUSTER_NAME)-$(1ST_COMP_NAME)-headless.$(NAMESPACE).svc, where 1ST_COMP_NAME is the 1st component that provide ClusterDefinition.spec.componentDefs[].service attribute;
  • $(SVC_FQDN) service FQDN placeholder, value pattern is $(CLUSTER_NAME)-$(1ST_COMP_NAME).$(NAMESPACE).svc, where 1ST_COMP_NAME is the 1st component that provide ClusterDefinition.spec.componentDefs[].service attribute;
  • $(SVC_PORT_{PORT-NAME}) is ServicePort’s port value with specified port name, i.e, a servicePort JSON struct:{"name": "mysql", "targetPort": "mysqlContainerPort", "port": 3306}, and $(SVC_PORT_mysql) in the connection credential value is 3306.

ClusterDefinitionStatus

(Appears on:ClusterDefinition)

ClusterDefinitionStatus defines the observed state of ClusterDefinition

FieldDescription
phase
Phase

ClusterDefinition phase, valid values are empty, Available, Unavailable. Available is ClusterDefinition become available, and can be referenced for co-related objects.

message
string
(Optional)

Extra message in current phase

observedGeneration
int64
(Optional)

observedGeneration is the most recent generation observed for this ClusterDefinition. It corresponds to the ClusterDefinition’s generation, which is updated on mutation by the API Server.

ClusterMonitor

(Appears on:ClusterSpec)

FieldDescription
monitoringInterval
Kubernetes api utils intstr.IntOrString
(Optional)

monitoringInterval specifies interval of monitoring, no monitor if set to 0

ClusterNetwork

(Appears on:ClusterSpec)

FieldDescription
hostNetworkAccessible
bool
(Optional)

hostNetworkAccessible specifies whether host network is accessible. It defaults to false

publiclyAccessible
bool
(Optional)

publiclyAccessible specifies whether it is publicly accessible. It defaults to false

ClusterObjectReference

(Appears on:CredentialVarSelector, ServiceRefVarSelector, ServiceVarSelector)

ClusterObjectReference contains information to let you locate the referenced object inside the same cluster.

FieldDescription
compDef
string
(Optional)

CompDef specifies the definition used by the component that the referent object resident in.

name
string
(Optional)

Name of the referent object.

optional
bool
(Optional)

Specify whether the object must be defined.

ClusterPhase (string alias)

(Appears on:ClusterStatus, OpsRequestBehaviour)

ClusterPhase defines the Cluster CR .status.phase

ValueDescription

"Abnormal"

"Creating"

"Deleting"

"Failed"

"Running"

"Stopped"

"Stopping"

"Updating"

ClusterResourceConstraintSelector

(Appears on:ComponentResourceConstraintSpec)

FieldDescription
clusterDefRef
string

clusterDefRef is the name of the cluster definition.

components
[]ComponentResourceConstraintSelector

selector is used to bind the resource constraint to components.

ClusterResources

(Appears on:ClusterSpec)

FieldDescription
cpu
Kubernetes resource.Quantity
(Optional)

cpu resource needed, more info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/

memory
Kubernetes resource.Quantity
(Optional)

memory resource needed, more info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/

ClusterService

(Appears on:ClusterSpec)

ClusterService defines the service of a cluster.

FieldDescription
Service
Service

(Members of Service are embedded into this type.)

shardingSelector
string
(Optional)

ShardingSelector extends the ServiceSpec.Selector by allowing you to specify a sharding name defined in Cluster.Spec.ShardingSpecs[x].Name as selectors for the service. ShardingSelector and ComponentSelector cannot be set at the same time.

componentSelector
string
(Optional)

ComponentSelector extends the ServiceSpec.Selector by allowing you to specify a component as selectors for the service. ComponentSelector and ShardingSelector cannot be set at the same time.

ClusterSpec

(Appears on:Cluster)

ClusterSpec defines the desired state of Cluster.

FieldDescription
clusterDefinitionRef
string
(Optional)

Cluster referencing ClusterDefinition name. This is an immutable attribute. If ClusterDefRef is not specified, ComponentDef must be specified for each Component in ComponentSpecs.

clusterVersionRef
string
(Optional)

Cluster referencing ClusterVersion name.

terminationPolicy
TerminationPolicyType

Cluster termination policy. Valid values are DoNotTerminate, Halt, Delete, WipeOut.

  • DoNotTerminate will block delete operation.
  • Halt will delete workload resources such as statefulset, deployment workloads but keep PVCs.
  • Delete is based on Halt and deletes PVCs.
  • WipeOut is based on Delete and wipe out all volume snapshots and snapshot data from backup storage location.
shardingSpecs
[]ShardingSpec
(Optional)

List of ShardingSpec which is used to define components with a sharding topology structure that make up a cluster. ShardingSpecs and ComponentSpecs cannot both be empty at the same time.

componentSpecs
[]ClusterComponentSpec
(Optional)

List of componentSpec which is used to define the components that make up a cluster. ComponentSpecs and ShardingSpecs cannot both be empty at the same time.

services
[]ClusterService
(Optional)

services defines the services to access a cluster.

affinity
Affinity
(Optional)

affinity is a group of affinity scheduling rules.

tolerations
[]Kubernetes core/v1.Toleration
(Optional)

tolerations are attached to tolerate any taint that matches the triple key,value,effect using the matching operator operator.

tenancy
TenancyType
(Optional)

tenancy describes how pods are distributed across node. SharedNode means multiple pods may share the same node. DedicatedNode means each pod runs on their own dedicated node.

availabilityPolicy
AvailabilityPolicyType
(Optional)

availabilityPolicy describes the availability policy, including zone, node, and none.

replicas
int32
(Optional)

replicas specifies the replicas of the first componentSpec, if the replicas of the first componentSpec is specified, this value will be ignored.

resources
ClusterResources
(Optional)

resources specifies the resources of the first componentSpec, if the resources of the first componentSpec is specified, this value will be ignored.

storage
ClusterStorage
(Optional)

storage specifies the storage of the first componentSpec, if the storage of the first componentSpec is specified, this value will be ignored.

monitor
ClusterMonitor
(Optional)

monitor specifies the configuration of monitor

network
ClusterNetwork
(Optional)

network specifies the configuration of network

backup
ClusterBackup
(Optional)

cluster backup configuration.

ClusterStatus

(Appears on:Cluster)

ClusterStatus defines the observed state of Cluster.

FieldDescription
observedGeneration
int64
(Optional)

observedGeneration is the most recent generation observed for this Cluster. It corresponds to the Cluster’s generation, which is updated on mutation by the API Server.

phase
ClusterPhase
(Optional)

phase describes the phase of the Cluster, the detail information of the phases are as following:

  • Creating: all components are in Creating phase.
  • Running: all components are in Running phase, means the cluster is working well.
  • Updating: all components are in Creating, Running or Updating phase, and at least one component is in Creating or Updating phase, means the cluster is doing an update.
  • Stopping: at least one component is in Stopping phase, means the cluster is in a stop progress.
  • Stopped: all components are in Stopped phase, means the cluster has stopped and didn’t provide any function anymore.
  • Failed: all components are in Failed phase, means the cluster is unavailable.
  • Abnormal: some components are in Failed or Abnormal phase, means the cluster in a fragile state. troubleshoot need to be done.
  • Deleting: the cluster is being deleted.
message
string
(Optional)

message describes cluster details message in current phase.

components
map[string]github.com/apecloud/kubeblocks/apis/apps/v1alpha1.ClusterComponentStatus
(Optional)

components record the current status information of all components of the cluster.

clusterDefGeneration
int64
(Optional)

clusterDefGeneration represents the generation number of ClusterDefinition referenced.

conditions
[]Kubernetes meta/v1.Condition
(Optional)

Describe current state of cluster API Resource, like warning.

ClusterStorage

(Appears on:ClusterSpec)

FieldDescription
size
Kubernetes resource.Quantity
(Optional)

storage size needed, more info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/

ClusterSwitchPolicy

(Appears on:ClusterComponentSpec)

FieldDescription
type
SwitchPolicyType
(Optional)

clusterSwitchPolicy defines type of the switchPolicy when workloadType is Replication.

  • MaximumAvailability: [WIP] when the primary is active, do switch if the synchronization delay = 0 in the user-defined lagProbe data delay detection logic, otherwise do not switch. The primary is down, switch immediately. It will be available in future versions.
  • MaximumDataProtection: [WIP] when the primary is active, do switch if synchronization delay = 0 in the user-defined lagProbe data lag detection logic, otherwise do not switch. If the primary is down, if it can be judged that the primary and secondary data are consistent, then do the switch, otherwise do not switch. It will be available in future versions.
  • Noop: KubeBlocks will not perform high-availability switching on components. Users need to implement HA by themselves or integrate open source HA solution.

ClusterVersionSpec

(Appears on:ClusterVersion)

ClusterVersionSpec defines the desired state of ClusterVersion

FieldDescription
clusterDefinitionRef
string

ref ClusterDefinition.

componentVersions
[]ClusterComponentVersion

List of components’ containers versioning context, i.e., container image ID, container commands, args, and environments.

ClusterVersionStatus

(Appears on:ClusterVersion)

ClusterVersionStatus defines the observed state of ClusterVersion

FieldDescription
phase
Phase
(Optional)

phase - in list of [Available,Unavailable]

message
string
(Optional)

A human readable message indicating details about why the ClusterVersion is in this phase.

observedGeneration
int64
(Optional)

generation number

clusterDefGeneration
int64
(Optional)

clusterDefGeneration represents the generation number of ClusterDefinition referenced.

CmdExecutorConfig

(Appears on:PostStartAction, SwitchoverAction, SystemAccountSpec)

CmdExecutorConfig specifies how to perform creation and deletion statements.

FieldDescription
CommandExecutorEnvItem
CommandExecutorEnvItem

(Members of CommandExecutorEnvItem are embedded into this type.)

CommandExecutorItem
CommandExecutorItem

(Members of CommandExecutorItem are embedded into this type.)

CommandExecutorEnvItem

(Appears on:CmdExecutorConfig, SwitchoverShortSpec, SystemAccountShortSpec)

FieldDescription
image
string

image for Connector when executing the command.

env
[]Kubernetes core/v1.EnvVar
(Optional)

envs is a list of environment variables.

CommandExecutorItem

(Appears on:CmdExecutorConfig)

FieldDescription
command
[]string

command to perform statements.

args
[]string
(Optional)

args is used to perform statements.

ComponentClass

(Appears on:ComponentClassDefinitionStatus, ComponentClassSeries)

FieldDescription
name
string
(Optional)

name is the class name

args
[]string
(Optional)

args are variable’s value

cpu
Kubernetes resource.Quantity
(Optional)

the CPU of the class

memory
Kubernetes resource.Quantity
(Optional)

the memory of the class

ComponentClassDefinitionSpec

(Appears on:ComponentClassDefinition)

ComponentClassDefinitionSpec defines the desired state of ComponentClassDefinition

FieldDescription
groups
[]ComponentClassGroup
(Optional)

group defines a list of class series that conform to the same constraint.

ComponentClassDefinitionStatus

(Appears on:ComponentClassDefinition)

ComponentClassDefinitionStatus defines the observed state of ComponentClassDefinition

FieldDescription
observedGeneration
int64
(Optional)

observedGeneration is the most recent generation observed for this ComponentClassDefinition. It corresponds to the ComponentClassDefinition’s generation, which is updated on mutation by the API Server.

classes
[]ComponentClass

classes is the list of classes that have been observed for this ComponentClassDefinition

ComponentClassGroup

(Appears on:ComponentClassDefinitionSpec)

FieldDescription
template
string
(Optional)

template is a class definition template that uses the Go template syntax and allows for variable declaration. When defining a class in Series, specifying the variable’s value is sufficient, as the complete class definition will be generated through rendering the template.

For example:

template: | cpu: "{{ or .cpu 1 }}" memory: "{{ or .memory 4 }}Gi"
vars
[]string
(Optional)

vars defines the variables declared in the template and will be used to generating the complete class definition by render the template.

series
[]ComponentClassSeries
(Optional)

series is a series of class definitions.

ComponentClassSeries

(Appears on:ComponentClassGroup)

FieldDescription
namingTemplate
string
(Optional)

namingTemplate is a template that uses the Go template syntax and allows for referencing variables defined in ComponentClassGroup.Template. This enables dynamic generation of class names. For example: name: “general-{{ .cpu }}c{{ .memory }}g”

classes
[]ComponentClass
(Optional)

classes are definitions of classes that come in two forms. In the first form, only ComponentClass.Args need to be defined, and the complete class definition is generated by rendering the ComponentClassGroup.Template and Name. In the second form, the Name, CPU and Memory must be defined.

ComponentConfigSpec

(Appears on:ClusterComponentDefinition, ClusterComponentVersion, ComponentDefinitionSpec, ComponentSpec, ConfigurationItemDetail)

FieldDescription
ComponentTemplateSpec
ComponentTemplateSpec

(Members of ComponentTemplateSpec are embedded into this type.)

keys
[]string
(Optional)

Specify a list of keys. If empty, ConfigConstraint takes effect for all keys in configmap.

legacyRenderedConfigSpec
LegacyRenderedTemplateSpec
(Optional)

lazyRenderedConfigSpec is optional: specify the secondary rendered config spec.

constraintRef
string
(Optional)

Specify the name of the referenced the configuration constraints object.

asEnvFrom
[]string
(Optional)

asEnvFrom is optional: the list of containers will be injected into EnvFrom.

ComponentDefRef

(Appears on:ClusterComponentDefinition)

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

FieldDescription
componentDefName
string

componentDefName is the name of the componentDef to select.

failurePolicy
FailurePolicyType
(Optional)

failurePolicy is the failure policy of the component. If failed to find the component, the failure policy will be used.

componentRefEnv
[]ComponentRefEnv
(Optional)

componentRefEnv specifies a list of values to be injected as env variables to each component.

ComponentDefinitionRef

(Appears on:OpsDefinitionSpec)

FieldDescription
name
string

refer to componentDefinition name.

accountName
string
(Optional)

the account name of the component. will inject the account username and password to KB_ACCOUNT_USERNAME and KB_ACCOUNT_PASSWORD in env of the job.

serviceName
string
(Optional)

reference the services[*].name. will map the service name and ports to KB_COMP_SVC_NAME and KB_COMP_SVC_PORT_$(portName) in env of the job. portName will replace the characters ‘-’ to ‘_’ and convert to uppercase.

varsRef
VarsRef
(Optional)

varsRef defines the envs that need to be referenced from the target component pod, and will inject to job’s containers. if it is set, will ignore the global “varsRef”.

ComponentDefinitionSpec

(Appears on:ComponentDefinition)

ComponentDefinitionSpec provides a workload component specification with attributes that strongly work with stateful workloads and day-2 operation behaviors.

FieldDescription
provider
string
(Optional)

Provider is the name of the component provider.

description
string
(Optional)

Description is a brief description of the component.

serviceKind
string
(Optional)

ServiceKind defines what kind of well-known service that the component provides (e.g., MySQL, Redis, ETCD, case insensitive). Cannot be updated.

serviceVersion
string
(Optional)

ServiceVersion defines the version of the well-known service that the component provides. Cannot be updated.

runtime
Kubernetes core/v1.PodSpec

Runtime defines primarily runtime information for the component, including:

  • Init containers
  • Containers
    • Image
    • Commands
    • Args
    • Envs
    • Mounts
    • Ports
    • Security context
    • Probes
    • Lifecycle
  • Volumes

CPU and memory resource limits, as well as scheduling settings (affinity, toleration, priority), should not be configured within this structure. Cannot be updated.

vars
[]EnvVar
(Optional)

Vars represents user-defined variables.

These variables can be utilized as environment variables for Pods and Actions, or to render the templates of config and script. When used as environment variables, these variables are placed in front of the environment variables declared in the Pod. Cannot be updated.

volumes
[]ComponentVolume
(Optional)

Volumes defines the persistent volumes needed by the component. The users are responsible for providing these volumes when creating a component instance. Cannot be updated.

services
[]ComponentService
(Optional)

Services defines endpoints that can be used to access the component service to manage the component.

In addition, a reserved headless service will be created by default, with the name pattern {clusterName}-{componentName}-headless. Cannot be updated.

configs
[]ComponentConfigSpec
(Optional)

The configs field provided by provider, and finally this configTemplateRefs will be rendered into the user’s own configuration file according to the user’s cluster. Cannot be updated.

logConfigs
[]LogConfig
(Optional)

LogConfigs is detail log file config which provided by provider. Cannot be updated.

monitor
MonitorConfig
(Optional)

Monitor is monitoring config which provided by provider. Cannot be updated.

scripts
[]ComponentTemplateSpec
(Optional)

The scripts field provided by provider, and finally this configTemplateRefs will be rendered into the user’s own configuration file according to the user’s cluster. Cannot be updated.

policyRules
[]Kubernetes rbac/v1.PolicyRule
(Optional)

PolicyRules defines the namespaced policy rules required by the component. If any rule application fails (e.g., due to lack of permissions), the provisioning of the component instance will also fail. Cannot be updated.

labels
map[string]string
(Optional)

Labels defines static labels that will be patched to all k8s resources created for the component. If a label key conflicts with any other system labels or user-specified labels, it will be silently ignored. Cannot be updated.

replicasLimit
ReplicasLimit
(Optional)

ReplicasLimit defines the limit of valid replicas supported. Cannot be updated.

systemAccounts
[]SystemAccount
(Optional)

SystemAccounts defines the pre-defined system accounts required to manage the component. Cannot be updated.

updateStrategy
UpdateStrategy
(Optional)

UpdateStrategy defines the strategy for updating the component instance. Cannot be updated.

roles
[]ReplicaRole
(Optional)

Roles defines all the roles that the component can assume. Cannot be updated.

roleArbitrator
RoleArbitrator
(Optional)

RoleArbitrator defines the strategy for electing the component’s active role. Cannot be updated.

lifecycleActions
ComponentLifecycleActions
(Optional)

LifecycleActions defines the operational actions that needed to interoperate with the component service and processes for lifecycle management. Cannot be updated.

serviceRefDeclarations
[]ServiceRefDeclaration
(Optional)

ServiceRefDeclarations is used to declare the service reference of the current component. Cannot be updated.

ComponentDefinitionStatus

(Appears on:ComponentDefinition)

ComponentDefinitionStatus defines the observed state of ComponentDefinition.

FieldDescription
observedGeneration
int64
(Optional)

ObservedGeneration is the most recent generation observed for this ComponentDefinition.

phase
Phase
(Optional)

Phase valid values are `,Available,Unavailable`. Available is ComponentDefinition become available, and can be used for co-related objects.

message
string
(Optional)

Extra message for current phase.

ComponentLifecycleActions

(Appears on:ComponentDefinitionSpec)

ComponentLifecycleActions defines a set of operational actions for interacting with component services and processes.

FieldDescription
postProvision
LifecycleActionHandler
(Optional)

PostProvision defines the actions to be executed and the corresponding policy when a component is created. You can define the preCondition for executing PostProvision using Action.PreCondition. The default PostProvision action preCondition is ComponentReady. The PostProvision Action will be executed only once. Dedicated env vars for the action:

  • KB_CLUSTER_COMPONENT_LIST: The list of all components in the cluster, joined by ‘,’ (e.g., “comp1,comp2”).
  • KB_CLUSTER_COMPONENT_POD_NAME_LIST: The list of all pods name in this component, joined by ‘,’ (e.g., “pod1,pod2”).
  • KB_CLUSTER_COMPONENT_POD_IP_LIST: The list of pod IPs where each pod resides in this component, corresponding one-to-one with each pod in the KB_CLUSTER_COMPONENT_POD_NAME_LIST. joined by ‘,’ (e.g., “podIp1,podIp2”).
  • KB_CLUSTER_COMPONENT_POD_HOST_NAME_LIST: The list of hostName where each pod resides in this component, corresponding one-to-one with each pod in the KB_CLUSTER_COMPONENT_POD_NAME_LIST. joined by ‘,’ (e.g., “hostName1,hostName2”).
  • KB_CLUSTER_COMPONENT_POD_HOST_IP_LIST: The list of host IPs where each pod resides in this component, corresponding one-to-one with each pod in the KB_CLUSTER_COMPONENT_POD_NAME_LIST. joined by ‘,’ (e.g., “hostIp1,hostIp2”).

Cannot be updated.

preTerminate
LifecycleActionHandler
(Optional)

PreTerminate defines the actions to be executed when a component is terminated due to an API request. The PreTerminate Action will be executed only once. Upon receiving a scale-down command for the Component, it is executed immediately. Only after the preTerminate action is successfully executed, the destruction of the Component and its underlying resources proceeds. Cannot be updated.

roleProbe
RoleProbe
(Optional)

RoleProbe defines how to probe the role of replicas. Cannot be updated.

switchover
ComponentSwitchover
(Optional)

Switchover defines how to proactively switch the current leader to a new replica to minimize the impact on availability. This action is typically invoked when the leader is about to become unavailable due to events, such as:

  • switchover
  • stop
  • restart
  • scale-in

Dedicated env vars for the action:

  • KB_SWITCHOVER_CANDIDATE_NAME: The name of the new candidate replica’s Pod. It may be empty.
  • KB_SWITCHOVER_CANDIDATE_FQDN: The FQDN of the new candidate replica. It may be empty.
  • KB_LEADER_POD_IP: The IP address of the original leader’s Pod before switchover.
  • KB_LEADER_POD_NAME: The name of the original leader’s Pod before switchover.
  • KB_LEADER_POD_FQDN: The FQDN of the original leader’s Pod before switchover.

The env vars with following prefix are deprecated and will be removed in the future:

  • KB_REPLICATION_PRIMARYPOD: The prefix of the environment variables of the original primary’s Pod before switchover.
  • KB_CONSENSUS_LEADERPOD: The prefix of the environment variables of the original leader’s Pod before switchover.

Cannot be updated.

memberJoin
LifecycleActionHandler
(Optional)

MemberJoin defines how to add a new replica to the replication group. This action is typically invoked when a new replica needs to be added, such as during scale-out. It may involve updating configuration, notifying other members, and ensuring data consistency. Cannot be updated.

memberLeave
LifecycleActionHandler
(Optional)

MemberLeave defines how to remove a replica from the replication group. This action is typically invoked when a replica needs to be removed, such as during scale-in. It may involve configuration updates and notifying other members about the departure, but it is advisable to avoid performing data migration within this action. Cannot be updated.

readonly
LifecycleActionHandler
(Optional)

Readonly defines how to set a replica service as read-only. This action is used to protect a replica in case of volume space exhaustion or excessive traffic. Cannot be updated.

readwrite
LifecycleActionHandler
(Optional)

Readwrite defines how to set a replica service as read-write. Cannot be updated.

dataPopulate
LifecycleActionHandler
(Optional)

DataPopulate defines how to populate the data to create new replicas. This action is typically used when a new replica needs to be constructed, such as:

  • scale-out
  • rebuild
  • clone

It should write the valid data to stdout without including any extraneous information. Cannot be updated.

dataAssemble
LifecycleActionHandler
(Optional)

DataAssemble defines how to assemble data synchronized from external before starting the service for a new replica. This action is typically used when creating a new replica, such as:

  • scale-out
  • rebuild
  • clone

The data will be streamed in via stdin. If any error occurs during the assembly process, the action must be able to guarantee idempotence to allow for retries from the beginning. Cannot be updated.

reconfigure
LifecycleActionHandler
(Optional)

Reconfigure defines how to notify the replica service that there is a configuration update. Cannot be updated.

accountProvision
LifecycleActionHandler
(Optional)

AccountProvision defines how to provision accounts. Cannot be updated.

ComponentMessageMap (map[string]string alias)

(Appears on:ClusterComponentStatus, ComponentStatus)

ComponentNameSet (map[string]struct alias)

ComponentOps

(Appears on:Expose, HorizontalScaling, OpsRequestSpec, Reconfigure, ScriptSpec, Switchover, VerticalScaling, VolumeExpansion)

ComponentOps defines the common variables of component scope operations.

FieldDescription
componentName
string

componentName cluster component name.

ComponentRefEnv

(Appears on:ComponentDefRef)

ComponentRefEnv specifies name and value of an env.

FieldDescription
name
string

name is the name of the env to be injected, and it must be a C identifier.

value
string
(Optional)

value is the value of the env to be injected.

valueFrom
ComponentValueFrom
(Optional)

valueFrom specifies the source of the env to be injected.

ComponentResourceConstraintSelector

(Appears on:ClusterResourceConstraintSelector, ComponentResourceConstraintSpec)

FieldDescription
componentDefRef
string

In versions prior to KB 0.8.0, ComponentDefRef is the name of the component definition in the ClusterDefinition. In KB 0.8.0 and later versions, ComponentDefRef is the name of ComponentDefinition.

rules
[]string

rules are the constraint rules that will be applied to the component.

ComponentResourceConstraintSpec

(Appears on:ComponentResourceConstraint)

ComponentResourceConstraintSpec defines the desired state of ComponentResourceConstraint

FieldDescription
rules
[]ResourceConstraintRule

Component resource constraint rules.

selector
[]ClusterResourceConstraintSelector
(Optional)

selector is used to bind the resource constraint to cluster definitions based on ClusterDefinition API.

componentSelector
[]ComponentResourceConstraintSelector
(Optional)

componentSelector is used to bind the resource constraint to components based on ComponentDefinition API.

ComponentResourceKey (string alias)

ComponentResourceKey defines the resource key of component, such as pod/pvc.

ValueDescription

"pods"

ComponentService

(Appears on:ComponentDefinitionSpec)

FieldDescription
Service
Service

(Members of Service are embedded into this type.)

generatePodOrdinalService
bool
(Optional)

GeneratePodOrdinalService indicates whether to create a corresponding Service for each Pod of the selected Component. If sets to true, a set of Service will be automatically generated for each Pod. And Service.RoleSelector will be ignored. They can be referred to by adding the PodOrdinal to the defined ServiceName with named pattern $(Service.ServiceName)-$(PodOrdinal). And the Service.Name will also be generated with named pattern $(Service.Name)-$(PodOrdinal). The PodOrdinal is zero-based, and the number of generated Services is equal to the number of replicas of the Component. For example, a Service might be defined as follows:

name: my-service serviceName: my-service generatePodOrdinalService: true spec: type: NodePort ports: - name: http port: 80 targetPort: 8080

Assuming that the Component has 3 replicas, then three services would be generated: my-service-0, my-service-1, and my-service-2, each pointing to its respective Pod.

ComponentSpec

(Appears on:Component)

ComponentSpec defines the desired state of Component

FieldDescription
compDef
string

compDef is the name of the referenced componentDefinition.

classDefRef
ClassDefRef
(Optional)

classDefRef references the class defined in ComponentClassDefinition.

serviceRefs
[]ServiceRef
(Optional)

serviceRefs define service references for the current component. Based on the referenced services, they can be categorized into two types:

  • Service provided by external sources: These services are provided by external sources and are not managed by KubeBlocks. They can be Kubernetes-based or non-Kubernetes services. For external services, you need to provide an additional ServiceDescriptor object to establish the service binding.
  • Service provided by other KubeBlocks clusters: These services are provided by other KubeBlocks clusters. You can bind to these services by specifying the name of the hosting cluster.

Each type of service reference requires specific configurations and bindings to establish the connection and interaction with the respective services. It should be noted that the ServiceRef has cluster-level semantic consistency, meaning that within the same Cluster, service references with the same ServiceRef.Name are considered to be the same service. It is only allowed to bind to the same Cluster or ServiceDescriptor.

resources
Kubernetes core/v1.ResourceRequirements
(Optional)

Resources requests and limits of workload.

volumeClaimTemplates
[]ClusterComponentVolumeClaimTemplate
(Optional)

VolumeClaimTemplates information for statefulset.spec.volumeClaimTemplates.

replicas
int32

Component replicas. The default value is used in ClusterDefinition spec if not specified.

configs
[]ComponentConfigSpec
(Optional)
monitor
bool
(Optional)

monitor is a switch to enable monitoring and is set as false by default. KubeBlocks provides an extension mechanism to support component level monitoring, which will scrape metrics auto or manually from servers in component and export metrics to Time Series Database.

enabledLogs
[]string
(Optional)

enabledLogs indicates which log file takes effect in the database cluster. element is the log type which is defined in ComponentDefinition logConfig.name, and will set relative variables about this log type in database kernel.

updateStrategy
UpdateStrategy
(Optional)
serviceAccountName
string
(Optional)

serviceAccountName is the name of the ServiceAccount that running component depends on.

affinity
Affinity
(Optional)
tolerations
[]Kubernetes core/v1.Toleration
(Optional)
tlsConfig
TLSConfig
(Optional)
rsmTransformPolicy
RsmTransformPolicy
(Optional)

RsmTransformPolicy defines the policy generate sts using rsm. ToSts: rsm transform to statefulSet ToPod: rsm transform to pods

nodes
[]k8s.io/apimachinery/pkg/types.NodeName
(Optional)

Nodes defines the list of nodes that pods can schedule If the RsmTransformPolicy is specified as OneToMul,the list of nodes will be used. If the list of nodes is empty, no specific node will be assigned. However, if the list of node is filled, all pods will be evenly scheduled across the nodes in the list.

instances
[]string
(Optional)

Instances defines the list of instance to be deleted priorly

ComponentStatus

(Appears on:Component)

ComponentStatus defines the observed state of Component

FieldDescription
observedGeneration
int64
(Optional)

observedGeneration is the most recent generation observed for this Component. It corresponds to the Cluster’s generation, which is updated on mutation by the API Server.

conditions
[]Kubernetes meta/v1.Condition
(Optional)

Describe current state of component API Resource, like warning.

phase
ClusterComponentPhase

phase describes the phase of the component and the detail information of the phases are as following:

  • Creating: Creating is a special Updating with previous phase empty(means “”) or Creating.
  • Running: component replicas > 0 and all pod specs are latest with a Running state.
  • Updating: component replicas > 0 and has no failed pods. the component is being updated.
  • Abnormal: component replicas > 0 but having some failed pods. the component basically works but in a fragile state.
  • Failed: component replicas > 0 but having some failed pods. the component doesn’t work anymore.
  • Stopping: component replicas = 0 and has terminating pods.
  • Stopped: component replicas = 0 and all pods have been deleted.
  • Deleting: the component is being deleted.
message
ComponentMessageMap
(Optional)

message records the component details message in current phase. Keys are podName or deployName or statefulSetName. The format is ObjectKind/Name.

ComponentSwitchover

(Appears on:ComponentLifecycleActions)

FieldDescription
withCandidate
Action
(Optional)

withCandidate corresponds to the switchover of the specified candidate primary or leader instance. Currently, only Action.Exec is supported, Action.HTTP is not supported.

withoutCandidate
Action
(Optional)

withoutCandidate corresponds to a switchover that does not specify a candidate primary or leader instance. Currently, only Action.Exec is supported, Action.HTTP is not supported.

scriptSpecSelectors
[]ScriptSpecSelector
(Optional)

scriptSpecSelectors defines the selector of the scriptSpecs that need to be referenced. Once ScriptSpecSelectors is defined, the scripts defined in scripts can be referenced in the Action.

ComponentTemplateSpec

(Appears on:ClusterComponentDefinition, ComponentConfigSpec, ComponentDefinitionSpec)

FieldDescription
name
string

Specify the name of configuration template.

templateRef
string

Specify the name of the referenced the configuration template ConfigMap object.

namespace
string
(Optional)

Specify the namespace of the referenced the configuration template ConfigMap object. An empty namespace is equivalent to the “default” namespace.

volumeName
string

volumeName is the volume name of PodTemplate, which 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)

defaultMode is optional: mode bits used to set permissions on created files by default.

Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511. YAML accepts both octal and decimal values, JSON requires decimal values for mode bits. Defaults to 0644.

Directories within the path are not affected by this setting. This might be in conflict with other options that affect the file mode, like fsGroup, and the result can be other mode bits set.

ComponentValueFrom

(Appears on:ComponentRefEnv)

FieldDescription
type
ComponentValueFromType

type is the type of the source to select. There are three types: FieldRef, ServiceRef, HeadlessServiceRef.

fieldPath
string
(Optional)

fieldRef is the jsonpath of the source to select when type is FieldRef. there are two objects registered in the jsonpath: componentDef and components:

  • componentDef is the component definition object specified in componentRef.componentDefName.
  • components is the component list objects referring to the component definition object.
format
string
(Optional)

format is the format of each headless service address. there are three builtin variables can be used as placeholder: $POD_ORDINAL, $POD_FQDN, $POD_NAME

  • $POD_ORDINAL is the ordinal of the pod.
  • $POD_FQDN is the fully qualified domain name of the pod.
  • $POD_NAME is the name of the pod
joinWith
string
(Optional)

joinWith is the string to join the values of headless service addresses.

ComponentValueFromType (string alias)

(Appears on:ComponentValueFrom)

ComponentValueFromType specifies the type of component value from.

ValueDescription

"FieldRef"

"HeadlessServiceRef"

"ServiceRef"

ComponentVolume

(Appears on:ComponentDefinitionSpec)

FieldDescription
name
string

The Name of the volume. Must be a DNS_LABEL and unique within the pod. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#namesCannot be updated.

needSnapshot
bool
(Optional)

NeedSnapshot indicates whether the volume need to snapshot when making a backup for the component. Cannot be updated.

highWatermark
int
(Optional)

HighWatermark defines the high watermark threshold for the volume space usage.

If there is any specified volumes who’s space usage is over the threshold, the pre-defined “LOCK” action will be triggered to degrade the service to protect volume from space exhaustion, such as to set the instance as read-only. And after that, if all volumes’ space usage drops under the threshold later, the pre-defined “UNLOCK” action will be performed to recover the service normally. Cannot be updated.

ConfigConstraintPhase (string alias)

(Appears on:ConfigConstraintStatus)

ConfigConstraintPhase defines the ConfigConstraint CR .status.phase

ValueDescription

"Available"

"Deleting"

"Unavailable"

ConfigConstraintSpec

(Appears on:ConfigConstraint)

ConfigConstraintSpec defines the desired state of ConfigConstraint

FieldDescription
reloadOptions
ReloadOptions
(Optional)

reloadOptions indicates whether the process supports reload.

if set, the controller will determine the behavior of the engine instance based on the configuration templates, restart or reload depending on whether any parameters in the StaticParameters have been modified.

toolsImageSpec
ToolsImageSpec
(Optional)

toolConfig used to config init container.

downwardAPIOptions
[]DownwardAPIOption
(Optional)

downwardAPIOptions is used to watch pod fields.

scriptConfigs
[]ScriptConfig
(Optional)

scriptConfigs, list of ScriptConfig, witch these scripts can be used by volume trigger,downward trigger, or tool image

cfgSchemaTopLevelName
string
(Optional)

cfgSchemaTopLevelName is cue type name, which generates openapi schema.

configurationSchema
CustomParametersValidation
(Optional)

configurationSchema imposes restrictions on database parameter’s rule.

staticParameters
[]string
(Optional)

staticParameters, list of StaticParameter, modifications of them trigger a process restart.

dynamicParameters
[]string
(Optional)

dynamicParameters, list of DynamicParameter, modifications of them trigger a config dynamic reload without process restart.

immutableParameters
[]string
(Optional)

immutableParameters describes parameters that prohibit user from modification.

selector
Kubernetes meta/v1.LabelSelector

selector is used to match the label on the pod, for example, a pod of the primary is match on the patroni cluster.

formatterConfig
FormatterConfig

formatterConfig describes the format of the configuration file, the controller will:

  1. parses configuration file
  2. analyzes the modified parameters
  3. applies corresponding policies.

ConfigConstraintStatus

(Appears on:ConfigConstraint)

ConfigConstraintStatus defines the observed state of ConfigConstraint.

FieldDescription
phase
ConfigConstraintPhase
(Optional)

phase is status of configuration template, when set to CCAvailablePhase, it can be referenced by ClusterDefinition or ClusterVersion.

message
string
(Optional)

message field describes the reasons of abnormal status.

observedGeneration
int64
(Optional)

observedGeneration is the latest generation observed for this ClusterDefinition. It refers to the ConfigConstraint’s generation, which is updated by the API Server.

ConfigMapRef

(Appears on:UserResourceRefs)

FieldDescription
ResourceMeta
ResourceMeta

(Members of ResourceMeta are embedded into this type.)

configMap
Kubernetes core/v1.ConfigMapVolumeSource

configMap defines the configmap volume source.

ConfigParams

(Appears on:ConfigurationItemDetail)

FieldDescription
content
string
(Optional)

fileContent indicates the configuration file content.

parameters
map[string]*string
(Optional)

updated parameters for a single configuration file.

ConfigTemplateExtension

(Appears on:ConfigurationItemDetail, LegacyRenderedTemplateSpec)

FieldDescription
templateRef
string

Specify the name of the referenced the configuration template ConfigMap object.

namespace
string
(Optional)

Specify the namespace of the referenced the configuration template ConfigMap object. An empty namespace is equivalent to the “default” namespace.

policy
MergedPolicy
(Optional)

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

ConfigurationItem

(Appears on:Reconfigure)

FieldDescription
name
string

name is a config template name.

policy
UpgradePolicy
(Optional)

policy defines the upgrade policy.

keys
[]ParameterConfig

keys is used to set the parameters to be updated.

ConfigurationItemDetail

(Appears on:ConfigurationSpec)

FieldDescription
name
string

Specify the name of configuration template.

version
string
(Optional)

Deprecated: Please use payload instead. version is the version of configuration template.

payload
Payload
(Optional)

Payload holds the configuration-related rerender.

configSpec
ComponentConfigSpec
(Optional)

configSpec is used to set the configuration template.

importTemplateRef
ConfigTemplateExtension
(Optional)

Specify the configuration template.

configFileParams
map[string]github.com/apecloud/kubeblocks/apis/apps/v1alpha1.ConfigParams
(Optional)

configFileParams is used to set the parameters to be updated.

ConfigurationItemDetailStatus

(Appears on:ConfigurationStatus)

FieldDescription
name
string

name is a config template name.

phase
ConfigurationPhase
(Optional)

phase is status of configurationItem.

lastDoneRevision
string
(Optional)

lastDoneRevision is the last done revision of configurationItem.

updateRevision
string
(Optional)

updateRevision is the update revision of configurationItem.

message
string
(Optional)

message field describes the reasons of abnormal status.

reconcileDetail
ReconcileDetail
(Optional)

reconcileDetail describes the details of the configuration change execution.

ConfigurationItemStatus

(Appears on:ReconfiguringStatus)

FieldDescription
name
string

name is a config template name.

updatePolicy
UpgradePolicy
(Optional)

updatePolicy describes the policy of reconfiguring.

status
string
(Optional)

status describes the current state of the reconfiguring state machine.

message
string
(Optional)

message describes the details about this operation.

succeedCount
int32
(Optional)

succeedCount describes the number of successful reconfiguring.

expectedCount
int32
(Optional)

expectedCount describes the number of expected reconfiguring.

lastStatus
string
(Optional)

lastStatus describes the last status for the reconfiguring controller.

lastAppliedConfiguration
map[string]string
(Optional)

LastAppliedConfiguration describes the last configuration.

updatedParameters
UpdatedParameters
(Optional)

updatedParameters describes the updated parameters.

ConfigurationPhase (string alias)

(Appears on:ConfigurationItemDetailStatus)

ConfigurationPhase defines the Configuration FSM phase

ValueDescription

"Creating"

"Deleting"

"FailedAndPause"

"FailedAndRetry"

"Finished"

"Init"

"MergeFailed"

"Merged"

"Pending"

"Running"

"Upgrading"

ConfigurationSpec

(Appears on:Configuration)

ConfigurationSpec defines the desired state of Configuration

FieldDescription
clusterRef
string

clusterRef references Cluster name.

componentName
string

componentName is cluster component name.

configItemDetails
[]ConfigurationItemDetail
(Optional)

customConfigurationItems describes user-defined config template.

ConfigurationStatus

(Appears on:Configuration)

ConfigurationStatus defines the observed state of Configuration

FieldDescription
message
string
(Optional)

message field describes the reasons of abnormal status.

observedGeneration
int64
(Optional)

observedGeneration is the latest generation observed for this ClusterDefinition. It refers to the ConfigConstraint’s generation, which is updated by the API Server.

conditions
[]Kubernetes meta/v1.Condition
(Optional)

conditions describes opsRequest detail status.

configurationStatus
[]ConfigurationItemDetailStatus

configurationStatus describes the status of the component reconfiguring.

ConnectionCredentialAuth

(Appears on:ServiceDescriptorSpec)

FieldDescription
username
CredentialVar
(Optional)

service connection based-on username and password credential.

password
CredentialVar
(Optional)

service connection based-on username and password credential.

ConnectionCredentialKey

(Appears on:TargetInstance)

FieldDescription
passwordKey
string
(Optional)

the key of password in the ConnectionCredential secret. if not set, the default key is “password”.

usernameKey
string
(Optional)

the key of username in the ConnectionCredential secret. if not set, the default key is “username”.

hostKey
string

hostKey specifies the map key of the host in the connection credential secret.

portKey
string

portKey specifies the map key of the port in the connection credential secret.

ConsensusMember

(Appears on:ConsensusSetSpec)

FieldDescription
name
string

name, role name.

accessMode
AccessMode

accessMode, what service this member capable.

replicas
int32
(Optional)

replicas, number of Pods of this role.

  • default 1 for Leader
  • default 0 for Learner
  • default Cluster.spec.componentSpec[*].Replicas - Leader.Replicas - Learner.Replicas for Followers

ConsensusMemberStatus

(Appears on:ConsensusSetStatus)

FieldDescription
name
string

Defines the role name.

accessMode
AccessMode

accessMode defines what service this pod provides.

pod
string

Pod name.

ConsensusSetSpec

(Appears on:ClusterComponentDefinition)

FieldDescription
StatefulSetSpec
StatefulSetSpec

(Members of StatefulSetSpec are embedded into this type.)

leader
ConsensusMember

leader, one single leader.

followers
[]ConsensusMember
(Optional)

followers, has voting right but not Leader.

learner
ConsensusMember
(Optional)

learner, no voting right.

ConsensusSetStatus

(Appears on:ClusterComponentStatus)

FieldDescription
leader
ConsensusMemberStatus

Leader status.

followers
[]ConsensusMemberStatus
(Optional)

Followers status.

learner
ConsensusMemberStatus
(Optional)

Learner status.

CredentialVar

(Appears on:ConnectionCredentialAuth, ServiceDescriptorSpec)

FieldDescription
value
string
(Optional)

Variable references $(VAR_NAME) are expanded using the 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 be unchanged. Double $$ are reduced to a single $, which allows for escaping the $(VAR_NAME) syntax: i.e. “$$(VAR_NAME)” will produce the string literal “$(VAR_NAME)”. Escaped references will never be expanded, regardless of whether the variable exists or not. Defaults to “”.

valueFrom
Kubernetes core/v1.EnvVarSource
(Optional)

Source for the environment variable’s value. Cannot be used if value is not empty.

CredentialVarSelector

(Appears on:VarSource)

CredentialVarSelector selects a var from a Credential (SystemAccount).

FieldDescription
ClusterObjectReference
ClusterObjectReference

(Members of ClusterObjectReference are embedded into this type.)

The Credential (SystemAccount) to select from.

CredentialVars
CredentialVars

(Members of CredentialVars are embedded into this type.)

CredentialVars

(Appears on:CredentialVarSelector, ServiceRefVars)

CredentialVars defines the vars 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.

FieldDescription
username
VarOption
(Optional)
password
VarOption
(Optional)

CustomLabelSpec

(Appears on:ClusterComponentDefinition)

FieldDescription
key
string

key name of label

value
string

value of label

resources
[]GVKResource

resources defines the resources to be labeled.

CustomOpsSpec

(Appears on:OpsRequestSpec)

FieldDescription
componentName
string

cluster component name.

opsDefinitionRef
string

reference a opsDefinition

params
[]string
(Optional)

the input for this operation declared in the opsDefinition.spec.parametersSchema. will create corresponding jobs for each array element. if the param type is array, the format must be “v1,v2,v3”.

CustomParametersValidation

(Appears on:ConfigConstraintSpec)

FieldDescription
schema
Kubernetes api extensions v1.JSONSchemaProps

schema provides a way for providers to validate the changed parameters through json.

cue
string
(Optional)

cue that to let provider verify user configuration through cue language.

DownwardAPIOption

(Appears on:ConfigConstraintSpec)

FieldDescription
name
string

Specify the name of the field.

mountPoint
string

mountPoint is the mount point of the scripts file.

items
[]Kubernetes core/v1.DownwardAPIVolumeFile

Items is a list of downward API volume file

command
[]string
(Optional)

command used to execute for downwrad api.

EnvMappingVar

(Appears on:BackupMethod)

FieldDescription
key
string

env key which needs to mapping.

valueFrom
ValueFrom

valueFrom defines source of the env value.

EnvVar

(Appears on:ComponentDefinitionSpec)

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

FieldDescription
name
string

Name of the variable. Must be a C_IDENTIFIER.

value
string
(Optional)

Variable references $(VAR_NAME) are expanded using the previously defined variables in the current context.

If a variable cannot be resolved, the reference in the input string will be unchanged. Double $$ are reduced to a single $, which allows for escaping the $(VAR_NAME) syntax: i.e.

  • ”$$(VAR_NAME)” will produce the string literal “$(VAR_NAME)”.

Escaped references will never be expanded, regardless of whether the variable exists or not. Defaults to “”.

valueFrom
VarSource
(Optional)

Source for the variable’s value. Cannot be used if value is not empty.

EnvVarRef

(Appears on:OpsVarSource)

FieldDescription
containerName
string
(Optional)

container name which defines in componentDefinition or is injected by kubeBlocks controller. if not specified, will use the first container by default.

envName
string

env name, it will .

ExecAction

(Appears on:Action)

FieldDescription
command
[]string
(Optional)

Command is the command line to execute inside the container, the working directory for the command is root (‘/’) in the container’s filesystem. The command is simply exec’d, it is not run inside a shell, so traditional shell instructions (‘|’, etc) won’t work. To use a shell, you need to explicitly call out to that shell. Exit status of 0 is treated as live/healthy and non-zero is unhealthy.

args
[]string
(Optional)

args is used to perform statements.

ExporterConfig

(Appears on:MonitorConfig)

FieldDescription
scrapePort
Kubernetes api utils intstr.IntOrString

scrapePort is exporter port for Time Series Database to scrape metrics.

scrapePath
string
(Optional)

scrapePath is exporter url path for Time Series Database to scrape metrics.

Expose

(Appears on:OpsRequestSpec)

FieldDescription
ComponentOps
ComponentOps

(Members of ComponentOps are embedded into this type.)

switch
ExposeSwitch

switch defines the switch of expose operation. if switch is set to Enable, the service will be exposed. if switch is set to Disable, the service will be removed.

services
[]OpsService

Setting the list of services to be exposed or removed.

ExposeSwitch (string alias)

(Appears on:Expose)

ExposeSwitch defines the switch of expose operation.

ValueDescription

"Disable"

"Enable"

FailurePolicyType (string alias)

(Appears on:ComponentDefRef)

FailurePolicyType specifies the type of failure policy

ValueDescription

"Fail"

ReportError means that an error will be reported.

"Ignore"

Ignore means that an error will be ignored but logged.

FormatterConfig

(Appears on:ConfigConstraintSpec)

FieldDescription
FormatterOptions
FormatterOptions

(Members of FormatterOptions are embedded into this type.)

(Optional)

The FormatterOptions represents the special options of configuration file. This is optional for now. If not specified.

format
CfgFileFormat

The configuration file format. Valid values are ini, xml, yaml, json,hcl, dotenv, properties and toml.

FormatterOptions

(Appears on:FormatterConfig)

FormatterOptions represents the special options of configuration file. Only one of its members may be specified.

FieldDescription
iniConfig
IniConfig
(Optional)

iniConfig represents the ini options.

GVKResource

(Appears on:CustomLabelSpec)

FieldDescription
gvk
string

gvk is Group/Version/Kind, for example “v1/Pod”, “apps/v1/StatefulSet”, etc.

when the gvk resource filtered by the selector already exists, if there is no corresponding custom label, it will be added, and if label already exists, it will be updated.

selector
map[string]string
(Optional)

selector is a label query over a set of resources.

HScaleDataClonePolicyType (string alias)

(Appears on:HorizontalScalePolicy)

HScaleDataClonePolicyType defines data clone policy when horizontal scaling.

ValueDescription

"CloneVolume"

"Snapshot"

"None"

HTTPAction

(Appears on:Action)

HTTPAction describes an action based on HTTP requests.

FieldDescription
path
string
(Optional)

Path to access on the HTTP server.

port
Kubernetes api utils intstr.IntOrString

Name or number of the port to access on the container. Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME.

host
string
(Optional)

Host name to connect to, defaults to the pod IP. You probably want to set “Host” in httpHeaders instead.

scheme
Kubernetes core/v1.URIScheme
(Optional)

Scheme to use for connecting to the host. Defaults to HTTP.

method
string
(Optional)

Method represents the HTTP request method, which can be one of the standard HTTP methods like “GET,” “POST,” “PUT,” etc. Defaults to Get.

httpHeaders
[]Kubernetes core/v1.HTTPHeader
(Optional)

Custom headers to set in the request. HTTP allows repeated headers.

HorizontalScalePolicy

(Appears on:ClusterComponentDefinition)

FieldDescription
type
HScaleDataClonePolicyType
(Optional)

type controls what kind of data synchronization do when component scale out. Policy is in enum of {None, CloneVolume}. The default policy is None.

  • None: Default policy, create empty volume and no data clone.
  • CloneVolume: Do data clone to newly scaled pods. Prefer to use volume snapshot first, and will try backup tool if volume snapshot is not enabled, finally report error if both above cannot work.
  • Snapshot: Deprecated, alias for CloneVolume.
backupPolicyTemplateName
string
(Optional)

BackupPolicyTemplateName reference the backup policy template.

volumeMountsName
string
(Optional)

volumeMountsName defines which volumeMount of the container to do backup, only work if Type is not None if not specified, the 1st volumeMount will be chosen

HorizontalScaling

(Appears on:OpsRequestSpec)

HorizontalScaling defines the variables of horizontal scaling operation

FieldDescription
ComponentOps
ComponentOps

(Members of ComponentOps are embedded into this type.)

replicas
int32

replicas for the workloads.

nodes
[]k8s.io/apimachinery/pkg/types.NodeName
(Optional)

Nodes defines the list of nodes that pods can schedule when scale up If the RsmTransformPolicy is specified as ToPod and expected replicas is more than current replicas,the list of Nodes will be used. If the list of Nodes is empty, no specific node will be assigned. However, if the list of Nodes is filled, all pods will be evenly scheduled across the Nodes in the list when scale up.

instances
[]string
(Optional)

Instances defines the name of instance that rsm scale down priorly. If the RsmTransformPolicy is specified as ToPod and expected replicas is less than current replicas, the list of Instances will be used.

  • current replicas - expected replicas > len(Instances): Scale down from the list of Instances priorly, the others will select from NodeAssignment.
  • current replicas - expected replicas < len(Instances): Scale down from the list of Instances.
  • current replicas - expected replicas < len(Instances): Scale down from a part of Instances.

IniConfig

(Appears on:FormatterOptions)

FieldDescription
sectionName
string
(Optional)

sectionName describes ini section.

Issuer

(Appears on:ClusterComponentSpec, TLSConfig)

Issuer defines Tls certs issuer

FieldDescription
name
IssuerName

Name of issuer. Options supported:

  • KubeBlocks - Certificates signed by KubeBlocks Operator.
  • UserProvided - User provided own CA-signed certificates.
secretRef
TLSSecretRef
(Optional)

secretRef. TLS certs Secret reference required when from is UserProvided

IssuerName (string alias)

(Appears on:Issuer)

IssuerName defines Tls certs issuer name

ValueDescription

"KubeBlocks"

IssuerKubeBlocks Certificates signed by KubeBlocks Operator.

"UserProvided"

IssuerUserProvided User provided own CA-signed certificates.

KBAccountType (byte alias)

KBAccountType is used for bitwise operation.

ValueDescription

0

LastComponentConfiguration

(Appears on:LastConfiguration)

FieldDescription
replicas
int32
(Optional)

replicas are the last replicas of the component.

ResourceRequirements
Kubernetes core/v1.ResourceRequirements

(Members of ResourceRequirements are embedded into this type.)

(Optional)

the last resources of the component.

classDefRef
ClassDefRef
(Optional)

classDefRef reference class defined in ComponentClassDefinition.

volumeClaimTemplates
[]OpsRequestVolumeClaimTemplate
(Optional)

volumeClaimTemplates records the last volumeClaimTemplates of the component.

services
[]ClusterComponentService
(Optional)

services records the last services of the component.

targetResources
map[github.com/apecloud/kubeblocks/apis/apps/v1alpha1.ComponentResourceKey][]string
(Optional)

targetResources records the affecting target resources information for the component. resource key is in list of [pods].

LastConfiguration

(Appears on:OpsRequestStatus)

FieldDescription
clusterVersionRef
string
(Optional)

clusterVersionRef references ClusterVersion name.

components
map[string]github.com/apecloud/kubeblocks/apis/apps/v1alpha1.LastComponentConfiguration
(Optional)

components records last configuration of the component.

LegacyRenderedTemplateSpec

(Appears on:ComponentConfigSpec)

FieldDescription
ConfigTemplateExtension
ConfigTemplateExtension

(Members of ConfigTemplateExtension are embedded into this type.)

LetterCase (string alias)

(Appears on:PasswordConfig)

LetterCase defines cases to use in password generation.

ValueDescription

"LowerCases"

"MixedCases"

"UpperCases"

LifecycleActionHandler

(Appears on:ComponentLifecycleActions, RoleProbe)

FieldDescription
builtinHandler
BuiltinActionHandlerType
(Optional)

builtinHandler specifies the builtin action handler name to do the action. the BuiltinHandler within the same ComponentLifecycleActions should be consistent. Details can be queried through official documentation in the future. use CustomHandler to define your own actions if none of them satisfies the requirement.

customHandler
Action
(Optional)

customHandler defines the custom way to do action.

LogConfig

(Appears on:ClusterComponentDefinition, ComponentDefinitionSpec)

FieldDescription
name
string

name log type name, such as slow for MySQL slow log file.

filePathPattern
string

filePathPattern log file path pattern which indicate how to find this file corresponding to variable (log path) in database kernel. please don’t set this casually.

MemoryConstraint

(Appears on:ResourceConstraintRule)

FieldDescription
sizePerCPU
Kubernetes resource.Quantity
(Optional)

The size of memory per vcpu core. For example: 1Gi, 200Mi. If SizePerCPU is specified, MinPerCPU and MaxPerCPU are ignore.

maxPerCPU
Kubernetes resource.Quantity
(Optional)

The maximum size of memory per vcpu core, [MinPerCPU, MaxPerCPU] defines a range for valid memory size per vcpu core. It is useful on GCP as the ratio between the CPU and memory may be a range. If SizePerCPU is specified, MinPerCPU and MaxPerCPU are ignored. Reference: https://cloud.google.com/compute/docs/general-purpose-machines#custom_machine_types

minPerCPU
Kubernetes resource.Quantity
(Optional)

The minimum size of memory per vcpu core, [MinPerCPU, MaxPerCPU] defines a range for valid memory size per vcpu core. It is useful on GCP as the ratio between the CPU and memory may be a range. If SizePerCPU is specified, MinPerCPU and MaxPerCPU are ignored. Reference: https://cloud.google.com/compute/docs/general-purpose-machines#custom_machine_types

MergedPolicy (string alias)

(Appears on:ConfigTemplateExtension)

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

ValueDescription

"none"

"add"

"patch"

"replace"

MonitorConfig

(Appears on:ClusterComponentDefinition, ComponentDefinitionSpec)

FieldDescription
builtIn
bool
(Optional)

builtIn is a switch to enable KubeBlocks builtIn monitoring. If BuiltIn is set to true, monitor metrics will be scraped automatically. If BuiltIn is set to false, the provider should set ExporterConfig and Sidecar container own.

exporterConfig
ExporterConfig
(Optional)

exporterConfig provided by provider, which specify necessary information to Time Series Database. exporterConfig is valid when builtIn is false.

NamedVar

(Appears on:ServiceVars)

FieldDescription
name
string
(Optional)
option
VarOption
(Optional)

OpsDefinitionSpec

(Appears on:OpsDefinition)

OpsDefinitionSpec defines the desired state of OpsDefinition

FieldDescription
componentDefinitionRefs
[]ComponentDefinitionRef

componentDefinitionRefs indicates which types of componentDefinitions are supported by the operation, and can refer some vars of the componentDefinition. if it is set, the component that does not meet the conditions will be intercepted.

varsRef
VarsRef
(Optional)

varsRef defines the envs that need to be referenced from the target component pod, and will inject to job’s containers.

parametersSchema
ParametersSchema
(Optional)

parametersSchema describes the schema used for validation, pruning, and defaulting.

jobSpec
Kubernetes batch/v1.JobSpec

jobSpec describes the job spec for the operation.

preConditions
[]PreCondition
(Optional)

preCondition if it meets the requirements to run the job for the operation.

OpsDefinitionStatus

(Appears on:OpsDefinition)

OpsDefinitionStatus defines the observed state of OpsDefinition

FieldDescription
observedGeneration
int64
(Optional)

ObservedGeneration is the most recent generation observed for this OpsDefinition.

phase
Phase
(Optional)

Phase valid values are `,Available,Unavailable`. Available is OpsDefinition become available, and can be used for co-related objects.

message
string
(Optional)

Extra message for current phase.

OpsEnvVar

(Appears on:VarsRef)

FieldDescription
name
string

Name of the variable. Must be a C_IDENTIFIER.

valueFrom
OpsVarSource

Source for the variable’s value. Cannot be used if value is not empty.

OpsPhase (string alias)

(Appears on:OpsRequestStatus)

OpsPhase defines opsRequest phase.

ValueDescription

"Cancelled"

"Cancelling"

"Creating"

"Failed"

"Pending"

"Running"

"Succeed"

OpsRecorder

FieldDescription
name
string

name OpsRequest name

type
OpsType

opsRequest type

inQueue
bool

indicates whether the current opsRequest is in the queue

OpsRequestBehaviour

FieldDescription
FromClusterPhases
[]ClusterPhase
ToClusterPhase
ClusterPhase

OpsRequestComponentStatus

(Appears on:OpsRequestStatus)

FieldDescription
phase
ClusterComponentPhase
(Optional)

phase describes the component phase, reference Cluster.status.component.phase.

lastFailedTime
Kubernetes meta/v1.Time
(Optional)

lastFailedTime is the last time the component phase transitioned to Failed or Abnormal.

progressDetails
[]ProgressStatusDetail
(Optional)

progressDetails describes the progress details of the component for this operation.

workloadType
WorkloadType
(Optional)

workloadType references workload type of component in ClusterDefinition.

reason
string
(Optional)

reason describes the reason for the component phase.

message
string
(Optional)

message is a human-readable message indicating details about this operation.

OpsRequestSpec

(Appears on:OpsRequest)

OpsRequestSpec defines the desired state of OpsRequest

FieldDescription
clusterRef
string

clusterRef references cluster object.

cancel
bool
(Optional)

cancel defines the action to cancel the Pending/Creating/Running opsRequest, supported types: VerticalScaling/HorizontalScaling. once cancel is set to true, this opsRequest will be canceled and modifying this property again will not take effect.

type
OpsType

type defines the operation type.

ttlSecondsAfterSucceed
int32
(Optional)

ttlSecondsAfterSucceed OpsRequest will be deleted after TTLSecondsAfterSucceed second when OpsRequest.status.phase is Succeed.

upgrade
Upgrade
(Optional)

upgrade specifies the cluster version by specifying clusterVersionRef.

horizontalScaling
[]HorizontalScaling
(Optional)

horizontalScaling defines what component need to horizontal scale the specified replicas.

volumeExpansion
[]VolumeExpansion
(Optional)

volumeExpansion defines what component and volumeClaimTemplate need to expand the specified storage.

restart
[]ComponentOps
(Optional)

restart the specified components.

switchover
[]Switchover
(Optional)

switchover the specified components.

verticalScaling
[]VerticalScaling
(Optional)

verticalScaling defines what component need to vertical scale the specified compute resources.

reconfigure
Reconfigure
(Optional)

reconfigure defines the variables that need to input when updating configuration.

reconfigures
[]Reconfigure
(Optional)

reconfigure defines the variables that need to input when updating configuration.

expose
[]Expose
(Optional)

expose defines services the component needs to expose.

restoreFrom
RestoreFromSpec
(Optional)

cluster RestoreFrom backup or point in time

ttlSecondsBeforeAbort
int32
(Optional)

ttlSecondsBeforeAbort OpsRequest will wait at most TTLSecondsBeforeAbort seconds for start-conditions to be met. If not specified, the default value is 0, which means that the start-conditions must be met immediately.

scriptSpec
ScriptSpec
(Optional)

scriptSpec defines the script to be executed.

backupSpec
BackupSpec
(Optional)

backupSpec defines how to backup the cluster.

restoreSpec
RestoreSpec
(Optional)

restoreSpec defines how to restore the cluster. note that this restore operation will roll back cluster services.

customSpec
CustomOpsSpec

OpsRequestStatus

(Appears on:OpsRequest)

OpsRequestStatus defines the observed state of OpsRequest

FieldDescription
clusterGeneration
int64
(Optional)

ClusterGeneration records the cluster generation after handling the opsRequest action.

phase
OpsPhase

phase describes OpsRequest phase.

progress
string
lastConfiguration
LastConfiguration
(Optional)

lastConfiguration records the last configuration before this operation take effected.

components
map[string]github.com/apecloud/kubeblocks/apis/apps/v1alpha1.OpsRequestComponentStatus
(Optional)

components defines the recorded the status information of changed components for operation request.

startTimestamp
Kubernetes meta/v1.Time
(Optional)

startTimestamp The time when the OpsRequest started processing.

completionTimestamp
Kubernetes meta/v1.Time
(Optional)

completionTimestamp defines the OpsRequest completion time.

cancelTimestamp
Kubernetes meta/v1.Time
(Optional)

CancelTimestamp defines cancel time.

reconfiguringStatus
ReconfiguringStatus
(Optional)

reconfiguringStatus defines the status information of reconfiguring.

reconfiguringStatusAsComponent
map[string]*github.com/apecloud/kubeblocks/apis/apps/v1alpha1.ReconfiguringStatus
(Optional)

reconfiguringStatus defines the status information of reconfiguring.

conditions
[]Kubernetes meta/v1.Condition
(Optional)

conditions describes opsRequest detail status.

OpsRequestVolumeClaimTemplate

(Appears on:LastComponentConfiguration, VolumeExpansion)

FieldDescription
storage
Kubernetes resource.Quantity

Request storage size.

name
string

name references volumeClaimTemplate name from cluster components.

OpsService

(Appears on:Expose)

FieldDescription
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.

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.

ports
[]Kubernetes core/v1.ServicePort
(Optional)

The list of ports that are exposed by this service. If Ports are not provided, the default Services Ports defined in the ClusterDefinition or ComponentDefinition that are neither of NodePort nor LoadBalancer service type will be used. If there is no corresponding Service defined in the ClusterDefinition or ComponentDefinition, the expose operation will fail. More info: https://kubernetes.io/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies

roleSelector
string
(Optional)

RoleSelector extends the ServiceSpec.Selector by allowing you to specify defined role as selector for the service.

selector
map[string]string
(Optional)

Route service traffic to pods with label keys and values matching this selector.

If empty or not present, the service is assumed to have an external process managing its endpoints, which Kubernetes will not modify. Only applies to types ClusterIP, NodePort, and LoadBalancer. Ignored if type is ExternalName.

More info: https://kubernetes.io/docs/concepts/services-networking/service/

serviceType
Kubernetes core/v1.ServiceType
(Optional)

type determines how the Service is exposed. Defaults to ClusterIP. Valid options are ExternalName, ClusterIP, NodePort, and LoadBalancer.

  • ClusterIP allocates a cluster-internal IP address for load-balancing to endpoints. Endpoints are determined by the selector or if that is not specified, they are determined by manual construction of an Endpoints object or EndpointSlice objects. If clusterIP is “None”, no virtual IP is allocated and the endpoints are published as a set of endpoints rather than a virtual IP.
  • NodePort builds on ClusterIP and allocates a port on every node which routes to the same endpoints as the clusterIP.
  • LoadBalancer builds on NodePort and creates an external load-balancer (if supported in the current cloud) which routes to the same endpoints as the clusterIP.

More info: https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services-service-types.

OpsType (string alias)

(Appears on:OpsRecorder, OpsRequestSpec)

OpsType defines operation types.

ValueDescription

"Backup"

DataScriptType the data script operation will execute the data script against the cluster.

"Custom"

"DataScript"

"Expose"

StartType the start operation will start the pods which is deleted in stop operation.

"HorizontalScaling"

"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)

FieldDescription
envVarRef
EnvVarRef

envVarRef defines which container and env that the variable references from. source: “env” or “envFrom” of the container.

ParameterConfig

(Appears on:ConfigurationItem)

FieldDescription
key
string

key indicates the key name of ConfigMap.

parameters
[]ParameterPair
(Optional)

Setting the list of parameters for a single configuration file. update specified the parameters.

fileContent
string
(Optional)

fileContent indicates the configuration file content. update whole file.

ParameterPair

(Appears on:ParameterConfig)

FieldDescription
key
string

key is name of the parameter to be updated.

value
string
(Optional)

parameter values to be updated. if set nil, the parameter defined by the key field will be deleted from the configuration file.

ParametersSchema

(Appears on:OpsDefinitionSpec)

FieldDescription
openAPIV3Schema
Kubernetes api extensions v1.JSONSchemaProps
(Optional)

openAPIV3Schema is the OpenAPI v3 schema to use for parameter schema. supported properties types:

  • string
  • number
  • integer
  • array: only supported the item with string type.

PasswordConfig

(Appears on:SystemAccount, SystemAccountSpec)

PasswordConfig helps provide to customize complexity of password generation pattern.

FieldDescription
length
int32
(Optional)

length defines the length of password.

numDigits
int32
(Optional)

numDigits defines number of digits.

numSymbols
int32
(Optional)

numSymbols defines number of symbols.

letterCase
LetterCase
(Optional)

letterCase defines to use lower-cases, upper-cases or mixed-cases of letters.

seed
string
(Optional)

seed specifies the seed used to generate the account’s password. Cannot be updated.

Payload

(Appears on:ConfigurationItemDetail)

FieldDescription
-
map[string]any
(Optional)

PersistentVolumeClaimSpec

(Appears on:ClusterComponentVolumeClaimTemplate)

FieldDescription
accessModes
[]Kubernetes core/v1.PersistentVolumeAccessMode
(Optional)

accessModes 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.ResourceRequirements
(Optional)

resources represents the minimum resources the volume should have. If RecoverVolumeExpansionFailure feature is enabled users are allowed to specify resource requirements that are lower than previous value but must still be higher than capacity recorded in the status field of the claim. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#resources.

storageClassName
string
(Optional)

storageClassName is 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)

volumeMode defines what type of volume is required by the claim.

Phase (string alias)

(Appears on:ClusterDefinitionStatus, ClusterVersionStatus, ComponentDefinitionStatus, OpsDefinitionStatus, ServiceDescriptorStatus)

Phase defines the ClusterDefinition and ClusterVersion CR .status.phase

ValueDescription

"Available"

"Unavailable"

PodAntiAffinity (string alias)

(Appears on:Affinity)

PodAntiAffinity defines pod anti-affinity strategy.

ValueDescription

"Preferred"

"Required"

PodSelectionStrategy (string alias)

(Appears on:VarsRef)

PodSelectionStrategy pod selection strategy.

ValueDescription

"Available"

"PreferredAvailable"

PointInTimeRefSpec

(Appears on:RestoreFromSpec)

FieldDescription
time
Kubernetes meta/v1.Time
(Optional)

specify the time point to restore, with UTC as the time zone.

ref
RefNamespaceName
(Optional)

specify a reference source cluster to restore

PostStartAction

(Appears on:ClusterComponentDefinition)

FieldDescription
cmdExecutorConfig
CmdExecutorConfig

cmdExecutorConfig is the executor configuration of the post-start command.

scriptSpecSelectors
[]ScriptSpecSelector
(Optional)

scriptSpecSelectors defines the selector of the scriptSpecs that need to be referenced. Once ScriptSpecSelectors is defined, the scripts defined in scriptSpecs can be referenced in the PostStartAction.CmdExecutorConfig.

PreCondition

(Appears on:OpsDefinitionSpec)

FieldDescription
rule
Rule

condition declares how the operation can be executed.

exec
PreConditionExec
(Optional)

a job will be run to execute preCondition. and the operation will be executed when the exec job is succeed.

PreConditionExec

(Appears on:PreCondition)

FieldDescription
image
string

image name.

env
[]Kubernetes core/v1.EnvVar
(Optional)

container env.

command
[]string
(Optional)

container commands.

args
[]string
(Optional)

container args.

PreConditionType (string alias)

(Appears on:Action)

PreConditionType defines the preCondition type of the action execution.

ValueDescription

"ClusterReady"

"ComponentReady"

"Immediately"

"RuntimeReady"

ProgressStatus (string alias)

(Appears on:ProgressStatusDetail)

ProgressStatus defines the status of the opsRequest progress.

ValueDescription

"Failed"

"Pending"

"Processing"

"Succeed"

ProgressStatusDetail

(Appears on:OpsRequestComponentStatus)

FieldDescription
group
string
(Optional)

group describes which group the current object belongs to. if the objects of a component belong to the same group, we can ignore it.

objectKey
string

objectKey is the unique key of the object.

status
ProgressStatus

status describes the state of processing the object.

message
string
(Optional)

message is a human readable message indicating details about the object condition.

startTime
Kubernetes meta/v1.Time
(Optional)

startTime is the start time of object processing.

endTime
Kubernetes meta/v1.Time
(Optional)

endTime is the completion time of object processing.

ProtectedVolume

(Appears on:VolumeProtectionSpec)

FieldDescription
name
string
(Optional)

Name of volume to protect.

highWatermark
int
(Optional)

Volume specified high watermark threshold, it will override the component level threshold. If the value is invalid, it will be ignored and the component level threshold will be used.

ProvisionPolicy

(Appears on:SystemAccountConfig)

ProvisionPolicy defines the policy details for creating accounts.

FieldDescription
type
ProvisionPolicyType

type defines the way to provision an account, either CreateByStmt or ReferToExisting.

scope
ProvisionScope

scope is the scope to provision account, and the scope could be AnyPods or AllPods.

statements
ProvisionStatements
(Optional)

statements will be used when Type is CreateByStmt.

secretRef
ProvisionSecretRef
(Optional)

secretRef will be used when Type is ReferToExisting.

ProvisionPolicyType (string alias)

(Appears on:ProvisionPolicy)

ProvisionPolicyType defines the policy for creating accounts.

ValueDescription

"CreateByStmt"

CreateByStmt will create account w.r.t. deletion and creation statement given by provider.

"ReferToExisting"

ReferToExisting will not create account, but create a secret by copying data from referred secret file.

ProvisionScope (string alias)

(Appears on:ProvisionPolicy)

ProvisionScope defines the scope (within component) of provision.

ValueDescription

"AllPods"

AllPods will create accounts for all pods belong to the component.

"AnyPods"

AnyPods will only create accounts on one pod.

ProvisionSecretRef

(Appears on:ProvisionPolicy, SystemAccount)

ProvisionSecretRef defines the information of secret referred to.

FieldDescription
name
string

name refers to the name of the secret.

namespace
string

namespace refers to the namespace of the secret.

ProvisionStatements

(Appears on:ProvisionPolicy)

ProvisionStatements defines the statements used to create accounts.

FieldDescription
creation
string

creation specifies statement how to create this account with required privileges.

update
string
(Optional)

update specifies statement how to update account’s password.

deletion
string
(Optional)

deletion specifies statement how to delete this account. Used in combination with CreateionStatement to delete the account before create it. For instance, one usually uses drop user if exists statement followed by create user statement to create an account. Deprecated: this field is deprecated, use update instead.

RSMSpec

(Appears on:ClusterComponentDefinition)

FieldDescription
roles
[]ReplicaRole
(Optional)

Roles, a list of roles defined in the system.

roleProbe
RoleProbe
(Optional)

RoleProbe provides method to probe role.

membershipReconfiguration
MembershipReconfiguration
(Optional)

MembershipReconfiguration provides actions to do membership dynamic reconfiguration.

memberUpdateStrategy
MemberUpdateStrategy
(Optional)

MemberUpdateStrategy, Members(Pods) update strategy.

  • serial: update Members one by one that guarantee minimum component unavailable time.Learner -> Follower(with AccessMode=none) -> Follower(with AccessMode=readonly) -> Follower(with AccessMode=readWrite) -> Leader
  • bestEffortParallel: update Members in parallel that guarantee minimum component un-writable time.Learner, Follower(minority) in parallel -> Follower(majority) -> Leader, keep majority online all the time.
  • parallel: force parallel

ReconcileDetail

(Appears on:ConfigurationItemDetailStatus)

FieldDescription
policy
string
(Optional)

policy is the policy of the latest execution.

execResult
string
(Optional)

execResult is the result of the latest execution.

currentRevision
string
(Optional)

currentRevision is the current revision of configurationItem.

succeedCount
int32
(Optional)

succeedCount is the number of pods for which configuration changes were successfully executed.

expectedCount
int32
(Optional)

expectedCount is the number of pods that need to be executed for configuration changes.

errMessage
string
(Optional)

errMessage is the error message when the configuration change execution fails.

Reconfigure

(Appears on:OpsRequestSpec)

Reconfigure defines the variables that need to input when updating configuration.

FieldDescription
ComponentOps
ComponentOps

(Members of ComponentOps are embedded into this type.)

configurations
[]ConfigurationItem

configurations defines which components perform the operation.

ReconfiguringStatus

(Appears on:OpsRequestStatus)

FieldDescription
conditions
[]Kubernetes meta/v1.Condition
(Optional)

conditions describes reconfiguring detail status.

configurationStatus
[]ConfigurationItemStatus

configurationStatus describes the status of the component reconfiguring.

RefNamespaceName

(Appears on:BackupRefSpec, PointInTimeRefSpec)

FieldDescription
name
string
(Optional)

specified the name

namespace
string
(Optional)

specified the namespace

ReloadOptions

(Appears on:ConfigConstraintSpec)

ReloadOptions defines reload options Only one of its members may be specified.

FieldDescription
unixSignalTrigger
UnixSignalTrigger
(Optional)

unixSignalTrigger used to reload by sending a signal.

shellTrigger
ShellTrigger
(Optional)

shellTrigger performs the reload command.

tplScriptTrigger
TPLScriptTrigger
(Optional)

goTplTrigger performs the reload command.

autoTrigger
AutoTrigger
(Optional)

autoTrigger performs the reload command.

ReplicaRole

(Appears on:ComponentDefinitionSpec)

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

FieldDescription
name
string

Name of the role. It will apply to “apps.kubeblocks.io/role” object label value. Cannot be updated.

serviceable
bool
(Optional)

Serviceable indicates whether a replica with this role can provide services. Cannot be updated.

writable
bool
(Optional)

Writable indicates whether a replica with this role is allowed to write data. Cannot be updated.

votable
bool
(Optional)

Votable indicates whether a replica with this role is allowed to vote. Cannot be updated.

ReplicasLimit

(Appears on:ComponentDefinitionSpec)

ReplicasLimit defines the limit of valid replicas supported.

FieldDescription
minReplicas
int32

The minimum limit of replicas.

maxReplicas
int32

The maximum limit of replicas.

ReplicationMemberStatus

(Appears on:ReplicationSetStatus)

FieldDescription
pod
string

Pod name.

ReplicationSetSpec

(Appears on:ClusterComponentDefinition)

FieldDescription
StatefulSetSpec
StatefulSetSpec

(Members of StatefulSetSpec are embedded into this type.)

ReplicationSetStatus

(Appears on:ClusterComponentStatus)

FieldDescription
primary
ReplicationMemberStatus

Primary status.

secondaries
[]ReplicationMemberStatus
(Optional)

Secondaries status.

ResourceConstraintRule

(Appears on:ComponentResourceConstraintSpec)

FieldDescription
name
string

The name of the constraint.

cpu
CPUConstraint

The constraint for vcpu cores.

memory
MemoryConstraint

The constraint for memory size.

storage
StorageConstraint
(Optional)

The constraint for storage size.

ResourceMeta

(Appears on:ConfigMapRef, SecretRef)

FieldDescription
name
string

name is the name of the referenced the Configmap/Secret object.

mountPoint
string

mountPath is the path at which to mount the volume.

subPath
string
(Optional)

subPath is a relative file path within the volume to mount.

asVolumeFrom
[]string
(Optional)

asVolumeFrom defines the list of containers where volumeMounts will be injected into.

RestoreFromSpec

(Appears on:OpsRequestSpec)

FieldDescription
backup
[]BackupRefSpec
(Optional)

use the backup name and component name for restore, support for multiple components’ recovery.

pointInTime
PointInTimeRefSpec
(Optional)

specified the point in time to recovery

RestoreSpec

(Appears on:OpsRequestSpec)

FieldDescription
backupName
string

backupName is the name of the backup.

effectiveCommonComponentDef
bool

effectiveCommonComponentDef describes this backup will be restored for all components which refer to common ComponentDefinition.

restoreTimeStr
string

restoreTime point in time to restore

volumeRestorePolicy
string

the volume claim restore policy, support values: [Serial, Parallel]

RetryPolicy

(Appears on:Action)

FieldDescription
maxRetries
int
(Optional)

MaxRetries specifies the maximum number of times the action should be retried.

retryInterval
time.Duration
(Optional)

RetryInterval specifies the interval between retry attempts.

RoleArbitrator (string alias)

(Appears on:ComponentDefinitionSpec)

RoleArbitrator defines how to arbitrate the role of replicas.

ValueDescription

"External"

"Lorry"

RoleProbe

(Appears on:ComponentLifecycleActions)

FieldDescription
LifecycleActionHandler
LifecycleActionHandler

(Members of LifecycleActionHandler are embedded into this type.)

initialDelaySeconds
int32
(Optional)

Number of seconds after the container has started before liveness probes are initiated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes

timeoutSeconds
int32
(Optional)

Number of seconds after which the probe times out. Defaults to 1 second. Minimum value is 1. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes

periodSeconds
int32
(Optional)

How often (in seconds) to perform the probe. 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. Must be 1 for liveness and startup. 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.

terminationGracePeriodSeconds
int64
(Optional)

Optional duration in seconds the pod needs to terminate gracefully upon probe failure.

The grace period is the duration in seconds after the processes running in the pod are sent a termination signal and the time when the processes are forcibly halted with a kill signal. Set this value longer than the expected cleanup time for your process.

If this value is nil, the pod’s terminationGracePeriodSeconds will be used. Otherwise, this value overrides the value provided by the pod spec. Value must be non-negative integer. The value zero indicates stop immediately via the kill signal (no opportunity to shut down).

This is a beta field and requires enabling ProbeTerminationGracePeriod feature gate. Minimum value is 1. spec.terminationGracePeriodSeconds is used if unset.

Rule

(Appears on:PreCondition)

FieldDescription
expression
string

expression declares how the operation can be executed using go template expression. it should return true or false, built-in objects:

  • params are input parameters.
  • cluster is referenced cluster object.
  • component is referenced the component Object.
message
string

report the message if the rule is not matched.

SchedulePolicy

(Appears on:BackupPolicy)

FieldDescription
enabled
bool
(Optional)

enabled specifies whether the backup schedule is enabled or not.

backupMethod
string

backupMethod specifies the backup method name that is defined in backupPolicy.

cronExpression
string

the cron expression for schedule, the timezone is in UTC. see https://en.wikipedia.org/wiki/Cron.

retentionPeriod
github.com/apecloud/kubeblocks/apis/dataprotection/v1alpha1.RetentionPeriod
(Optional)

retentionPeriod determines a duration up to which the backup should be kept. controller will remove all backups that are older than the RetentionPeriod. For example, RetentionPeriod of 30d will keep only the backups of last 30 days. Sample duration format:

  • years: 2y
  • months: 6mo
  • days: 30d
  • hours: 12h
  • minutes: 30m You can also combine the above durations. For example: 30d12h30m

ScriptConfig

(Appears on:ConfigConstraintSpec, TPLScriptTrigger)

FieldDescription
scriptConfigMapRef
string

scriptConfigMapRef used to execute for reload.

namespace
string
(Optional)

Specify the namespace of the referenced the tpl script ConfigMap object. An empty namespace is equivalent to the “default” namespace.

ScriptFrom

(Appears on:ScriptSpec)

ScriptFrom defines the script to be executed from configMap or secret.

FieldDescription
configMapRef
[]Kubernetes core/v1.ConfigMapKeySelector
(Optional)

configMapRef defines the configMap to be executed.

secretRef
[]Kubernetes core/v1.SecretKeySelector
(Optional)

secretRef defines the secret to be executed.

ScriptSecret

(Appears on:ScriptSpec)

ScriptSecret defines the secret to be used to execute the script.

FieldDescription
name
string

name is the name of the secret.

usernameKey
string
(Optional)

usernameKey field is used to specify the username of the secret.

passwordKey
string
(Optional)

passwordKey field is used to specify the password of the secret.

ScriptSpec

(Appears on:OpsRequestSpec)

ScriptSpec defines the script to be executed. It is not a general purpose script executor. It is designed to execute the script to perform some specific operations, such as create database, create user, etc. It is applicable for engines, such as MySQL, PostgreSQL, Redis, MongoDB, etc.

FieldDescription
ComponentOps
ComponentOps

(Members of ComponentOps are embedded into this type.)

image
string
(Optional)

exec command with image, by default use the image of kubeblocks-datascript.

secret
ScriptSecret
(Optional)

secret defines the secret to be used to execute the script. If not specified, the default cluster root credential secret will be used.

script
[]string
(Optional)

script defines the script to be executed.

scriptFrom
ScriptFrom
(Optional)

scriptFrom defines the script to be executed from configMap or secret.

selector
Kubernetes meta/v1.LabelSelector
(Optional)

KubeBlocks, by default, will execute the script on the primary pod, with role=leader. There are some exceptions, such as Redis, which does not synchronize accounts info between primary and secondary. In this case, we need to execute the script on all pods, matching the selector. selector indicates the components on which the script is executed.

ScriptSpecSelector

(Appears on:ComponentSwitchover, PostStartAction, SwitchoverAction)

FieldDescription
name
string

ScriptSpec name of the referent, refer to componentDefs[x].scriptSpecs[y].Name.

SecretRef

(Appears on:UserResourceRefs)

FieldDescription
ResourceMeta
ResourceMeta

(Members of ResourceMeta are embedded into this type.)

secret
Kubernetes core/v1.SecretVolumeSource

secret defines the secret volume source.

Service

(Appears on:ClusterService, ComponentService)

FieldDescription
name
string

Name defines the name of the service. otherwise, it indicates the name of the service. Others can refer to this service by its name. (e.g., connection credential) Cannot be updated.

serviceName
string
(Optional)

ServiceName defines the name of the underlying service object. If not specified, the default service name with different patterns will be used:

  • CLUSTER_NAME: for cluster-level services
  • CLUSTER_NAME-COMPONENT_NAME: for component-level services

Only one default service name is allowed. Cannot be updated.

annotations
map[string]string
(Optional)

If ServiceType is LoadBalancer, cloud provider related parameters can be put here More info: https://kubernetes.io/docs/concepts/services-networking/service/#loadbalancer.

spec
Kubernetes core/v1.ServiceSpec
(Optional)

Spec defines the behavior of a service.https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status



ports
[]Kubernetes core/v1.ServicePort

The list of ports that are exposed by this service. More info: https://kubernetes.io/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies

selector
map[string]string
(Optional)

Route service traffic to pods with label keys and values matching this selector. If empty or not present, the service is assumed to have an external process managing its endpoints, which Kubernetes will not modify. Only applies to types ClusterIP, NodePort, and LoadBalancer. Ignored if type is ExternalName. More info: https://kubernetes.io/docs/concepts/services-networking/service/

clusterIP
string
(Optional)

clusterIP is the IP address of the service and is usually assigned randomly. If an address is specified manually, is in-range (as per system configuration), and is not in use, it will be allocated to the service; otherwise creation of the service will fail. This field may not be changed through updates unless the type field is also being changed to ExternalName (which requires this field to be blank) or the type field is being changed from ExternalName (in which case this field may optionally be specified, as describe above). Valid values are “None”, empty string (“”), or a valid IP address. Setting this to “None” makes a “headless service” (no virtual IP), which is useful when direct endpoint connections are preferred and proxying is not required. Only applies to types ClusterIP, NodePort, and LoadBalancer. If this field is specified when creating a Service of type ExternalName, creation will fail. This field will be wiped when updating a Service to type ExternalName. More info: https://kubernetes.io/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies

clusterIPs
[]string
(Optional)

ClusterIPs is a list of IP addresses assigned to this service, and are usually assigned randomly. If an address is specified manually, is in-range (as per system configuration), and is not in use, it will be allocated to the service; otherwise creation of the service will fail. This field may not be changed through updates unless the type field is also being changed to ExternalName (which requires this field to be empty) or the type field is being changed from ExternalName (in which case this field may optionally be specified, as describe above). Valid values are “None”, empty string (“”), or a valid IP address. Setting this to “None” makes a “headless service” (no virtual IP), which is useful when direct endpoint connections are preferred and proxying is not required. Only applies to types ClusterIP, NodePort, and LoadBalancer. If this field is specified when creating a Service of type ExternalName, creation will fail. This field will be wiped when updating a Service to type ExternalName. If this field is not specified, it will be initialized from the clusterIP field. If this field is specified, clients must ensure that clusterIPs[0] and clusterIP have the same value.

This field may hold a maximum of two entries (dual-stack IPs, in either order). These IPs must correspond to the values of the ipFamilies field. Both clusterIPs and ipFamilies are governed by the ipFamilyPolicy field. More info: https://kubernetes.io/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies

type
Kubernetes core/v1.ServiceType
(Optional)

type determines how the Service is exposed. Defaults to ClusterIP. Valid options are ExternalName, ClusterIP, NodePort, and LoadBalancer. “ClusterIP” allocates a cluster-internal IP address for load-balancing to endpoints. Endpoints are determined by the selector or if that is not specified, by manual construction of an Endpoints object or EndpointSlice objects. If clusterIP is “None”, no virtual IP is allocated and the endpoints are published as a set of endpoints rather than a virtual IP. “NodePort” builds on ClusterIP and allocates a port on every node which routes to the same endpoints as the clusterIP. “LoadBalancer” builds on NodePort and creates an external load-balancer (if supported in the current cloud) which routes to the same endpoints as the clusterIP. “ExternalName” aliases this service to the specified externalName. Several other fields do not apply to ExternalName services. More info: https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services-service-types

externalIPs
[]string
(Optional)

externalIPs is a list of IP addresses for which nodes in the cluster will also accept traffic for this service. These IPs are not managed by Kubernetes. The user is responsible for ensuring that traffic arrives at a node with this IP. A common example is external load-balancers that are not part of the Kubernetes system.

sessionAffinity
Kubernetes core/v1.ServiceAffinity
(Optional)

Supports “ClientIP” and “None”. Used to maintain session affinity. Enable client IP based session affinity. Must be ClientIP or None. Defaults to None. More info: https://kubernetes.io/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies

loadBalancerIP
string
(Optional)

Only applies to Service Type: LoadBalancer. This feature depends on whether the underlying cloud-provider supports specifying the loadBalancerIP when a load balancer is created. This field will be ignored if the cloud-provider does not support the feature. Deprecated: This field was under-specified and its meaning varies across implementations. Using it is non-portable and it may not support dual-stack. Users are encouraged to use implementation-specific annotations when available.

loadBalancerSourceRanges
[]string
(Optional)

If specified and supported by the platform, this will restrict traffic through the cloud-provider load-balancer will be restricted to the specified client IPs. This field will be ignored if the cloud-provider does not support the feature.” More info: https://kubernetes.io/docs/tasks/access-application-cluster/create-external-load-balancer/

externalName
string
(Optional)

externalName is the external reference that discovery mechanisms will return as an alias for this service (e.g. a DNS CNAME record). No proxying will be involved. Must be a lowercase RFC-1123 hostname (https://tools.ietf.org/html/rfc1123) and requires type to be “ExternalName”.

externalTrafficPolicy
Kubernetes core/v1.ServiceExternalTrafficPolicy
(Optional)

externalTrafficPolicy describes how nodes distribute service traffic they receive on one of the Service’s “externally-facing” addresses (NodePorts, ExternalIPs, and LoadBalancer IPs). If set to “Local”, the proxy will configure the service in a way that assumes that external load balancers will take care of balancing the service traffic between nodes, and so each node will deliver traffic only to the node-local endpoints of the service, without masquerading the client source IP. (Traffic mistakenly sent to a node with no endpoints will be dropped.) The default value, “Cluster”, uses the standard behavior of routing to all endpoints evenly (possibly modified by topology and other features). Note that traffic sent to an External IP or LoadBalancer IP from within the cluster will always get “Cluster” semantics, but clients sending to a NodePort from within the cluster may need to take traffic policy into account when picking a node.

healthCheckNodePort
int32
(Optional)

healthCheckNodePort specifies the healthcheck nodePort for the service. This only applies when type is set to LoadBalancer and externalTrafficPolicy is set to Local. If a value is specified, is in-range, and is not in use, it will be used. If not specified, a value will be automatically allocated. External systems (e.g. load-balancers) can use this port to determine if a given node holds endpoints for this service or not. If this field is specified when creating a Service which does not need it, creation will fail. This field will be wiped when updating a Service to no longer need it (e.g. changing type). This field cannot be updated once set.

publishNotReadyAddresses
bool
(Optional)

publishNotReadyAddresses indicates that any agent which deals with endpoints for this Service should disregard any indications of ready/not-ready. The primary use case for setting this field is for a StatefulSet’s Headless Service to propagate SRV DNS records for its Pods for the purpose of peer discovery. The Kubernetes controllers that generate Endpoints and EndpointSlice resources for Services interpret this to mean that all endpoints are considered “ready” even if the Pods themselves are not. Agents which consume only Kubernetes generated endpoints through the Endpoints or EndpointSlice resources can safely assume this behavior.

sessionAffinityConfig
Kubernetes core/v1.SessionAffinityConfig
(Optional)

sessionAffinityConfig contains the configurations of session affinity.

ipFamilies
[]Kubernetes core/v1.IPFamily
(Optional)

IPFamilies is a list of IP families (e.g. IPv4, IPv6) assigned to this service. This field is usually assigned automatically based on cluster configuration and the ipFamilyPolicy field. If this field is specified manually, the requested family is available in the cluster, and ipFamilyPolicy allows it, it will be used; otherwise creation of the service will fail. This field is conditionally mutable: it allows for adding or removing a secondary IP family, but it does not allow changing the primary IP family of the Service. Valid values are “IPv4” and “IPv6”. This field only applies to Services of types ClusterIP, NodePort, and LoadBalancer, and does apply to “headless” services. This field will be wiped when updating a Service to type ExternalName.

This field may hold a maximum of two entries (dual-stack families, in either order). These families must correspond to the values of the clusterIPs field, if specified. Both clusterIPs and ipFamilies are governed by the ipFamilyPolicy field.

ipFamilyPolicy
Kubernetes core/v1.IPFamilyPolicy
(Optional)

IPFamilyPolicy represents the dual-stack-ness requested or required by this Service. If there is no value provided, then this field will be set to SingleStack. Services can be “SingleStack” (a single IP family), “PreferDualStack” (two IP families on dual-stack configured clusters or a single IP family on single-stack clusters), or “RequireDualStack” (two IP families on dual-stack configured clusters, otherwise fail). The ipFamilies and clusterIPs fields depend on the value of this field. This field will be wiped when updating a service to type ExternalName.

allocateLoadBalancerNodePorts
bool
(Optional)

allocateLoadBalancerNodePorts defines if NodePorts will be automatically allocated for services with type LoadBalancer. Default is “true”. It may be set to “false” if the cluster load-balancer does not rely on NodePorts. If the caller requests specific NodePorts (by specifying a value), those requests will be respected, regardless of this field. This field may only be set for services with type LoadBalancer and will be cleared if the type is changed to any other type.

loadBalancerClass
string
(Optional)

loadBalancerClass is the class of the load balancer implementation this Service belongs to. If specified, the value of this field must be a label-style identifier, with an optional prefix, e.g. “internal-vip” or “example.com/internal-vip”. Unprefixed names are reserved for end-users. This field can only be set when the Service type is ‘LoadBalancer’. If not set, the default load balancer implementation is used, today this is typically done through the cloud provider integration, but should apply for any default implementation. If set, it is assumed that a load balancer implementation is watching for Services with a matching class. Any default load balancer implementation (e.g. cloud providers) should ignore Services that set this field. This field can only be set when creating or updating a Service to type ‘LoadBalancer’. Once set, it can not be changed. This field will be wiped when a service is updated to a non ‘LoadBalancer’ type.

internalTrafficPolicy
Kubernetes core/v1.ServiceInternalTrafficPolicy
(Optional)

InternalTrafficPolicy describes how nodes distribute service traffic they receive on the ClusterIP. If set to “Local”, the proxy will assume that pods only want to talk to endpoints of the service on the same node as the pod, dropping the traffic if there are no local endpoints. The default value, “Cluster”, uses the standard behavior of routing to all endpoints evenly (possibly modified by topology and other features).

roleSelector
string
(Optional)

RoleSelector extends the ServiceSpec.Selector by allowing you to specify defined role as selector for the service. if GeneratePodOrdinalService sets to true, RoleSelector will be ignored.

ServiceDescriptorSpec

(Appears on:ServiceDescriptor)

ServiceDescriptorSpec defines the desired state of ServiceDescriptor

FieldDescription
serviceKind
string

service kind, indicating the type or nature of the service. It should be well-known application cluster type, e.g. {mysql, redis, mongodb}. The serviceKind is case-insensitive and supports abbreviations for some well-known databases. For example, both zk and zookeeper will be considered as a ZooKeeper cluster, and pg, postgres, postgresql will all be considered as a PostgreSQL cluster.

serviceVersion
string

The version of the service reference.

endpoint
CredentialVar
(Optional)

endpoint is the endpoint of the service connection credential.

auth
ConnectionCredentialAuth
(Optional)

auth is the auth of the service connection credential.

port
CredentialVar
(Optional)

port is the port of the service connection credential.

ServiceDescriptorStatus

(Appears on:ServiceDescriptor)

ServiceDescriptorStatus defines the observed state of ServiceDescriptor

FieldDescription
phase
Phase
(Optional)

phase - in list of [Available,Unavailable]

message
string
(Optional)

A human-readable message indicating details about why the ServiceConnectionCredential is in this phase.

observedGeneration
int64
(Optional)

generation number

ServicePort

(Appears on:ServiceSpec)

FieldDescription
name
string

The name of this port within the service. This must be a DNS_LABEL. All ports within a ServiceSpec must have unique names. When considering the endpoints for a Service, this must match the ‘name’ field in the EndpointPort.

protocol
Kubernetes core/v1.Protocol
(Optional)

The IP protocol for this port. Supports “TCP”, “UDP”, and “SCTP”. Default is TCP.

appProtocol
string
(Optional)

The application protocol for this port. This field follows standard Kubernetes label syntax. Un-prefixed names are reserved for IANA standard service names (as per RFC-6335 and https://www.iana.org/assignments/service-names). Non-standard protocols should use prefixed names such as mycompany.com/my-custom-protocol.

port
int32

The port that will be exposed by this service.

targetPort
Kubernetes api utils intstr.IntOrString
(Optional)

Number or name of the port to access on the pods targeted by the service.

Number must be in the range 1 to 65535. Name must be an IANA_SVC_NAME.

  • If this is a string, it will be looked up as a named port in the target Pod’s container ports.
  • If this is not specified, the value of the port field is used (an identity map).

This field is ignored for services with clusterIP=None, and should be omitted or set equal to the port field.

More info: https://kubernetes.io/docs/concepts/services-networking/service/#defining-a-service

ServiceRef

(Appears on:ClusterComponentSpec, ComponentSpec)

FieldDescription
name
string

name of the service reference declaration. references the serviceRefDeclaration name defined in clusterDefinition.componentDefs[].serviceRefDeclarations[].name

namespace
string
(Optional)

namespace defines the namespace of the referenced Cluster or the namespace of the referenced ServiceDescriptor object. If not set, the referenced Cluster and ServiceDescriptor will be searched in the namespace of the current cluster by default.

cluster
string
(Optional)

When referencing a service provided by other KubeBlocks cluster, you need to provide the name of the Cluster being referenced.

By default, when other KubeBlocks Cluster are referenced, the ClusterDefinition.spec.connectionCredential secret corresponding to the referenced Cluster will be used to bind to the current component. Currently, if a KubeBlocks cluster is to be referenced, the connection credential secret should include and correspond to the following fields: endpoint, port, username, and password.

Under this referencing approach, the ServiceKind and ServiceVersion of service reference declaration defined in the ClusterDefinition will not be validated. If both Cluster and ServiceDescriptor are specified, the Cluster takes precedence.

serviceDescriptor
string
(Optional)

serviceDescriptor defines the service descriptor of the service provided by external sources.

When referencing a service provided by external sources, you need to provide the ServiceDescriptor object name to establish the service binding. And serviceDescriptor is the name of the ServiceDescriptor object, furthermore, the ServiceDescriptor.spec.serviceKind and ServiceDescriptor.spec.serviceVersionshould match clusterDefinition.componentDefs[*].serviceRefDeclarations[*].serviceRefDeclarationSpecs[*].serviceKindand the regular expression defines in clusterDefinition.componentDefs[*].serviceRefDeclarations[*].serviceRefDeclarationSpecs[*].serviceVersion.

If both Cluster and ServiceDescriptor are specified, the Cluster takes precedence.

ServiceRefDeclaration

(Appears on:ClusterComponentDefinition, ComponentDefinitionSpec)

FieldDescription
name
string

The name of the service reference declaration. The service reference can come from an external service that is not part of KubeBlocks, or services provided by other KubeBlocks Cluster objects. The specific type of service reference depends on the binding declaration when creates a Cluster.

serviceRefDeclarationSpecs
[]ServiceRefDeclarationSpec

serviceRefDeclarationSpecs is a collection of service descriptions for a service reference declaration.

Each ServiceRefDeclarationSpec defines a service Kind and Version. When multiple ServiceRefDeclarationSpecs are defined, it indicates that the ServiceRefDeclaration can be any one of the specified ServiceRefDeclarationSpecs.

For example, when the ServiceRefDeclaration is declared to require an OLTP database, which can be either MySQL or PostgreSQL, you can define a ServiceRefDeclarationSpec for MySQL and another ServiceRefDeclarationSpec for PostgreSQL, when referencing the service within the cluster, as long as the serviceKind and serviceVersion match either MySQL or PostgreSQL, it can be used.

ServiceRefDeclarationSpec

(Appears on:ServiceRefDeclaration)

FieldDescription
serviceKind
string

service kind, indicating the type or nature of the service. It should be well-known application cluster type, e.g. {mysql, redis, mongodb}. The serviceKind is case-insensitive and supports abbreviations for some well-known databases. For example, both zk and zookeeper will be considered as a ZooKeeper cluster, and pg, postgres, postgresql will all be considered as a PostgreSQL cluster.

serviceVersion
string

The service version of the service reference. It is a regular expression that matches a version number pattern. For example, ^8.0.8$, 8.0.\d{1,2}$, ^[v\-]*?(\d{1,2}\.){0,3}\d{1,2}$

ServiceRefVarSelector

(Appears on:VarSource)

ServiceRefVarSelector selects a var from a ServiceRefDeclaration.

FieldDescription
ClusterObjectReference
ClusterObjectReference

(Members of ClusterObjectReference are embedded into this type.)

The ServiceRefDeclaration to select from.

ServiceRefVars
ServiceRefVars

(Members of ServiceRefVars are embedded into this type.)

ServiceRefVars

(Appears on:ServiceRefVarSelector)

ServiceRefVars defines the vars can be referenced from a ServiceRef.

FieldDescription
endpoint
VarOption
(Optional)
port
VarOption
(Optional)
CredentialVars
CredentialVars

(Members of CredentialVars are embedded into this type.)

ServiceSpec

(Appears on:ClusterComponentDefinition)

FieldDescription
ports
[]ServicePort
(Optional)

The list of ports that are exposed by this service. More info: https://kubernetes.io/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies

ServiceVarSelector

(Appears on:VarSource)

ServiceVarSelector selects a var from a Service.

FieldDescription
ClusterObjectReference
ClusterObjectReference

(Members of ClusterObjectReference are embedded into this type.)

The Service to select from. It can be referenced from the default headless service by setting the name to “headless”.

ServiceVars
ServiceVars

(Members of ServiceVars are embedded into this type.)

generatePodOrdinalServiceVar
bool
(Optional)

GeneratePodOrdinalServiceVar indicates whether to create a corresponding ServiceVars reference variable for each Pod. If set to true, a set of ServiceVars that can be referenced will be automatically generated for each Pod Ordinal. They can be referred to by adding the PodOrdinal to the defined name template with named pattern $(Vars[x].Name)_$(PodOrdinal). For example, a ServiceVarRef might be defined as follows:

name: MY_SERVICE_PORT valueFrom: serviceVarRef: compDef: my-component-definition name: my-service optional: true generatePodOrdinalServiceVar: true port: name: redis-sentinel

Assuming that the Component has 3 replicas, then you can reference the port of existing services named my-service-0, my-service-1, and my-service-2 with $MY_SERVICE_PORT_0, $MY_SERVICE_PORT_1, and $MY_SERVICE_PORT_2, respectively. It should be used in conjunction with Service.GeneratePodOrdinalService.

ServiceVars

(Appears on:ServiceVarSelector)

ServiceVars defines the vars can be referenced from a Service.

FieldDescription
host
VarOption
(Optional)
port
NamedVar
(Optional)
nodePort
NamedVar
(Optional)

ShardingSpec

(Appears on:ClusterSpec)

ShardingSpec defines the sharding spec.

FieldDescription
name
string

name defines sharding name, this name is also part of Service DNS name, so this name will comply with IANA Service Naming rule. The name is also used to generate the name of the underlying components with the naming pattern $(ShardingSpec.Name)-$(ShardID). At the same time, the name of component template defined in ShardingSpec.Template.Name will be ignored.

template
ClusterComponentSpec

template defines the component template. A ShardingSpec generates a set of components (also called shards) based on the component template, and this group of components or shards have the same specifications and definitions.

shards
int32

shards indicates the number of component, and these components have the same specifications and definitions.

It should be noted that the number of replicas for each component should be defined by template.replicas. Moreover, the logical relationship between these components should be maintained by the components themselves, KubeBlocks only provides the following capabilities for managing the lifecycle of sharding:

  1. When the number of shards increases, the postProvision Action defined in the ComponentDefinition will be executed if the conditions are met.
  2. When the number of shards decreases, the preTerminate Action defined in the ComponentDefinition will be executed if the conditions are met. Additionally, the resources and data associated with the corresponding Component will be deleted as well.

ShellTrigger

(Appears on:ReloadOptions)

FieldDescription
command
[]string

command used to execute for reload.

sync
bool
(Optional)

Specify synchronize updates parameters to the config manager.

SignalType (string alias)

(Appears on:UnixSignalTrigger)

SignalType defines which signals are valid.

ValueDescription

"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"

StatefulSetSpec

(Appears on:ClusterComponentDefinition, ConsensusSetSpec, ReplicationSetSpec)

FieldDescription
updateStrategy
UpdateStrategy
(Optional)

updateStrategy, Pods update strategy. In case of workloadType=Consensus the update strategy will be following:

  • serial: update Members one by one that guarantee minimum component unavailable time.Learner -> Follower(with AccessMode=none) -> Follower(with AccessMode=readonly) -> Follower(with AccessMode=readWrite) -> Leader
  • bestEffortParallel: update Members in parallel that guarantee minimum component un-writable time.Learner, Follower(minority) in parallel -> Follower(majority) -> Leader, keep majority online all the time.
  • parallel: force parallel
llPodManagementPolicy
Kubernetes apps/v1.PodManagementPolicyType
(Optional)

llPodManagementPolicy is the low-level controls how pods are created during initial scale up, when replacing pods on nodes, or when scaling down.

  • OrderedReady policy specify where pods are created in increasing order (pod-0, then pod-1, etc) and the controller will wait until each pod is ready before continuing. When scaling down, the pods are removed in the opposite order.
  • Parallel policy specify create pods in parallel to match the desired scale without waiting, and on scale down will delete all pods at once.
llUpdateStrategy
Kubernetes apps/v1.StatefulSetUpdateStrategy
(Optional)

llUpdateStrategy indicates the low-level StatefulSetUpdateStrategy that will be employed to update Pods in the StatefulSet when a revision is made to Template. Will ignore updateStrategy attribute if provided.

StatefulSetWorkload

StatefulSetWorkload interface

StatelessSetSpec

(Appears on:ClusterComponentDefinition)

FieldDescription
updateStrategy
Kubernetes apps/v1.DeploymentStrategy
(Optional)

updateStrategy defines the underlying deployment strategy to use to replace existing pods with new ones.

StorageConstraint

(Appears on:ResourceConstraintRule)

FieldDescription
min
Kubernetes resource.Quantity
(Optional)

The minimum size of storage.

max
Kubernetes resource.Quantity
(Optional)

The maximum size of storage.

SwitchPolicyType (string alias)

(Appears on:ClusterSwitchPolicy)

SwitchPolicyType defines switchPolicy type. Currently, only Noop is supported. MaximumAvailability and MaximumDataProtection will be supported in the future.

ValueDescription

"MaximumAvailability"

"MaximumDataProtection"

"Noop"

Switchover

(Appears on:OpsRequestSpec)

FieldDescription
ComponentOps
ComponentOps

(Members of ComponentOps are embedded into this type.)

instanceName
string

instanceName is used to specify the candidate primary or leader instanceName for switchover.

If instanceName is set to “*”, it means that no specific primary or leader is specified for the switchover, and the switchoverAction defined in clusterDefinition.componentDefs[x].switchoverSpec.withoutCandidate will be executed.

It is required that clusterDefinition.componentDefs[x].switchoverSpec.withoutCandidate is not empty.

If instanceName is set to a valid instanceName other than “*”, it means that a specific candidate primary or leader is specified for the switchover. the value of instanceName can be obtained using kbcli cluster list-instances, any other value is invalid. In this case, the switchoverAction defined in clusterDefinition.componentDefs[x].switchoverSpec.withCandidate will be executed, and it is required that clusterDefinition.componentDefs[x].switchoverSpec.withCandidate is not empty.

SwitchoverAction

(Appears on:SwitchoverSpec)

FieldDescription
cmdExecutorConfig
CmdExecutorConfig

cmdExecutorConfig is the executor configuration of the switchover command.

scriptSpecSelectors
[]ScriptSpecSelector
(Optional)

scriptSpecSelectors defines the selector of the scriptSpecs that need to be referenced. Once ScriptSpecSelectors is defined, the scripts defined in scriptSpecs can be referenced in the SwitchoverAction.CmdExecutorConfig.

SwitchoverShortSpec

(Appears on:ClusterComponentVersion)

SwitchoverShortSpec is a short version of SwitchoverSpec, with only CommandExecutorEnvItem field.

FieldDescription
cmdExecutorConfig
CommandExecutorEnvItem

CmdExecutorConfig is the command executor config.

SwitchoverSpec

(Appears on:ClusterComponentDefinition)

FieldDescription
withCandidate
SwitchoverAction
(Optional)

withCandidate corresponds to the switchover of the specified candidate primary or leader instance.

withoutCandidate
SwitchoverAction
(Optional)

withoutCandidate corresponds to a switchover that does not specify a candidate primary or leader instance.

SystemAccount

(Appears on:ComponentDefinitionSpec)

FieldDescription
name
string

The name of the account. Others can refer to this account by the name. Cannot be updated.

initAccount
bool
(Optional)

InitAccount indicates whether this is the unique system initialization account (e.g., MySQL root). Only one system init account is allowed. Cannot be updated.

statement
string
(Optional)

Statement specifies the statement used to create the account with required privileges. Cannot be updated.

passwordGenerationPolicy
PasswordConfig
(Optional)

PasswordGenerationPolicy defines the policy for generating the account’s password. Cannot be updated.

secretRef
ProvisionSecretRef
(Optional)

SecretRef specifies the secret from which data will be copied to create the new account. Cannot be updated.

SystemAccountConfig

(Appears on:SystemAccountSpec)

SystemAccountConfig specifies how to create and delete system accounts.

FieldDescription
name
AccountName

name is the name of a system account.

provisionPolicy
ProvisionPolicy

provisionPolicy defines how to create account.

SystemAccountShortSpec

(Appears on:ClusterComponentVersion)

SystemAccountShortSpec is a short version of SystemAccountSpec, with only CmdExecutorConfig field.

FieldDescription
cmdExecutorConfig
CommandExecutorEnvItem

cmdExecutorConfig configs how to get client SDK and perform statements.

SystemAccountSpec

(Appears on:ClusterComponentDefinition)

SystemAccountSpec specifies information to create system accounts.

FieldDescription
cmdExecutorConfig
CmdExecutorConfig

cmdExecutorConfig configs how to get client SDK and perform statements.

passwordConfig
PasswordConfig

passwordConfig defines the pattern to generate password.

accounts
[]SystemAccountConfig

accounts defines system account config settings.

TLSConfig

(Appears on:ComponentSpec)

FieldDescription
enable
bool
(Optional)
issuer
Issuer
(Optional)

TLSSecretRef

(Appears on:Issuer)

TLSSecretRef defines Secret contains Tls certs

FieldDescription
name
string

Name of the Secret

ca
string

CA cert key in Secret

cert
string

Cert key in Secret

key
string

Key of TLS private key in Secret

TPLScriptTrigger

(Appears on:ReloadOptions)

FieldDescription
ScriptConfig
ScriptConfig

(Members of ScriptConfig are embedded into this type.)

sync
bool
(Optional)

Specify synchronize updates parameters to the config manager.

TargetInstance

(Appears on:BackupMethod, BackupPolicy)

FieldDescription
role
string

select instance of corresponding role for backup, role are:

  • the name of Leader/Follower/Leaner for Consensus component.
  • primary or secondary for Replication component.

finally, invalid role of the component will be ignored. such as if workload type is Replication and component’s replicas is 1, the secondary role is invalid. and it also will be ignored when component is Stateful/Stateless. the role will be transformed to a role LabelSelector for BackupPolicy’s target attribute.

account
string
(Optional)

refer to spec.componentDef.systemAccounts.accounts[*].name in ClusterDefinition. the secret created by this account will be used to connect the database. if not set, the secret created by spec.ConnectionCredential of the ClusterDefinition will be used. it will be transformed to a secret for BackupPolicy’s target secret.

strategy
github.com/apecloud/kubeblocks/apis/dataprotection/v1alpha1.PodSelectionStrategy
(Optional)

PodSelectionStrategy specifies the strategy to select when multiple pods are selected for backup target. Valid values are:

  • Any: select any one pod that match the labelsSelector.
  • All: select all pods that match the labelsSelector.
connectionCredentialKey
ConnectionCredentialKey
(Optional)

connectionCredentialKey defines connection credential key in secret which created by spec.ConnectionCredential of the ClusterDefinition. it will be ignored when “account” is set.

TargetPodSelector (string alias)

(Appears on:Action)

TargetPodSelector defines how to select pod(s) to execute a action.

ValueDescription

"All"

"Any"

"Ordinal"

"Role"

TenancyType (string alias)

(Appears on:Affinity, ClusterSpec)

TenancyType for cluster tenant resources.

ValueDescription

"DedicatedNode"

"SharedNode"

TerminationPolicyType (string alias)

(Appears on:ClusterSpec)

TerminationPolicyType defines termination policy types.

ValueDescription

"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.

ToolConfig

(Appears on:ToolsImageSpec)

FieldDescription
name
string

Specify the name of initContainer. Must be a DNS_LABEL name.

image
string
(Optional)

tools Container image name.

command
[]string

exec used to execute for init containers.

ToolsImageSpec

(Appears on:ConfigConstraintSpec)

FieldDescription
mountPoint
string

mountPoint is the mount point of the scripts file.

toolConfigs
[]ToolConfig
(Optional)

toolConfig used to config init container.

UnixSignalTrigger

(Appears on:ReloadOptions)

FieldDescription
signal
SignalType

signal is valid for unix signal. e.g: SIGHUP url: ../../pkg/configuration/configmap/handler.go:allUnixSignals

processName
string

processName is process name, sends unix signal to proc.

UpdateStrategy (string alias)

(Appears on:ClusterComponentSpec, ComponentDefinitionSpec, ComponentSpec, StatefulSetSpec)

UpdateStrategy defines Cluster Component update strategy.

ValueDescription

"BestEffortParallel"

"Parallel"

"Serial"

UpdatedParameters

(Appears on:ConfigurationItemStatus)

FieldDescription
addedKeys
map[string]string
(Optional)

addedKeys describes the key added.

deletedKeys
map[string]string
(Optional)

deletedKeys describes the key deleted.

updatedKeys
map[string]string
(Optional)

updatedKeys describes the key updated.

Upgrade

(Appears on:OpsRequestSpec)

Upgrade defines the variables of upgrade operation.

FieldDescription
clusterVersionRef
string

clusterVersionRef references ClusterVersion name.

UpgradePolicy (string alias)

(Appears on:ConfigurationItem, ConfigurationItemStatus)

UpgradePolicy defines the policy of reconfiguring.

ValueDescription

"autoReload"

"none"

"simple"

"operatorSyncUpdate"

"parallel"

"rolling"

UserResourceRefs

(Appears on:ClusterComponentSpec)

FieldDescription
secretRefs
[]SecretRef
(Optional)

secretRefs defines the user-defined secrets.

configMapRefs
[]ConfigMapRef
(Optional)

configMapRefs defines the user-defined configmaps.

ValueFrom

(Appears on:EnvMappingVar)

FieldDescription
clusterVersionRef
[]ValueMapping
(Optional)

mapped ClusterVersionRef to env value.

componentDef
[]ValueMapping
(Optional)

mapped ComponentDefinition to env value.

ValueMapping

(Appears on:ValueFrom)

FieldDescription
names
[]string

the array of ClusterVersion name which can be mapped to the env value.

mappingValue
string

mapping value for the specified ClusterVersion names.

VarOption (string alias)

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

VarOption defines whether a variable is required or optional.

VarSource

(Appears on:EnvVar)

VarSource represents a source for the value of an EnvVar.

FieldDescription
configMapKeyRef
Kubernetes core/v1.ConfigMapKeySelector
(Optional)

Selects a key of a ConfigMap.

secretKeyRef
Kubernetes core/v1.SecretKeySelector
(Optional)

Selects a key of a Secret.

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.

VarsRef

(Appears on:ComponentDefinitionRef, OpsDefinitionSpec)

FieldDescription
podSelectionStrategy
PodSelectionStrategy

podSelectionStrategy how to select the target component pod for variable references based on the strategy.

  • PreferredAvailable: prioritize the selection of available pod.
  • Available: only select available pod. if not found, terminating the operation.
vars
[]OpsEnvVar

List of environment variables to set in the job’s container.

VersionsContext

(Appears on:ClusterComponentVersion)

FieldDescription
initContainers
[]Kubernetes core/v1.Container
(Optional)

Provide ClusterDefinition.spec.componentDefs.podSpec.initContainers override values, typical scenarios are application container image updates.

containers
[]Kubernetes core/v1.Container
(Optional)

Provide ClusterDefinition.spec.componentDefs.podSpec.containers override values, typical scenarios are application container image updates.

VerticalScaling

(Appears on:OpsRequestSpec)

VerticalScaling defines the variables that need to input when scaling compute resources.

FieldDescription
ComponentOps
ComponentOps

(Members of ComponentOps are embedded into this type.)

ResourceRequirements
Kubernetes core/v1.ResourceRequirements

(Members of ResourceRequirements are embedded into this type.)

resources specifies the computing resource size of verticalScaling.

classDefRef
ClassDefRef
(Optional)

classDefRef reference class defined in ComponentClassDefinition.

VolumeExpansion

(Appears on:OpsRequestSpec)

VolumeExpansion defines the variables of volume expansion operation.

FieldDescription
ComponentOps
ComponentOps

(Members of ComponentOps are embedded into this type.)

volumeClaimTemplates
[]OpsRequestVolumeClaimTemplate

volumeClaimTemplates specifies the storage size and volumeClaimTemplate name.

VolumeProtectionSpec

(Appears on:ClusterComponentDefinition)

FieldDescription
highWatermark
int
(Optional)

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

volumes
[]ProtectedVolume
(Optional)

Volumes to protect.

VolumeType (string alias)

(Appears on:VolumeTypeSpec)

VolumeType defines volume type for backup data or log.

ValueDescription

"data"

"log"

VolumeTypeSpec

(Appears on:ClusterComponentDefinition)

FieldDescription
name
string

name definition is the same as the name of the VolumeMounts field in PodSpec.Container, similar to the relations of Volumes[].name and VolumesMounts[].name in Pod.Spec.

type
VolumeType
(Optional)

type is in enum of {data, log}. VolumeTypeData: the volume is for the persistent data storage. VolumeTypeLog: the volume is for the persistent log storage.

WorkloadType (string alias)

(Appears on:ClusterComponentDefinition, OpsRequestComponentStatus)

WorkloadType defines ClusterDefinition’s component workload type.

ValueDescription

"Consensus"

"Replication"

"Stateful"

"Stateless"


workloads.kubeblocks.io/v1alpha1

Resource Types:

ReplicatedStateMachine

ReplicatedStateMachine is the Schema for the replicatedstatemachines API.

FieldDescription
apiVersion
string
workloads.kubeblocks.io/v1alpha1
kind
string
ReplicatedStateMachine
metadata
Kubernetes meta/v1.ObjectMeta
Refer to the Kubernetes API documentation for the fields of themetadata field.
spec
ReplicatedStateMachineSpec


replicas
int32
(Optional)

replicas is the desired number of replicas of the given Template. These are replicas in the sense that they are instantiations of the same Template, but individual replicas also have a consistent identity. If unspecified, defaults to 1.

selector
Kubernetes meta/v1.LabelSelector

selector is a label query over pods that should match the replica count. It must match the pod template’s labels. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors

serviceName
string

serviceName is the name of the service that governs this StatefulSet. This service must exist before the StatefulSet, and is responsible for the network identity of the set. Pods get DNS/hostnames that follow the pattern: pod-specific-string.serviceName.default.svc.cluster.local where “pod-specific-string” is managed by the StatefulSet controller.

service
Kubernetes core/v1.Service
(Optional)

service defines the behavior of a service spec. provides read-write servicehttps://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status

alternativeServices
[]Kubernetes core/v1.Service
(Optional)

AlternativeServices defines Alternative Services selector pattern specifier. can be used for creating Readonly service.

template
Kubernetes core/v1.PodTemplateSpec
volumeClaimTemplates
[]Kubernetes core/v1.PersistentVolumeClaim
(Optional)

volumeClaimTemplates is a list of claims that pods are allowed to reference. The ReplicatedStateMachine controller is responsible for mapping network identities to claims in a way that maintains the identity of a pod. Every claim in this list must have at least one matching (by name) volumeMount in one container in the template. A claim in this list takes precedence over any volumes in the template, with the same name.

podManagementPolicy
Kubernetes apps/v1.PodManagementPolicyType
(Optional)

podManagementPolicy controls how pods are created during initial scale up, when replacing pods on nodes, or when scaling down.

  • The default policy is OrderedReady, where pods are created in increasing order (pod-0, then pod-1, etc) and the controller will wait until each pod is ready before continuing. When scaling down, the pods are removed in the opposite order.
  • The alternative policy is Parallel which will create pods in parallel to match the desired scale without waiting, and on scale down will delete all pods at once.
updateStrategy
Kubernetes apps/v1.StatefulSetUpdateStrategy

updateStrategy indicates the StatefulSetUpdateStrategy that will be employed to update Pods in the RSM when a revision is made to Template. UpdateStrategy.Type will be set to appsv1.OnDeleteStatefulSetStrategyType if MemberUpdateStrategy is not nil

roles
[]ReplicaRole
(Optional)

Roles, a list of roles defined in the system.

roleProbe
RoleProbe
(Optional)

RoleProbe provides method to probe role.

membershipReconfiguration
MembershipReconfiguration
(Optional)

MembershipReconfiguration provides actions to do membership dynamic reconfiguration.

memberUpdateStrategy
MemberUpdateStrategy
(Optional)

MemberUpdateStrategy, Members(Pods) update strategy.

  • serial: update Members one by one that guarantee minimum component unavailable time.Learner -> Follower(with AccessMode=none) -> Follower(with AccessMode=readonly) -> Follower(with AccessMode=readWrite) -> Leader
  • bestEffortParallel: update Members in parallel that guarantee minimum component un-writable time.Learner, Follower(minority) in parallel -> Follower(majority) -> Leader, keep majority online all the time.
  • parallel: force parallel
paused
bool
(Optional)

Paused indicates that the rsm is paused, means the reconciliation of this rsm object will be paused.

credential
Credential
(Optional)

Credential used to connect to DB engine

rsmTransformPolicy
RsmTransformPolicy
(Optional)

RsmTransformPolicy defines the policy generate sts using rsm. Passed from cluster. ToSts: rsm transform to statefulSet ToPod: rsm transform to pod

nodeAssignment
[]NodeAssignment
(Optional)

NodeAssignment defines the expected assignment of nodes.

status
ReplicatedStateMachineStatus

AccessMode (string alias)

(Appears on:ReplicaRole)

AccessMode defines SVC access mode enums.

ValueDescription

"None"

"ReadWrite"

"Readonly"

Action

(Appears on:MembershipReconfiguration, RoleProbe)

FieldDescription
image
string
(Optional)

utility image contains command that can be used to retrieve of process role info

command
[]string

Command will be executed in Container to retrieve or process role info

Credential

(Appears on:ReplicatedStateMachineSpec)

FieldDescription
username
CredentialVar

Username variable name will be KB_RSM_USERNAME

password
CredentialVar

Password variable name will be KB_RSM_PASSWORD

CredentialVar

(Appears on:Credential)

FieldDescription
value
string
(Optional)

Variable references $(VAR_NAME) are expanded using the 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 be unchanged. Double $$ are reduced to a single $, which allows for escaping the $(VAR_NAME) syntax: i.e. “$$(VAR_NAME)” will produce the string literal “$(VAR_NAME)”. Escaped references will never be expanded, regardless of whether the variable exists or not. Defaults to “”.

valueFrom
Kubernetes core/v1.EnvVarSource
(Optional)

Source for the environment variable’s value. Cannot be used if value is not empty.

MemberStatus

(Appears on:ClusterComponentStatus, ReplicatedStateMachineStatus)

FieldDescription
podName
string

PodName pod name.

role
ReplicaRole
readyWithoutPrimary
bool
(Optional)

Is it required for rsm to have at least one primary pod to be ready.

MemberUpdateStrategy (string alias)

(Appears on:RSMSpec, ReplicatedStateMachineSpec)

MemberUpdateStrategy defines Cluster Component update strategy.

ValueDescription

"BestEffortParallel"

"Parallel"

"Serial"

MembershipReconfiguration

(Appears on:RSMSpec, ReplicatedStateMachineSpec)

FieldDescription
switchoverAction
Action
(Optional)

Environment variables can be used in all following Actions:

  • KB_RSM_USERNAME username part of credential
  • KB_RSM_PASSWORD password part of credential
  • KB_RSM_LEADER_HOST leader host
  • KB_RSM_TARGET_HOST target host
  • KB_RSM_SERVICE_PORT port

SwitchoverAction specifies how to do switchover latest BusyBox image will be used if Image not configured

memberJoinAction
Action
(Optional)

MemberJoinAction specifies how to add member previous none-nil action’s Image will be used if not configured

memberLeaveAction
Action
(Optional)

MemberLeaveAction specifies how to remove member previous none-nil action’s Image will be used if not configured

logSyncAction
Action
(Optional)

LogSyncAction specifies how to trigger the new member to start log syncing previous none-nil action’s Image will be used if not configured

promoteAction
Action
(Optional)

PromoteAction specifies how to tell the cluster that the new member can join voting now previous none-nil action’s Image will be used if not configured

NodeAssignment

(Appears on:ReplicatedStateMachineSpec)

FieldDescription
name
string
(Optional)

Name defines the name of statefulSet that needs to allocate node.

nodeSpec
NodeSpec
(Optional)

NodeSpec defines the detailed node info that will assign to the statefulSet.

NodeSpec

(Appears on:NodeAssignment)

FieldDescription
nodeName
k8s.io/apimachinery/pkg/types.NodeName
(Optional)

ReplicaRole

(Appears on:RSMSpec, MemberStatus, ReplicatedStateMachineSpec)

FieldDescription
name
string

Name, role name.

accessMode
AccessMode

AccessMode, what service this member capable.

canVote
bool
(Optional)

CanVote, whether this member has voting rights

isLeader
bool
(Optional)

IsLeader, whether this member is the leader

ReplicatedStateMachineSpec

(Appears on:ReplicatedStateMachine)

ReplicatedStateMachineSpec defines the desired state of ReplicatedStateMachine

FieldDescription
replicas
int32
(Optional)

replicas is the desired number of replicas of the given Template. These are replicas in the sense that they are instantiations of the same Template, but individual replicas also have a consistent identity. If unspecified, defaults to 1.

selector
Kubernetes meta/v1.LabelSelector

selector is a label query over pods that should match the replica count. It must match the pod template’s labels. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors

serviceName
string

serviceName is the name of the service that governs this StatefulSet. This service must exist before the StatefulSet, and is responsible for the network identity of the set. Pods get DNS/hostnames that follow the pattern: pod-specific-string.serviceName.default.svc.cluster.local where “pod-specific-string” is managed by the StatefulSet controller.

service
Kubernetes core/v1.Service
(Optional)

service defines the behavior of a service spec. provides read-write servicehttps://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status

alternativeServices
[]Kubernetes core/v1.Service
(Optional)

AlternativeServices defines Alternative Services selector pattern specifier. can be used for creating Readonly service.

template
Kubernetes core/v1.PodTemplateSpec
volumeClaimTemplates
[]Kubernetes core/v1.PersistentVolumeClaim
(Optional)

volumeClaimTemplates is a list of claims that pods are allowed to reference. The ReplicatedStateMachine controller is responsible for mapping network identities to claims in a way that maintains the identity of a pod. Every claim in this list must have at least one matching (by name) volumeMount in one container in the template. A claim in this list takes precedence over any volumes in the template, with the same name.

podManagementPolicy
Kubernetes apps/v1.PodManagementPolicyType
(Optional)

podManagementPolicy controls how pods are created during initial scale up, when replacing pods on nodes, or when scaling down.

  • The default policy is OrderedReady, where pods are created in increasing order (pod-0, then pod-1, etc) and the controller will wait until each pod is ready before continuing. When scaling down, the pods are removed in the opposite order.
  • The alternative policy is Parallel which will create pods in parallel to match the desired scale without waiting, and on scale down will delete all pods at once.
updateStrategy
Kubernetes apps/v1.StatefulSetUpdateStrategy

updateStrategy indicates the StatefulSetUpdateStrategy that will be employed to update Pods in the RSM when a revision is made to Template. UpdateStrategy.Type will be set to appsv1.OnDeleteStatefulSetStrategyType if MemberUpdateStrategy is not nil

roles
[]ReplicaRole
(Optional)

Roles, a list of roles defined in the system.

roleProbe
RoleProbe
(Optional)

RoleProbe provides method to probe role.

membershipReconfiguration
MembershipReconfiguration
(Optional)

MembershipReconfiguration provides actions to do membership dynamic reconfiguration.

memberUpdateStrategy
MemberUpdateStrategy
(Optional)

MemberUpdateStrategy, Members(Pods) update strategy.

  • serial: update Members one by one that guarantee minimum component unavailable time.Learner -> Follower(with AccessMode=none) -> Follower(with AccessMode=readonly) -> Follower(with AccessMode=readWrite) -> Leader
  • bestEffortParallel: update Members in parallel that guarantee minimum component un-writable time.Learner, Follower(minority) in parallel -> Follower(majority) -> Leader, keep majority online all the time.
  • parallel: force parallel
paused
bool
(Optional)

Paused indicates that the rsm is paused, means the reconciliation of this rsm object will be paused.

credential
Credential
(Optional)

Credential used to connect to DB engine

rsmTransformPolicy
RsmTransformPolicy
(Optional)

RsmTransformPolicy defines the policy generate sts using rsm. Passed from cluster. ToSts: rsm transform to statefulSet ToPod: rsm transform to pod

nodeAssignment
[]NodeAssignment
(Optional)

NodeAssignment defines the expected assignment of nodes.

ReplicatedStateMachineStatus

(Appears on:ReplicatedStateMachine)

ReplicatedStateMachineStatus defines the observed state of ReplicatedStateMachine

FieldDescription
StatefulSetStatus
Kubernetes apps/v1.StatefulSetStatus

(Members of StatefulSetStatus are embedded into this type.)

initReplicas
int32

InitReplicas is the number of pods(members) when cluster first initialized it’s set to spec.Replicas at object creation time and never changes

readyInitReplicas
int32
(Optional)

ReadyInitReplicas is the number of pods(members) already in MembersStatus in the cluster initialization stage will never change once equals to InitReplicas

currentGeneration
int64
(Optional)

CurrentGeneration, if not empty, indicates the version of the RSM used to generate the underlying workload

membersStatus
[]MemberStatus
(Optional)

members’ status.

RoleProbe

(Appears on:RSMSpec, ReplicatedStateMachineSpec)

RoleProbe defines how to observe role

FieldDescription
builtinHandlerName
string
(Optional)

BuiltinHandler specifies the builtin handler name to use to probe the role of the main container. current available handlers: mysql, postgres, mongodb, redis, etcd, kafka. use CustomHandler to define your own role probe function if none of them satisfies the requirement.

customHandler
[]Action
(Optional)

CustomHandler defines the custom way to do role probe. if the BuiltinHandler satisfies the requirement, use it instead.

how the actions defined here works:

Actions will be taken in serial. after all actions done, the final output should be a single string of the role name defined in spec.Roles latest BusyBox image will be used if Image not configured Environment variables can be used in Command:

  • v_KB_RSM_LASTSTDOUT stdout from last action, watch ‘v’ prefixed
  • KB_RSM_USERNAME username part of credential
  • KB_RSM_PASSWORD password part of credential
initialDelaySeconds
int32
(Optional)

Number of seconds after the container has started before role probe has started.

timeoutSeconds
int32
(Optional)

Number of seconds after which the probe times out. Defaults to 1 second. Minimum value is 1.

periodSeconds
int32
(Optional)

How often (in seconds) to perform the probe. Default to 2 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.

roleUpdateMechanism
RoleUpdateMechanism
(Optional)

RoleUpdateMechanism specifies the way how pod role label being updated.

RoleUpdateMechanism (string alias)

(Appears on:RoleProbe)

RoleUpdateMechanism defines the way how pod role label being updated.

ValueDescription

"DirectAPIServerEventUpdate"

"ReadinessProbeEventUpdate"

RsmTransformPolicy (string alias)

(Appears on:ClusterComponentSpec, ComponentSpec, ReplicatedStateMachineSpec)

RsmTransformPolicy defines rsm transform type ToSts and ToPod is supported

ValueDescription

"ToPod"

"ToSts"


Generated with gen-crd-api-reference-docs