KubeBlocks
BlogsKubeBlocks Cloud

Getting Started

Introduction
Supported addons
Installation

Concepts and Features

Concepts

Backup and Restore

Introduction

Backup

Configure BackupRepo
Configure BackupPolicy
Scheduled backup
On-demand backup

Restore

Restore from backup set
Point-in-Time Recovery

In Place Update

Introduction
Enable in-place update

Instance Template

Introduction
Apply instance template

Trouble Shooting

FAQs

References

API Reference

Cluster
Operations
Parameters
Dataprotection
Add-On
Terminology
Install Addons
Install kbcli
Create a test Kubernetes cluster
Kubernetes and Operator 101

Upgrade KubeBlocks

Upgrade to v0.8
Upgrade to v0.9.0
Upgrade to v0.9.x

Release Notes

v1.0.0-cn
v1.0.0
v0.9.3
v0.9.2
v0.9.1
v0.9.0

    Packages:

    • parameters.kubeblocks.io/v1alpha1

    parameters.kubeblocks.io/v1alpha1

    Resource Types:

    • ComponentParameter
    • ParamConfigRenderer
    • Parameter
    • ParametersDefinition

    ComponentParameter

    ComponentParameter is the Schema for the componentparameters API

    FieldDescription

    apiVersion
    string

    parameters.kubeblocks.io/v1alpha1

    kind
    string

    ComponentParameter

    metadata

    Kubernetes meta/v1.ObjectMeta

    Refer to the Kubernetes API documentation for the fields of the metadata field.

    spec

    ComponentParameterSpec



    clusterName

    string

    (Optional)

    Specifies the name of the Cluster that this configuration is associated with.

    componentName

    string

    Represents the name of the Component that this configuration pertains to.

    configItemDetails

    []ConfigTemplateItemDetail

    (Optional)

    ConfigItemDetails is an array of ConfigTemplateItemDetail objects.

    Each ConfigTemplateItemDetail corresponds to a configuration template, which is a ConfigMap that contains multiple configuration files. Each configuration file is stored as a key-value pair within the ConfigMap.

    The ConfigTemplateItemDetail includes information such as:

    • The configuration template (a ConfigMap)

    • The corresponding ConfigConstraint (constraints and validation rules for the configuration)

    • Volume mounts (for mounting the configuration files)

    status

    ComponentParameterStatus

    ParamConfigRenderer

    ParamConfigRenderer is the Schema for the paramconfigrenderers API

    FieldDescription

    apiVersion
    string

    parameters.kubeblocks.io/v1alpha1

    kind
    string

    ParamConfigRenderer

    metadata

    Kubernetes meta/v1.ObjectMeta

    Refer to the Kubernetes API documentation for the fields of the metadata field.

    spec

    ParamConfigRendererSpec



    componentDef

    string

    Specifies the ComponentDefinition custom resource (CR) that defines the Component’s characteristics and behavior.

    serviceVersion

    string

    (Optional)

    ServiceVersion specifies the version of the Service expected to be provisioned by this Component. The version should follow the syntax and semantics of the “Semantic Versioning” specification (http://semver.org/). If no version is specified, the latest available version will be used.

    parametersDefs

    []string

    (Optional)

    Specifies the ParametersDefinition custom resource (CR) that defines the Component parameter’s schema and behavior.

    configs

    []ComponentConfigDescription

    (Optional)

    Specifies the configuration files.

    status

    ParamConfigRendererStatus

    Parameter

    Parameter is the Schema for the parameters API

    FieldDescription

    apiVersion
    string

    parameters.kubeblocks.io/v1alpha1

    kind
    string

    Parameter

    metadata

    Kubernetes meta/v1.ObjectMeta

    Refer to the Kubernetes API documentation for the fields of the metadata field.

    spec

    ParameterSpec



    clusterName

    string

    Specifies the name of the Cluster resource that this operation is targeting.

    componentParameters

    []ComponentParametersSpec

    Lists ComponentParametersSpec objects, each specifying a Component and its parameters and template updates.

    status

    ParameterStatus

    ParametersDefinition

    ParametersDefinition is the Schema for the parametersdefinitions API

    FieldDescription

    apiVersion
    string

    parameters.kubeblocks.io/v1alpha1

    kind
    string

    ParametersDefinition

    metadata

    Kubernetes meta/v1.ObjectMeta

    Refer to the Kubernetes API documentation for the fields of the metadata field.

    spec

    ParametersDefinitionSpec



    fileName

    string

    (Optional)

    Specifies the config file name in the config template.

    parametersSchema

    ParametersSchema

    (Optional)

    Defines a list of parameters including their names, default values, descriptions, types, and constraints (permissible values or the range of valid values).

    reloadAction

    ReloadAction

    (Optional)

    Specifies the dynamic reload (dynamic reconfiguration) actions supported by the engine. When set, the controller executes the scripts defined in these actions to handle dynamic parameter updates.

    Dynamic reloading is triggered only if both of the following conditions are met:

    1. The modified parameters are listed in the dynamicParameters field. If dynamicParameterSelectedPolicy is set to “all”, modifications to staticParameters can also trigger a reload.

    2. reloadAction is set.

    If reloadAction is not set or the modified parameters are not listed in dynamicParameters, dynamic reloading will not be triggered.

    Example:

    dynamicReloadAction: tplScriptTrigger: namespace: kb-system scriptConfigMapRef: mysql-reload-script sync: true

    downwardAPIChangeTriggeredActions

    []DownwardAPIChangeTriggeredAction

    (Optional)

    Specifies a list of actions to execute specified commands based on Pod labels.

    It utilizes the K8s Downward API to mount label information as a volume into the pod. The ‘config-manager’ sidecar container watches for changes in the role label and dynamically invoke registered commands (usually execute some SQL statements) when a change is detected.

    It is designed for scenarios where:

    • Replicas with different roles have different configurations, such as Redis primary & secondary replicas.

    • After a role switch (e.g., from secondary to primary), some changes in configuration are needed to reflect the new role.

    deletedPolicy

    ParameterDeletedPolicy

    (Optional)

    Specifies the policy when parameter be removed.

    mergeReloadAndRestart

    bool

    (Optional)

    Indicates whether to consolidate dynamic reload and restart actions into a single restart.

    • If true, updates requiring both actions will result in only a restart, merging the actions.

    • If false, updates will trigger both actions executed sequentially: first dynamic reload, then restart.

    This flag allows for more efficient handling of configuration changes by potentially eliminating an unnecessary reload step.

    reloadStaticParamsBeforeRestart

    bool

    (Optional)

    Configures whether the dynamic reload specified in reloadAction applies only to dynamic parameters or to all parameters (including static parameters).

    • false (default): Only modifications to the dynamic parameters listed in dynamicParameters will trigger a dynamic reload.

    • true: Modifications to both dynamic parameters listed in dynamicParameters and static parameters listed in staticParameters will trigger a dynamic reload. The “all” option is for certain engines that require static parameters to be set via SQL statements before they can take effect on restart.

    staticParameters

    []string

    (Optional)

    List static parameters. Modifications to any of these parameters require a restart of the process to take effect.

    dynamicParameters

    []string

    (Optional)

    List dynamic parameters. Modifications to these parameters trigger a configuration reload without requiring a process restart.

    immutableParameters

    []string

    (Optional)

    Lists the parameters that cannot be modified once set. Attempting to change any of these parameters will be ignored.

    status

    ParametersDefinitionStatus

    AutoTrigger

    (Appears on:ReloadAction)

    AutoTrigger automatically perform the reload when specified conditions are met.

    FieldDescription

    processName

    string

    (Optional)

    The name of the process.

    CfgFileFormat (string alias)

    (Appears on:FileFormatConfig)

    CfgFileFormat defines formatter of configuration files.

    ValueDescription

    "dotenv"

    "hcl"

    "ini"

    "json"

    "properties"

    "props-plus"

    "redis"

    "toml"

    "xml"

    "yaml"

    ComponentConfigDescription

    (Appears on:ParamConfigRendererSpec)

    FieldDescription

    name

    string

    Specifies the config file name in the config template.

    templateName

    string

    (Optional)

    Specifies the name of the referenced componentTemplateSpec.

    fileFormatConfig

    FileFormatConfig

    (Optional)

    Specifies the format of the configuration file and any associated parameters that are specific to the chosen format. Supported formats include ini, xml, yaml, json, hcl, dotenv, properties, and toml.

    Each format may have its own set of parameters that can be configured. For instance, when using the ini format, you can specify the section name.

    Example:

    fileFormatConfig: format: ini iniConfig: sectionName: mysqld

    reRenderResourceTypes

    []RerenderResourceType

    (Optional)

    Specifies whether the configuration needs to be re-rendered after v-scale or h-scale operations to reflect changes.

    In some scenarios, the configuration may need to be updated to reflect the changes in resource allocation or cluster topology. Examples:

    • Redis: adjust maxmemory after v-scale operation.

    • MySQL: increase max connections after v-scale operation.

    • Zookeeper: update zoo.cfg with new node addresses after h-scale operation.

    ComponentParameterSpec

    (Appears on:ComponentParameter)

    ComponentParameterSpec defines the desired state of ComponentConfiguration

    FieldDescription

    clusterName

    string

    (Optional)

    Specifies the name of the Cluster that this configuration is associated with.

    componentName

    string

    Represents the name of the Component that this configuration pertains to.

    configItemDetails

    []ConfigTemplateItemDetail

    (Optional)

    ConfigItemDetails is an array of ConfigTemplateItemDetail objects.

    Each ConfigTemplateItemDetail corresponds to a configuration template, which is a ConfigMap that contains multiple configuration files. Each configuration file is stored as a key-value pair within the ConfigMap.

    The ConfigTemplateItemDetail includes information such as:

    • The configuration template (a ConfigMap)

    • The corresponding ConfigConstraint (constraints and validation rules for the configuration)

    • Volume mounts (for mounting the configuration files)

    ComponentParameterStatus

    (Appears on:ComponentParameter)

    ComponentParameterStatus defines the observed state of ComponentConfiguration

    FieldDescription

    message

    string

    (Optional)

    Provides a description of any abnormal status.

    phase

    ParameterPhase

    (Optional)

    Indicates the current status of the configuration item.

    Possible values include “Creating”, “Init”, “Running”, “Pending”, “Merged”, “MergeFailed”, “FailedAndPause”, “Upgrading”, “Deleting”, “FailedAndRetry”, “Finished”.

    observedGeneration

    int64

    (Optional)

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

    conditions

    []Kubernetes meta/v1.Condition

    (Optional)

    Provides detailed status information for opsRequest.

    configurationStatus

    []ConfigTemplateItemDetailStatus

    Provides the status of each component undergoing reconfiguration.

    ComponentParameters (map[string]*string alias)

    (Appears on:ComponentParametersSpec)

    ComponentParametersSpec

    (Appears on:ParameterSpec)

    FieldDescription

    componentName

    string

    Specifies the name of the Component.

    parameters

    ComponentParameters

    (Optional)

    Specifies the user-defined configuration template or parameters.

    userConfigTemplates

    map[string]github.com/apecloud/kubeblocks/apis/parameters/v1alpha1.ConfigTemplateExtension

    (Optional)

    Specifies the user-defined configuration template.

    When provided, the importTemplateRef overrides the default configuration template specified in configSpec.templateRef. This allows users to customize the configuration template according to their specific requirements.

    ComponentReconfiguringStatus

    (Appears on:ParameterStatus)

    FieldDescription

    componentName

    string

    Specifies the name of the Component.

    phase

    ParameterPhase

    (Optional)

    Indicates the current status of the configuration item.

    Possible values include “Creating”, “Init”, “Running”, “Pending”, “Merged”, “MergeFailed”, “FailedAndPause”, “Upgrading”, “Deleting”, “FailedAndRetry”, “Finished”.

    parameterStatus

    []ReconfiguringStatus

    Describes the status of the component reconfiguring.

    ConfigTemplateExtension

    (Appears on:ComponentParametersSpec, ConfigTemplateItemDetail, ReconfiguringStatus)

    FieldDescription

    templateRef

    string

    Specifies the name of the referenced configuration template ConfigMap object.

    namespace

    string

    (Optional)

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

    policy

    MergedPolicy

    (Optional)

    Defines the strategy for merging externally imported templates into component templates.

    ConfigTemplateItemDetail

    (Appears on:ComponentParameterSpec)

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

    FieldDescription

    name

    string

    Defines the unique identifier of the configuration template.

    It must be a string of maximum 63 characters, and can only include lowercase alphanumeric characters, hyphens, and periods. The name must start and end with an alphanumeric character.

    payload

    Payload

    (Optional)

    External controllers can trigger a configuration rerender by modifying this field.

    Note: Currently, the payload field is opaque and its content is not interpreted by the system. Modifying this field will cause a rerender, regardless of the specific content of this field.

    configSpec

    github.com/apecloud/kubeblocks/apis/apps/v1.ComponentFileTemplate

    (Optional)

    Specifies the name of the configuration template (a ConfigMap), ConfigConstraint, and other miscellaneous options.

    The configuration template is a ConfigMap that contains multiple configuration files. Each configuration file is stored as a key-value pair within the ConfigMap.

    ConfigConstraint allows defining constraints and validation rules for configuration parameters. It ensures that the configuration adheres to certain requirements and limitations.

    userConfigTemplates

    ConfigTemplateExtension

    (Optional)

    Specifies the user-defined configuration template.

    When provided, the importTemplateRef overrides the default configuration template specified in configSpec.templateRef. This allows users to customize the configuration template according to their specific requirements.

    configFileParams

    map[string]github.com/apecloud/kubeblocks/apis/parameters/v1alpha1.ParametersInFile

    (Optional)

    Specifies the user-defined configuration parameters.

    When provided, the parameter values in configFileParams override the default configuration parameters. This allows users to override the default configuration according to their specific needs.

    ConfigTemplateItemDetailStatus

    (Appears on:ComponentParameterStatus, ReconfiguringStatus)

    FieldDescription

    name

    string

    Specifies the name of the configuration template. It is a required field and must be a string of maximum 63 characters. The name should only contain lowercase alphanumeric characters, hyphens, or periods. It should start and end with an alphanumeric character.

    phase

    ParameterPhase

    (Optional)

    Indicates the current status of the configuration item.

    Possible values include “Creating”, “Init”, “Running”, “Pending”, “Merged”, “MergeFailed”, “FailedAndPause”, “Upgrading”, “Deleting”, “FailedAndRetry”, “Finished”.

    lastDoneRevision

    string

    (Optional)

    Represents the last completed revision of the configuration item. This field is optional.

    updateRevision

    string

    (Optional)

    Represents the updated revision of the configuration item. This field is optional.

    message

    string

    (Optional)

    Provides a description of any abnormal status. This field is optional.

    reconcileDetail

    ReconcileDetail

    (Optional)

    Provides detailed information about the execution of the configuration change. This field is optional.

    DownwardAPIChangeTriggeredAction

    (Appears on:ParametersDefinitionSpec)

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

    FieldDescription

    name

    string

    Specifies the name of the field. It must be a string of maximum length 63. The name should match the regex pattern ^[a-z0-9]([a-z0-9\.\-]*[a-z0-9])?$.

    mountPoint

    string

    Specifies the mount point of the Downward API volume.

    items

    []Kubernetes core/v1.DownwardAPIVolumeFile

    Represents a list of files under the Downward API volume.

    command

    []string

    (Optional)

    Specifies the command to be triggered when changes are detected in Downward API volume files. It relies on the inotify mechanism in the config-manager sidecar to monitor file changes.

    scriptConfig

    ScriptConfig

    (Optional)

    ScriptConfig object specifies a ConfigMap that contains script files that should be mounted inside the pod. The scripts are mounted as volumes and can be referenced and executed by the DownwardAction to perform specific tasks or configurations.

    DynamicParameterSelectedPolicy (string alias)

    DynamicParameterSelectedPolicy determines how to select the parameters of dynamic reload actions

    ValueDescription

    "all"

    "dynamic"

    DynamicReloadType (string alias)

    DynamicReloadType defines reload method.

    ValueDescription

    "auto"

    "http"

    "sql"

    "exec"

    "tpl"

    "signal"

    FileFormatConfig

    (Appears on:ComponentConfigDescription)

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

    FieldDescription

    FormatterAction

    FormatterAction

    (Members of FormatterAction are embedded into this type.)

    (Optional)

    Each format may have its own set of parameters that can be configured. For instance, when using the ini format, you can specify the section name.

    format

    CfgFileFormat

    The config file format. Valid values are ini, xml, yaml, json, hcl, dotenv, properties and toml. Each format has its own characteristics and use cases.

    • ini: is a text-based content with a structure and syntax comprising key–value pairs for properties, reference wiki: https://en.wikipedia.org/wiki/INI_file

    • xml: refers to wiki: https://en.wikipedia.org/wiki/XML

    • yaml: supports for complex data types and structures.

    • json: refers to wiki: https://en.wikipedia.org/wiki/JSON

    • hcl: The HashiCorp Configuration Language (HCL) is a configuration language authored by HashiCorp, reference url: https://www.linode.com/docs/guides/introduction-to-hcl/

    • dotenv: is a plain text file with simple key–value pairs, reference wiki: https://en.wikipedia.org/wiki/Configuration_file#MS-DOS

    • properties: a file extension mainly used in Java, reference wiki: https://en.wikipedia.org/wiki/.properties

    • toml: refers to wiki: https://en.wikipedia.org/wiki/TOML

    • props-plus: a file extension mainly used in Java, supports CamelCase(e.g: brokerMaxConnectionsPerIp)

    FormatterAction

    (Appears on:FileFormatConfig)

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

    FieldDescription

    iniConfig

    IniConfig

    (Optional)

    Holds options specific to the ‘ini’ file format.

    IniConfig

    (Appears on:FormatterAction)

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

    FieldDescription

    sectionName

    string

    (Optional)

    A string that describes the name of the ini section.

    MergedPolicy (string alias)

    (Appears on:ConfigTemplateExtension)

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

    ValueDescription

    "none"

    "add"

    "patch"

    "replace"

    ParamConfigRendererSpec

    (Appears on:ParamConfigRenderer)

    ParamConfigRendererSpec defines the desired state of ParamConfigRenderer

    FieldDescription

    componentDef

    string

    Specifies the ComponentDefinition custom resource (CR) that defines the Component’s characteristics and behavior.

    serviceVersion

    string

    (Optional)

    ServiceVersion specifies the version of the Service expected to be provisioned by this Component. The version should follow the syntax and semantics of the “Semantic Versioning” specification (http://semver.org/). If no version is specified, the latest available version will be used.

    parametersDefs

    []string

    (Optional)

    Specifies the ParametersDefinition custom resource (CR) that defines the Component parameter’s schema and behavior.

    configs

    []ComponentConfigDescription

    (Optional)

    Specifies the configuration files.

    ParamConfigRendererStatus

    (Appears on:ParamConfigRenderer)

    ParamConfigRendererStatus defines the observed state of ParamConfigRenderer

    FieldDescription

    observedGeneration

    int64

    (Optional)

    The most recent generation number of the ParamsDesc object that has been observed by the controller.

    message

    string

    (Optional)

    Provides additional information about the current phase.

    phase

    ParametersDescPhase

    (Optional)

    Specifies the status of the configuration template. When set to PDAvailablePhase, the ParamsDesc can be referenced by ComponentDefinition.

    ParameterDeletedMethod (string alias)

    (Appears on:ParameterDeletedPolicy)

    ParameterDeletedMethod defines how to handle parameter remove

    ValueDescription

    "RestoreToDefault"

    "Reset"

    ParameterDeletedPolicy

    (Appears on:ParametersDefinitionSpec)

    FieldDescription

    deletedMethod

    ParameterDeletedMethod

    Specifies the method to handle the deletion of a parameter. If set to “RestoreToDefault”, the parameter will be restored to its default value, which requires engine support, such as pg. If set to “Reset”, the parameter will be re-rendered through the configuration template.

    defaultValue

    string

    (Optional)

    Specifies the value to use if DeletedMethod is RestoreToDefault. Example: pg SET configuration_parameter TO DEFAULT;

    ParameterPhase (string alias)

    (Appears on:ComponentParameterStatus, ComponentReconfiguringStatus, ConfigTemplateItemDetailStatus, ParameterStatus)

    ParameterPhase defines the Configuration FSM phase

    ValueDescription

    "Creating"

    "Deleting"

    "FailedAndPause"

    "FailedAndRetry"

    "Finished"

    "Init"

    "MergeFailed"

    "Merged"

    "Pending"

    "Running"

    "Upgrading"

    ParameterSpec

    (Appears on:Parameter)

    ParameterSpec defines the desired state of Parameter

    FieldDescription

    clusterName

    string

    Specifies the name of the Cluster resource that this operation is targeting.

    componentParameters

    []ComponentParametersSpec

    Lists ComponentParametersSpec objects, each specifying a Component and its parameters and template updates.

    ParameterStatus

    (Appears on:Parameter)

    ParameterStatus defines the observed state of Parameter

    FieldDescription

    message

    string

    (Optional)

    Provides a description of any abnormal status.

    phase

    ParameterPhase

    (Optional)

    Indicates the current status of the configuration item.

    Possible values include “Creating”, “Init”, “Running”, “Pending”, “Merged”, “MergeFailed”, “FailedAndPause”, “Upgrading”, “Deleting”, “FailedAndRetry”, “Finished”.

    observedGeneration

    int64

    (Optional)

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

    componentReconfiguringStatus

    []ComponentReconfiguringStatus

    (Optional)

    Records the status of a reconfiguring operation if opsRequest.spec.type equals to “Reconfiguring”.

    ParametersDefinitionSpec

    (Appears on:ParametersDefinition)

    ParametersDefinitionSpec defines the desired state of ParametersDefinition

    FieldDescription

    fileName

    string

    (Optional)

    Specifies the config file name in the config template.

    parametersSchema

    ParametersSchema

    (Optional)

    Defines a list of parameters including their names, default values, descriptions, types, and constraints (permissible values or the range of valid values).

    reloadAction

    ReloadAction

    (Optional)

    Specifies the dynamic reload (dynamic reconfiguration) actions supported by the engine. When set, the controller executes the scripts defined in these actions to handle dynamic parameter updates.

    Dynamic reloading is triggered only if both of the following conditions are met:

    1. The modified parameters are listed in the dynamicParameters field. If dynamicParameterSelectedPolicy is set to “all”, modifications to staticParameters can also trigger a reload.

    2. reloadAction is set.

    If reloadAction is not set or the modified parameters are not listed in dynamicParameters, dynamic reloading will not be triggered.

    Example:

    dynamicReloadAction: tplScriptTrigger: namespace: kb-system scriptConfigMapRef: mysql-reload-script sync: true

    downwardAPIChangeTriggeredActions

    []DownwardAPIChangeTriggeredAction

    (Optional)

    Specifies a list of actions to execute specified commands based on Pod labels.

    It utilizes the K8s Downward API to mount label information as a volume into the pod. The ‘config-manager’ sidecar container watches for changes in the role label and dynamically invoke registered commands (usually execute some SQL statements) when a change is detected.

    It is designed for scenarios where:

    • Replicas with different roles have different configurations, such as Redis primary & secondary replicas.

    • After a role switch (e.g., from secondary to primary), some changes in configuration are needed to reflect the new role.

    deletedPolicy

    ParameterDeletedPolicy

    (Optional)

    Specifies the policy when parameter be removed.

    mergeReloadAndRestart

    bool

    (Optional)

    Indicates whether to consolidate dynamic reload and restart actions into a single restart.

    • If true, updates requiring both actions will result in only a restart, merging the actions.

    • If false, updates will trigger both actions executed sequentially: first dynamic reload, then restart.

    This flag allows for more efficient handling of configuration changes by potentially eliminating an unnecessary reload step.

    reloadStaticParamsBeforeRestart

    bool

    (Optional)

    Configures whether the dynamic reload specified in reloadAction applies only to dynamic parameters or to all parameters (including static parameters).

    • false (default): Only modifications to the dynamic parameters listed in dynamicParameters will trigger a dynamic reload.

    • true: Modifications to both dynamic parameters listed in dynamicParameters and static parameters listed in staticParameters will trigger a dynamic reload. The “all” option is for certain engines that require static parameters to be set via SQL statements before they can take effect on restart.

    staticParameters

    []string

    (Optional)

    List static parameters. Modifications to any of these parameters require a restart of the process to take effect.

    dynamicParameters

    []string

    (Optional)

    List dynamic parameters. Modifications to these parameters trigger a configuration reload without requiring a process restart.

    immutableParameters

    []string

    (Optional)

    Lists the parameters that cannot be modified once set. Attempting to change any of these parameters will be ignored.

    ParametersDefinitionStatus

    (Appears on:ParametersDefinition)

    ParametersDefinitionStatus defines the observed state of ParametersDefinition

    FieldDescription

    observedGeneration

    int64

    (Optional)

    The most recent generation number of the ParamsDesc object that has been observed by the controller.

    phase

    ParametersDescPhase

    (Optional)

    Specifies the status of the configuration template. When set to PDAvailablePhase, the ParamsDesc can be referenced by ComponentDefinition.

    conditions

    []Kubernetes meta/v1.Condition

    (Optional)

    Represents a list of detailed status of the ParametersDescription object.

    This field is crucial for administrators and developers to monitor and respond to changes within the ParametersDescription. It provides a history of state transitions and a snapshot of the current state that can be used for automated logic or direct inspection.

    ParametersDescPhase (string alias)

    (Appears on:ParamConfigRendererStatus, ParametersDefinitionStatus)

    ParametersDescPhase defines the ParametersDescription CR .status.phase

    ValueDescription

    "Available"

    "Deleting"

    "Unavailable"

    ParametersInFile

    (Appears on:ConfigTemplateItemDetail, ReconfiguringStatus)

    FieldDescription

    content

    string

    (Optional)

    Holds the configuration keys and values. This field is a workaround for issues found in kubebuilder and code-generator. Refer to https://github.com/kubernetes-sigs/kubebuilder/issues/528 and https://github.com/kubernetes/code-generator/issues/50 for more details.

    Represents the content of the configuration file.

    parameters

    map[string]*string

    (Optional)

    Represents the updated parameters for a single configuration file.

    ParametersSchema

    (Appears on:ParametersDefinitionSpec)

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

    FieldDescription

    topLevelKey

    string

    (Optional)

    Specifies the top-level key in the ‘configSchema.cue’ that organizes the validation rules for parameters. This key must exist within the CUE script defined in ‘configSchema.cue’.

    cue

    string

    (Optional)

    Hold a string that contains a script written in CUE language that defines a list of configuration items. Each item is detailed with its name, default value, description, type (e.g. string, integer, float), and constraints (permissible values or the valid range of values).

    CUE (Configure, Unify, Execute) is a declarative language designed for defining and validating complex data configurations. It is particularly useful in environments like K8s where complex configurations and validation rules are common.

    This script functions as a validator for user-provided configurations, ensuring compliance with the established specifications and constraints.

    schemaInJSON

    Kubernetes api extensions v1.JSONSchemaProps

    Generated from the ‘cue’ field and transformed into a JSON format.

    Payload (map[string]encoding/json.RawMessage alias)

    (Appears on:ConfigTemplateItemDetail)

    Payload holds the payload data. This field is optional and can contain any type of data. Not included in the JSON representation of the object.

    ReconcileDetail

    (Appears on:ConfigTemplateItemDetailStatus)

    FieldDescription

    policy

    string

    (Optional)

    Represents the policy applied during the most recent execution.

    execResult

    string

    (Optional)

    Represents the outcome of the most recent execution.

    currentRevision

    string

    (Optional)

    Represents the current revision of the configuration item.

    succeedCount

    int32

    (Optional)

    Represents the number of pods where configuration changes were successfully applied.

    expectedCount

    int32

    (Optional)

    Represents the total number of pods that require execution of configuration changes.

    errMessage

    string

    (Optional)

    Represents the error message generated when the execution of configuration changes fails.

    ReconfiguringStatus

    (Appears on:ComponentReconfiguringStatus)

    FieldDescription

    ConfigTemplateItemDetailStatus

    ConfigTemplateItemDetailStatus

    (Members of ConfigTemplateItemDetailStatus are embedded into this type.)

    updatedParameters

    map[string]github.com/apecloud/kubeblocks/apis/parameters/v1alpha1.ParametersInFile

    (Optional)

    Contains the updated parameters.

    userConfigTemplates

    ConfigTemplateExtension

    (Optional)

    Specifies the user-defined configuration template.

    When provided, the importTemplateRef overrides the default configuration template specified in configSpec.templateRef. This allows users to customize the configuration template according to their specific requirements.

    ReloadAction

    (Appears on:ParametersDefinitionSpec)

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

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

    FieldDescription

    unixSignalTrigger

    UnixSignalTrigger

    (Optional)

    Used to trigger a reload by sending a specific Unix signal to the process.

    shellTrigger

    ShellTrigger

    (Optional)

    Allows to execute a custom shell script to reload the process.

    tplScriptTrigger

    TPLScriptTrigger

    (Optional)

    Enables reloading process using a Go template script.

    autoTrigger

    AutoTrigger

    (Optional)

    Automatically perform the reload when specified conditions are met.

    targetPodSelector

    Kubernetes meta/v1.LabelSelector

    (Optional)

    Used to match labels on the pod to determine whether a dynamic reload should be performed.

    In some scenarios, only specific pods (e.g., primary replicas) need to undergo a dynamic reload. The reloadedPodSelector allows you to specify label selectors to target the desired pods for the reload process.

    If the reloadedPodSelector is not specified or is nil, all pods managed by the workload will be considered for the dynamic reload.

    ReloadPolicy (string alias)

    ReloadPolicy defines the policy of reconfiguring.

    ValueDescription

    "asyncReload"

    "dynamicReloadBeginRestart"

    "none"

    "restartContainer"

    "restart"

    "rolling"

    "syncReload"

    RerenderResourceType (string alias)

    (Appears on:ComponentConfigDescription)

    RerenderResourceType defines the resource requirements for a component.

    ValueDescription

    "hscale"

    "tls"

    "vscale"

    "shardingHScale"

    ScriptConfig

    (Appears on:DownwardAPIChangeTriggeredAction, ShellTrigger, TPLScriptTrigger)

    FieldDescription

    scriptConfigMapRef

    string

    Specifies the reference to the ConfigMap containing the scripts.

    namespace

    string

    (Optional)

    Specifies the namespace for the ConfigMap. If not specified, it defaults to the “default” namespace.

    ShellTrigger

    (Appears on:ReloadAction)

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

    FieldDescription

    command

    []string

    Specifies the command to execute in order to reload the process. It should be a valid shell command.

    sync

    bool

    (Optional)

    Determines the synchronization mode of parameter updates with “config-manager”.

    • ‘True’: Executes reload actions synchronously, pausing until completion.

    • ‘False’: Executes reload actions asynchronously, without waiting for completion.

    batchReload

    bool

    (Optional)

    Controls whether parameter updates are processed individually or collectively in a batch:

    • ‘True’: Processes all changes in one batch reload.

    • ‘False’: Processes each change individually.

    Defaults to ‘False’ if unspecified.

    batchParamsFormatterTemplate

    string

    (Optional)

    Specifies a Go template string for formatting batch input data. It’s used when batchReload is ‘True’ to format data passed into STDIN of the script. The template accesses key-value pairs of updated parameters via the ‘$’ variable. This allows for custom formatting of the input data.

    Example template:

    batchParamsFormatterTemplate: |- {{- range $pKey, $pValue := $ }} {{ printf "%s:%s" $pKey $pValue }} {{- end }}

    This example generates batch input data in a key

    format, sorted by keys.

    key1

    key2
    key3

    If not specified, the default format is key=value, sorted by keys, for each updated parameter.

    key1=value1 key2=value2 key3=value3

    toolsSetup

    ToolsSetup

    (Optional)

    Specifies the tools container image used by ShellTrigger for dynamic reload. If the dynamic reload action is triggered by a ShellTrigger, this field is required. This image must contain all necessary tools for executing the ShellTrigger scripts.

    Usually the specified image is referenced by the init container, which is then responsible for copy the tools from the image to a bin volume. This ensures that the tools are available to the ‘config-manager’ sidecar.

    scriptConfig

    ScriptConfig

    (Optional)

    ScriptConfig object specifies a ConfigMap that contains script files that should be mounted inside the pod. The scripts are mounted as volumes and can be referenced and executed by the dynamic reload.

    SignalType (string alias)

    (Appears on:UnixSignalTrigger)

    SignalType defines which signals are valid.

    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"

    TPLScriptTrigger

    (Appears on:ReloadAction)

    TPLScriptTrigger Enables reloading process using a Go template script.

    FieldDescription

    ScriptConfig

    ScriptConfig

    (Members of ScriptConfig are embedded into this type.)

    Specifies the ConfigMap that contains the script to be executed for reload.

    sync

    bool

    (Optional)

    Determines whether parameter updates should be synchronized with the “config-manager”. Specifies the controller’s reload strategy:

    • If set to ‘True’, the controller executes the reload action in synchronous mode, pausing execution until the reload completes.

    • If set to ‘False’, the controller executes the reload action in asynchronous mode, updating the ConfigMap without waiting for the reload process to finish.

    ToolConfig

    (Appears on:ToolsSetup)

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

    FieldDescription

    name

    string

    Specifies the name of the init container.

    asContainerImage

    bool

    (Optional)

    Indicates whether the tool image should be used as the container image for a sidecar. This is useful for large tool images, such as those for C++ tools, which may depend on numerous libraries (e.g., *.so files).

    If enabled, the tool image is deployed as a sidecar container image.

    Examples:

    toolsSetup:: mountPoint: /kb_tools toolConfigs:

    • name: kb-tools asContainerImage: true image: apecloud/oceanbase:4.2.0.0-100010032023083021

    generated containers:

    initContainers:

    • name: install-config-manager-tool image: apecloud/kubeblocks-tools:${version} command:
      • cp
      • /bin/config_render
      • /opt/tools volumemounts:
      • name: kb-tools mountpath: /opt/tools containers:
    • name: config-manager image: apecloud/oceanbase:4.2.0.0-100010032023083021 imagePullPolicy: IfNotPresent command:
      • /opt/tools/reloader
      • --log-level
      • info
      • --operator-update-enable
      • --tcp
      • "9901"
      • --config
      • /opt/config-manager/config-manager.yaml volumemounts:
      • name: kb-tools mountpath: /opt/tools

    image

    string

    (Optional)

    Specifies the tool container image.

    command

    []string

    (Optional)

    Specifies the command to be executed by the init container.

    ToolsSetup

    (Appears on:ShellTrigger)

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

    Example:

    toolsSetup: mountPoint: /kb_tools toolConfigs:

    • name: kb-tools command:
      • cp
      • /bin/ob-tools
      • /kb_tools/obtools image: docker.io/apecloud/obtools

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

    FieldDescription

    mountPoint

    string

    Specifies the directory path in the container where the tools-related files are to be copied. This field is typically used with an emptyDir volume to ensure a temporary, empty directory is provided at pod creation.

    toolConfigs

    []ToolConfig

    (Optional)

    Specifies a list of settings of init containers that prepare tools for dynamic reload.

    UnixSignalTrigger

    (Appears on:ReloadAction)

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

    FieldDescription

    signal

    SignalType

    Specifies a valid Unix signal to be sent. For a comprehensive list of all Unix signals, see: ../../pkg/configuration/configmap/handler.go

    processName

    string

    Identifies the name of the process to which the Unix signal will be sent.


    Generated with gen-crd-api-reference-docs

    © 2025 ApeCloud PTE. Ltd.