Ansible Module Deep Dive: Using vmware_guest for Full Control
VMware environments often begin with a few manually created virtual machines and quickly grow into a fleet that needs consistent provisioning. The vmware_guest module in the Ansible community VMware collection provides a practical way to manage that lifecycle through repeatable playbooks rather than vSphere Client clicks.
It can create, update, power on, shut down, clone, customise and remove virtual machines. Used carefully, it becomes a single automation interface for compute, memory, virtual hardware, disks, networks, guest operating system settings and VMware Tools behaviour.
This matters in Australian IT environments where distributed offices, managed service providers and regional data centres add operational complexity. A workload running in Sydney may need different network mappings from one hosted in Melbourne, while a Perth site can expose latency and DNS assumptions that remain invisible in a small lab.
The module is powerful, but it rewards deliberate design. Inventory structure, API permissions, naming conventions and idempotent task definitions have as much influence on the result as the module parameters themselves. The examples below use current Ansible VMware practices and assume the community.vmware collection is installed.
Preparing Credentials And Collection Dependencies
Install the collection on the Ansible control node before writing a playbook:
ansible-galaxy collection install community.vmware
The module communicates with vCenter through the VMware API, so the target does not need an Ansible agent. Use a vCenter FQDN or IP address, a dedicated service account and encrypted credentials stored with Ansible Vault. Avoid placing passwords directly in YAML, particularly when playbooks are shared between an internal team and an external MSP.
A typical task starts with connection variables:
- name: Provision a virtual machine
community.vmware.vmware_guest:
hostname: "{{ vcenter_hostname }}"
username: "{{ vcenter_username }}"
password: "{{ vcenter_password }}"
validate_certs: true
datacenter: "{{ datacenter }}"
folder: "{{ vm_folder }}"
name: "{{ vm_name }}"
state: poweredon
guest_id: ubuntu64Guest
hardware:
memory_mb: 8192
num_cpus: 4
Use validate_certs: false only when a lab uses an untrusted certificate and the risk is understood. In production, install a trusted vCenter certificate instead. Details about the person and technology work behind this style of automation are available in Jonathan's background.
Building A Predictable Virtual Machine Definition
A reliable VM definition specifies placement, compute, storage and networking explicitly. The datastore, cluster, resource_pool, folder and networks options should reflect your environment rather than relying on vCenter defaults.
disk:
- size_gb: 40
type: thin
datastore: "{{ datastore }}"
networks:
- name: "{{ portgroup }}"
type: static
ip: "{{ vm_ip }}"
netmask: "{{ vm_netmask }}"
gateway: "{{ vm_gateway }}"
start_connected: true
For a clone workflow, add template and use customization to apply hostname, DNS, domain membership or Linux settings. Keep the base template patched and free of machine-specific identity. A Sydney colocation facility might use a port group called Prod-SYD, while a Melbourne site uses Prod-MEL; variables should handle that difference instead of duplicating entire playbooks.
Storage policy needs equal care. Thin provisioning saves capacity, but overcommit can create an unpleasant arvo when a datastore fills during a backup cycle. Define disk sizes and provisioning types in group variables, then review changes with the same discipline used for application infrastructure.
Controlling Power, Hardware And Lifecycle State
The state parameter controls the desired lifecycle state. present ensures the VM exists, poweredon ensures it exists and is running, poweredoff stops it, and absent removes it. Be cautious with absent, especially when a variable can be supplied from a pipeline or service catalogue.
Hardware changes can be managed in the same task:
hardware:
num_cpus: 8
num_cpu_cores_per_socket: 4
memory_mb: 16384
hotadd_cpu: true
hotadd_memory: true
version: 19
Some changes require a shutdown, guest restart or VMware compatibility consideration. CPU hot-add can affect NUMA presentation, and upgrading virtual hardware may prevent a VM from moving back to an older ESXi host. Treat these options as an explicit lifecycle decision, not as harmless configuration drift.
For operations teams supporting Brisbane offices or remote sites over constrained links, idempotence is especially valuable. A playbook can enforce the intended state without requiring an administrator to maintain a separate checklist for every location. Test modifications with --check where supported, and review the task output before applying changes.
Managing Disks, NICs And Guest Customisation
vmware_guest supports multiple disks and network adapters, which makes it suitable for application servers with separate operating system, database and log volumes. Specify controller types, unit numbers and persistence requirements when the design depends on stable device ordering. Use tags or an external inventory system to record why a disk exists; YAML alone is rarely enough documentation after several years.
Network definitions can include port groups, VLAN-backed networks, MAC addresses and connection state. For static guest customisation, make sure the address is reserved and that DNS records are prepared. A common failure in hybrid Australian environments is a correct vSphere network paired with incorrect DNS search domains or firewall rules between cloud, office and colocation segments.
Guest customisation also depends on VMware Tools and the template operating system. Linux and Windows customisation have different requirements, and domain joins may need credentials with narrowly scoped permissions. When a workflow needs a PowerCLI operation that the module does not expose cleanly, a custom automation approach can complement Ansible; this PowerCLI module guide covers that pattern.
Troubleshooting, Security And Reusable Automation
Start troubleshooting with the rendered task arguments, vCenter events and the module's return data. Common errors include an incorrect folder path, a datastore unavailable to the selected cluster, a missing port group, invalid guest IDs and insufficient privileges. Use register to capture results and debug selectively, while keeping passwords out of logs.
Split reusable values into inventory groups, host variables and vaulted secrets. A role can expose variables for CPU, RAM, datastore, template, network and customisation while keeping the task structure stable. This approach fits both a home lab on an NBN connection and a larger enterprise estate spread across Sydney, Melbourne and Perth.
Limit the service account to the permissions required for the role. Separate provisioning from deletion when possible, and use approvals for destructive operations. Free virtualisation tools can also support documentation, icon standards and day-to-day VMware administration around the Ansible workflow.
Build a small test matrix before broad rollout: create a VM, rerun the playbook, resize it, attach a disk, change its network, power it off and remove it in a disposable folder. Confirm that each run converges without unnecessary changes, then promote the role through version control and CI.
Put vmware_guest at the centre of a versioned provisioning role, store secrets safely with Ansible Vault, and test every lifecycle action against a non-production vCenter. That combination turns VMware administration into an auditable workflow that can scale from a home lab to Australia-wide infrastructure.