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
ansible-galaxy collection install qsypoq.vmware_desktop
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"
validate_certs: no
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.
If you are using HTTPS you might want to use validate_certs, default is set to no.
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. If you need more details you can find a file named $module.py available for both windows & unix version in the modules folder.
First POC: Your VM needs to be named after VM's FQDN (myvm.mylocaldomain for example)
- Create a file named
vmware_desktop.ymlwith this content:
plugin: 'qsypoq.vmware_desktop.inventory'
url: 'your_api_ip'
port: 'you_api_port'
user: 'your_api_user'
password: 'your_api_password'
You can now pass it as an argument like ansible-playbook test.yml -i vmware_desktop.yml
For this first POC VM have only one hostvar: their VM ID, so you can use it in your playbook to target them with target_vm
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.
Specify the collection qsypoq.vmware_desktop
Playbook's host should be the machine hosting the API:
- hosts: vmware-workstation-host
gather_facts: no
collections:
- qsypoq.vmware_desktop
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"
- Retrieve the VM restrictions
- name: "Get restrictions"
win_vmware_desktop_vminfos:
target_vm_name: "Windows 10"
restrictions: True
username: "api-username"
password: "api-password"
- Retrieve specific VMX param
- name: "Get extendedConfigFile from VM ID 42"
win_vmware_desktop_vminfos:
target_vm: "42"
param: "extendedConfigFile"
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"
- Register a VM
- name: "Register VM with name ansible_test2"
win_vmware_desktop_vmmgmt:
name: "ansible_test2"
action: register
vmx_path: 'C:\Users\Qsypoq\Documents\Virtual Machines\ansible_test2\svc_pfSense.vmx'
username: "api-username"
password: "api-password"
- Update specific VMX param (NOT WORKING ATM)
- name: "Update displayName param"
win_vmware_desktop_vmmgmt:
target_vm_name: "pfsense"
action: update
param: displayName
value: pfsense_OLD
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 may be replaced/optimised.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent