Try SpotterManagement 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>
Install with ansible-galaxy collection install community.general:==8.5.0
collections:
- name: community.general
version: 8.5.0Allows 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