virsh-pool-delete

Delete the underlying storage system for the storage pool specified by name or UUID (determine using virsh pool-list)

$ virsh pool-delete --pool [name|uuid]

virsh pool-delete pool-name [--metadata-only]

pool-name
    The name of the storage pool to be deleted. This is a mandatory argument that identifies the specific pool to be targeted for complete removal.

--metadata-only
    An optional flag. When this flag is specified, the virsh pool-delete command will only remove the pool's definition from libvirt's configuration. It will not attempt to destroy or delete the actual underlying storage data, files, or devices associated with the pool. This is useful when the physical storage is managed externally or needs to be preserved.

The virsh pool-delete command is a powerful and destructive operation used to completely remove a previously defined storage pool from libvirt and, by default, its underlying storage resources. A storage pool represents a managed collection of physical storage, such as directories, LVM volume groups, or iSCSI targets, from which virtual machine disks (volumes) are allocated.

When this command is executed, libvirt first attempts to stop and destroy the pool's operations (e.g., unmount a filesystem, deactivate an LVM volume group) and then proceeds to permanently delete the actual data and resources associated with the pool (e.g., recursively delete a directory for a 'dir' type pool). Finally, the pool's definition is removed from the libvirt daemon.

The --metadata-only option is crucial for scenarios where you only wish to remove the pool's definition from libvirt while leaving the actual physical storage data and associated files or devices completely intact. It is paramount to ensure that no virtual machines are actively using volumes from the targeted pool before executing pool-delete without --metadata-only, as this will lead to irreversible data loss and potential corruption or failure of those virtual machines.

Irreversible Data Loss: By default, virsh pool-delete is a highly destructive command. It will attempt to permanently remove the underlying storage resources (e.g., delete directories, unmount filesystems, remove LVM logical volumes) managed by libvirt for the specified pool. This action is irreversible and will lead to permanent data loss for anything stored within that pool. Always ensure you have comprehensive backups or explicitly use the --metadata-only option if you intend to preserve the physical storage.

Impact on Virtual Machines: If virtual machines are actively using storage volumes residing within the pool being deleted, executing pool-delete without the --metadata-only option will result in immediate failure, data corruption, or inability to boot for those virtual machines. It is absolutely critical to verify that no VMs are dependent on the pool's volumes before proceeding. Use commands such as virsh vol-list pool-name to list volumes and virsh domblklist domain-name to check VM disk usage. Migrate or delete dependent VMs/volumes beforehand.

Distinction from pool-undefine: It is crucial to understand that virsh pool-delete is not the same as virsh pool-undefine. pool-undefine solely removes the pool's definition from libvirt without touching the underlying storage, making it a much safer operation for simply tidying up libvirt's configuration. pool-delete, conversely, is a full destructive removal.

Libvirt does not typically offer a 'dry run' option for destructive commands like pool-delete. Always carefully review the target pool's name and its contents (virsh vol-list pool-name) before execution to prevent accidental data loss.

If the pool is active when pool-delete is executed, libvirt will attempt to automatically destroy (deactivate) it before proceeding with the deletion of its contents and definition. However, if the pool is in use or encounters unresolvable issues during deactivation, the pool-delete command might also fail.

The virsh command-line tool is the primary interface for managing libvirt, the open-source virtualization management library. Libvirt was first released in 2005 and has since become a standard API for interacting with various virtualization technologies, including KVM, QEMU, Xen, VMware ESX, and more. The pool-delete subcommand, like other storage pool management commands (pool-define, pool-start, pool-list, etc.), was introduced as part of libvirt's comprehensive storage management capabilities, designed to provide a unified way to manage heterogeneous storage backends for virtual machines. Its development reflects the critical need for robust and flexible control over VM disk provisioning and lifecycle.

virsh(1), virsh pool-list(1), virsh pool-define(1), virsh pool-start(1), virsh pool-destroy(1), virsh pool-undefine(1), virsh vol-list(1), virsh vol-delete(1)