Skip to content

Simplyblock Operator

The Simplyblock Operator provides a declarative, Kubernetes-native interface for installing and operating simplyblock. The control plane, the CSI driver, storage clusters, storage nodes, devices, pools, and backups are described by custom resources of the API group storage.simplyblock.io, and the operator continuously reconciles their desired state with the actual state of the simplyblock cluster. Imperative operations, such as restarting a node or migrating a volume, are separate *Ops resources rather than fields on the entities.

The current API version is storage.simplyblock.io/v1alpha2. All examples in this documentation use it.

For the complete field reference, see Simplyblock Operator Reference.

Served Versions

Every kind of the API group is served at storage.simplyblock.io/v1alpha2, which is also its storage version.

The four replication kinds are the exception. ReplicationPair, ReplicationPolicy, ReplicationSlot, and ReplicationOps have no v1alpha2 yet and are served at storage.simplyblock.io/v1alpha1, keeping their lowercase enum values such as mode: failover. See Asynchronous Replication.

Resource Kinds

Every v1alpha2 kind belongs to one of three categories:

  • Entity: A resource that declares desired state and is reconciled continuously.
  • Observed: A resource that mirrors backend state. It is written by the operator only.
  • Action: An *Ops resource that runs one operation against one target and then stays as its record.
Kind Short name Scope Category Purpose Documentation
ControlPlane cp Namespaced, singleton simplyblock Entity The control plane (FoundationDB and management API), installed locally or managed elsewhere. Created by the Helm chart. Install Simplyblock Operator, Control Plane Cluster Architecture
ControlPlaneOps cpops Namespaced Action Restart, Upgrade, or Backup of a local control plane. Upgrading a Cluster, FoundationDB Backup and Restore
SimplyblockDriver sbd Namespaced, one per Kubernetes cluster Entity The CSI driver deployment. Created by the Helm chart. Install Simplyblock Operator, Connecting to an External Control Plane
OperatorOps oops Namespaced Action Discover: probes the workers and writes a draft ClusterDeploymentConfig. Create a Storage Cluster
ClusterDeploymentConfig cdc Namespaced Entity A complete deployment in one document. Once approved, it is expanded into a storage cluster and its nodes. Create a Storage Cluster
StorageCluster stc Namespaced, at most one per namespace Entity One simplyblock storage cluster. Owns its nodes and pools and creates the default pool. Create a Storage Cluster, Multi-Tenancy
StorageClusterOps scops Namespaced Action Activate, Expand, Shutdown, Start, Restart, RollingRestart, or CancelTask. Storage Cluster Actions
StorageNode sn Namespaced Entity One storage node on a worker and socket. Owned by its cluster. Storage Nodes
StorageNodeOps snops Namespaced Action Shutdown, Restart, Suspend, Resume, Remove, Migrate, or HostMaintenance. Storage Node Actions
StorageDevice sd Namespaced Observed Mirrors one device of a storage node. Owned by its node. Cluster Health
StorageDeviceOps sdops Namespaced Action Restart of one device. Restarting a Storage Device
StoragePool sp Namespaced Entity A tenancy unit with limits, volume defaults, and allowed nodes. StorageClasses attach to it by label. Multi-Tenancy, Storage Class
StoragePoolOps spops Namespaced Action Rebalance is declared but refused at run time. Operation Kinds
PersistentVolumeOps pvops Cluster Action Migrate: moves the logical volume of a PersistentVolume to another storage node. Volume Migration
StorageBackup sb Namespaced Observed One backup found in the backup store. Users cannot create or delete it. Listing Backups
StorageBackupPolicy sbp Namespaced Entity Backup schedule and retention for the claims its selector matches. Backup Policies
StorageBackupOps sbops Namespaced Action Restore of a backup into a new PersistentVolumeClaim. Restoring a Backup
VolumeGroupSnapshotOps vgsops Namespaced Action Restore of every member of a VolumeGroupSnapshot. Snapshotting

The names of StorageCluster, StorageNode, and StoragePool resources, and every clusterRef, are limited to 63 characters.

Common Ops Shape

Every *Ops kind shares one shape. The full description, with examples, is in Operations.

  • spec.action: The operation to perform, as a PascalCase value, for example, Restart or RollingRestart. It is required and immutable.
  • Target reference: The entity the operation acts on, for example, spec.clusterRef or spec.nodeRef. It is immutable. OperatorOps has no target reference.
  • spec.abort: The only mutable field. Setting it to true stops a running operation at its current step, if that step can be stopped cleanly.
  • status.phase: Pending, Running, Succeeded, Failed, or Aborted. The last three are terminal.
  • status.step: The current step, as state and deadline. A step that outlives its deadline fails the operation.
  • Further status fields: status.message, status.startedAt, status.completedAt, and status.observedGeneration.

Only one operation acts on an entity at a time. The operation that holds the lock is named in status.activeOpsRef of the target. For PersistentVolumes, the lock is the annotation storage.simplyblock.io/active-ops. A second operation for the same target waits in Pending. A finished operation cannot be edited or re-run, and a running operation whose current step cannot be aborted cannot be deleted.

All Ops kinds emit the same event reasons:

Reason Meaning
OperationQueued The target is held by another operation, and this one waits.
OperationStarted The operation acquired the lock on its target and started.
OperationSucceeded The operation completed.
OperationFailed The operation failed. The message carries the reason.
OperationAborted The operation was stopped through spec.abort.
StepDeadlineExceeded A step outlived its deadline, which fails the operation.

Metrics API

The operator also serves the read-only API metrics.simplyblock.io/v1alpha2 through an aggregated API server. Its kinds are not CRDs and are not stored. The API is enabled by default through the Helm value metricsAPI.enabled.

Kind Short name Named after
StorageClusterMetrics scm The StorageCluster
StorageNodeMetrics snm The StorageNode
StoragePoolMetrics spm The StoragePool
StorageDeviceMetrics sdm The StorageDevice
LogicalVolumeMetrics lvm The PersistentVolumeClaim, in its namespace

Each reading carries a timestamp and a capacity block. For the fields and access control, see Capacity Metrics API.

Labels and Annotations

Labels and annotations are written with the prefix storage.simplyblock.io/, for example, storage.simplyblock.io/selected-storage-node on a PersistentVolumeClaim. The older spellings with the prefixes simplyblock.io/ and simplybk/ are still read, so objects created by earlier releases keep working. When an object carries more than one spelling, the newest one wins.

The following keys are still read only under the old simplyblock.io/ prefix:

Key Carried by Documentation
simplyblock.io/pod-affinity A PersistentVolumeClaim Automatic Volume Placement
simplyblock.io/auto-restart-on-pathloss A StorageClass or a PersistentVolumeClaim Recovering from Path Loss
simplyblock.io/guardian-disable A PersistentVolumeClaim Recovering from Path Loss
simplyblock.io/trigger-realignment A StorageCluster Data Realignment

Pinned volumes, which carry storage.simplyblock.io/selected-storage-node, are covered in Pinned Volumes and, for node removal, in Removing a Storage Node.

Field Reference

The Simplyblock Operator Reference lists every field of every kind.