vmware.vmware_rest.vcenter_vm_hardware_boot module – Manage the boot configuration of a virtual machine.

Note

This module is part of the vmware.vmware_rest collection (version 5.0.0).

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 vmware.vmware_rest.

To use it in a playbook, specify: vmware.vmware_rest.vcenter_vm_hardware_boot.

New in vmware.vmware_rest 5.0.0

Synopsis

  • Update the boot-related settings of a virtual machine.

  • Controls the firmware type (BIOS or EFI), the boot delay, the network boot protocol, and how the virtual machine behaves when a boot attempt fails.

  • Only the settings you provide are changed; any option left unset keeps its current value.

Parameters

Parameter

Comments

delay

integer

Delay in milliseconds before the firmware boot process begins when the virtual machine is powered on.

This delay gives users a time window to connect to the virtual machine console and enter BIOS setup mode.

If not set, the current value is left unchanged.

efi_legacy_boot

boolean

Whether to use EFI legacy boot mode.

Only relevant when type=EFI.

If not set, the current value is left unchanged.

Choices:

  • false

  • true

enter_setup_mode

boolean

Whether the firmware boot process should automatically enter setup mode the next time the virtual machine boots.

This flag is automatically reset to false once the virtual machine enters setup mode.

If not set, the current value is left unchanged.

Choices:

  • false

  • true

network_protocol

string

Protocol to use when the virtual machine attempts to boot over the network.

IPV4 uses PXE or Apple NetBoot over IPv4.

IPV6 uses PXE over IPv6.

Only relevant when type=EFI.

If not set, the current value is left unchanged.

retry

boolean

Whether the virtual machine should automatically retry the boot process after a failure.

If not set, the current value is left unchanged.

Choices:

  • false

  • true

retry_delay

integer

Delay in milliseconds before retrying the boot process after a failure.

Only applied when retry=true.

If not set, the current value is left unchanged.

session_timeout

float

Timeout in seconds for the whole operation including connection establishment, request sending, and response.

Default: 300.0

state

string

The desired state of the resource.

Use present to create or update the resource.

Choices:

  • "present" ← (default)

type

string

The firmware type used by the virtual machine when it boots.

BIOS uses Basic Input/Output System (BIOS) firmware.

EFI uses Extensible Firmware Interface (EFI) firmware.

If not set, the current value is left unchanged.

vcenter_hostname

string / required

The hostname or IP address of the vSphere vCenter.

If the value is not specified in the task, the value of environment variable VMWARE_HOST will be used instead.

vcenter_password

string / required

The vSphere vCenter password.

If the value is not specified in the task, the value of environment variable VMWARE_PASSWORD will be used instead.

vcenter_port

integer

The port number of the vSphere vCenter.

If the value is not specified in the task, the value of environment variable VMWARE_PORT will be used instead.

vcenter_rest_log_file

string

Optional path to a log file for HTTP REST interaction.

If the value is not specified in the task, the value of environment variable VMWARE_REST_LOG_FILE will be used instead.

vcenter_username

string / required

The vSphere vCenter username.

If the value is not specified in the task, the value of environment variable VMWARE_USER will be used instead.

vcenter_validate_certs

boolean

Allows connection when SSL certificates are not valid.

Set to false when certificates are not trusted.

If the value is not specified in the task, the value of environment variable VMWARE_VALIDATE_CERTS will be used instead.

Choices:

  • false

  • true ← (default)

vm

string / required

Identifier of the virtual machine whose boot configuration should be managed.

Must be an identifier (MOID) for a Vm resource.

Notes

Note

  • Generated from vSphere API spec 9.1.0.

  • Compatible with vSphere API 7.0.3.

  • Compatible with vSphere API 8.0.2.

Examples

- name: Look up the virtual machine by name
  register: search_result
  vmware.vmware_rest.vcenter_vm_info:
    filter_names:
      - test_vm1

- name: Set a boot delay so the console can be opened before boot
  vmware.vmware_rest.vcenter_vm_hardware_boot:
    vm: '{{ search_result.value[0].vm }}'
    delay: 10000
    state: present

- name: Configure EFI firmware with network boot and automatic retry
  vmware.vmware_rest.vcenter_vm_hardware_boot:
    vm: '{{ search_result.value[0].vm }}'
    type: EFI
    network_protocol: IPV4
    retry: true
    retry_delay: 15000
    state: present

Return Values

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

Key

Description

id

string

MOID of the virtual machine whose boot configuration was managed.

Returned: When state is present, or when a resource is deleted, or when state is set to a supported action.

Sample: "vm-1001"

value

any

The raw API response body from the vCenter operation.

The boot update endpoint returns no content on success, so this value is typically empty.

Returned: On success.

Sample: {}

Authors

  • Ansible Eco Content Team (@eco-ansible-content)