StoragePool Resource Kind

Kind: StoragePoolapiVersion: pivirt.hu/v1Aliases: pool, pools, storage

The StoragePool resource defines a local or network storage target on the hypervisor host. Storage pools provide the volume backing for virtual machine disks (VirtualDisk), ISO installation images, and template caches across multiple filesystem backends.

---

Accepted Kind Aliases

In pivirtctl commands, any of the following aliases are recognized: StoragePool, storagepool, storagepools, storage-pool, storage-pools, pool, pools, storage.

---

Example Manifests

Directory Pool (dir)

apiVersion: pivirt.hu/v1
kind: StoragePool
metadata:
  name: default
  labels:
    tier: standard
spec:
  type: dir
  path: /var/lib/pivirt/storage/default
  active: true
  options:
    preallocation: falloc
    discard: unmap

Ceph / RADOS Pool (ceph)

apiVersion: pivirt.hu/v1
kind: StoragePool
metadata:
  name: ceph-nvme
  labels:
    tier: high-iops
    storage-class: distributed
spec:
  type: ceph
  active: true
  options:
    monitors: "10.10.0.1:6789,10.10.0.2:6789"
    pool: vms
    user: admin
    keyring: /etc/ceph/ceph.client.admin.keyring

iSCSI LUN Pool (iscsi)

apiVersion: pivirt.hu/v1
kind: StoragePool
metadata:
  name: iscsi-san
  labels:
    tier: san
spec:
  type: iscsi
  path: /mnt/pivirt-iscsi
  active: true
  options:
    portal: "10.10.0.20:3260"
    target: "iqn.2024-01.hu.pilab:storage.target01"
    lun: "0"
    fsType: "ext4"
    mkfs: "true"

NFS Network Pool (nfs)

apiVersion: pivirt.hu/v1
kind: StoragePool
metadata:
  name: nfs-shared
  labels:
    tier: shared
spec:
  type: nfs
  path: /mnt/pivirt-nfs
  active: true
  options:
    server: "10.10.0.10"
    export: "/exports/vms"
    version: "4.2"
    mountOptions: "hard,intr"

---

Specification Reference (spec)

Field	Type	Required	Default	Description
type	string	No	dir	Storage backend type: dir, nfs, iscsi, ceph
path	string	No	/var/lib/pivirt/storage/<name>	Local directory path or mount point
active	bool	No	true	Whether the pool is active and available for allocations
options	map[string]string	No	{}	Backend-specific tuning options

Supported Storage Backend Types

1. dir (Default Filesystem Directory):
   • Stores disk images as sparse .qcow2 or .raw files in a local POSIX filesystem.
   • Key options: mode (directory octal permissions, e.g. 0755).
2. nfs (Network File System):
   • Mounts an external NFS export onto the hypervisor node.
   • Key options: server (NFS server hostname or IP), export (remote exported path), version (3, 4, 4.0, 4.1, 4.2), mountOptions, softMount, readOnly.
3. iscsi (iSCSI Block LUN):
   • Connects to an iSCSI portal and targets a LUN, mounting it formatted as ext4 or xfs, or exposing it as a raw device.
   • Key options: portal, target, lun, fsType (ext4, xfs, none), mkfs, chapUser, chapPassword.
4. ceph (Ceph / RADOS Block Device Pool):
   • Directly backs VirtualDisks on Ceph distributed block storage (rbd).
   • Key options: monitors (or monHost), pool (RBD pool name), user, keyring, secret, conf.

---

CLI Management Examples

# Apply a new storage pool manifest
pivirtctl apply -f pool-fast.yaml

# List all storage pools (using plural alias)
pivirtctl get pools

# List using multi-word alias
pivirtctl get storage pools

# Query details as YAML
pivirtctl get pool/fast-nvme -o yaml

# Inspect pool status and capacity
pivirtctl describe pool fast-nvme

# Delete a storage pool
pivirtctl delete pool fast-nvme