community.vmware.vmware_guest_disk module – Manage disks related to virtual machine in given vCenter infrastructure
Note
This module is part of the community.vmware collection (version 1.18.2).
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.vmware.
To use it in a playbook, specify: community.vmware.vmware_guest_disk.
Synopsis
This module can be used to add, remove and update disks belonging to given virtual machine.
All parameters and VMware object names are case sensitive.
This module is destructive in nature, please read documentation carefully before proceeding.
Be careful while removing disk specified as this may lead to data loss.
Requirements
The below requirements are needed on the host that executes this module.
python >= 2.6
PyVmomi
Parameters
Parameter |
Comments |
|---|---|
The datacenter name to which virtual machine belongs to. |
|
A list of disks to add or remove. The virtual disk related information is provided using this list. All values and parameters are case sensitive. Default: [] |
|
Select the less used datastore. Specify only if Choices:
|
|
Only functions with Paravirtual SCSI Controller. Allows for the sharing of the scsi bus between two virtual machines. Choices:
|
|
This value allows for the sharing of an RDM between two machines. The primary machine holding the RDM uses the default The secondary machine holding the RDM uses Choices:
|
|
Compatibility mode for raw devices. Required for disk type ‘rdm’ Choices:
|
|
This parameter is used with Choices:
|
|
This parameter is added for managing disks attaching other types of controllers, e.g., SATA or NVMe. If either Choices:
|
|
Name of datastore or datastore cluster to be used for the disk. |
|
If Choices:
|
|
Type of disk mode. If not specified then use If set to ‘persistent’ mode, changes are immediately and permanently written to the virtual disk. If set to ‘independent_persistent’ mode, same as persistent, but not affected by snapshots. If set to ‘independent_nonpersistent’ mode, changes to virtual disk are made to a redo log and discarded at power off, but not affected by snapshots. Choices:
|
|
Existing disk image to be used. Filename must already exist on the datastore. Specify filename string in |
|
Section specifies the shares and limit for storage I/O resource. |
|
Section specifies values for limit where the utilization of a virtual machine will not exceed, even if there are available resources. |
|
Specifies different types of shares user can add for the given disk. |
|
Specifies different level for the shares section. Choices:
|
|
Custom value when |
|
Path of LUN for Raw Device Mapping required for disk type Only valid if |
|
SCSI controller number. Only 4 SCSI controllers are allowed per VM. Care should be taken while specifying ‘scsi_controller’ is 0 and ‘unit_number’ as 0 as this disk may contain OS. Choices:
|
|
Type of SCSI controller. This value is required only for the first occurrence of SCSI Controller. This value is ignored, if SCSI Controller is already present or Choices:
|
|
Section for iolimit section tells about what are all different types of shares user can add for disk. |
|
Tells about different level for the shares section. Choices:
|
|
Custom value when |
|
The sharing mode of the virtual disk. Setting sharing means that multiple virtual machines can write to the virtual disk. Sharing can only be set if Choices:
|
|
Disk storage size. If size specified then unit must be specified. There is no space allowed in between size number and unit. Only first occurrence in disk element will be considered, even if there are multiple size* parameters available. |
|
Disk storage size in gb. |
|
Disk storage size in kb. |
|
Disk storage size in mb. |
|
Disk storage size in tb. |
|
State of disk. If set to ‘absent’, disk will be removed permanently from virtual machine configuration and from VMware storage. If set to ‘present’, disk will be added if not present at given Controller and Unit Number. or disk exists with different size, disk size is increased, reducing disk size is not allowed. Choices:
|
|
The type of disk, if not specified then use The disk type Choices:
|
|
Disk Unit Number. Valid value range from 0 to 15, except 7 for SCSI Controller. Valid value range from 0 to 64, except 7 for Paravirtual SCSI Controller on Virtual Hardware version 14 or higher Valid value range from 0 to 29 for SATA controller. Valid value range from 0 to 14 for NVME controller. |
|
Destination folder, absolute or relative path to find an existing guest. This is a required parameter, only if multiple VMs are found with same name. The folder should include the datacenter. ESX’s datacenter is ha-datacenter Examples:
|
|
The hostname or IP address of the vSphere vCenter or ESXi server. If the value is not specified in the task, the value of environment variable Environment variable support added in Ansible 2.6. |
|
Managed Object ID of the instance to manage if known, this is a unique identifier only within a single vCenter instance. This is required if |
|
Name of the virtual machine. This is a required parameter, if parameter |
|
The password of the vSphere vCenter or ESXi server. If the value is not specified in the task, the value of environment variable Environment variable support added in Ansible 2.6. |
|
The port number of the vSphere vCenter or ESXi server. If the value is not specified in the task, the value of environment variable Environment variable support added in Ansible 2.6. Default: 443 |
|
Address of a proxy that will receive all HTTPS requests and relay them. The format is a hostname or a IP. If the value is not specified in the task, the value of environment variable This feature depends on a version of pyvmomi greater than v6.7.1.2018.12 |
|
Port of the HTTP proxy that will receive all HTTPS requests and relay them. If the value is not specified in the task, the value of environment variable |
|
Whether to use the VMware instance UUID rather than the BIOS UUID. Choices:
|
|
The username of the vSphere vCenter or ESXi server. If the value is not specified in the task, the value of environment variable Environment variable support added in Ansible 2.6. |
|
UUID of the instance to gather facts if known, this is VMware’s unique identifier. This is a required parameter, if parameter |
|
Allows connection when SSL certificates are not valid. Set to If the value is not specified in the task, the value of environment variable Environment variable support added in Ansible 2.6. If set to Choices:
|
Notes
Note
Tested on vSphere 6.0 and 6.5
All modules requires API write access and hence is not supported on a free ESXi license.
Examples
- name: Add disks to virtual machine using UUID
community.vmware.vmware_guest_disk:
hostname: "{{ vcenter_hostname }}"
username: "{{ vcenter_username }}"
password: "{{ vcenter_password }}"
datacenter: "{{ datacenter_name }}"
uuid: 421e4592-c069-924d-ce20-7e7533fab926
disk:
- size_mb: 10
type: thin
datastore: datacluster0
state: present
scsi_controller: 1
unit_number: 1
scsi_type: 'paravirtual'
disk_mode: 'persistent'
- size_gb: 10
type: eagerzeroedthick
state: present
autoselect_datastore: True
scsi_controller: 2
scsi_type: 'buslogic'
unit_number: 12
disk_mode: 'independent_persistent'
- size: 10Gb
type: eagerzeroedthick
state: present
autoselect_datastore: True
scsi_controller: 2
scsi_type: 'buslogic'
unit_number: 1
disk_mode: 'independent_nonpersistent'
- filename: "[datastore1] path/to/existing/disk.vmdk"
delegate_to: localhost
register: disk_facts
- name: Add disks with specified shares to the virtual machine
community.vmware.vmware_guest_disk:
hostname: "{{ vcenter_hostname }}"
username: "{{ vcenter_username }}"
password: "{{ vcenter_password }}"
datacenter: "{{ datacenter_name }}"
disk:
- size_gb: 1
type: thin
datastore: datacluster0
state: present
scsi_controller: 1
unit_number: 1
disk_mode: 'independent_persistent'
shares:
level: custom
level_value: 1300
delegate_to: localhost
register: test_custom_shares
- name: Add physical raw device mapping to virtual machine using name
community.vmware.vmware_guest_disk:
hostname: "{{ vcenter_hostname }}"
username: "{{ vcenter_username }}"
password: "{{ vcenter_password }}"
datacenter: "{{ datacenter_name }}"
validate_certs: no
name: "Test_VM"
disk:
- type: rdm
state: present
scsi_controller: 1
unit_number: 5
rdm_path: /vmfs/devices/disks/naa.060000003b1234efb453
compatibility_mode: 'physicalMode'
- name: Add virtual raw device mapping to virtual machine using name and virtual mode
community.vmware.vmware_guest_disk:
hostname: "{{ vcenter_hostname }}"
username: "{{ vcenter_username }}"
password: "{{ vcenter_password }}"
datacenter: "{{ datacenter_name }}"
validate_certs: no
name: "Test_VM"
disk:
- type: rdm
state: present
scsi_controller: 1
unit_number: 5
rdm_path: /vmfs/devices/disks/naa.060000003b1234efb453
compatibility_mode: 'virtualMode'
disk_mode: 'persistent'
- name: Add raw device mapping to virtual machine with Physical bus sharing
community.vmware.vmware_guest_disk:
hostname: "{{ vcenter_hostname }}"
username: "{{ vcenter_username }}"
password: "{{ vcenter_password }}"
datacenter: "{{ datacenter_name }}"
validate_certs: no
name: "Test_VM"
disk:
- type: rdm
state: present
scsi_controller: 1
unit_number: 5
rdm_path: /vmfs/devices/disks/naa.060000003b1234efb453
compatibility_mode: 'virtualMode'
disk_mode: 'persistent'
bus_sharing: physicalSharing
- name: Add raw device mapping to virtual machine with Physical bus sharing and clustered disk
community.vmware.vmware_guest_disk:
hostname: "{{ vcenter_hostname }}"
username: "{{ vcenter_username }}"
password: "{{ vcenter_password }}"
datacenter: "{{ datacenter_name }}"
validate_certs: no
name: "Test_VM"
disk:
- type: rdm
state: present
scsi_controller: 1
unit_number: 5
compatibility_mode: 'virtualMode'
disk_mode: 'persistent'
bus_sharing: physicalSharing
filename: "[datastore1] path/to/rdm/disk-marker.vmdk"
- name: create new disk with custom IO limits and shares in IO Limits
community.vmware.vmware_guest_disk:
hostname: "{{ vcenter_hostname }}"
username: "{{ vcenter_username }}"
password: "{{ vcenter_password }}"
datacenter: "{{ datacenter_name }}"
disk:
- size_gb: 1
type: thin
datastore: datacluster0
state: present
scsi_controller: 1
unit_number: 1
disk_mode: 'independent_persistent'
iolimit:
limit: 1506
shares:
level: custom
level_value: 1305
delegate_to: localhost
register: test_custom_IoLimit_shares
- name: Remove disks from virtual machine using name
community.vmware.vmware_guest_disk:
hostname: "{{ vcenter_hostname }}"
username: "{{ vcenter_username }}"
password: "{{ vcenter_password }}"
datacenter: "{{ datacenter_name }}"
name: VM_225
disk:
- state: absent
scsi_controller: 1
unit_number: 1
delegate_to: localhost
register: disk_facts
- name: Remove disk from virtual machine using moid
community.vmware.vmware_guest_disk:
hostname: "{{ vcenter_hostname }}"
username: "{{ vcenter_username }}"
password: "{{ vcenter_password }}"
datacenter: "{{ datacenter_name }}"
moid: vm-42
disk:
- state: absent
scsi_controller: 1
unit_number: 1
delegate_to: localhost
register: disk_facts
- name: Remove disk from virtual machine but keep the VMDK file on the datastore
community.vmware.vmware_guest_disk:
hostname: "{{ vcenter_hostname }}"
username: "{{ vcenter_username }}"
password: "{{ vcenter_password }}"
datacenter: "{{ datacenter_name }}"
name: VM_225
disk:
- state: absent
scsi_controller: 1
unit_number: 2
destroy: no
delegate_to: localhost
register: disk_facts
- name: Add disks to virtual machine using UUID to SATA and NVMe controller
community.vmware.vmware_guest_disk:
hostname: "{{ vcenter_hostname }}"
username: "{{ vcenter_username }}"
password: "{{ vcenter_password }}"
datacenter: "{{ datacenter_name }}"
validate_certs: no
uuid: 421e4592-c069-924d-ce20-7e7533fab926
disk:
- size_mb: 256
type: thin
datastore: datacluster0
state: present
controller_type: sata
controller_number: 1
unit_number: 1
disk_mode: 'persistent'
- size_gb: 1
state: present
autoselect_datastore: True
controller_type: nvme
controller_number: 2
unit_number: 3
disk_mode: 'independent_persistent'
delegate_to: localhost
register: disk_facts
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
|---|---|
metadata about the virtual machine’s disks after managing them Returned: always Sample: {“0”: {“backing_datastore”: “datastore2”, “backing_disk_mode”: “persistent”, “backing_eagerlyscrub”: false, “backing_filename”: “[datastore2] VM_225/VM_225.vmdk”, “backing_thinprovisioned”: false, “backing_uuid”: “421e4592-c069-924d-ce20-7e7533fab926”, “backing_writethrough”: false, “capacity_in_bytes”: 10485760, “capacity_in_kb”: 10240, “controller_key”: 1000, “key”: 2000, “label”: “Hard disk 1”, “summary”: “10,240 KB”, “unit_number”: 0}} |
Authors
Abhijeet Kasurde (@Akasurde)