pillar-csiDocs
Star

CRD reference

Field reference for the pillar-csi v1alpha1 CRDs: PillarAgent, PillarStore, PillarProtocol, PillarStorageClass and PillarVolumeState, from the Go types.

On this page

All pillar-csi resources are cluster-scoped. The controller manages PillarVolumeState objects; do not create them by hand.

The field descriptions come from comments in the Go API types. A few of them mention iSCSI, NFS or other file protocols. Those protocols are not supported yet; NVMe-oF/TCP is the only protocol pillar-csi exports today.

Packages

pillar-csi.bhyoo.com/v1alpha1

Package v1alpha1 contains API Schema definitions for the pillar-csi v1alpha1 API group.

Resource Types

AgentCapabilities

AgentCapabilities describes what backends and protocols the remote agent supports.

Appears in:

Field Description Default Validation
backends string array backends lists the backend driver types the agent can manage
(zfs-zvol, lvm-lv). 		Optional
protocols string array protocols lists the network protocols the agent can export storage over
(nvmeof-tcp). 		Optional

BackendOverrides

BackendOverrides is the per-binding or per-volume override document for the storage backend. Exactly one member must be set, and it must match the backend member configured on the referenced PillarStore.

Appears in:

Field Description Default Validation
zfs ZFSBackendOverrides zfs overrides ZFS-specific tunables; valid only when the store’s
backend is zfs. 		Optional
lvm LVMBackendOverrides lvm overrides LVM-specific tunables; valid only when the store’s
backend is lvm. 		Optional

BackendSpec

BackendSpec describes the storage backend of a PillarStore. Exactly one member must be set: the member name selects the backend (zfs or lvm) and its value carries that backend’s configuration.

The same union shape is reused for the agent’s backend placement config file; per-volume and per-binding override documents use BackendOverrides, which keeps only the tunable subset.

Appears in:

Field Description Default Validation
zfs ZFSBackendConfig zfs holds ZFS-specific configuration. Optional
lvm LVMBackendConfig lvm holds LVM-specific configuration. Optional

DiscoveredPool

DiscoveredPool is a storage pool reported by the remote agent.

Appears in:

Field Description Default Validation
name string name is the pool name as known to the storage subsystem (e.g. ZFS pool name). Required
type string type is the storage technology (e.g. zfs, lvm). Required
total Quantity total is the total raw capacity of the pool. Optional
available Quantity available is the free capacity of the pool. Optional
parentDataset string parentDataset is, for ZFS pools, the dataset relative to the pool under
which the agent creates volumes (its config zfs.parentDataset); empty means
the pool root dataset. A PillarStore on this pool must declare the
same spec.backend.zfs.parentDataset to become Ready. 		Optional
thinPool string thinPool is, for LVM volume groups, the thin pool LV the agent creates
thin volumes in (its config lvm.thinPool); empty means none. A
PillarStore on this VG must declare the same spec.backend.lvm.thinPool
to become Ready. 		Optional

ExternalSpec

ExternalSpec defines a storage agent outside the Kubernetes cluster.

Appears in:

Field Description Default Validation
address string address is the IP or hostname of the external agent. MinLength: 1
Required
port integer port is the agent gRPC port. Maximum: 65535
Minimum: 1
Required

FilesystemConfig

FilesystemConfig describes the filesystem axis: which filesystem the CSI node creates on a new block volume and how it mounts it. The same shape is used at every layer that may set it — PillarStorageClass.spec.filesystem, a hand-written StorageClass’s pillar-csi.bhyoo.com/filesystem parameter and the pillar-csi.bhyoo.com/filesystem PVC annotation.

List fields use list semantics on every layer: omitted (absent or null) inherits the value of the layer below, an explicit empty list [] clears it.

Appears in:

Field Description Default Validation
fsType string fsType is the filesystem the node formats a new volume with when
volumeMode is Filesystem. 		ext4 Enum: [ext4 xfs]
Optional
mkfsOptions string mkfsOptions are additional mkfs arguments used when the node formats a
new volume; a volume that already carries a filesystem is never
reformatted. Each element is one argv element (no shell); only
filesystem tuning flags of the formatted type are accepted.
A null/omitted value inherits the options of the layer below; an
explicit empty list [] clears them. 		Optional
mountOptions string mountOptions are the mount options the node applies when mounting a
Filesystem-mode volume. On a PillarStorageClass they are written to
the generated Kubernetes StorageClass’s mountOptions; a PVC annotation
value overrides them for that volume.
A null/omitted value inherits the options of the layer below; an
explicit empty list [] clears them. 		Optional

LVMBackendConfig

LVMBackendConfig holds LVM-specific volume group and thin pool settings.

Appears in:

Field Description Default Validation
volumeGroup string volumeGroup is the LVM Volume Group name that pillar-csi will create
logical volumes in (e.g. “data-vg”). The VG must be pre-created on
the node before the agent starts; the driver does not manage VG lifecycle. 		MinLength: 1
Required
thinPool string thinPool is the name of the LVM thin pool LV within the volume group
(e.g. “thin-pool-0”). When non-empty the backend operates in thin-
provisioned mode; when empty it creates fully-allocated linear LVs.
The thin pool must be pre-created before the agent starts, and must
equal the thinPool of the agent’s backend configuration for this VG
(chart agent.backends[].lvm.thinPool; empty = none): on a mismatch the
store is not Ready (PoolDiscovered=False, BackendLayoutMismatch) and
CreateVolume fails instead of using another thin pool. 		Optional
provisioningMode LVMProvisioningMode provisioningMode controls whether new volumes are created as fully-
allocated linear LVs or as thin-provisioned LVs inside the thinPool.
Defaults to “linear”; set to “thin” together with a non-empty thinPool
to enable thin provisioning. 		linear Enum: [linear thin]
Optional

LVMBackendOverrides

LVMBackendOverrides holds the per-volume-tunable subset of LVMBackendConfig. Structural placement fields (volumeGroup, thinPool) are not part of this type and are rejected with their path by the shared document decoder.

Appears in:

Field Description Default Validation
provisioningMode LVMProvisioningMode provisioningMode overrides the LVM provisioning mode for this volume or
binding: “linear” (fully-allocated LV) or “thin” (thin-provisioned LV
inside the backend’s thin pool). When omitted, the PillarStore-level
value is used. 		Enum: [linear thin]
Optional

LVMProvisioningMode

Underlying type: string

LVMProvisioningMode selects between linear and thin LV provisioning.

Validation:

  • Enum: [linear thin]

Appears in:

Field Description
linear LVMProvisioningModeLinear creates fully-allocated linear logical volumes
directly in the volume group (lvcreate -L <size>b).
thin LVMProvisioningModeThin creates thin-provisioned logical volumes inside a
pre-existing thin pool LV (lvcreate -V <size>b --thinpool <pool>).

NVMeOFTCPConfig

NVMeOFTCPConfig holds NVMe-oF/TCP-specific protocol parameters. Target bind IP is not included here — the controller resolves it at runtime from the referenced PillarAgent.

Appears in:

Field Description Default Validation
port integer port is the TCP port on which the NVMe-oF target listens.
Defaults to 4420. 		4420 Maximum: 65535
Minimum: 1
Optional
acl boolean acl enables host NQN-based access control when true.
When false the subsystem uses allow_any_host.
Defaults to false (allow_any_host) so that e2e tests and simple
deployments work without registering initiator NQNs. 		false Optional
maxQueueSize integer maxQueueSize is the I/O queue depth the initiator requests for each
queue of the connection (the fabrics queue_size connect option).
Unset keeps the kernel default (128). The kernel accepts 16-1024.
Applies to connections made after the change; a staged volume keeps
the value from its CreateVolume. 		Maximum: 1024
Minimum: 16
Optional
inCapsuleDataSize integer inCapsuleDataSize is the maximum in-capsule data size in bytes the
target advertises (the nvmet port’s param_inline_data_size). It is a
property of the listening port, shared by every volume exported on the
same storage node address and port: exporting a volume that requests a
value different from the port’s current value fails instead of
silently using the port’s value. Unset keeps the transport default
(16384 for TCP on 4 KiB pages) and accepts whatever value the port has.
The minimum is 1024: NVMe/TCP hosts send the 1024-byte fabrics Connect
data in-capsule, so a smaller value makes every connect fail. 		Minimum: 1024
Optional
ctrlLossTmo integer ctrlLossTmo is the maximum seconds to wait before declaring a target
permanently lost after connectivity failure. 		Minimum: 0
Optional
reconnectDelay integer reconnectDelay is the interval in seconds between reconnect attempts. Minimum: 0
Optional

NVMeOFTCPOverrides

NVMeOFTCPOverrides holds the per-volume-tunable subset of NVMeOFTCPConfig. Structural fields (port — which listener the export lives on — and acl — the security policy anchor) are not part of this type and are rejected with their path by the shared document decoder.

Appears in:

Field Description Default Validation
maxQueueSize integer maxQueueSize overrides the protocol-level maxQueueSize (the initiator’s
fabrics queue_size; the kernel accepts 16-1024). 		Maximum: 1024
Minimum: 16
Optional
inCapsuleDataSize integer inCapsuleDataSize overrides the protocol-level inCapsuleDataSize (the
target port’s param_inline_data_size, shared by every volume exported
on the same storage node address and port; at least 1024). 		Minimum: 1024
Optional
ctrlLossTmo integer ctrlLossTmo overrides the protocol-level ctrlLossTmo (seconds before
declaring a target permanently lost). 		Minimum: 0
Optional
reconnectDelay integer reconnectDelay overrides the protocol-level reconnectDelay (seconds
between reconnect attempts). 		Minimum: 0
Optional

NodeRefSpec

NodeRefSpec references a Kubernetes Node for agent address resolution.

Appears in:

Field Description Default Validation
name string name is the Kubernetes Node name. MinLength: 1
Required
addressType string addressType selects which address type to use from the node’s status.addresses.
Defaults to InternalIP. 		InternalIP Enum: [InternalIP ExternalIP]
Optional
addressSelector string addressSelector is an optional CIDR filter applied when multiple addresses of
the same type exist on the node. 		Optional
port integer port overrides the default agent gRPC port (9500). Maximum: 65535
Minimum: 1
Optional

PartialFailureInfo

PartialFailureInfo records what happened when a CSI operation partially succeeded, leaving the volume in an inconsistent state that requires explicit recovery or cleanup.

Appears in:

Field Description Default Validation
failedOperation string failedOperation is the name of the CSI or agent-level operation that
failed (e.g., “ExportVolume”, “NodeStageMount”). 		Required
failedAt Time failedAt is the time when the partial failure was recorded. Required
reason string reason is a brief, machine-readable CamelCase word that describes the
category of failure (e.g., “AgentRPCFailed”, “MountFailed”). 		Optional
message string message is a human-readable sentence describing what failed and how to
recover. 		Optional
backendCreated boolean backendCreated is true when the backend storage resource (zvol, LVM LV,
etc.) was successfully created before the failure occurred. When false,
DeleteVolume only needs to call UnexportVolume (idempotent no-op); when
true, it must also call DeleteVolume on the agent to reclaim the storage. 		Optional
exportCreated boolean exportCreated is true when the network export (NVMe-oF subsystem) was
successfully created before the failure. When
true, cleanup must call UnexportVolume before DeleteVolume. 		Optional

PillarAgent

PillarAgent represents a storage agent instance that pillar-csi controller manages. Users create PillarAgent resources; the controller reconciles gRPC connectivity and populates status fields.

Field Description Default Validation
apiVersion string pillar-csi.bhyoo.com/v1alpha1
kind string PillarAgent
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata. Optional
spec PillarAgentSpec spec defines the desired state of PillarAgent. Required
status PillarAgentStatus status defines the observed state of PillarAgent. Optional

PillarAgentSpec

PillarAgentSpec defines the desired state of PillarAgent. Exactly one of nodeRef or external must be set (discriminated union).

Appears in:

Field Description Default Validation
nodeRef NodeRefSpec nodeRef references a Kubernetes Node whose agent is accessible via the node’s IP.
Mutually exclusive with external. 		Optional
external ExternalSpec external addresses a storage agent that lives outside the Kubernetes cluster.
Mutually exclusive with nodeRef. 		Optional

PillarAgentStatus

PillarAgentStatus defines the observed state of PillarAgent.

Appears in:

Field Description Default Validation
resolvedAddress string resolvedAddress is the IP address selected for gRPC communication with the agent. Optional
agentVersion string agentVersion is the version string reported by the connected agent. Optional
capabilities AgentCapabilities capabilities summarizes what the connected agent is capable of. Optional
discoveredPools DiscoveredPool array discoveredPools lists storage pools found on the agent at last reconcile. Optional
conditions Condition array conditions represent the current state of the PillarAgent resource.
Known condition types:
• “NodeExists” – the referenced K8s Node is present in the cluster.
• “AgentConnected” – the gRPC connection to the storage agent.
The reason field distinguishes the authentication level:
True / “Authenticated” – mTLS handshake succeeded; both sides verified.
True / “Dialed” – TCP connection established; no mTLS in use.
False / “TLSHandshakeFailed” – mTLS configured but handshake failed (cert error).
False / “HealthCheckFailed” – TCP-level or transport error.
False / “AgentUnhealthy” – agent reachable but reports degraded health.
False / “DialerNotConfigured”– no gRPC dialer is wired (dev/test only).
• “ExportsReady” – the agent’s export restore has completed and it
serves exports. Reasons:
True / “ExportsServing” – no export restore is pending (or it finished).
False / “ExportRestorePending” – the agent is restoring exports after a restart.
False / “ExportRestoreFailed” – the last restore attempt failed; it is retried.
Unknown – agent connectivity is not established.
• “Ready” – all checks pass; the target is ready to serve pools. 		Optional

PillarProtocol

PillarProtocol describes a reusable network-storage protocol configuration. It is node-independent: the same PillarProtocol can be referenced by multiple PillarStorageClass resources across different pools and targets. The controller resolves the target bind address at runtime from the relevant PillarAgent.

Field Description Default Validation
apiVersion string pillar-csi.bhyoo.com/v1alpha1
kind string PillarProtocol
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec PillarProtocolSpec
status PillarProtocolStatus

PillarProtocolSpec

PillarProtocolSpec defines the desired state of PillarProtocol.

Appears in:

Field Description Default Validation
protocol ProtocolSpec protocol selects the network storage protocol and its configuration.
Exactly one member must be set. 		Required

PillarProtocolStatus

PillarProtocolStatus defines the observed state of PillarProtocol.

Appears in:

Field Description Default Validation
storageClassCount integer storageClassCount is the number of PillarStorageClass resources that reference
this protocol. Maintained automatically by the reconciler. 		Optional
activeAgents string array activeAgents lists the names of PillarAgents currently serving
volumes via this protocol. Maintained automatically by the reconciler. 		Optional
conditions Condition array conditions represent the current state of the PillarProtocol resource.
Known condition types:
• “Ready” – the protocol configuration is valid and ready for use. 		Optional

PillarStorageClass

PillarStorageClass combines a PillarStore and a PillarProtocol to create a Kubernetes StorageClass. A validation webhook rejects incompatible backend/protocol combinations (e.g. a block backend with a file protocol). Parameter overrides allow fine-tuning per binding without changing the shared store or protocol resources.

Field Description Default Validation
apiVersion string pillar-csi.bhyoo.com/v1alpha1
kind string PillarStorageClass
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec PillarStorageClassSpec
status PillarStorageClassStatus

PillarStorageClassSpec

PillarStorageClassSpec defines the desired state of PillarStorageClass.

Appears in:

Field Description Default Validation
storeRef string storeRef is the name of the PillarStore to use for provisioning. MinLength: 1
Required
protocolRef string protocolRef is the name of the PillarProtocol used to expose volumes. MinLength: 1
Required
storageClass StorageClassTemplate storageClass configures the Kubernetes StorageClass that this binding
generates. The controller creates and owns the StorageClass; deleting
the PillarStorageClass also deletes the StorageClass. 		Optional
filesystem FilesystemConfig filesystem configures the filesystem axis for volumes of this binding:
which filesystem the node formats and which mount options it applies. 		Optional
overrides StorageClassOverrides overrides provides a fine-grained parameter layer on top of the
referenced store and protocol defaults. 		Optional

PillarStorageClassStatus

PillarStorageClassStatus defines the observed state of PillarStorageClass.

Appears in:

Field Description Default Validation
storageClassName string storageClassName is the name of the generated StorageClass. Optional
conditions Condition array conditions represent the current state of the PillarStorageClass resource.
Known condition types:
• “StoreReady” – the referenced PillarStore is in Ready state.
• “ProtocolValid” – the referenced PillarProtocol exists and is valid.
• “Compatible” – the pool backend and protocol are compatible
(e.g. block backend cannot be combined with a file protocol).
• “StorageClassCreated” – the Kubernetes StorageClass has been created.
• “Ready” – all checks pass; the binding is operational. 		Optional

PillarStore

PillarStore represents a specific storage pool on a PillarAgent. Users create PillarStore resources to declare that a pool is available for CSI volume provisioning; the controller validates availability and updates status.

Field Description Default Validation
apiVersion string pillar-csi.bhyoo.com/v1alpha1
kind string PillarStore
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata.
spec PillarStoreSpec
status PillarStoreStatus

PillarStoreSpec

PillarStoreSpec defines the desired state of PillarStore.

Appears in:

Field Description Default Validation
agentRef string agentRef is the name of the PillarAgent this pool lives on. MinLength: 1
Required
backend BackendSpec backend describes the storage backend and pool to use. Exactly one
member (zfs or lvm) must be set. 		Required

PillarStoreStatus

PillarStoreStatus defines the observed state of PillarStore.

Appears in:

Field Description Default Validation
capacity StoreCapacity capacity reflects the latest capacity reading for this pool. Optional
conditions Condition array conditions represent the current state of the PillarStore resource.
Known condition types:
• “AgentReady” – the referenced PillarAgent is in Ready state.
• “PoolDiscovered” – the pool named in spec.backend has been found on the agent
and the agent creates volumes in it where the store declares
(zfs.parentDataset, lvm.thinPool); reason BackendLayoutMismatch
otherwise.
• “BackendSupported” – the backend is listed in the agent’s capabilities.
• “Ready” – all checks pass; the pool can provision volumes. 		Optional

PillarVolumeState

PillarVolumeState tracks the lifecycle state of a single CSI volume provisioned by pillar-csi. The controller creates a PillarVolumeState during CreateVolume, updates it at each lifecycle stage, and deletes it during DeleteVolume.

The primary purpose of PillarVolumeState is to provide durable partial-failure state tracking: if CreateVolume creates the backend zvol but then crashes before ExportVolume returns, the PillarVolumeStatePhaseCreatePartial phase is already written to etcd, allowing the next CreateVolume call (or an automated recovery controller) to skip the backend-creation step and retry only the export.

Field Description Default Validation
apiVersion string pillar-csi.bhyoo.com/v1alpha1
kind string PillarVolumeState
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata. Optional
spec PillarVolumeStateSpec spec holds the immutable volume identity and routing parameters. Required
status PillarVolumeStateStatus status reflects the mutable lifecycle state of the volume. Optional

PillarVolumeStatePhase

Underlying type: string

PillarVolumeStatePhase describes the lifecycle phase of a CSI volume as tracked by the pillar-csi controller.

The phases map to VolumeState constants in the internal/csi package:

plaintext
PillarVolumeStatePhaseProvisioning     → in-progress CreateVolume (transient)
PillarVolumeStatePhaseCreatePartial    → StateCreatePartial (backend created, export failed)
PillarVolumeStatePhaseReady            → StateCreated (fully provisioned)
PillarVolumeStatePhaseControllerPublished → StateControllerPublished
PillarVolumeStatePhaseNodeStagePartial → StateNodeStagePartial
PillarVolumeStatePhaseNodeStaged       → StateNodeStaged
PillarVolumeStatePhaseNodePublished    → StateNodePublished

Validation:

  • Enum: [Provisioning CreatePartial Ready ControllerPublished NodeStagePartial NodeStaged NodePublished]

Appears in:

Field Description
Provisioning PillarVolumeStatePhaseProvisioning means CreateVolume has been started but
has not yet completed. This is a transient state; the controller should
advance it to CreatePartial or Ready before returning to the caller.
CreatePartial PillarVolumeStatePhaseCreatePartial means the backend storage resource
(zvol, LVM LV, etc.) was created successfully, but the ExportVolume
step failed. The volume exists on the storage node but is not yet
accessible over the network.
Recovery options:
• Retry CreateVolume: the controller re-attempts ExportVolume.
• Call DeleteVolume: the controller calls UnexportVolume (noop) and
then DeleteVolume on the agent to clean up the backend resource.
Ready PillarVolumeStatePhaseReady means CreateVolume completed fully: both the
backend resource and its network export (NVMe-oF target, iSCSI target,
NFS share) exist. Corresponds to StateCreated in VolumeStateMachine.
ControllerPublished PillarVolumeStatePhaseControllerPublished means ControllerPublishVolume has
succeeded. The initiator NQN has been granted access to the NVMe-oF
subsystem.
NodeStagePartial PillarVolumeStatePhaseNodeStagePartial means NodeStageVolume partially
succeeded: the NVMe-oF connect step completed but the mount step
failed. Corresponds to StateNodeStagePartial in VolumeStateMachine.
NodeStaged PillarVolumeStatePhaseNodeStaged means NodeStageVolume has succeeded.
The volume is formatted and mounted at the CSI staging target path.
NodePublished PillarVolumeStatePhaseNodePublished means NodePublishVolume has succeeded.
The staging path has been bind-mounted into a pod’s target path.

PillarVolumeStateSpec

PillarVolumeStateSpec defines the immutable identity and routing information for a CSI volume. Fields are populated by the controller at CreateVolume time and never changed thereafter.

Appears in:

Field Description Default Validation
volumeID string volumeID is the CSI volume ID assigned by the controller.
Format: <target-name>/<protocol-type>/<backend-type>/<agent-vol-id> 		MinLength: 1
Required
agentVolumeID string agentVolumeID is the volume identifier used in agent RPCs. The format
is “<pool>/<volume-name>” where pool is the storage pool name (e.g. ZFS
pool name), or just “<volume-name>” for backends with no pool prefix. 		MinLength: 1
Required
agentRef string agentRef is the name of the PillarAgent that hosts this volume. MinLength: 1
Required
backendType string backendType is the storage backend routing token (e.g. “zfs-zvol”,
“lvm-lv”). It is the backend member selected by the store’s
spec.backend union at CreateVolume time. 		Required
protocolType string protocolType is the network storage protocol routing token
(e.g. “nvmeof-tcp”). It is the protocol member selected by the
protocol’s spec.protocol union at CreateVolume time. 		Required
capacityBytes integer capacityBytes is the requested volume size in bytes. Minimum: 0
Optional
claimRef VolumeClaimRef claimRef identifies the PersistentVolumeClaim this volume was
provisioned for, when the provisioner named it (external-provisioner
--extra-create-metadata); its UID is read from the claim at the first
CreateVolume. The controller uses it to recognize a provisioning
attempt that was abandoned because its claim was removed before any
PersistentVolume was created. Without it the claim UID is derived from
the default “pvc-<claim UID>” volume name. 		Optional
resolved ResolvedVolumeConfig resolved is the effective per-volume configuration resolved at the
first CreateVolume attempt from the PillarStore, PillarProtocol,
PillarStorageClass overrides, StorageClass parameter documents and PVC
annotations (in that precedence order). It is replayed on every retry
so the volume keeps the settings it was provisioned with even when the
claim or the CRDs behind the overrides no longer exist. 		Optional

PillarVolumeStateStatus

PillarVolumeStateStatus reflects the controller-observed state of a PillarVolumeState.

Appears in:

Field Description Default Validation
phase PillarVolumeStatePhase phase is the current lifecycle phase of the volume.
See PillarVolumeStatePhase for the full state diagram. 		Enum: [Provisioning CreatePartial Ready ControllerPublished NodeStagePartial NodeStaged NodePublished]
Optional
partialFailure PartialFailureInfo partialFailure is populated whenever the volume is in a partial-failure
phase (CreatePartial, NodeStagePartial). It records what succeeded and
what failed so that the recovery controller can take the minimum
necessary corrective action. Cleared when the partial failure is
resolved. 		Optional
backendDevicePath string backendDevicePath is the device path returned by agent.CreateVolume
(e.g. “/dev/zvol/pool/pvc-abc123”). Persisted when the volume enters
the CreatePartial phase so that a retry of CreateVolume can skip the
backend-creation step and call agent.ExportVolume directly, using this
stored path rather than re-querying the agent.
Cleared when the volume reaches the Ready phase. 		Optional
exportInfo VolumeExportInfo exportInfo holds the network export parameters returned by ExportVolume.
Populated when phase is Ready or later. Used by DeleteVolume to
unmount the export after a controller restart without re-querying the
agent. 		Optional
publishedNodes VolumePublication array publishedNodes lists every node the volume is currently published to
by ControllerPublishVolume. ControllerPublishVolume rejects a publish
that is incompatible with an existing entry (for example a second node
for a SINGLE_NODE_* access mode); ControllerUnpublishVolume removes the
entry after the agent revoked the node’s access; DeleteVolume refuses
to delete a volume while this list is non-empty. Entries are also the
exact initiator set the storage target’s ACL must contain. 		Optional
exportSpec VolumeExportSpec exportSpec is the export configuration the controller requested at
CreateVolume time. It is the durable desired state the resync
controller uses to re-create the export after the storage node loses
its target state. Volumes created before this field existed have no
exportSpec and are reported via the ExportReconciled condition instead
of being recovered. 		Optional
publicationGeneration integer publicationGeneration is a monotonically increasing counter bumped by
exactly 1 on every status update that changes publishedNodes or sets
deleting. The value committed by that update is sent to the agent as
the fencing generation on AllowInitiator, DenyInitiator, UnexportVolume
and ReconcileState; the agent rejects any request carrying a lower
generation than the one it last applied. This closes the window where
a stale (former leader) controller’s in-flight RPC lands after a new
leader already changed the publication set. 		Minimum: 0
Optional
deleting boolean deleting is set by DeleteVolume before it removes the export and the
backend resource. It is written by a resourceVersion compare-and-swap
that only succeeds while publishedNodes is empty, so a volume can never
be concurrently published and deleted. ControllerPublishVolume rejects
reservations while deleting is true, and state resync skips the volume. 		Optional
conditions Condition array conditions represent the current observed state of the PillarVolumeState.
Known condition types:
• “BackendCreated” – the backend storage resource exists on the agent.
• “ExportCreated” – the network export exists on the agent.
• “Ready” – both backend and export exist; volume is usable. 		Optional

ProtocolOverrides

ProtocolOverrides is the per-binding or per-volume override document for the transport protocol. Exactly one member must be set, and it must match the protocol member configured on the referenced PillarProtocol.

Appears in:

Field Description Default Validation
nvmeofTcp NVMeOFTCPOverrides nvmeofTcp overrides NVMe-oF/TCP tunables; valid only when the
protocol’s member is nvmeofTcp. 		Optional

ProtocolSpec

ProtocolSpec describes the transport protocol of a PillarProtocol. Exactly one member must be set: the member name selects the protocol (nvmeofTcp) and its value carries that protocol’s configuration.

Per-binding and per-volume override documents use ProtocolOverrides, which keeps only the tunable subset.

Appears in:

Field Description Default Validation
nvmeofTcp NVMeOFTCPConfig nvmeofTcp holds NVMe-oF/TCP configuration. Optional

ReclaimPolicy

Underlying type: string

ReclaimPolicy mirrors corev1.PersistentVolumeReclaimPolicy for inline use.

Validation:

  • Enum: [Delete Retain]

Appears in:

Field Description
Delete
Retain

ResolvedVolumeConfig

ResolvedVolumeConfig is the durable record of the effective configuration a volume was provisioned with. The shapes reuse the CRD union documents so the stored object reads exactly like the layers it was resolved from.

Appears in:

Field Description Default Validation
backend BackendSpec backend is the effective storage backend configuration: the store’s
spec.backend with binding, StorageClass-document and PVC tunable
overrides applied. 		Required
protocol ProtocolSpec protocol is the effective transport configuration: the protocol’s
spec.protocol with binding, StorageClass-document and PVC tunable
overrides applied. 		Required
filesystem FilesystemConfig filesystem is the effective filesystem configuration the node applies
when the volume is a Filesystem-mode mount. 		Optional

StorageClassOverrides

StorageClassOverrides is the optional layer of per-binding parameter overrides applied on top of the store and protocol defaults.

Appears in:

Field Description Default Validation
backend BackendOverrides backend contains backend tunable overrides (same shape as the
pillar-csi.bhyoo.com/backend PVC annotation document). 		Optional
protocol ProtocolOverrides protocol contains protocol tunable overrides (same shape as the
pillar-csi.bhyoo.com/protocol PVC annotation document). 		Optional

StorageClassTemplate

StorageClassTemplate defines the parameters used to generate a Kubernetes StorageClass from this binding.

A StorageClass is immutable apart from allowVolumeExpansion, so a change to reclaimPolicy or volumeBindingMode makes the controller delete and re-create the StorageClass. Tunable overrides do not feed the StorageClass parameters — they are resolved from live CRs at CreateVolume — so editing them never forces a StorageClass recreation.

Appears in:

Field Description Default Validation
name string name is the name of the generated StorageClass.
Defaults to the PillarStorageClass’s own name when omitted.
Immutable: PVCs reference their StorageClass by name. 		MinLength: 1
Optional
reclaimPolicy ReclaimPolicy reclaimPolicy determines what happens to a PersistentVolume when its
PersistentVolumeClaim is deleted. 		Delete Enum: [Delete Retain]
Optional
volumeBindingMode VolumeBindingMode volumeBindingMode controls when volume binding and dynamic provisioning occur. Immediate Enum: [Immediate WaitForFirstConsumer]
Optional
allowVolumeExpansion boolean allowVolumeExpansion enables online volume expansion.
When unset the controller derives the value from backend capabilities. 		Optional

StoreCapacity

StoreCapacity reports the measured capacity of the pool.

Appears in:

Field Description Default Validation
total Quantity total is the gross capacity of the pool. Optional
available Quantity available is the free capacity available for new volumes. Optional
used Quantity used is the amount of capacity already consumed. Optional

VolumeBindingMode

Underlying type: string

VolumeBindingMode mirrors storagev1.VolumeBindingMode for inline use.

Validation:

  • Enum: [Immediate WaitForFirstConsumer]

Appears in:

Field Description
Immediate
WaitForFirstConsumer

VolumeClaimRef

VolumeClaimRef identifies the PersistentVolumeClaim a volume was provisioned for. The UID pins one claim: a claim deleted and re-created under the same name is a different claim.

Appears in:

Field Description Default Validation
uid string uid is the UID of the PersistentVolumeClaim. MinLength: 1
Required
namespace string namespace is the namespace of the PersistentVolumeClaim. Optional
name string name is the name of the PersistentVolumeClaim. Optional

VolumeExportInfo

VolumeExportInfo holds the network export information returned by the agent’s ExportVolume RPC. These values are stored durably so that DeleteVolume can tear down the export after a controller restart.

Appears in:

Field Description Default Validation
targetID string targetID is the NVMe Qualified Name (NQN) of the NVMe-oF subsystem. Optional
address string address is the IP address of the storage node (same as
PillarAgent.Status.ResolvedAddress with the port stripped). 		Optional
port integer port is the TCP port on which the NVMe-oF target listens. Optional
volumeRef string volumeRef is the protocol-level reference for this volume (the NVMe-oF
subsystem name). 		Optional

VolumeExportSpec

VolumeExportSpec is the export configuration requested from the agent at CreateVolume time. It is the durable desired state from which the controller re-creates the export after the storage node loses its target state (agent restart, node reboot), independent of later StorageClass or PillarProtocol changes.

Appears in:

Field Description Default Validation
bindAddress string bindAddress is the storage node address the target listens on. MinLength: 1
Required
port integer port is the TCP port the target listens on; 0 selects the protocol’s
default port, exactly as in the original export request. 		Maximum: 65535
Minimum: 0
Required
aclEnabled boolean aclEnabled is true when the target admits only the initiators of
published nodes; false admits any initiator. 		Required
inCapsuleDataSize integer inCapsuleDataSize is the NVMe-oF/TCP in-capsule data size in bytes the
export requires on its port; absent when the export accepts the port’s
value. NVMe-oF/TCP only. 		Minimum: 1024
Optional

VolumePublication

VolumePublication records one node to which ControllerPublishVolume granted access to this volume. The list of publications is the durable source of truth for CSI publish exclusivity (a SINGLE_NODE_* volume may be published to at most one node) and for the initiator ACL set the storage target must hold. An entry is written before the agent grants access and removed only after the agent revoked it, so a crash between the two steps leaves the record fail-closed.

Appears in:

Field Description Default Validation
nodeID string nodeID is the CSI node_id (Kubernetes node name) the volume is
published to. 		MinLength: 1
Required
initiatorID string initiatorID is the protocol-specific initiator identity granted access
(NVMe-oF host NQN, iSCSI IQN, or the node ID for file protocols). It is
recorded so the grant can be revoked even after the node’s CSINode
object is gone. 		MinLength: 1
Required
accessMode string accessMode is the CSI VolumeCapability access mode name requested by
the publish (e.g. “SINGLE_NODE_WRITER”, “MULTI_NODE_READER_ONLY”). 		MinLength: 1
Required
readonly boolean readonly mirrors ControllerPublishVolumeRequest.readonly. Optional
revoking boolean revoking is set by ControllerUnpublishVolume in the same update that
allocates the fencing generation for the revoke, and the record is
removed once the agent revoked the initiator. A revoking record still
occupies the volume for exclusivity (fail-closed) but is not part of the
initiator set the target should grant: state recovery must exclude it,
and a publish to the same node is rejected until the unpublish finishes. 		Optional

ZFSBackendConfig

ZFSBackendConfig holds ZFS-specific pool and dataset settings.

Appears in:

Field Description Default Validation
volumeType ZFSVolumeType volumeType selects the ZFS volume kind. Only “zvol” is implemented. zvol Enum: [zvol]
Optional
pool string pool is the ZFS pool name (e.g. “hot-data”). MinLength: 1
Required
parentDataset string parentDataset is the ZFS dataset path under which pillar-csi will
create per-volume zvols (e.g. “k8s”). It must equal the parentDataset
of the agent’s backend configuration for this pool (chart
agent.backends[].zfs.parentDataset; empty = pool root): on a mismatch
the store is not Ready (PoolDiscovered=False, BackendLayoutMismatch)
and CreateVolume fails instead of placing volumes elsewhere. 		Optional
properties object (keys:string, values:string) properties are arbitrary ZFS properties applied to every volume created
in this pool (e.g. compression, volblocksize). 		Optional

ZFSBackendOverrides

ZFSBackendOverrides holds the per-volume-tunable subset of ZFSBackendConfig. Structural placement fields (pool, parentDataset, volumeType) are not part of this type and are rejected with their path by the shared document decoder.

Appears in:

Field Description Default Validation
properties object (keys:string, values:string) properties are arbitrary ZFS properties that override pool defaults
(e.g. volblocksize, compression). Entries merge key-wise onto the
PillarStore’s zfs.properties. 		Optional

ZFSVolumeType

Underlying type: string

ZFSVolumeType enumerates the ZFS volume kinds the driver can create.

Validation:

  • Enum: [zvol]

Appears in:

Field Description
zvol ZFSVolumeTypeZvol creates block-device zvols. It is currently the
only implemented kind; zfs datasets are a future variant.

Edit this page on GitHub

Type to search every page.