CRD Reference

This page documents the Custom Resource Definitions (CRDs) that DirectPV creates and manages.

Overview

DirectPV uses the following CRDs:

CRD Description
DirectPVDrive Represents a drive managed by DirectPV.
DirectPVVolume Represents a volume provisioned on a drive.
DirectPVNode Represents a node with discovered devices.
DirectPVInitRequest Represents a drive initialization request.

All CRDs use:

  • API Group: directpv.min.io
  • API Version: v1beta1
  • Scope: Cluster

DirectPVDrive

Represents a drive that DirectPV manages for volume provisioning.

Spec fields

Field Type Required Description
unschedulable boolean No When true, marks the drive as unavailable for volume scheduling.
relabel boolean No When true, indicates the drive filesystem should be relabeled.

Status fields

Field Type Required Description
totalCapacity int64 Yes Total storage capacity of the drive in bytes.
allocatedCapacity int64 Yes Capacity allocated to volumes in bytes.
freeCapacity int64 Yes Free capacity available in bytes. Deprecated: calculated as totalCapacity - allocatedCapacity.
fsuuid string Yes Filesystem UUID identifying the drive.
status string Yes Current drive status. See Drive status values.
topology map[string]string Yes Topology labels (node, zone, region, rack).
make string No Drive manufacturer information.
conditions []Condition No Array of condition objects for error states. See Drive conditions.

Drive status values

Status Description
Ready Drive is ready for volume scheduling.
Lost Associated data by FSUUID is lost.
Error Drive is in error state and volume scheduling is prevented.
Removed Drive is removed.
Moving Drive is moving volumes.
Repairing Drive filesystem is being repaired.

Drive conditions

Condition type Description
MountError Drive has a mount error.
MultipleMatches Drive has multiple matches.
IOError Drive has an I/O error.
RelabelError Drive has a relabel error.

Drive labels

DirectPV applies these labels to drive resources:

Label Description
directpv.min.io/node Node ID where the drive is located.
directpv.min.io/drive-name Drive name (for example, sda, nvme0n1).
directpv.min.io/access-tier Access tier (Default, Warm, Hot, Cold).
directpv.min.io/version API version.
directpv.min.io/created-by Component that created the resource.
directpv.min.io/migrated Migration flag for legacy DirectCSI drives.
directpv.min.io/suspend Suspension flag (true or false).

Example 

apiVersion: directpv.min.io/v1beta1
kind: DirectPVDrive
metadata:
  name: 8a1b2c3d-4e5f-6789-abcd-ef0123456789
  labels:
    directpv.min.io/node: node1
    directpv.min.io/drive-name: nvme0n1
    directpv.min.io/access-tier: hot
spec:
  unschedulable: false
status:
  totalCapacity: 1000204886016
  allocatedCapacity: 536870912
  freeCapacity: 999667015104
  fsuuid: a1b2c3d4-e5f6-7890-abcd-ef0123456789
  status: Ready
  topology:
    directpv.min.io/node: node1
  make: Samsung

DirectPVVolume

Represents a volume provisioned on a DirectPV drive.

Spec fields

DirectPVVolume has no spec fields. All configuration is in the status section.

Status fields

Field Type Required Description
dataPath string Yes Path where volume data is stored on the drive.
stagingTargetPath string Yes Kubernetes CSI staging target path.
targetPath string Yes Kubernetes CSI target path where volume is published.
fsuuid string Yes Filesystem UUID of the associated drive.
totalCapacity int64 Yes Total capacity allocated to volume in bytes.
availableCapacity int64 Yes Currently available capacity in bytes.
usedCapacity int64 Yes Currently used capacity in bytes.
status string Yes Current volume status. See Volume status values.
requestParameters map[string]string No CSI request parameters for volume creation.
preferredAccessibleTopology []map[string]string No Preferred topology for volume accessibility.
requisiteAccessibleTopology []map[string]string No Required topology for volume accessibility.
conditions []Condition No Array of condition objects.

Volume status values

Status Description
Pending Volume creation in progress.
Ready Volume is ready for use.

Volume conditions

Condition type Description
Lost Volume is lost because the associated drive was removed.

Volume labels

DirectPV applies these labels to volume resources:

Label Description
directpv.min.io/node Node ID where the drive is located.
directpv.min.io/drive Associated drive ID.
directpv.min.io/drive-name Associated drive name.
directpv.min.io/pod.name Associated pod name.
directpv.min.io/pod.namespace Associated pod namespace.
directpv.min.io/pod.statefulset Associated StatefulSet name.
directpv.min.io/version API version.
directpv.min.io/created-by Component that created the resource.
directpv.min.io/migrated Migration flag.
directpv.min.io/suspend Suspension flag.
directpv.min.io/tenant Tenant name.

Example 

apiVersion: directpv.min.io/v1beta1
kind: DirectPVVolume
metadata:
  name: pvc-12345678-90ab-cdef-1234-567890abcdef
  labels:
    directpv.min.io/node: node1
    directpv.min.io/drive: 8a1b2c3d-4e5f-6789-abcd-ef0123456789
    directpv.min.io/drive-name: nvme0n1
    directpv.min.io/pod.name: minio-0
    directpv.min.io/pod.namespace: default
status:
  dataPath: /var/lib/directpv/mnt/8a1b2c3d-4e5f-6789-abcd-ef0123456789/pvc-12345678-90ab-cdef-1234-567890abcdef
  stagingTargetPath: /var/lib/kubelet/plugins/kubernetes.io/csi/pv/pvc-12345678-90ab-cdef-1234-567890abcdef/globalmount
  targetPath: /var/lib/kubelet/pods/abcd1234-5678-90ab-cdef-1234567890ab/volumes/kubernetes.io~csi/pvc-12345678-90ab-cdef-1234-567890abcdef/mount
  fsuuid: a1b2c3d4-e5f6-7890-abcd-ef0123456789
  totalCapacity: 536870912
  availableCapacity: 268435456
  usedCapacity: 268435456
  status: Ready

DirectPVNode

Represents a node with devices that DirectPV has discovered.

Spec fields

Field Type Required Description
refresh boolean No When true, signals the node to refresh device discovery.

Status fields

Field Type Required Description
devices []Device Yes List of devices discovered on the node.
conditions []Condition No Array of condition objects.

Device structure

Field Type Required Description
name string Yes Device name (for example, /dev/sda).
id string Yes Unique device ID (WWN or serial number).
majorMinor string Yes Device major:minor number.
size int64 Yes Device size in bytes.
make string No Device manufacturer information.
fsType string No Filesystem type if formatted.
fsuuid string No Filesystem UUID if formatted.
deniedReason string No Reason why device was denied for DirectPV use.

Node labels

Label Description
directpv.min.io/node Node ID.
directpv.min.io/version API version.
directpv.min.io/created-by Component that created the resource.

Example 

apiVersion: directpv.min.io/v1beta1
kind: DirectPVNode
metadata:
  name: node1
  labels:
    directpv.min.io/node: node1
spec:
  refresh: false
status:
  devices:
    - name: /dev/nvme0n1
      id: nvme.samsung-MZQLB960HAJR-00007-S4YNNE0N123456
      majorMinor: "259:0"
      size: 960197124096
      make: Samsung
    - name: /dev/sda
      id: scsi-SATA_WDC_WD10EZEX-00B_WD-WMC3F0123456
      majorMinor: "8:0"
      size: 1000204886016
      make: WDC
      deniedReason: "in use by system"

DirectPVInitRequest

Represents a request to initialize drives for DirectPV management.

Spec fields

Field Type Required Description
devices []InitDevice Yes List of devices to initialize.

InitDevice structure

Field Type Required Description
id string Yes Device ID (unique identifier on node).
name string Yes Device name (for example, /dev/sda).
force boolean Yes Force initialization even if data exists.

Status fields

Field Type Required Description
status string Yes Current initialization request status. See Init status values.
results []InitDeviceResult Yes Results of initialization for each device.

Init status values

Status Description
Pending Initialization request is still pending.
Processed Initialization request has been processed.
Error Initialization request failed.

InitDeviceResult structure

Field Type Required Description
name string Yes Device name.
error string No Error message if initialization failed.

Init request labels

Label Description
directpv.min.io/node Node ID where initialization occurs.
directpv.min.io/version API version.
directpv.min.io/created-by Component that created the resource.
directpv.min.io/request-id Request ID.

Example 

apiVersion: directpv.min.io/v1beta1
kind: DirectPVInitRequest
metadata:
  name: c24e22f5-d582-49ba-a883-2ce56909904e
  labels:
    directpv.min.io/node: node1
    directpv.min.io/request-id: c24e22f5-d582-49ba-a883-2ce56909904e
spec:
  devices:
    - id: nvme.samsung-MZQLB960HAJR-00007-S4YNNE0N123456
      name: /dev/nvme0n1
      force: false
status:
  status: Processed
  results:
    - name: /dev/nvme0n1

Condition structure

All CRDs use standard Kubernetes conditions:

Field Type Description
type string Condition type (CamelCase, max 316 characters).
status string One of: True, False, Unknown.
reason string Reason for condition (CamelCase, max 1024 characters).
message string Human-readable message (max 32768 characters).
lastTransitionTime time Timestamp of last status change.
observedGeneration int64 Generation number when condition was set.