community / community.general / 8.5.0 / module / proxmox_disk Management of a disk of a Qemu(KVM) VM in a Proxmox VE cluster | "added in version" 5.7.0 of community.general" Authors: Castor Sky (@castorsky) <csky57@gmail.com>community.general.proxmox_disk (8.5.0) — module
Install with ansible-galaxy collection install community.general:==8.5.0
collections: - name: community.general version: 8.5.0
Allows you to perform some supported operations on a disk in Qemu(KVM) Virtual Machines in a Proxmox VE cluster.
- 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
ro: description: - Whether the drive is read-only. type: bool aio: choices: - native - threads - io_uring description: - AIO type to use. type: str ssd: description: - Whether to expose this drive as an SSD, rather than a rotational hard disk. type: bool wwn: description: - The drive's worldwide name, encoded as 16 bytes hex string, prefixed by V(0x). type: str cyls: description: - Force the drive's physical geometry to have a specific cylinder count. type: int disk: description: - The disk key (V(unused[n]), V(ide[n]), V(sata[n]), V(scsi[n]) or V(virtio[n])) you want to operate on. - Disk buses (IDE, SATA and so on) have fixed ranges of V(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. ' required: true type: str iops: description: - Maximum total r/w I/O in operations per second. - You can specify either total limit or per operation (mutually exclusive with O(iops_rd) and O(iops_wr)). type: int mbps: description: - 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 O(mbps_rd) and O(mbps_wr)). type: float name: description: - The unique name of the VM. - You can specify either O(name) or O(vmid) or both of them. type: str secs: description: - Force the drive's physical geometry to have a specific sector count. type: int size: description: - Desired volume size in GB to allocate when O(state=present) (specify O(size) without suffix). - 'New (or additional) size of volume when O(state=resized). With the V(+) sign the value is added to the actual size of the volume and without it, the value is taken as an absolute one. ' type: str vmid: description: - The unique ID of the VM. - You can specify either O(vmid) or O(name) or both of them. type: int cache: choices: - none - writethrough - writeback - unsafe - directsync description: - The drive's cache mode. type: str heads: description: - Force the drive's physical geometry to have a specific head count. type: int media: choices: - cdrom - disk description: - The drive's media type. type: str state: choices: - present - resized - detached - moved - absent default: present description: - Indicates desired state of the disk. - 'O(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 O(create) parameter description to control behavior of this option. ' - Some updates on options (like O(cache)) are not being applied instantly and require VM restart. - 'Use O(state=detached) to detach existing disk from VM but do not remove it entirely. When O(state=detached) and disk is V(unused[n]) it will be left in same state (not removed). ' - 'O(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). ' - 'O(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 O(state=absent). type: str trans: choices: - auto - lba - none description: - Force disk geometry bios translation mode. type: str backup: description: - Whether the drive should be included when making backups. type: bool create: choices: - disabled - regular - forced default: regular description: - With O(create) flag you can control behavior of O(state=present). - When O(create=disabled) it will not create new disk (if not exists) but will update options in existing disk. - When O(create=regular) it will either create new disk (if not exists) or update options in existing disk. - When O(create=forced) it will always create new disk (if disk exists it will be detached and left unused). type: str format: choices: - raw - cow - qcow - qed - qcow2 - vmdk - cloop description: - The drive's backing file's data format. type: str queues: description: - Number of queues (SCSI only). type: int rerror: choices: - ignore - report - stop description: - Read error action. type: str serial: description: - The drive's reported serial number, url-encoded, up to 20 bytes long. type: str shared: description: - Mark this locally-managed volume as available on all nodes. - This option does not share the volume automatically, it assumes it is shared already! type: bool werror: choices: - enospc - ignore - report - stop description: - Write error action. type: str bwlimit: description: - Override I/O bandwidth limit (in KB/s). - Used only when O(state=moved). type: int discard: choices: - ignore - 'on' description: - Control whether to pass discard/trim requests to the underlying storage. type: str iops_rd: description: - Maximum read I/O in operations per second. - You can specify either read or total limit (mutually exclusive with O(iops)). type: int iops_wr: description: - Maximum write I/O in operations per second. - You can specify either write or total limit (mutually exclusive with O(iops)). type: int mbps_rd: description: - Maximum read speed in megabytes per second. - You can specify either read or total limit (mutually exclusive with O(mbps)). type: float mbps_wr: description: - Maximum write speed in megabytes per second. - You can specify either write or total limit (mutually exclusive with O(mbps)). type: float storage: description: - The drive's backing storage. - Used only when O(state) is V(present). type: str timeout: default: 600 description: - Timeout in seconds to wait for slow operations such as importing disk or moving disk between storages. - Used only when O(state) is V(present) or V(moved). type: int api_host: description: - Specify the target host of the Proxmox VE cluster. required: true type: str api_user: description: - Specify the user to authenticate with. required: true type: str iops_max: description: - Maximum unthrottled total r/w I/O pool in operations per second. type: int iothread: description: - Whether to use iothreads for this drive (only for SCSI and VirtIO) type: bool mbps_max: description: - Maximum unthrottled total r/w pool in megabytes per second. type: float snapshot: description: - Control qemu's snapshot mode feature. - If activated, changes made to the disk are temporary and will be discarded when the VM is shutdown. type: bool iso_image: description: - The ISO image to be mounted on the specified in O(disk) CD-ROM. - O(media=cdrom) needs to be specified for this option to work. - 'Image string format:' - V(<STORAGE>:iso/<ISO_NAME>) to mount ISO. - V(cdrom) to use physical CD/DVD drive. - V(none) to unmount image from existent CD-ROM or create empty CD-ROM drive. type: str version_added: 8.1.0 version_added_collection: community.general replicate: description: - Whether the drive should considered for replication jobs. type: bool scsiblock: description: - 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. type: bool import_from: description: - Import volume from this existing one. - Volume string format - C(<STORAGE>:<VMID>/<FULL_NAME>) or C(<ABSOLUTE_PATH>/<FULL_NAME>) - Attention! Only root can use absolute paths. - This parameter is mutually exclusive with O(size). - Increase O(timeout) parameter when importing large disk images or using slow storage. type: str iops_rd_max: description: - Maximum unthrottled read I/O pool in operations per second. type: int iops_wr_max: description: - Maximum unthrottled write I/O pool in operations per second. type: int mbps_rd_max: description: - Maximum unthrottled read pool in megabytes per second. type: float mbps_wr_max: description: - Maximum unthrottled write pool in megabytes per second. type: float target_disk: description: - The config key the disk will be moved to on the target VM (for example, V(ide0) or V(scsi1)). - Default is the source disk key. - Used only when O(state=moved). type: str target_vmid: description: - The (unique) ID of the VM where disk will be placed when O(state=moved). - You can move disk between VMs only when the same storage is used. - Mutually exclusive with O(target_vmid). type: int api_password: description: - Specify the password to authenticate with. - You can use E(PROXMOX_PASSWORD) environment variable. type: str api_token_id: description: - Specify the token ID. - Requires C(proxmoxer>=1.1.0) to work. type: str version_added: 1.3.0 version_added_collection: community.general delete_moved: description: - Delete the original disk after successful copy. - By default the original disk is kept as unused disk. - Used only when O(state=moved). type: bool detect_zeroes: description: - Control whether to detect and try to optimize writes of zeroes. type: bool bps_max_length: description: - Maximum length of total r/w I/O bursts in seconds. type: int target_storage: description: - Move the disk to this storage when O(state=moved). - You can move between storages only in scope of one VM. - Mutually exclusive with O(target_vmid). - Consider increasing O(timeout) in case of large disk images or slow storage backend. type: str validate_certs: default: false description: - If V(false), SSL certificates will not be validated. - This should only be used on personally controlled sites using self-signed certificates. type: bool iops_max_length: description: - Maximum length of total r/w I/O bursts in seconds. type: int api_token_secret: description: - Specify the token secret. - Requires C(proxmoxer>=1.1.0) to work. type: str version_added: 1.3.0 version_added_collection: community.general bps_rd_max_length: description: - Maximum length of read I/O bursts in seconds. type: int bps_wr_max_length: description: - Maximum length of write I/O bursts in seconds. type: int iops_rd_max_length: description: - Maximum length of read I/O bursts in seconds. type: int iops_wr_max_length: description: - Maximum length of write I/O bursts in seconds. type: int
msg: description: A short message on what the module did. returned: always sample: Disk scsi3 created in VM 101 type: str vmid: description: The VM vmid. returned: success sample: 101 type: int