Ansible modules interacting with VMware Workstation/Fusion Pro's REST API

Introduction: How I ended up developing a VMware Workstation/Fusion Pro Ansible module

First goal of the project is to implement all the REST API requests, for the time being, following VMware's logic.
Next goal is to rework some natives API functions interactions to make it's use simpler.

This project is still in early stage developpement.

---

Getting Started

Get vmrest up and running

Set up your credentials:

• On Windows, change directories to the Workstation Pro installation folder, and run vmrest.exe -C.
• On Unix, run vmrest -C.

Then run vmrest:

• On Windows, change directories to the Workstation Pro installation folder, and run vmrest.exe command.
• On Unix, run vmrest.

More informations on VMware REST API's docs: Workstation Pro | Fusion Pro

Install the modules

Manual installation ATM (ansible-galaxy integration as collection is WIP):

Put the content of plugins/modules to ~/.ansible/plugins/modules/ or in a library folder next to your playbooks.

Information

Info retriving

For the modules with infos retriving only purposes you must set your ansible command with verbose flag, like:

ansible-playbook -i hosts.yml playbook.yml -vvv

Native use/exploitation of returned infos is WIP.

Common variables

This 4 variables can/must to used with all the modules:

    username: "api-username"
    password: "api-password"
    api_url: "http://127.0.0.1"
    api_port: "8697"

If you are using defaults vmrest url settings then you don't have to use api_url and api_port, as their defaults values are set to vmrest's defaults.

Each time you can use target_vm you can also use target_vm_name instead, which require the display name of your VM. (The one you see on your GUI).

Documentation

Here you will found basic examples of the modules. If you need more details like all the parameters possibilities, you will found in the library folder a file name $module.py available for both windows & unix version.

Modules examples

This example are for windows's modules (Workstation Pro on Windows) but are the same for unix (Workstation Pro on Linux or Fusion Pro on macOS), you just need to replace win with unix.

Create your first playbook

Target of the playbook should be the machine who's hosting the API:

- hosts: vmware-workstation-host
  tasks:

  - name: "List all VMs"
    win_vmware_desktop_vminfos:
      username: "api-username"
      password: "api-password"

win_vmware_desktop_vminfos

• Returns a list of VM IDs and paths for all VMs

- name: "Get infos"
  win_vmware_desktop_vminfos:
    username: "api-username"
    password: "api-password"

• Returns the VM setting information of a VM

- name: "Retrieve CPU & RAM from VM with ID 42"
  win_vmware_desktop_vminfos:
    target_vm: "42"
    username: "api-username"
    password: "api-password"

win_vmware_desktop_vmmgmt

• Updates a VM CPU/RAM allocation

- name: "Change VM with ID 42's RAM allocation to 2048 & 2 vCPU"
  win_vmware_desktop_vmmgmt:
    target_vm: "42"
    action: update
    num_cpus: 2
    memory_mb: 2048
    username: "api-username"
    password: "api-password"

• Clone a VM

- name: "Clone VM with ID 42 as KMS-Server-Clone "
  win_vmware_desktop_vmmgmt:
    target_vm: "42"
    action: clone
    name: "KMS-Server-Clone"
    username: "api-username"
    password: "api-password"

• Deletes a VM

- name: "Delete VM ID 42"
  win_vmware_desktop_vmmgmt:
    target_vm: "42"
    action: delete
    username: "api-username"
    password: "api-password"

win_vmware_desktop_adaptersmgmt

• Return all network adapters in the VM

- name: "Return all network adapters in VM 42"
  win_vmware_desktop_adaptersmgmt:
    target_vm: "42"
    action: "list"
    user: "workstation-api-user"
    password: "api-password"

• Updates a network adapter in the VM

- name: "Edit NIC N°1 of VM 42 to assign it a custom type targetting vmnet10"
    win_vmware_desktop_adaptersmgmt:
    target_vm: "42"
    action: "update"
    index: 1
    type: custom
    vmnet: vmnet10
    user: "workstation-api-user"
    password: "api-password"

• Creates a network adapter in the VM

- name: "Create NIC N°1 of VM 42 and assign it a custom type targetting vmnet10"
    win_vmware_desktop_adaptersmgmt:
    target_vm: "42"
    action: "create"
    type: custom
    vmnet: vmnet10
    user: "workstation-api-user"
    password: "api-password"

• Deletes a VM network adapter

- name: "Delete NIC N°1 of VM 42 "
    win_vmware_desktop_adaptersmgmt:
    target_vm: "42"
    action: "delete"
    index: 1
    user: "workstation-api-user"
    password: "api-password"

• Returns the IP address of a VM

Doesn't work with VMs having multiple NICs

- name: "Return IP address of VM 42"
  win_vmware_desktop_adaptersmgmt:
    target_vm: "42"
    action: "getip"
    user: "workstation-api-user"
    password: "api-password"

win_vmware_desktop_power

• Returns the power state of the VM

- name: "Get power state of the VM with ID 42 "
  win_vmware_desktop_power:
    target_vm: "42"
    username: "api-username"
    password: "api-password"

• Changes the VM power state

- name: "Start VM with ID 42"
  win_vmware_desktop_power:
    target_vm: "42"
    state: "on"
    username: "api-username"
    password: "api-password"

win_vmware_desktop_foldersmgmt

• Returns all shared folders mounted in a VM

- name: "List all shared folders mounted on VM ID 42"
  win_vmware_desktop_foldersmgmt:
    target_vm: "42"
    action: "infos"
    username "api-username"
    password: "api-password"

• Create a shared folder mounted in a VM

- name: "Create shared folder named ODBG110 on VM ID 42"
  win_vmware_desktop_foldersmgmt:
    target_vm: "42"
    folder_name: "ODBG110"
    folder_path: C:\Users\qsypoq\Desktop\odbg110
    access: "rw"
    action: "create"
    username "api-username"
    password: "api-password"

• Update shared folder

- name: "Update shared folder named ODBG110 with new path and access rights"
  win_vmware_desktop_foldersmgmt:
    target_vm: "42"
    folder_name: "ODBG110"
    folder_path: C:\Users\qsypoq\Desktop
    access: "r"
    action: "update"
    username "api-username"
    password: "api-password"

• Deletes a shared folder

- name: "Delete shared folder named ODBG110 on VM ID 42"
  win_vmware_desktop_foldersmgmt:
    target_vm: "42"
    folder_name: "ODBG110"
    action: "delete"
    username "api-username"
    password: "api-password"

win_vmware_desktop_netmgmt

For this part to work you need to run vmrest with privileges.

• Returns all virtual networks

- name: "Get infos of all the configured vmnets"
  win_vmware_desktop_netmgmt:
    action: infos
    username: "api-username"
    password: "api-password"

• Creates a virtual network

- name: "Create a new vmnet as vmnet13, as host only"   
  win_vmware_desktop_netmgmt:
    vmnet: "vmnet13"
    type: "hostonly"
    action: create
    username: "api-username"
    password: "api-password"

• Returns all MAC-to-IP settings for DHCP service

- name: "Return all Mac-to-IP settings from vmnet8"
  win_vmware_desktop_netmgmt:
    action: infos
    vmnet: "vmnet8"
    setting: "mactoip"
    username: "api-username"
    password: "api-password"

• Returns all port forwardings

- name: "Return all the forwarded ports settings from vmnet8"
  win_vmware_desktop_netmgmt:
    action: infos
    vmnet: "vmnet13"
    setting "portforward"
    username: "api-username"
    password: "api-password"

• Deletes port forwarding

- name: "Delete the forwarded 1337 tcp port from vmnet8"   
  win_vmware_desktop_netmgmt:
    vmnet: "vmnet8"
    protocol: "TCP"
    port: "1337"
    action: delete
    username: "api-username"
    password: "api-password"

• Updates port forwarding

- name: "Update the forwarded 1337 tcp port from vmnet8 to 172.13.13.13:1111 with "itworks!" as description"
  win_vmware_desktop_netmgmt:
    vmnet: "vmnet8"
    protocol: "TCP"
    port: "1337"
    guest_ip_address: "172.13.13.13"
    guest_port: "1111"
    guest_description: "itworks!"
    action: update_pf
    username: "api-username"
    password: "api-password"

• Updates the MAC-to-IP binding

- name: "Update the MAC 00:12:29:34:4B:56 to be assigned as 192.168.188.13 on vmnet8"
  win_vmware_desktop_netmgmt:
    vmnet: "vmnet8"
    mac_address: "00:12:29:34:4B:56"
    ip_address: "192.168.188.13"
    action: update_mti
    username: "api-username"
    password: "api-password"

🚧 Todo-List / Roadmap

Information gathering / Returned infos to user while running playbooks

• Make information returned by requests (like VM Id or state) easily exploitable via playbook.

• Create self explaining error info when something goes wrong instead of "Check your inputs"

Check user input/rationnal behaviour

• Example: Would be great if we could prevent a user to disconnect the network adapter of the VM ansible is run from.

Code refractoring

• If statements can be replaced/optimised/concatenated.