community.general.proxmox_disk module – Management of a disk of a Qemu(KVM) VM in a Proxmox VE cluster

Note

This module is part of the community.general collection (version 10.0.1).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.general. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: community.general.proxmox_disk.

New in community.general 5.7.0

Synopsis

• Allows you to perform some supported operations on a disk in Qemu(KVM) Virtual Machines in a Proxmox VE cluster.

Requirements

The below requirements are needed on the host that executes this module.

• proxmoxer

• requests

Parameters

Parameter	Comments
aio string	AIO type to use. Choices: "native" "threads" "io_uring"
api_host string / required	Specify the target host of the Proxmox VE cluster.
api_password string	Specify the password to authenticate with. You can use PROXMOX_PASSWORD environment variable.
api_port integer added in community.general 9.1.0	Specify the target port of the Proxmox VE cluster. Uses the PROXMOX_PORT environment variable if not specified.
api_token_id string added in community.general 1.3.0	Specify the token ID. Requires proxmoxer>=1.1.0 to work.
api_token_secret string added in community.general 1.3.0	Specify the token secret. Requires proxmoxer>=1.1.0 to work.
api_user string / required	Specify the user to authenticate with.
backup boolean	Whether the drive should be included when making backups. Choices: false true
bps_max_length integer	Maximum length of total r/w I/O bursts in seconds.
bps_rd_max_length integer	Maximum length of read I/O bursts in seconds.
bps_wr_max_length integer	Maximum length of write I/O bursts in seconds.
bwlimit integer	Override I/O bandwidth limit (in KB/s). Used only when state=moved.
cache string	The drive’s cache mode. Choices: "none" "writethrough" "writeback" "unsafe" "directsync"
create string	With create flag you can control behavior of state=present. When create=disabled it will not create new disk (if not exists) but will update options in existing disk. When create=regular it will either create new disk (if not exists) or update options in existing disk. When create=forced it will always create new disk (if disk exists it will be detached and left unused). Choices: "disabled" "regular" ← (default) "forced"
cyls integer	Force the drive’s physical geometry to have a specific cylinder count.
delete_moved boolean	Delete the original disk after successful copy. By default the original disk is kept as unused disk. Used only when state=moved. Choices: false true
detect_zeroes boolean	Control whether to detect and try to optimize writes of zeroes. Choices: false true
discard string	Control whether to pass discard/trim requests to the underlying storage. Choices: "ignore" "on"
disk string / required	The disk key (unused[n], ide[n], sata[n], scsi[n] or virtio[n]) you want to operate on. Disk buses (IDE, SATA and so on) have fixed ranges of n that accepted by Proxmox API. For IDE: 0-3; for SCSI: 0-30; for SATA: 0-5; for VirtIO: 0-15; for Unused: 0-255.
format string	The drive’s backing file’s data format. Choices: "raw" "cow" "qcow" "qed" "qcow2" "vmdk" "cloop"
heads integer	Force the drive’s physical geometry to have a specific head count.
import_from string	Import volume from this existing one. Volume string format <STORAGE>:<VMID>/<FULL_NAME> or <ABSOLUTE_PATH>/<FULL_NAME> Attention! Only root can use absolute paths. This parameter is mutually exclusive with size. Increase timeout parameter when importing large disk images or using slow storage.
iops integer	Maximum total r/w I/O in operations per second. You can specify either total limit or per operation (mutually exclusive with iops_rd and iops_wr).
iops_max integer	Maximum unthrottled total r/w I/O pool in operations per second.
iops_max_length integer	Maximum length of total r/w I/O bursts in seconds.
iops_rd integer	Maximum read I/O in operations per second. You can specify either read or total limit (mutually exclusive with iops).
iops_rd_max integer	Maximum unthrottled read I/O pool in operations per second.
iops_rd_max_length integer	Maximum length of read I/O bursts in seconds.
iops_wr integer	Maximum write I/O in operations per second. You can specify either write or total limit (mutually exclusive with iops).
iops_wr_max integer	Maximum unthrottled write I/O pool in operations per second.
iops_wr_max_length integer	Maximum length of write I/O bursts in seconds.
iothread boolean	Whether to use iothreads for this drive (only for SCSI and VirtIO) Choices: false true
iso_image string added in community.general 8.1.0	The ISO image to be mounted on the specified in disk CD-ROM. media=cdrom needs to be specified for this option to work. Image string format: <STORAGE>:iso/<ISO_NAME> to mount ISO. cdrom to use physical CD/DVD drive. none to unmount image from existent CD-ROM or create empty CD-ROM drive.
mbps float	Maximum total r/w speed in megabytes per second. Can be fractional but use with caution - fractionals less than 1 are not supported officially. You can specify either total limit or per operation (mutually exclusive with mbps_rd and mbps_wr).
mbps_max float	Maximum unthrottled total r/w pool in megabytes per second.
mbps_rd float	Maximum read speed in megabytes per second. You can specify either read or total limit (mutually exclusive with mbps).
mbps_rd_max float	Maximum unthrottled read pool in megabytes per second.
mbps_wr float	Maximum write speed in megabytes per second. You can specify either write or total limit (mutually exclusive with mbps).
mbps_wr_max float	Maximum unthrottled write pool in megabytes per second.
media string	The drive’s media type. Choices: "cdrom" "disk"
name string	The unique name of the VM. You can specify either name or vmid or both of them.
queues integer	Number of queues (SCSI only).
replicate boolean	Whether the drive should considered for replication jobs. Choices: false true
rerror string	Read error action. Choices: "ignore" "report" "stop"
ro boolean	Whether the drive is read-only. Choices: false true
scsiblock boolean	Whether to use scsi-block for full passthrough of host block device. Can lead to I/O errors in combination with low memory or high memory fragmentation on host. Choices: false true
secs integer	Force the drive’s physical geometry to have a specific sector count.
serial string	The drive’s reported serial number, url-encoded, up to 20 bytes long.
shared boolean	Mark this locally-managed volume as available on all nodes. This option does not share the volume automatically, it assumes it is shared already! Choices: false true
size string	Desired volume size in GB to allocate when state=present (specify size without suffix). New (or additional) size of volume when state=resized. With the + sign the value is added to the actual size of the volume and without it, the value is taken as an absolute one.
snapshot boolean	Control qemu’s snapshot mode feature. If activated, changes made to the disk are temporary and will be discarded when the VM is shutdown. Choices: false true
ssd boolean	Whether to expose this drive as an SSD, rather than a rotational hard disk. Choices: false true
state string	Indicates desired state of the disk. state=present can be used to create, replace disk or update options in existing disk. It will create missing disk or update options in existing one by default. See the create parameter description to control behavior of this option. Some updates on options (like cache) are not being applied instantly and require VM restart. Use state=detached to detach existing disk from VM but do not remove it entirely. When state=detached and disk is unused[n] it will be left in same state (not removed). state=moved may be used to change backing storage for the disk in bounds of the same VM or to send the disk to another VM (using the same backing storage). state=resized intended to change the disk size. As of Proxmox 7.2 you can only increase the disk size because shrinking disks is not supported by the PVE API and has to be done manually. To entirely remove the disk from backing storage use state=absent. Choices: "present" ← (default) "resized" "detached" "moved" "absent"
storage string	The drive’s backing storage. Used only when state is present.
target_disk string	The config key the disk will be moved to on the target VM (for example, ide0 or scsi1). Default is the source disk key. Used only when state=moved.
target_storage string	Move the disk to this storage when state=moved. You can move between storages only in scope of one VM. Mutually exclusive with target_vmid. Consider increasing timeout in case of large disk images or slow storage backend.
target_vmid integer	The (unique) ID of the VM where disk will be placed when state=moved. You can move disk between VMs only when the same storage is used. Mutually exclusive with target_vmid.
timeout integer	Timeout in seconds to wait for slow operations such as importing disk or moving disk between storages. Used only when state is present or moved. Default: 600
trans string	Force disk geometry bios translation mode. Choices: "auto" "lba" "none"
validate_certs boolean	If false, SSL certificates will not be validated. This should only be used on personally controlled sites using self-signed certificates. Choices: false ← (default) true
vmid integer	The unique ID of the VM. You can specify either vmid or name or both of them.
werror string	Write error action. Choices: "enospc" "ignore" "report" "stop"
wwn string	The drive’s worldwide name, encoded as 16 bytes hex string, prefixed by 0x.

Attributes

Attribute	Support	Description
action_group	Action group: community.general.proxmox added in community.general 9.0.0	Use group/community.general.proxmox in module_defaults to set defaults for this module.
check_mode	Support: none	Can run in check_mode and return changed status prediction without modifying target.
diff_mode	Support: none	Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode.

Examples

- name: Create new disk in VM (do not rewrite in case it exists already)
  community.general.proxmox_disk:
    api_host: node1
    api_user: root@pam
    api_token_id: token1
    api_token_secret: some-token-data
    name: vm-name
    disk: scsi3
    backup: true
    cache: none
    storage: local-zfs
    size: 5
    state: present

- name: Create new disk in VM (force rewrite in case it exists already)
  community.general.proxmox_disk:
    api_host: node1
    api_user: root@pam
    api_token_id: token1
    api_token_secret: some-token-data
    vmid: 101
    disk: scsi3
    format: qcow2
    storage: local
    size: 16
    create: forced
    state: present

- name: Update existing disk
  community.general.proxmox_disk:
    api_host: node1
    api_user: root@pam
    api_token_id: token1
    api_token_secret: some-token-data
    vmid: 101
    disk: ide0
    backup: false
    ro: true
    aio: native
    state: present

- name: Grow existing disk
  community.general.proxmox_disk:
    api_host: node1
    api_user: root@pam
    api_token_id: token1
    api_token_secret: some-token-data
    vmid: 101
    disk: sata4
    size: +5G
    state: resized

- name: Detach disk (leave it unused)
  community.general.proxmox_disk:
    api_host: node1
    api_user: root@pam
    api_token_id: token1
    api_token_secret: some-token-data
    name: vm-name
    disk: virtio0
    state: detached

- name: Move disk to another storage
  community.general.proxmox_disk:
    api_host: node1
    api_user: root@pam
    api_password: secret
    vmid: 101
    disk: scsi7
    target_storage: local
    format: qcow2
    state: moved

- name: Move disk from one VM to another
  community.general.proxmox_disk:
    api_host: node1
    api_user: root@pam
    api_token_id: token1
    api_token_secret: some-token-data
    vmid: 101
    disk: scsi7
    target_vmid: 201
    state: moved

- name: Remove disk permanently
  community.general.proxmox_disk:
    api_host: node1
    api_user: root@pam
    api_password: secret
    vmid: 101
    disk: scsi4
    state: absent

- name: Mount ISO image on CD-ROM (create drive if missing)
  community.general.proxmox_disk:
    api_host: node1
    api_user: root@pam
    api_token_id: token1
    api_token_secret: some-token-data
    vmid: 101
    disk: ide2
    media: cdrom
    iso_image: local:iso/favorite_distro_amd64.iso
    state: present

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key	Description
msg string	A short message on what the module did. Returned: always Sample: "Disk scsi3 created in VM 101"
vmid integer	The VM vmid. Returned: success Sample: 101

Authors

• Castor Sky (@castorsky)

Collection links

• Issue Tracker
• Repository (Sources)
• Ask for help
• Submit a bug report
• Request a feature
• Communication