scale_computing.hypercore.vm_disk module – Manage VM’s disks

Note

This module is part of the scale_computing.hypercore collection (version 1.6.0).

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 scale_computing.hypercore.

To use it in a playbook, specify: scale_computing.hypercore.vm_disk.

New in scale_computing.hypercore 1.0.0

Synopsis

  • Use this module to add, delete or set disks to the VM. The module can also remove all disks from a VM, attach and/or detach ISO image to the VM by ISO’s name, detach ISO image from the VM by disk’s disk slot, or update the existing disks (disk size etc.).

  • For a given VM, a particular disk is selected by combination of (type, disk_slot). disk_slot means slot on bus (IDE, virtio or SCSI bus).

  • Changing disk type can change its disk_slot. For example, VM has one IDE CD-ROM and one virtio_disk. The disk will have type=virtio_disk and disk_slot=0, and CD-ROM will have type=ide_cdrom and disk_slot=0. Changing disk type to ide_disk will as place disk on IDE bus, after the CD-ROM, and disk will get disk_slot=1.

  • Module tries to remove disks from a running VM. If disk cannot be removed from running VM, then VM will be shutdown, disk will be removed, and VM is started back.

  • VM has shutdown_timeout time to respond to shutdown request. If VM is not shutoff within shutdown_timeout, then a force shutdown will be issued if force_reboot=True.

Parameters

Parameter

Comments

cluster_instance

dictionary

Scale Computing HyperCore instance information.

auth_method

string

Select login method. If not set, the value of the SC_AUTH_METHOD environment variable will be used.

Value local - username/password is verified by the HyperCore server (the local users).

Value oidc - username/password is verified by the configured OIDC provider.

Choices:

  • "local" ← (default)

  • "oidc"

host

string / required

The HyperCore instance URL.

If not set, the value of the SC_HOST environment variable will be used.

For example “https://10.1.2.3:443”.

password

string / required

Password used for authentication.

If not set, the value of the SC_PASSWORD environment variable will be used.

timeout

float

Timeout in seconds for the connection with the Scale Computing HyperCore API instance.

If not set, the value of the SC_TIMEOUT environment variable will be used.

username

string / required

Username used for authentication.

If not set, the value of the SC_USERNAME environment variable will be used.

force

boolean

A safeguard to prevent unintentional removal of all disks.

To remove all disks, items should be set to items=[] and state should be state=set (see example below).

In addition, the force=true must be provided.

Choices:

  • false ← (default)

  • true

force_reboot

boolean

Can VM be forced to power off and on.

Only used when modifications to the VM require it to be powered off and VM does not respond to a shutdown request within shutdown_timeout limit.

Before this is utilized, a shutdown request is sent.

Choices:

  • false ← (default)

  • true

items

list / elements=dictionary

The disk items we want to change.

Default: []

cache_mode

string

The cache mode the VM will use.

Choices:

  • "none"

  • "writeback"

  • "writethrough"

disable_snapshotting

boolean

Disables the ability to snapshot the drive.

Choices:

  • false

  • true

disk_slot

integer / required

Virtual slot the drive will occupy.

iso_name

string

The name of ISO image we want to attach/detach from existing VM.

In case of attaching ISO image (see example below), iso_name is required. If creating an empty CD-ROM but not mount anything, set the value of iso_name to empty string.

In case of detaching ISO image (see example below), name is optional. If not specified, ISO image present on the ide_cdrom disk will get removed.

size

integer

Logical size of the device in bytes. size is used for resizing or creating the disk.

Will get ignored if performing operations on CD-ROM - type=ide_cdrom.

tiering_priority_factor

integer

SSD tiering priority factor for block placement.

Check the tiering documentation for best practices when modifying this.

tiering_priority_factor won’t be relevant on cluster that only has a single tier - ie. only spinning disk or all flash.

Choices:

  • 0

  • 1

  • 2

  • 3

  • 4 ← (default)

  • 5

  • 6

  • 7

  • 8

  • 9

  • 10

  • 11

type

string / required

The bus type the VirDomainBlockDevice will use.

If type=ide_cdrom, iso_name is also required. Se documentation of iso_name for more details.

Choices:

  • "ide_cdrom"

  • "virtio_disk"

  • "ide_disk"

  • "scsi_disk"

  • "ide_floppy"

  • "nvram"

  • "vtpm"

type_new

string

Only relevant if we want to update the disk parameters.

The type we want to assign the disk with.

shutdown_timeout

float

How long does ansible controller wait for VMs response to a shutdown request.

In seconds.

Default: 300.0

state

string / required

The desired state of the disks specified by items.

With state=present (or state=absent), the disks in items are added to VM, or removed from VM. Individual disk is resized if needed.

With state=set, the VM is reconfigured to have exactly such disks as specified by items.

Choices:

  • "present"

  • "absent"

  • "set"

vm_name

string / required

Virtual machine name.

Used to identify selected virtual machine by name.

Notes

Note

  • check_mode is not supported.

Examples

- name: Set exact disk
  scale_computing.hypercore.vm_disk:
    vm_name: demo-vm
    force_reboot: true
    shutdown_timeout: "{{ '5minutes' | community.general.to_time_unit('seconds') }}"
    items:
      - disk_slot: 0
        type: virtio_disk
        size: "{{ '10.1 GB' | human_to_bytes }}"
    state: set

- name: Remove all disks
  scale_computing.hypercore.vm_disk:
    vm_name: demo-vm
    items: []
    state: set
    force: true

- name: Remove one disk
  scale_computing.hypercore.vm_disk:
    vm_name: demo-vm
    items:
      - disk_slot: 0
        type: virtio_disk
    state: absent

- name: Example add/update one disk.
  scale_computing.hypercore.vm_disk:
    vm_name: demo-vm
    items:
      - disk_slot: 0
        type: virtio_disk
        size: "{{ '10.1 GB' | human_to_bytes }}"
    state: present

- name: Add an empty CD-ROM.
  scale_computing.hypercore.vm_disk:
    vm_name: demo-vm
    items:
      - disk_slot: 0
        type: ide_cdrom
        iso_name: ""
    state: present

- name: Remove empty CD-ROM.
  scale_computing.hypercore.vm_disk:
    vm_name: demo-vm
    items:
      - disk_slot: 0
        type: ide_cdrom
    state: absent

- name: Attach existing ISO image to existing VM
  scale_computing.hypercore.vm_disk:
    vm_name: demo-vm
    items:
      - name: CentOS-Stream-9-latest-x86_64-dvd1.iso
        disk_slot: 0
        type: ide_cdrom
    state: present

- name: Detach ISO image from cdrom disk on slot 0
  scale_computing.hypercore.vm_disk:
    vm_name: demo-vm
    items:
      - name: CentOS-Stream-9-latest-x86_64-dvd1.iso
        disk_slot: 0
        type: ide_cdrom
    state: absent

- name: Detach ISO image from existing VM, find CD-ROM by slot number and type
  scale_computing.hypercore.vm_disk:
    vm_name: demo-vm
    items:
      - disk_slot: 0
        type: ide_cdrom
    state: absent

- name: Update existing disk - resize, change type etc
  scale_computing.hypercore.vm_disk:
    vm_name: demo-vm
    items:
      - disk_slot: 0
        type: ide_disk
        type_new: virtio_disk
        size: "{{ '11.1 GB' | human_to_bytes }}"
        cache_mode: writeback
    state: present

- name: Resize disk
  scale_computing.hypercore.vm_disk:
    vm_name: demo-vm
    items:
      - disk_slot: 0
        type: virtio_disk
        size: "{{ '20 GB' | human_to_bytes }}"
    state: present

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

record

dictionary

The modified record from the HyperCore API endpoint /rest/v1/VirDomainBlockDevice.

Returned: success

cache_mode

string

The cache mode the VirDomainBlockDevice will use

Returned: success

Sample: "none"

disable_snapshotting

boolean

Disables the ability to snapshot the drive

Returned: success

Sample: false

disk_slot

integer

Virtual slot the drive will occupy

Returned: success

Sample: 0

iso_name

string

Name of the virtual storage device

Returned: success

Sample: "jc1-disk-0"

mount_points

list / elements=string

Mount points of the drive in the guest OS, populated by the guest-agent

Returned: success

Sample: []

read_only

boolean

True if the device is read-only

Returned: success

Sample: false

size

integer

Logical size of the device in bytes, and can be increased on update or clone

Returned: success

Sample: 81001000100

tiering_priority_factor

integer

SSD tiering priority factor for block placement

Returned: success

Sample: 8

type

string

The bus type the VirDomainBlockDevice will use

Returned: success

Sample: "virtio_disk"

uuid

string

Unique Identifier

Returned: success

Sample: "056ea04b-069c-4a22-84d5-5489b100029f"

vm_uuid

string

Identifier of the VirDomain this device is attached to

Returned: success

Sample: "1596dab1-6f90-494c-9607-b14221830433"

vm_rebooted

boolean

Info if reboot of the VM was performed.

Returned: success

Sample: true

Authors

  • Tjaž Eržen (@tjazsch)