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 8.6.4).
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.
Aliases: cloud.misc.proxmox_disk
Requirements
The below requirements are needed on the host that executes this module.
proxmoxer
requests
Parameters
Parameter |
Comments |
---|---|
AIO type to use. Choices:
|
|
Specify the target host of the Proxmox VE cluster. |
|
Specify the password to authenticate with. You can use |
|
Specify the token ID. Requires |
|
Specify the token secret. Requires |
|
Specify the user to authenticate with. |
|
Whether the drive should be included when making backups. Choices:
|
|
Maximum length of total r/w I/O bursts in seconds. |
|
Maximum length of read I/O bursts in seconds. |
|
Maximum length of write I/O bursts in seconds. |
|
Override I/O bandwidth limit (in KB/s). Used only when |
|
The drive’s cache mode. Choices:
|
|
With When When When Choices:
|
|
Force the drive’s physical geometry to have a specific cylinder count. |
|
Delete the original disk after successful copy. By default the original disk is kept as unused disk. Used only when Choices:
|
|
Control whether to detect and try to optimize writes of zeroes. Choices:
|
|
Control whether to pass discard/trim requests to the underlying storage. Choices:
|
|
The disk key ( Disk buses (IDE, SATA and so on) have fixed ranges of For IDE: 0-3; for SCSI: 0-30; for SATA: 0-5; for VirtIO: 0-15; for Unused: 0-255. |
|
The drive’s backing file’s data format. Choices:
|
|
Force the drive’s physical geometry to have a specific head count. |
|
Maximum unthrottled total r/w I/O pool in operations per second. |
|
Maximum length of total r/w I/O bursts in seconds. |
|
Maximum read I/O in operations per second. You can specify either read or total limit (mutually exclusive with |
|
Maximum unthrottled read I/O pool in operations per second. |
|
Maximum length of read I/O bursts in seconds. |
|
Maximum write I/O in operations per second. You can specify either write or total limit (mutually exclusive with |
|
Maximum unthrottled write I/O pool in operations per second. |
|
Maximum length of write I/O bursts in seconds. |
|
Whether to use iothreads for this drive (only for SCSI and VirtIO) Choices:
|
|
The ISO image to be mounted on the specified in
Image string format:
|
|
Maximum unthrottled total r/w pool in megabytes per second. |
|
Maximum read speed in megabytes per second. You can specify either read or total limit (mutually exclusive with |
|
Maximum unthrottled read pool in megabytes per second. |
|
Maximum write speed in megabytes per second. You can specify either write or total limit (mutually exclusive with |
|
Maximum unthrottled write pool in megabytes per second. |
|
The drive’s media type. Choices:
|
|
Number of queues (SCSI only). |
|
Whether the drive should considered for replication jobs. Choices:
|
|
Read error action. Choices:
|
|
Whether the drive is read-only. Choices:
|
|
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:
|
|
Force the drive’s physical geometry to have a specific sector count. |
|
The drive’s reported serial number, url-encoded, up to 20 bytes long. |
|
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:
|
|
Desired volume size in GB to allocate when New (or additional) size of volume when |
|
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:
|
|
Whether to expose this drive as an SSD, rather than a rotational hard disk. Choices:
|
|
Indicates desired state of the disk.
Some updates on options (like Use
To entirely remove the disk from backing storage use Choices:
|
|
The drive’s backing storage. Used only when |
|
The config key the disk will be moved to on the target VM (for example, Default is the source disk key. Used only when |
|
Move the disk to this storage when You can move between storages only in scope of one VM. Mutually exclusive with Consider increasing |
|
The (unique) ID of the VM where disk will be placed when You can move disk between VMs only when the same storage is used. Mutually exclusive with |
|
Timeout in seconds to wait for slow operations such as importing disk or moving disk between storages. Used only when Default: |
|
Force disk geometry bios translation mode. Choices:
|
|
If This should only be used on personally controlled sites using self-signed certificates. Choices:
|
|
Write error action. Choices:
|
|
The drive’s worldwide name, encoded as 16 bytes hex string, prefixed by |
Attributes
Attribute |
Support |
Description |
---|---|---|
Support: none |
Can run in |
|
Support: none |
Will return details on what has changed (or possibly needs changing in |
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 |
---|---|
A short message on what the module did. Returned: always Sample: |
|
The VM vmid. Returned: success Sample: |