scale_computing.hypercore.vm module – Create, update or delete a VM.

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.

New in scale_computing.hypercore 1.0.0

Synopsis

  • Use this module to create, update or delete a VM. When creating or updating a VM, setting the disks, network nics and boot order is possible.

  • 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

attach_guest_tools_iso

boolean

If supported by operating system, create an extra device to attach the Scale Guest OS tools ISO.

Supported by operating_system=os_windows_server_2012.

Choices:

  • false ← (default)

  • true

boot_devices

list / elements=dictionary

Ordered list of boot devices (disks and nics) you want to set

disk_slot

integer

If setting the boot device order of disk, that is type=virtio_disk, type=ide_disk, type=scsi_disk, type=ide_floppy or type=nvram disk_slot is required.

If setting the boot device order of CD-ROM, that is type=ide_cdrom, at least one of iso_name or disk_slot is required.

If type=nic, disk_slot is not relevant.

At least one of disk_slot, nic_vlan and iso_name is required to identify the VM device to which we’re setting the boot order.

iso_name

string

The name of ISO image that CD-ROM device is attached to.

Only relevant if type=ide_cdrom. If type=cdrom, at least one of iso_name or disk_slot is required to identify CD-ROM device.

Otherwise, iso_name is not relevant.

At least one of disk_slot, nic_vlan and i(iso_name) is required to identify the vm device to which we’re setting the boot order.

nic_vlan

integer

Nic’s vlan.

If type=nic, nic_vlan is required.

Otherwise, nic_vlan is not relevant.

At least one of disk_slot, nic_vlan and iso_name is required to identify the vm device to which we’re setting the boot order.

type

string / required

The type of device we want to set the boot order to.

If setting the boot order for nic, type should be equal to nic.

If setting the boot order for disk, type should be equal to one of the specific types, listed below.

Choices:

  • "nic"

  • "ide_cdrom"

  • "virtio_disk"

  • "ide_disk"

  • "scsi_disk"

  • "ide_floppy"

  • "nvram"

cloud_init

dictionary

Configuration to be used by cloud-init (Linux) or cloudbase-init (Windows).

When non-empty will create an extra ISO device attached to VirDomain as a NoCloud datasource.

There has to be cloud-config comment present at the beginning of cloud_init file or raw yaml.

Default: {}

meta_data

string

Configuration meta-data to be used by cloud-init (Linux) or cloudbase-init (Windows).

Valid YAML syntax.

user_data

string

Configuration user-data to be used by cloud-init (Linux) or cloudbase-init (Windows).

Valid YAML syntax.

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.

description

string

VM’s description.

Only relevant if state=present. value.

disks

list / elements=dictionary

List of disks we want to create.

Required if state=present.

cache_mode

string

The cache mode the VM will use.

Choices:

  • "none"

  • "writeback"

  • "writethrough"

disk_slot

integer / required

Virtual slot the drive will occupy.

iso_name

string

The name of the ISO image we want to attach to the CD-ROM.

Required if type=ide_cdrom

Only relevant if type=ide_cdrom.

size

integer

Logical size of the device in bytes.

type

string / required

The bus type the VM will use.

If type=ide_cdrom, it’s assumed you want to attach ISO image to cdrom disk. In that case, field iso_name is required.

Choices:

  • "ide_cdrom"

  • "virtio_disk"

  • "ide_disk"

  • "scsi_disk"

  • "ide_floppy"

  • "nvram"

  • "vtpm"

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

machine_type

string

added in scale_computing.hypercore 1.1.0

Scale Hardware version.

Required if creating a new VM.

Only relevant when creating the VM. This property cannot be modified.

HyperCore needs to support requested machine_type. BIOS and UEFI - available since 9.1. vTPM+UEFI - available since 9.2. vTPM+UEFI-compatible - available since 9.3.

Choices:

  • "BIOS"

  • "UEFI"

  • "vTPM+UEFI"

  • "vTPM+UEFI-compatible"

memory

integer

VM’s physical memory in bytes.

Required if state=present. Irrelevant if state=absent.

nics

list / elements=dictionary

List of network interfaces we want to create.

Required if state=present.

connected

boolean

Is network interface connected or not.

Choices:

  • false

  • true ← (default)

mac

string

Mac address of the network interface.

type

string

Defines type of the network interface.

Choices:

  • "virtio" ← (default)

  • "RTL8139"

  • "INTEL_E1000"

vlan

integer

Network interface virtual LAN.

Default: 0

operating_system

string

Operating system name.

Used to select drivers package

Choices:

  • "os_windows_server_2012" ← (default)

  • "os_other"

power_state

string

Desired VM state.

States PAUSE and LIVEMIGRATE are not exposed in this module (this can be done with raw api module).

Note that - shutdown will trigger a graceful ACPI shutdown. - reboot will trigger a graceful ACPI reboot. - stop will trigger an abrupt shutdown (force power off). VM might loose data, and filesystem might be corrupted afterwards. - reset will trigger an abrupt reset (force power reset). VM might loose data, and filesystem might be corrupted afterwards.

Choices:

  • "start" ← (default)

  • "shutdown"

  • "stop"

  • "reboot"

  • "reset"

shutdown_timeout

float

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

In seconds.

Default: 300.0

snapshot_schedule

string

The name of an existing snapshot_schedule to assign to VM.

VM can have 0 or 1 snapshot schedules assigned.

state

string / required

Desired state of the VM.

Choices:

  • "present"

  • "absent"

tags

list / elements=string

Tags of the VM.

The first tag determines the group that the VM is going to belong.

vcpu

integer

Number of Central processing units on the VM.

Required if state=present. If state=absent, vcpu is not relevant.

vm_name

string / required

Virtual machine name.

Used to identify selected virtual machine by name.

vm_name_new

string

Use it to rename a VM.

If the VM already exists, VM’s new name.

Only relevant if state=present.

Notes

Note

  • The record return value will be changed from list (containing a single item) to dict. There will be no release where both old and new variant work at the same time. The change will happen with release 3.0.0. To ease migration, the only change between last 1.x or 2.x release and 3.0.0 release will be changing the record return value. List of deprecation changes includes examples to help with transition.

  • check_mode is not supported.

See Also

See also

scale_computing.hypercore.vm_info

Retrieve information about the VMs.

scale_computing.hypercore.vm_params

Manage VM’s parameters.

scale_computing.hypercore.vm_boot_devices

Manage HyperCore VM’s boot devices.

scale_computing.hypercore.vm_disk

Manage VM’s disks.

scale_computing.hypercore.vm_nic

Handles actions over network interfaces.

scale_computing.hypercore.vm_node_affinity

Update virtual machine’s node affinity.

scale_computing.hypercore.vm_replication

Handles VM replications.

scale_computing.hypercore.vm_clone

Handles cloning of the VM.

scale_computing.hypercore.vm_import

Handles import of the virtual machine.

scale_computing.hypercore.vm_export

Handles export of the virtual machine.

Examples

- name: Create and start the VM with disks, nics and boot devices set. Attach ISO onto the VM. Add cloud init data
  scale_computing.hypercore.vm:
    vm_name: vm-integration-test-vm
    description: Demo VM
    state: present
    tags:
      - my-group
      - mytag1
      - mytag2
    memory: "{{ '512 MB' | human_to_bytes }}"
    vcpu: 2
    attach_guest_tools_iso: true
    power_state: start
    force_reboot: true
    shutdown_timeout: "{{ '5minutes' | community.general.to_time_unit('seconds') }}"
    disks:
      - type: virtio_disk
        disk_slot: 0
        size: "{{ '10.1 GB' | human_to_bytes }}"
      - type: ide_cdrom
        disk_slot: 0
        iso_name: TinyCore-current.iso
    nics:
      - vlan: 0
        type: RTL8139
    boot_devices:
      - type: virtio_disk
        disk_slot: 0
      - type: nic
        nic_vlan: 0
    cloud_init:
      user_data: "{{ lookup('file', 'cloud-init-user-data-example.yml') }}"
      meta_data: |
        # Content for cloud-init meta-data (or user-data) can be inline too.
  register: result

- name: Delete the VM
  scale_computing.hypercore.vm:
    vm_name: demo-VM
    state: absent
  register: result

Return Values

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

Key

Description

record

list / elements=dictionary

Created VM, if creating the record. If deleting the record, none is returned.

Returned: success

boot_devices

list / elements=dictionary

Bootable disks or nics, in the order that they will boot

Returned: success

Sample: {"cache_mode": "none", "disable_snapshotting": false, "disk_slot": 2, "iso_name": "", "mount_points": [], "read_only": false, "size": 10737418240, "tiering_priority_factor": 8, "type": "virtio_disk", "uuid": "d48847d0-91b1-4edf-ab28-3be864494711", "vm_uuid": "183c5d7c-1e2e-4871-84e8-9ef35bfda5ca"}

description

string

Human-readable description

Returned: success

Sample: "demo-vm-description"

disks

list / elements=dictionary

Attached virtual block devices

Returned: success

Sample: {"cache_mode": "none", "disable_snapshotting": false, "disk_slot": 0, "iso_name": "", "mount_points": [], "read_only": false, "size": 8100100100, "tiering_priority_factor": 8, "type": "virtio_disk", "uuid": "e8c8aa6b-1043-48a0-8407-2c432d705378", "vm_uuid": "1596dab1-6f90-494c-9607-b14221830433"}

nics

list / elements=dictionary

Attached virtual network devices

Returned: success

Sample: {"connected": true, "ipv4_addresses": [], "mac": "12-34-56-78-AB", "type": "virtio", "uuid": "07a2a68a-0afa-4718-9c6f-00a39d08b67e", "vlan": 15}

node_affinity

dictionary

VM’s node affinity strategy

Returned: success

Sample: {"backup_node": {"backplane_ip": "10.0.0.3", "lan_ip": "10.0.0.4", "node_uuid": "f6v3c6b3-99c6-475b-8e8e-9ae2587db5fc", "peer_id": 2}, "preferred_node": {"backplane_ip": "10.0.0.1", "lan_ip": "10.0.0.2", "node_uuid": "638920f2-1069-42ed-b311-5368946f4aca", "peer_id": 1}, "strict_affinity": true}

power_state

string

VM’s power state

Returned: success

Sample: "stopped"

replication_source_vm_uuid

string

added in scale_computing.hypercore 1.3.0

UUID of source VM if this VM is a replicated VM. Empty string is returned if this VM is not replicated.

Returned: success

Sample: "64c9b3a1-3eab-4d16-994f-177bed274f84"

snapshot_schedule

string

Name identifier of a snapshot schedule for automated snapshots

Returned: success

Sample: "demo-snapshot-schedule"

tags

string

User-modifiable words for organizing a group of VMs

Returned: success

Sample: "group-name,tag1,tag2"

uuid

string

Unique identifier

Returned: success

Sample: "f0c91f97-cbfc-40f8-b918-ab77ae8ea7fb"

vcpu

integer

Number of allotted virtual CPUs

Returned: success

Sample: 2

vm_name

string

Human-readable virtual machine name

Returned: success

Sample: "demo-vm"

vm_rebooted

boolean

Info if reboot of the VM was performed.

Returned: success

Sample: true

Authors

  • Domen Dobnikar (@domen_dobnikar)

  • Tjaž Eržen (@tjazsch)