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 5.8.3).
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 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. |
|
Specify the token secret. |
|
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 state=moved. |
|
The drive’s cache mode. Choices:
|
|
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:
|
|
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 state=moved. 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. |
|
Import volume from this existing one. Volume string format
Attention! Only root can use absolute paths. This parameter is mutually exclusive with size. |
|
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). |
|
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 iops). |
|
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 iops). |
|
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:
|
|
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). |
|
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 mbps). |
|
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 mbps). |
|
Maximum unthrottled write pool in megabytes per second. |
|
The drive’s media type. Choices:
|
|
The unique name of the VM. You can specify either name or vmid or both of them. |
|
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 state=present (specify size without suffix). New (or additional) size of volume when state=resized. With the |
|
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. 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 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:
|
|
The drive’s backing storage. Used only when state is |
|
The config key the disk will be moved to on the target VM (for example, Default is the source disk key. Used only when state=moved. |
|
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. |
|
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 in seconds to wait when moving disk. Used only when state=moved. Default: |
|
Force disk geometry bios translation mode. Choices:
|
|
If This should only be used on personally controlled sites using self-signed certificates. Choices:
|
|
The unique ID of the VM. You can specify either vmid or name or both of them. |
|
Write error action. Choices:
|
|
The drive’s worldwide name, encoded as 16 bytes hex string, prefixed by |
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
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: |
Collection links
Issue Tracker Repository (Sources) Submit a bug report Request a feature Communication