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.
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.execommand. - On Unix, run
vmrest.
More informations on VMware REST API's docs: Workstation Pro | Fusion Pro
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.
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.
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).
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.
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.
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"
- 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"
- 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"
- 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"
- 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"
- 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"
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"
-
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"
- Example: Would be great if we could prevent a user to disconnect the network adapter of the VM ansible is run from.
- If statements can be replaced/optimised/concatenated.