Packages:
- operations.kubeblocks.io/v1alpha1
operations.kubeblocks.io/v1alpha1
Resource Types:
- OpsDefinition- OpsRequest
OpsDefinition
OpsDefinition is the Schema for the OpsDefinitions API.
Table (html):
| Field | Description |
| apiVersion
string | operations.kubeblocks.io/v1alpha1 |
| kind
string | OpsDefinition |
| metadata
Kubernetes
meta/v1.ObjectMeta | Refer to the Kubernetes API documentation for the fields of the metadata field. |
| spec
OpsDefinitionSpec | |
| preConditions
[PreCondition](preconditions.png) |
| podInfoExtractors
[PodInfoExtractor](podInfoExtractor) |
| podInfoExtractors
[PodInfoExtractor](podInfoExtractor) |
| preConditions:
- rule:
expression: '{ eq .component.status-phase "Running" }'
message: Component is not in Running status. |
| (Optional)
Specifies a list of PodInfoExtractor, each designed to select a specific Pod and extract selected runtime info from its PodSpec. The extracted information, such as environment variables, volumes and tolerations, are |
Table (html):
| Field | Description |
| | then injected into Jobs or Pods that execute the OpsActions defined in actions. |
| componentInfos
[ComponentInfo] | (Optional)
Specifies a list of ComponentDefinition for Components associated with this OpsDefinition. It also includes connection credentials (address and account) for each Component. |
| parametersSchema
ParametersSchema | (Optional)
Specifies the schema for validating the data types and value ranges of parameters in OpsActions before their usage. |
| actions
[OpsAction] | Specifies a list of OpsAction where each customized action is executed sequentially. |
| status
OpsDefinitionStatus | |
OpsRequest
OpsRequest is the Schema for the opsrequests API
Table (html):
| Field | Description | |
| apiVersion
string | operations.kubernetes.io/v1alpha1 | |
| kind
string | OpsRequest | |
| metadata
Kubernetes
meta/v1.ObjectMeta | Refer to the Kubernetes API documentation for the fields of the metadata field. | |
| spec
OpsRequestSpec | | |
| clusterName
string | Specifies the name of the Cluster resource that this operation is targeting. |
| cancel
bool | (Optional)
Indicates whether the current operation should be canceled and terminated gracefully if it's in the "Pending", "Creating", or "Running" state. This field applies only to "VerticalScaling" and "HorizontalScaling" opsRequests. |
Table (html):
| Field | Description |
| | Note: Setting cancel to true is irreversible; further modifications to this field are ineffective. |
| force
bool | (Optional)
Instructs the system to bypass pre-checks (including cluster state checks and customized pre-conditions hooks) and immediately execute the opsRequest, except for the opsRequest of 'Start' type, which will still undergo pre-checks even if force is true.
This is useful for concurrent execution of 'VerticalScaling' and 'HorizontalScaling' opsRequests. By setting force to true, you can bypass the default checks and demand these opsRequests to run simultaneously.
Note: Once set, the force field is immutable and cannot be updated. |
| enqueueOnForce
bool | (Optional)
Indicates whether opsRequest should continue to queue when 'force' is set to true. |
| type
OpsType | Specifies the type of this operation. Supported types include "Start", "Stop", "Restart",
"Switchover", "VerticalScaling", "HorizontalScaling", "VolumeExpansion", "Reconfiguring", "Upgrade",
"Backup", "Restore", "Expose", "RebuildInstance",
"Custom".
Note: This field is immutable once set. |
| ttlSecondsAfterSucceed
int32 | (Optional)
Specifies the duration in seconds that an OpsRequest will remain in the system after successfully completing (when opsRequest.status.phase is "Succeed") before automatic deletion. |
| ttlSecondsAfterUnsuccessfulCompletion
int32 | (Optional)
Specifies the duration in seconds that an OpsRequest will remain in the system after completion for any phase other than "Succeed" (e.g., "Failed", "Cancelled", "Aborted") before automatic deletion. |
| preConditionDeadlineSeconds
int32 | (Optional)
Specifies the maximum time in seconds that the OpsRequest will wait for its pre-conditions to be met before it aborts the operation. If set to 0 (default), pre-conditions must be satisfied immediately for the OpsRequest to proceed. |
Table (html):
| Field | Description |
| timeoutSeconds
int32 | (Optional)
Specifies the maximum duration (in seconds) that an opsRequest is allowed to run. If the opsRequest runs longer than this duration, its phase will be marked as Aborted. If this value is not set or set to 0, the timeout will be ignored and the opsRequest will run indefinitely. |
| SpecificOpsRequest
SpecificOpsRequest | (Members of SpecificOpsRequest are embedded into this type.)
Exactly one of its members must be set. |
| status
OpsRequestStatus | |
ActionTask
(Appears on
)
Table (html):
| Field | Description | |
| objectKey
string | Represents the name of the task. |
| namespace
string | Represents the namespace where the task is deployed. |
| status
ActionTaskStatus | Indicates the current status of the task, including “Processing”, “Failed”, “Succeed”. |
| targetPodName
string | (Optional)
The name of the Pod that the task is associated with or operates on. |
| retries
int32 | (Optional)
The count of retry attempts made for this task. |
ActionTaskStatus(string alias)
(Appears on
)
ActionTaskStatus defines the status of the task.
Table (html):
Table (html):
| Value | Description |
| "Processing" | |
| "Succeed" | |
Backup
(Appears on
)
Table (html):
| Field | Description |
| backupName
string | (Optional)
Specifies the name of the Backup custom resource. |
| backupPolicyName
string | (Optional)
Indicates the name of the BackupPolicy applied to perform this Backup. |
| backupMethod
string | (Optional)
Specifies the name of BackupMethod. The specified BackupMethod must be defined in the BackupPolicy. |
| deletionPolicy
string | (Optional)
Determines whether the backup contents stored in backup repository should be deleted when the Backup custom resource is deleted. Supported values are 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)
Determines the duration for which the Backup custom resources should be retained. The controller will automatically remove all Backup objects that are older than the specified RetentionPeriod. For example, RetentionPeriod of 30d will keep only the Backup objects of last 30 days. Sample duration format:
• years: 2y
• months: 6mo
• days: 30d
• hours: 12h |
Table (html):
| Field | Description |
| • minutes: 30m
You can also combine the above durations. For example: 30d12h30m. If not set, the Backup objects will be kept forever.
If the deletionPolicy is set to 'Delete', then the associated backup data will also be deleted along with the Backup object. Otherwise, only the Backup custom resource will be deleted. |
| parentBackupName | (Optional)
If the specified BackupMethod is incremental, parentBackupName is required. |
| string |
| parameters | |
BackupRefSpec
Table (html):
| Field | Description | |
| ref
RefNamespaceName | (Optional)
Refers to a reference backup that needs to be restored. | |
CompletionProbe
(Appears on
)
Table (html):
| Field | Description |
| initialDelaySeconds
int32 | (Optional)
Specifies the number of seconds to wait after the resource has been patched before initiating completion probes. The default value is 5 seconds, with a minimum value of 1. |
| timeoutSeconds
int32 | (Optional)
Specifies the number of seconds after which the probe times out. The default value is 60 seconds, with a minimum value of 1. |
| periodSeconds
int32 | (Optional)
Specifies the frequency (in seconds) at which the probe should be performed. The default value is 5 seconds, with a minimum value of 1. |
| matchExpressions
MatchExpressions | Executes expressions regularly, based on the value of PeriodSeconds, to determine if the action has been completed. |
ComponentInfo
(Appears on
)
Table (html):
| Field | Description |
| componentDefinitionName
string | Specifies the name of the ComponentDefinition. The name can represent an exact name, a name prefix, or a regular expression pattern.
For example:
·"mysql-8.0.30-v1alpha1": Matches the exact name "mysql-8.0.30-v1alpha1"
·"mysql-8.0.30": Matches all names starting with "mysql-8.0.30"
·"^mysql-8.0.\d{1,2}$: Matches all names starting with "mysql-8.0." followed by one or two digits. |
| accountName
string | (Optional)
Specifies the account name associated with the Component. If set, the corresponding account username and password are injected into containers' environment variables
KB_ACCOUNT_USERNAME and KB_ACCOUNT_PASSWORD. |
| serviceName
string | (Optional)
Specifies the name of the Service. If set, the service name is injected as the KB_COMP_SVC_NAME environment variable in the containers, and each service port is mapped to a corresponding environment variable named KB_COMP_SVC_PORT.$ (portName). The portName is transformed by replacing '-' with '-' and converting to uppercase. |
ComponentOps
(Appears on
, HorizontalScaling, RebuildInstance, Reconfigure, SpecificOpsRequest, UpgradeComponent, VerticalScaling, VolumeExpansion)
ComponentOps specifies the Component to be operated on.
Table (html):
| Field | Description | |
| componentName
string | Specifies the name of the Component as defined in the cluster.spec | |
CustomOps
(Appears on
)
Table (html):
| Field | Description |
| opsDefinitionName
string | Specifies the name of the OpsDefinition. |
| serviceAccountName
string | Specifies the name of the ServiceAccount to be used for executing the custom operation. |
| maxConcurrentComponents | (Optional) |
Table (html):
| Field | Description |
| Kubernetes api utils
intstr.IntOrString | Specifies the maximum number of components to be operated on concurrently to mitigate performance impact on clusters with multiple components.
It accepts an absolute number (e.g., 5) or a percentage of components to execute in parallel (e.g., "10%"). Percentages are rounded up to the nearest whole number of components. For example, if "10%" results in less than one, it rounds up to 1.
When unspecified, all components are processed simultaneously by default.
Note: This feature is not implemented yet. |
| components
[CustomOpsComponent | Specifies the components and their parameters for executing custom actions as defined in OpsDefinition. Requires at least one component. |
CustomOpsComponent
Appears on
)
Table (html):
| Field | Description |
| ComponentOps
ComponentOps | (Members of ComponentOps are embedded into this type.)
Specifies the name of the Component. |
| parameters
Parameter | (Optional)
Specifies the parameters that match the schema specified in the opsDefinition.spec.parametersSchema. |
EnvVarRef
Appears on
)
Table (html):
| Field | Description |
| targetContainerName
string | (Optional)
Specifies the container name in the target Pod. If not specified, the first container will be used by default. |
| envName
string | Defines the name of the environment variable. This name can originate from an 'env' entry or be a data key from an 'envFrom' source. |
Expose
Appears on
)
Table (html):
| Field | Description |
| componentName
string | Specifies the name of the Component. |
| switch
ExposeSwitch | Indicates whether the services will be exposed: 'Enable' exposes the services. while 'Disable' removes the exposed Service. |
Table (html):
| Field | Description |
| services
opsService | Specifies a list of OpsService. When an OpsService is exposed, a corresponding ClusterService will be added to cluster.spec.services. On the other hand, when an OpsService is unexposed, the corresponding ClusterService will be removed from cluster.spec.services.
Note: If componentName is not specified, the ports and selector fields must be provided in each OpsService definition. |
ExposeSwitch(string alias)
Appears on
)
ExposeSwitch Specifies the switch for the expose operation. This switch can be used to enable or disable the expose operation.
Table (html):
| Value | Description | |
| "Disable" | | |
| "Enable" | | |
FailurePolicyType(string alias)
Appears on
)
FailurePolicyType specifies the type of failure policy.
Table (html):
| Value | Description | |
| "Fail" | FailurePolicyFail means that an error will be reported. | |
| "Ignore" | FailurePolicyIgnore means that an error will be ignored but logged. | |
HorizontalScaling
Appears on
)
HorizontalScaling defines the parameters of a horizontal scaling operation.
Table (html):
| Field | Description |
| ComponentOps ComponentOps | (Members of ComponentOps are embedded into this type.) Specifies the name of the Component. |
| shards int32 | Specifies the desired number of shards for the component. This parameter is mutually exclusive with other parameters. |
Table (html):
| Field | Description |
| scaleOut
ScaleOut | (Optional)
Specifies the replica changes for scaling out components and instance templates, and brings offline instances back online. Can be used in conjunction with the "scaleIn" operation. Note: Any configuration that deletes instances is considered invalid. |
| scaleIn
ScaleIn | (Optional)
Specifies the replica changes for scaling in components and instance templates, and takes specified instances offline. Can be used in conjunction with the "scaleOut" operation. Note: Any configuration that creates instances is considered invalid. |
Instance
(Appears on
)
Table (html):
| Field | Description |
| name | Pod name of the instance. |
| string |
| targetNodeName | (Optional) |
| string | The instance will rebuild on the specified node. If not set, it will rebuild on a random node. |
InstanceReplicasTemplate
(Appears on
)
InstanceReplicasTemplate defines the template for instance replicas.
Table (html):
| Field | Description |
| name | Specifies the name of the instance template. |
| string |
| replicaChanges | Specifies the replica changes for the instance template. |
| int32 |
InstanceResourceTemplate
(Appears on
)
Table (html):
| Field | Description |
| name | Refer to the instance template name of the component or sharding. |
| string |
| ResourceRequirements
Kubernetes core/v1. ResourceRequirements | (Members of ResourceRequirements are embedded into this type.) Defines the computational resource size for vertical scaling. |
Table (html):
| Field | Description | |
| name
string | Refer to the instance template name of the component or sharding. |
| volumeClaimTemplates
[OpsRequestVolumeClaimTemplate | volumeClaimTemplates specifies the storage size and volumeClaimTemplate name. |
JSONPatchOperation
(Appears on
)
Table (html):
| Field | Description | |
| op
string | Specifies the type of JSON patch operation. It supports the following values: 'add', 'remove', 'replace'. | |
| path
string | Specifies the json patch path. | |
| value
string | Specifies the value to be used in the JSON patch operation. | |
LastComponentConfiguration
(Appears on
)
LastComponentConfiguration can be used to track and compare the desired state of the Component over time.
Table (html):
| Field | Description |
| replicas
int32 | (Optional)
Records the replicas of the Component prior to any changes. |
| shards
int32 | (Optional)
Records the shards of the Component prior to any changes. |
| ResourceRequirements
Kubernetes core/v1. ResourceRequirements | (Members of ResourceRequirements are embedded into this type.)
(Optional)
Records the resources of the Component prior to any changes. |
| volumeClaimTemplates
[OpsRequestVolumeClaimTemplate | (Optional)
Records volumes' storage size of the Component prior to any changes. |
Table (html):
| Field | Description |
| services
[github.com/apecloud/kubeblocks/apis/apps/v1.ClusterComponentService | (Optional)
Records the ClusterComponentService list of the Component prior to any changes. |
| instances
[github.com/apecloud/kubeblocks/apis/apps/v1.InstanceTemplate | (Optional)
Records the InstanceTemplate list of the Component prior to any changes. |
| offlineInstances
[string | (Optional)
Records the offline instances of the Component prior to any changes. |
| serviceVersion
string | (Optional)
Records the version of the Service expected to be provisioned by this Component prior to any changes. |
| componentDefinitionName
string | (Optional)
Records the name of the ComponentDefinition prior to any changes. |
LastConfiguration
(Appears on
)
Table (html):
| Field | Description |
| components
map[string]github.com/apecloud/kubeblocks/apis/operations/v1alpha1.LastComponentConfiguration | (Optional)
Records the configuration of each Component prior to any changes. |
MatchExpressions
(Appears on
)
Table (html):
| Field | Description |
| failure
string | (Optional)
Specifies a failure condition for an action using a Go template expression. Should evaluate to either true or false. The current resource object is parsed into the Go template. for example, you can use '{eq.spec.replicas 1}'. |
| success
string | Specifies a success condition for an action using a Go template expression. Should evaluate to either true or false. The current resource object is parsed into the Go template. for example, using '{eq.spec.replicas 1}' |
OpsAction
(Appears on
)
opsAction specifies a custom action defined in OpsDefinition for execution in a "Custom" OpsRequest.
OpsAction can be of three types: - workload: Creates a Job or Pod to run custom scripts, ideal for isolated or long- running tasks. - exec: Executes commands directly within an existing container using the kubectl exec interface, suitable for immediate, short- lived operations. - resourceModifier: Modifies a K8s object using JSON patches, useful for updating the spec of some resource.
Table (html):
| Field | Description |
| name | Specifies the name of the OpsAction. |
| string | (Optional) |
| failurePolicy | Specifies the failure policy of the OpsAction. Valid values are:
·“Fail”: Marks the entire OpsRequest as failed if the action fails.
·“Ignore”: The OpsRequest continues processing despite the failure of the action. |
| parameters | (Optional) |
| [string | For ‘workload’ or ‘exec’ actions, parameters are injected as environment variables.
·For ‘resourceModifier’ actions, parameter can be referenced using $() in fields
resourceModifier.completionProbe.matchExpressions and
resourceModifier.jsonPatches[*].value. |
| workload | (Optional) |
| OpsWorkloadAction | Specifies the configuration for a ‘workload’ action. This action leads to the creation of a K8s workload, such as a Pod or Job, to execute specified tasks. |
| exec | (Optional) |
| OpsExecAction | Specifies the configuration for a ‘exec’ action. It creates a Pod and invokes a ‘kubectl exec’ to run command inside a specified container with the target Pod. |
| resourceModifier | (Optional) |
| OpsResourceModifierAction | Specifies the configuration for a ‘resourceModifier’ action. This action allows for modifications to existing K8s objects.
Note: This feature has not been implemented yet. |
OpsDefinitionSpec (Appears on
) OpsDefinitionSpec defines the desired state of OpsDefinition.
Table (html):
| Field | Description |
| preConditions
[PreCondition] | (Optional)
Specifies the preconditions that must be met to run the actions for the operation. If set, it will check the condition before the Component runs this operation. Example:
preConditions:
rule:
expression: {{eq.component.status.phase "Running" }}'
message: Component is not in Running status. |
| podInfoExtractors
[PodInfoExtractor] | (Optional)
Specifies a list of PodInfoExtractor, each designed to select a specific Pod and extract selected runtime info from its PodSpec. The extracted information, such as environment variables, volumes and tolerations, are then injected into Jobs or Pods that execute the OpsActions defined in :actions . |
| componentInfos
[ComponentInfo] | (Optional)
Specifies a list of ComponentDefinition for Components associated with this OpsDefinition. It also includes connection credentials (address and account) for each Component. |
| parametersSchema
ParametersSchema | (Optional)
Specifies the schema for validating the data types and value ranges of parameters in OpsActions before their usage. |
| actions
[OpsAction] | Specifies a list of OpsAction where each customized action is executed sequentially. |
OpsDefinitionStatus
(Appears on
)
OpsDefinitionStatus defines the observed state of OpsDefinition
Table (html):
| Field | Description |
| observedGeneration int64 | (Optional)
Represents the most recent generation observed of this OpsDefinition. |
| phase
Phase | (Optional)
Represents the current state of the OpsDefinition. Valid values are “”, “Available”, “Unavailable”. When it equals to “Available”, the OpsDefinition is ready and can be used in a “Custom” OpsRequest. |
| message
string | (Optional)
Provides additional information about the current phase. |
Table (html):
| Field | Description |
| name | Specifies the name of the environment variable to be injected into Pods executing OpsActions. It must conform to the C_IDENTIFIER format, which includes only alphanumeric characters and underscores, and cannot begin with a digit. |
| string |
| valueFromOpsVarSource | Specifies the source of the environment variable's value. |
OpsExecAction
(Appears on
)
Table (html):
| Field | Description |
| podInfoExtractorName
string | Specifies a PodInfoExtractor defined in the opsDefinition.spec.podInfoExtractors. |
| backoffLimit
int32 | (Optional)
Specifies the number of retries allowed before marking the action as failed. |
| command
string | The command to be executed via 'kubectl exec –'. |
| containerName
string | (Optional)
The name of the container in the target pod where the command should be executed. This corresponds to the -c {containerName} option in kubectl exec.
If not set, the first container is used. |
OpsPhase(string alias)
(Appears on
)
OpsPhase defines opsRequest phase.
Table (html):
| Value | Description |
| "Aborted" | |
| "Cancelled" | |
| "Cancelling" | |
| "Creating" | |
| "Failed" | |
Table (html):
| Value | Description |
| "Pending" | |
| "Running" | |
| "Succeed" | |
[TableCaption: OpsRecorder]
Table (html):
| Field | Description |
| name
string | name OpsRequest name |
| type
OpsType | opsRequest type |
| inQueue
bool | indicates whether the current opsRequest is in the queue |
| queueBySelf
bool | indicates that the operation is queued for execution within its own-type scope. |
OpsRequestBehaviour
Table (html):
| Field | Description | |
| FromClusterPhases
[github.com/apecloud/kubeblocks/apis/apps/v1.ClusterPhase | |
| ToClusterPhase
github.com/apecloud/kubeblocks/apis/apps/v1.ClusterPhase | |
OpsRequestComponentStatus
(Appears on
)
Table (html):
| Field | Description |
| phase
github.com/apecloud/kubeblocks/apis/apps/v1.ComponentPhase | (Optional)
Records the current phase of the Component, mirroring cluster.status.components[componentName], phase. |
| lastFailedTime
Kubernetes meta/v1.Time | (Optional)
Records the timestamp when the Component last transitioned to a “Failed” phase. |
Table (html):
| Field | Description |
| preCheck
PreCheckResult | (Optional)
Records the result of the preConditions check of the opsRequest, which determines subsequent steps. |
| progressDetails
[ProgressStatusDetail | (Optional)
Describes the progress details of objects or actions associated with the Component. |
| reason
string | (Optional)
Provides an explanation for the Component being in its current state. |
| message
string | (Optional)
Provides a human-readable message indicating details about this operation. |
| OpsRequestSpec
(Appears on:OpsRequest)
OpsRequestSpec defines the desired state of OpsRequest |
| Field | Description |
| clusterName
string | Specifies the name of the Cluster resource that this operation is targeting. |
| cancel
bool | (Optional)
Indicates whether the current operation should be canceled and terminated
gracefully if it's in the "Pending", "Creating", or "Running" state.
This field applies only to "VerticalScaling" and "HorizontalScaling" opsRequests.
Note: Setting cancel to true is irreversible; further modifications to this field are ineffective. |
| force
bool | (Optional)
Instructs the system to bypass pre-checks (including cluster state checks and customized pre-conditions hooks) and immediately execute the opsRequest, except for the opsRequest of 'Start' type, which will still undergo pre-checks even if force is true.
This is useful for concurrent execution of 'VerticalScaling' and 'HorizontalScaling' opsRequests. By setting force to true, you can bypass the default checks and demand these opsRequests to run simultaneously.
Note: Once set, the force field is immutable and cannot be updated. |
| enqueueOnForce
bool | (Optional)
Indicates whether opsRequest should continue to queue when 'force' is set to true. |
OpsRequestStatus
(Appears on
)
OpsRequestStatus represents the observed state of an OpsRequest.
Table (html):
| Field | Description |
| clusterGeneration | (Optional)
Records the cluster generation after the OpsRequest action has been handled. |
Table (html):
| Field | Description |
| phase
OpsPhase | |
| progress
string | Represents the progress of the OpsRequest. |
| lastConfiguration
LastConfiguration | (Optional)
Records the configuration prior to any changes. |
| components
map[string]github.com/apecloud/kubeblocks/apis/operations/v1alpha1.OpsRequestComponentStatus | (Optional)
Records the status information of Components changed due to the OpsRequest. |
| extras
string | A collection of additional key-value pairs that provide supplementary information for the OpsRequest. |
| startTimestamp
Kubernetes meta/v1.Time | (Optional)
Records the time when the OpsRequest started processing. |
| completionTimestamp
Kubernetes meta/v1.Time | (Optional)
Records the time when the OpsRequest was completed. |
| cancelTimestamp
Kubernetes meta/v1.Time | (Optional)
Records the time when the OpsRequest was cancelled. |
| conditions
[Kubernetes meta/v1.Condition] | (Optional)
Describes the detailed status of the OpsRequest. Possible condition types include “Cancelled”,
“WaitForProgressing”,
“Validated”,
“Succeed” |
Table (html):
| Field | Description |
| "Failed","Restarting",
"VerticalScaling",
"HorizontalScaling",
"VolumeExpanding",
"Reconfigure",
"Switchover","Stopping",
"Starting",
"VersionUpgrading",
"Exposing","Backup",
"InstancesRebuilding",
"CustomOperation". |
OpsRequestVolumeClaimTemplate
(Appears on
, LastComponentConfiguration, VolumeExpansion)
Table (html):
| Field | Description |
| storage
Kubernetes
resource.Quantity | Specifies the desired storage size for the volume. |
| name
string | Specify the name of the volumeClaimTemplate in the Component. The specified name must match one of the volumeClaimTemplates defined in the clusterComponentSpec.volumeClaimTemplates field. |
OpsResourceModifierAction
(Appears on
)
Table (html):
| Field | Description |
| resource
TypedObjectRef | Specifies the K8s object that is to be updated. |
| jsonPatches
//JSONPatchOperation | Specifies a list of patches for modifying the object. |
| completionProbe
CompletionProbe | Specifies a method to determine if the action has been completed.
Note: This feature has not been implemented yet. |
OpsService
(Appears on
)
OpsService represents the parameters to dynamically create or remove a ClusterService in the cluster.spec.services array.
Table (html):
| Field | Description |
| name | Specifies the name of the Service. This name is used to set clusterService.name . |
Table (html):
| map[string]string | Contains cloud provider related parameters if ServiceType is LoadBalancer.
More info: https://kubernetes.io/docs/concepts/services-networking/service/#loadbalancer. |
| ports | Specifies Port definitions that are to be exposed by a ClusterService.
If not specified, the Port definitions from non-NodePort and non-LoadBalancer type ComponentService defined in the ComponentDefinition ( componentDefinition.spec.services ) will be used. If no matching ComponentService is found, the expose operation will fail.
More info: https://kubernetes.io/docs/concepts/services-networking/service/#field-spec-ports |
| roleSelector | Specifies a role to target with the service. If specified, the service will only be exposed to pods with the matching role.
Note: If the component has roles, at least one of 'roleSelector' or 'podSelector' must be specified. If both are specified, a pod must match both conditions to be selected. |
| podSelector | Routes service traffic to pods with matching label keys and values. If specified, the service will only be exposed to pods matching the selection.
Note: If the component has roles, at least one of 'roleSelector' or 'podSelector' must be specified. If both are specified, a pod must match both conditions to be selected. |
| serviceType | Specifies how the Service is exposed. Defaults to 'ClusterIP'. Valid options are 'ClusterIP', 'NodePort', and 'LoadBalancer'.
·ClusterIP: allocates a cluster-internal IP address for load-balancing to endpoints. Endpoints are determined by the selector or if that is not specified, they are determined by manual construction of an Endpoints object or EndpointSlice objects.
·NodePort: builds on ClusterIP and allocates a port on every node which routes to the same endpoints as the clusterIP.
·LoadBalancer: builds on NodePort and creates an external load-balancer (if supported in the current cloud) which routes to the same endpoints as the clusterIP.
Note: although K8s Service type allows the 'ExternalName' type, it is not a valid option for the expose operation.
For more info, see: https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services-service-types. |
| ipFamilies | Optional |
| [Kubernetes core/v1.IPFamily | A list of IP families (e.g., IPv4, IPv6) assigned to this Service.
Usually assigned automatically based on the cluster configuration and the ipFamilyPolicy field. If specified manually, the requested IP family must be available in the cluster and allowed by the ipFamilyPolicy. If the requested IP family is not available or not allowed, the Service creation will fail.
Valid values:
·"IPv4"
·"IPv6" |
Table (html):
| Field | Description |
| This field may hold a maximum of two entries (dual-stack families, in either order).
Common combinations of ipFamilies and ipFamilyPolicy are:
• ipFamilies=['+ ipFamilyPolicy="PreferDualStack" : The Service prefers dual-stack but can fall back to single-stack if the cluster does not support dual-stack. The IP family is automatically assigned based on the cluster configuration.
• ipFamilies=['"IPV4","IPV6"] + ipFamilyPolicy="RequiredDualStack" : The Service requires dual-stack and will only be created if the cluster supports both IPv4 and IPv6. The primary IP family is IPV4.
• ipFamilies=['"IPV6","IPV4"] + ipFamilyPolicy="RequiredDualStack" : The Service requires dual-stack and will only be created if the cluster supports both IPv4 and IPv6. The primary IP family is IPV6.
• ipFamilies=['"IPV4"] + ipFamilyPolicy="SingleStack" : The Service uses a single-stack with IPv4 only.
• ipFamilies=['"IPV6"] + ipFamilyPolicy="SingleStack" : The Service uses a single-stack with IPv6 only. |
| ipFamilyPolicy
Kubernetes
core/v1.IPFamilyPolicy | (Optional)
Specifies whether the Service should use a single IP family (SingleStack) or two IP families (DualStack).
Possible values:
• 'SingleStack' (default) : The Service uses a single IP family. If no value is provided, IPFamilyPolicy defaults to SingleStack.
• 'PreferDualStack' : The Service prefers to use two IP families on dual-stack configured clusters or a single IP family on single-stack clusters.
• 'RequiredDualStack' : The Service requires two IP families on dual-stack configured clusters. If the cluster is not configured for dual-stack, the Service creation fails. |
OpsType (string alias)
(Appears on
, OpsRequestSpec)
OpsType defines operation types.
Table (html):
| Value | Description |
| "Backup" | |
| "Custom" | RebuildInstance rebuilding an instance is very useful when a node is offline or an instance is unrecoverable. |
| "Expose" | StartType the start operation will start the pods which is deleted in stop operation. |
| "HorizontalScaling" | |
| "RebuildInstance" | |
| "Reconfiguring" | |
Table (html):
| Value | Description |
| "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
)
Table (html):
| Field | Description |
| envRef
EnvVarRef | (Optional)
Specifies a reference to a specific environment variable within a container. Used to specify the source of the variable, which can be either "env" or "envFrom". |
| fieldPath
Kubernetes
core/v1.ObjectFieldSelector | (Optional)
Represents the JSONPath expression pointing to the specific data within the JSON structure of the target Pod. It is used to extract precise data locations for operations on the Pod. |
OpsWorkloadAction
(Appears on
)
Table (html):
| Field | Description |
| type
OpsWorkloadType | Defines the workload type of the action. Valid values include "Job" and "Pod".
• "Job": Creates a Job to execute the action.
• "Pod": Creates a Pod to execute the action. Note: unlike Jobs, manually deleting a Pod does not affect the backoffLimit. |
| podInfoExtractorName
string | Specifies a PodInfoExtractor defined in the opsDefinition.spec.podInfoExtractors. |
| backoffLimit | (Optional) |
Table (html):
| Field | Description |
| int32 | Specifies the number of retries allowed before marking the action as failed. |
| podSpec
Kubernetes
core/v1.PodSpec | Specifies the PodSpec of the 'workload' action. |
OpsWorkloadType(string alias)
(Appears on
)
OpsWorkloadType policy after action failure.
Table (html):
| Value | Description | |
| "Job" | | |
| "Pod" | | |
Parameter
(Appears on
)
Table (html):
| Field | Description |
| name
string | Specifies the identifier of the parameter as defined in the OpsDefinition. |
| value
string | Holds the data associated with the parameter. If the parameter type is an array, the format should be "v1,v2,v3". |
| valueFrom
ParameterSource | Source for the parameter's value. Cannot be used if value is not empty. |
ParameterPair
(Appears on
)
Table (html):
| Field | Description |
| key
string | Represents the name of the parameter that is to be updated. |
| value
string | (Optional)
Represents the parameter values that are to be updated. If set to nil, the parameter defined by the Key field will be removed from the configuration file. |
ParameterSource
Appears on
)
Table (html):
| Field | Description | |
| configMapKeyRef
Kubernetes core/v1.ConfigMapKeySelector | (Optional)
Selects a key of a ConfigMap. | |
| secretKeyRef
Kubernetes core/v1.SecretKeySelector | (Optional)
Selects a key of a Secret. | |
ParametersSchema
Appears on
)
Table (html):
| Field | Description |
| openAPIV3Schema
Kubernetes api extensions
v1. JSON SchemaProps | (Optional)
Defines the schema for parameters using the OpenAPI v3. The supported property types include:
•string
•number
•integer
•array: Note that only items of string type are supported. |
Phase(string alias)
Appears on
)
Phase represents the current status of the ClusterDefinition CR.
Table (html):
| Value | Description |
| "Available" | AvailablePhase indicates that the object is in an available state. |
| "Unavailable" | UnavailablePhase indicates that the object is in an unavailable state. |
PodInfoExtractor
Appears on
)
Table (html):
| Field | Description |
| name
string | Specifies the name of the PodInfoExtractor. |
| env
[OpsEnvVar | (Optional)
Specifies a list of environment variables to be extracted from a selected Pod, and injected into the containers executing each OpsAction. |
Table (html):
| Field | Description |
| podSelector
PodSelector | Used to select the target Pod from which environment variables and volumes are extracted from its PodSpec. |
| volumeMounts
Kubernetes
core/v1.VolumeMount | (Optional)
Specifies a list of volumes, along with their respective mount points, that are to be extracted from a selected Pod, and mounted onto the containers executing each OpsAction. This allows the containers to access shared or persistent data necessary for the operation. |
PodSelectionPolicy(string alias)
Appears on
)
PodSelectionPolicy pod selection strategy.
Table (html):
| Value | Description |
| "All" | |
| "Any" | |
PodSelector
Appears on
)
PodSelector selects the target Pod from which environment variables and volumes are extracted from its PodSpec.
Table (html):
| Field | Description |
| role
string | (Optional)
Specifies the role of the target Pod. |
| multiPodSelectionPolicy
PodSelectionPolicy | Defines the policy for selecting the target pod when multiple pods match the podSelector. It can be either ‘Any’ (select any one pod that matches the podSelector) or ‘All’ (select all pods that match the podSelector). |
PointInTimeRefSpec
Table (html):
| Field | Description |
| time
Kubernetes meta/v1.Time | (Optional)
Refers to the specific time point for restoration, with UTC as the time zone. |
| ref
RefNamespaceName | (Optional)
Refers to a reference source cluster that needs to be restored. |
PreCheckResult
Appears on
)
Table (html):
| Field | Description |
| pass | Indicates whether the preCheck operation passed or failed. |
| bool |
| message | (Optional) |
| string | Provides explanations related to the preCheck result in a human-readable format. |
PreCondition
Appears on
)
Table (html):
| Field | Description |
| rule
Rule | Specifies the conditions that must be met for the operation to execute. |
ProgressStatus ( string alias)
Appears on
)
ProgressStatus defines the status of the opsRequest progress.
Table (html):
| Value | Description |
| "Failed" | |
| "Pending" | |
| "Processing" | |
| "Succeed" | |
ProgressStatusDetail
Appears on
)
Table (html):
| Field | Description |
| group | (Optional) |
| string | Specifies the group to which the current object belongs to. |
| objectKey | (Optional) |
| string | objectKey uniquely identifies the object, which can be any K8s object, like a Pod, Job, Component, or PVC. Either objectKey or actionName must be provided. |
| actionName | (Optional) |
Table (html):
| Field | Description |
| string | Indicates the name of an OpsAction, as defined in opsDefinition.spec.actions[*], name .Either objectKey or actionName must be provided. |
| actionTasks
ActionTask | (Optional)
Lists the tasks, such as Jobs or Pods, that carry out the action. |
| status
ProgressStatus | Represents the current processing state of the object, including "Processing", "Pending", "Failed", "Succeed" |
| message
string | (Optional)
Provides a human-readable explanation of the object's condition. |
| startTime
Kubernetes
meta/v1.Time | (Optional)
Records the start time of object processing. |
| endTime
Kubernetes
meta/v1.Time | (Optional)
Records the completion time of object processing. |
RebuildInstance
(Appears on
)
Table (html):
| Field | Description |
| ComponentOps
ComponentOps | (Members of ComponentOps are embedded into this type.)
Specifies the name of the Component. |
| instances
Instance | Specifies the instances (Pods) that need to be rebuilt, typically operating as standbys. |
| inPlace
bool | When it is set to true, the instance will be rebuilt in-place. If false, a new pod will be created. Once the new pod is ready to serve, the instance that require rebuilding will be taken offline. |
| backupName
string | (Optional)
Indicates the name of the Backup custom resource from which to recover the instance. Defaults to an empty PersistentVolume if unspecified.
Note:
• Only full physical backups are supported for multi-replica Components (e.g., 'xtrabackup' for MySQL).
• Logical backups (e.g., 'mysqldump' for MySQL) are unsupported in the current version. |
| sourceBackupTargetName
string | (Optional)
When multiple source targets exist of the backup, you must specify the source target to restore. |
| restoreEnv | (Optional) |
Table (html):
| Field | Description |
| [Kubernetes core/v1. EnvVar | Defines container environment variables for the restore process. merged with the ones specified in the Backup and ActionSet resources.
Merge priority: Restore env > Backup env > ActionSet env.
Purpose: Some databases require different configurations when being restored as a standby compared to being restored as a primary. For example, when restoring MySQL as a replica, you need to set skip_slave_start=" ON" for 5.7 or skip_replica_start=" ON" for 8.0. Allowing environment variables to be passed in makes it more convenient to control these behavioral differences during the restore process. |
Reconfigure
Appears on
Reconfigure defines the parameters for updating a Component's configuration.
Table (html):
| Field | Description |
| ComponentOps
ComponentOps | (Members of ComponentOps are embedded into this type.)
Specifies the name of the Component. |
| parameters
ParameterPair | (Optional)
Specifies a list of key-value pairs representing parameters and their corresponding values within a single configuration file. This field is used to override or set the values of parameters without modifying the entire configuration file. |
RefNamespaceName
Appears on
,PointInTimeRefSpec)
Table (html):
| Field | Description |
| name | (Optional) |
| string | Refers to the specific name of the resource. |
| namespace | (Optional) |
| string | Refers to the specific namespace of the resource. |
ReplicaChanger
Appears on
,ScaleOut)
ReplicaChanger defines the parameters for changing the number of replicas.
Table (html):
| Field | Description |
| replicaChanges
int32 | Specifies the replica changes for the component. |
| instances | (Optional) |
Table (html):
| Field | Description | |
| [InstanceReplicasTemplate] | Modifies the desired replicas count for existing InstanceTemplate. if the inst |
| Restore |
| (Appears on:SpecificOpsRequest) |
| Field | Description | |
| backupName
string | Specifies the name of the Backup custom resource. |
| backupNamespace
string | (Optional)
Specifies the namespace of the backup custom resource. If not specified, the namespace of the opsRequest will be used. |
| restorePointInTime
string | Specifies the point in time to which the restore should be performed. Supported time formats:
·RFC3339 format, e.g. "2023-11-25T18:52:53Z"
·A human-readable date-time format, e.g. "Jul 25,2023 8:52:53 UTC+0800" |
| env
[Kubernetes core/v1. EnvVar | (Optional)
Specifies a list of environment variables to be set in the container. |
| volumeRestorePolicy
string | Specifies the policy for restoring volume claims of a Component's Pods. It determines whether the volume claims should be restored sequentially (one by one) or in parallel (all at once). Support values:
·“Serial”
·“Parallel” |
| deferPostReadyUntilClusterRunning
bool | Controls the timing of PostReady actions during the recovery process. If false (default), PostReady actions execute when the Component reaches the “Running” state. If true, PostReady actions are delayed until the entire Cluster is “Running,” ensuring the cluster’s overall stability before proceeding. This setting is useful for coordinating PostReady operations across the Cluster for optimal cluster conditions. |
Table (html):
| Field | Description |
| parameters
[github.com/apecloud/kubeblocks/apis/dataprotection/v1alpha1.ParameterPair |
Rule
(Appears on
)
Table (html):
| Field | Description |
| expression string | Specifies a Go template expression that determines how the operation can be executed. The return value must be either true or false. Available built-in objects that can be referenced in the expression include:
•params: Input parameters.
•cluster: The referenced Cluster object.
•component: The referenced Component object. |
| message string | Specifies the error or status message reported if the expression does not evaluate to true. |
ScaleIn
(Appears on
)
ScaleIn defines the configuration for a scale- in operation.
Table (html):
| Field | Description |
| ReplicaChanger
ReplicaChanger | (Members of ReplicaChanger are embedded into this type.)
Modifies the replicas of the component and instance templates. |
| onlineInstancesToOffline
String | (Optional)
Specifies the instance names that need to be taken offline. |
ScaleOut
(Appears on
)
ScaleOut defines the configuration for a scale- out operation.
Table (html):
| Field | Description |
| ReplicaChanger
ReplicaChanger | (Members of ReplicaChange are embedded into this type.) |
Table (html):
| Field | Description |
| Modifies the replicas of the component and instance templates. |
| (Optional)
Defines the configuration for new instances added during scaling, including resource requirements, labels, annotations, etc. New instances are created based on the provided instance templates. |
| offlineInstancesToOnline
[]string | (Optional)
Specifies the instances in the offline list to bring back online. |
SpecificOpsRequest
(Appears on
)
Table (html):
| Field | Description |
| upgrade
Upgrade | (Optional)
Specifies the desired new version of the Cluster.
Note: This field is immutable once set. |
| horizontalScaling
HorizontalScaling | (Optional)
Lists HorizontalScaling objects, each specifying scaling requirements for a Component, including desired replica changes, configurations for new instances, modifications for existing instances, and take offline/online the specified instances. |
| volumeExpansion
VolumeExpansion | (Optional)
Lists VolumeExpansion objects, each specifying a component and its corresponding volumeClaimTemplates that requires storage expansion. |
| start
ComponentOps | (Optional)
Lists Components to be started. If empty, all components will be started. |
| stop
ComponentOps | (Optional)
Lists Components to be stopped. If empty, all components will be stopped. |
| restart
ComponentOps | (Optional)
Lists Components to be restarted. |
| switchover
SWitchover | (Optional)
Lists Switchover objects, each specifying a Component to perform the switchover operation. |
| verticalScaling
VerticalScaling | (Optional)
Lists VerticalScaling objects, each specifying a component and its desired compute resources for vertical scaling. |
| reconfigures | (Optional) |
Table (html):
| Field | Description |
| Reconfigure | Lists Reconfigure objects, each specifying a Component and its configuration updates. |
| expose
Expose | (Optional)
Lists Expose objects, each specifying a Component and its services to be exposed. |
| backup
Backup | (Optional)
Specifies the parameters to back up a Cluster. |
| restore
Restore | (Optional)
Specifies the parameters to restore a Cluster. Note that this restore operation will roll back cluster services. |
| rebuildFrom
RebuildInstance | (Optional)
Specifies the parameters to rebuild some instances. Rebuilding an instance involves restoring its data from a backup or another database replica. The instances being rebuilt usually serve as standby in the cluster. Hence, rebuilding instances is often also referred to as “standby reconstruction”. |
| custom
CustomOps | (Optional)
Specifies a custom operation defined by OpsDefinition. |
Switchover
(Appears on
)
Table (html):
| Field | Description |
| componentName
string | (Optional)
Specifies the name of the Component as defined in the cluster.spec. |
| componentObjectName
string | (Optional)
Specifies the name of the Component object. |
| instanceName
string | Specifies the instance whose role will be transferred. A typical usage is to transfer the leader role in a consensus system. |
| candidateName
string | (Optional)
If CandidateName is specified, the role will be transferred to this instance. The name must match one of the pods in the component. Refer to ComponentDefinition's Switchover lifecycle action for more details. |
TypedObjectRef
(Appears on
)
Table (html):
| Field | Description |
| apiGroup string | Specifies the group for the resource being referenced. If not specified, the referenced Kind must belong to the core API group. For all third-party types, this is mandatory. |
| kind string | Specifies the type of resource being referenced. |
| name string | Indicates the name of the resource being referenced. |
UpdatedParameters
UpdatedParameters holds details about the modifications made to configuration parameters. Example:
updatedParameters: updatedKeys: my.cnf: {"mysql":"max_connections":"100"}
Table (html):
| Field | Description |
| addedKeys
map[string]string | (Optional)
Maps newly added configuration files to their content. |
| deletedKeys
map[string]string | (Optional)
Lists the name of configuration files that have been deleted. |
| updatedKeys
map[string]string | (Optional)
Maps the name of configuration files to their updated content, detailing the changes made. |
Upgrade
Uppears on
)
Upgrade defines the parameters for an upgrade operation.
Table (html):
| Field | Description |
| components
UpgradeComponent | (Optional)
Lists components to be upgrade based on desired ComponentDefinition and ServiceVersion. From the perspective of cluster API, the reasonable combinations should be:
1. (comp-def, service-ver) - upgrade to the specified service version and component definition, the user takes the responsibility to ensure that they are compatible.
2. ("" service-ver) - upgrade to the specified service version, let the operator choose the latest compatible component definition.
3. (comp-def, "") - upgrade to the specified component definition, let the operator choose the latest compatible service version. |
Table (html):
| Field | Description |
| 4. ("m", "m") - upgrade to the latest service version and component definition, the operator will ensure the compatibility between the selected versions. |
UpgradeComponent
(Appears on
)
Table (html):
| Field | Description |
| ComponentOps
ComponentOps | (Members of ComponentOps are embedded into this type.)
Specifies the name of the Component. |
| componentDefinitionName
string | (Optional)
Specifies the name of the ComponentDefinition, only exact matches are supported. |
| serviceVersion
string | (Optional)
Specifies the version of the Service expected to be provisioned by this Component. Referring to the ServiceVersion defined by the ComponentDefinition and ComponentVersion. And ServiceVersion in ClusterComponentSpec is optional, when no version is specified, use the latest available version in ComponentVersion. |
VerticalScaling
(Appears on
)
VerticalScaling refers to the process of adjusting compute resources (e.g., CPU, memory) allocated to a Component. It defines the parameters required for the operation.
Table (html):
| Field | Description |
| ComponentOps
ComponentOps | (Members of ComponentOps are embedded into this type.)
Specifies the name of the Component. |
| ResourceRequirements
Kubernetes
core/v1.ResourceRequirements | (Members of ResourceRequirements are embedded into this type.)
Defines the desired compute resources of the Component's instances. |
| instances
[InstanceResourceTemplate] | (Optional)
Specifies the desired compute resources of the instance template that need to vertical scale. |
VolumeExpansion
(Appears on
)
VolumeExpansion encapsulates the parameters required for a volume expansion operation.
Table (html):
| Field | Description |
| ComponentOps
ComponentOps | (Members of ComponentOps are embedded into this type.)
Specifies the name of the Component. |
| volumeClaimTemplates
[OpsRequestVolumeClaimTemplate | Specifies a list of OpsRequestVolumeClaimTemplate objects, defining the volumeClaimTemplates that are used to expand the storage and the desired storage size for each one. |
Generated with gen- crd- api- reference- docs