In last post of this series we looked into some basic Rest API’s to fetch info about datacenter and cluster.
In this post we will explore API options for virtual machines. Out of all the components like host, cluster etc, max number of available API options are for virtual machines.
Let’s start with figuring out available options:
To start exploring the different API options available for virtual machine, you can use below query:
|
1 |
# curl -sik -H 'Accept: application/json' -H 'vmware-api-session-id: 3762fda1e69484ce746e93d9332f6ada' -X GET https://vcentersrv01.alex.local/rest/com/vmware/vapi/rest/navigation/resource/id:VirtualMachine |
1: List all VM’s in all datacenter
|
1 |
# curl -sik -H 'Accept: application/json' -H 'vmware-api-session-id: 3762fda1e69484ce746e93d9332f6ada' -X GET https://vcentersrv01.alex.local/rest/vcenter/vm |
Output of above query will give you VM ID, cpu/memory stats, VM name and their power status.
2: List Powered off VM’s
You can list all powered off VM’s in datacenter using the filter power_states in above query.
|
1 2 |
curl -sik -H 'Accept: application/json' -H 'vmware-api-session-id: 3762fda1e69484ce746e93d9332f6ada' -X GET https://vcentersrv01.alex.local/rest/vcenter/vm?filter.power_states=POWERED_OFF |
3: List all VM in a specific datacenter
If you have more than one datacenter/vcenter, then you can use filter.datacenters to list VM’s belonging to that datacenter. Remember that we have to supply datacenter ID and not the name in below query:
|
1 2 |
# curl -sik -H 'Accept: application/json' -H 'vmware-api-session-id: 3762fda1e69484ce746e93d9332f6ada' -X GET https://vcentersrv01.alex.local/rest/vcenter/vm?filter.datacenters=datacenter-2 |
4: List all VM in a cluster
Below query will list details of all VM’s that are in a clusters. Again we have to use a filter for cluster and supply the cluster id.
|
1 2 |
# curl -sik -H 'Accept: application/json' -H 'vmware-api-session-id: 3762fda1e69484ce746e93d9332f6ada' -X GET https://vcentersrv01.alex.local/rest/vcenter/vm?filter.clusters=domain-c26 |
5: List all VM on a particular host
You can list all VM’s that resides on a particular host by using the filter for hosts.
|
1 2 |
# curl -sik -H 'Accept: application/json' -H 'vmware-api-session-id: 3762fda1e69484ce746e93d9332f6ada' -X GET https://vcentersrv01.alex.local/rest/vcenter/vm?filter.hosts=host-28 |
You can grab id of your esxi hosts using below query
# curl -sik -X GET -H ‘Accept: application/json’ -H ‘vmware-api-session-id: 68398bd2a6aa39a9aa81fe0bc65ab3d1’ https://vcentersrv01.alex.local/rest/vcenter/host
|
1 2 3 4 5 6 7 |
{"host":"host-28","name":"esxi01.alex.local","connection_state":"CONNECTED","power_state":"POWERED_ON"} {"host":"host-31","name":"esxi02.alex.local","connection_state":"CONNECTED","power_state":"POWERED_ON"} {"host":"host-33","name":"esxi03.alex.local","connection_state":"CONNECTED","power_state":"POWERED_ON"} {"host":"host-35","name":"esxi04.alex.local","connection_state":"CONNECTED","power_state":"POWERED_ON"} |
6: Delete a particular vm
Below query will remove a particular VM from your environment. For doing this you should know the VM ID of the VM which you want to delete. You can use query#1 of this post to grab VM ID
|
1 2 |
# curl -sik -H 'Accept: application/json' -H 'vmware-api-session-id: 3762fda1e69484ce746e93d9332f6ada' -X DELETE https://vcentersrv01.alex.local/rest/vcenter/vm/vm-40 |
You can verify VM deletion in Web Client Task and Events.
7: Info about particular vm
Below query will return a lot of info for a VM like number of disks and their type, info about CD ROM and whether or not its connected. Also CPU/Memory stats with hot add enabled or not etc.
# curl -sik -H ‘Accept: application/json’ -H ‘vmware-api-session-id: 3762fda1e69484ce746e93d9332f6ada’ -X GET
https://vcentersrv01.alex.local/rest/vcenter/vm/vm-40
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 |
"cdroms": [ { "value": { "start_connected": false, "backing": { "auto_detect": false, "device_access_type": "EMULATION", "type": "HOST_DEVICE", "host_device": "CD/DVD drive 0" }, "allow_guest_control": true, "label": "CD/DVD drive 1", "ide": { "primary": true, "master": true }, "state": "NOT_CONNECTED", "type": "IDE" }, "key": "3000" } ], "memory": { "hot_add_increment_size_MiB": 128, "size_MiB": 10240, "hot_add_enabled": true, "hot_add_limit_MiB": 163840 }, "disks": [ { "value": { "scsi": { "bus": 0, "unit": 9 }, "backing": { "vmdk_file": "[iSCSI-1] vcentersrv02.alex.local/vcentersrv02.alex.local.vmdk", "type": "VMDK_FILE" }, "label": "Hard disk 1", "type": "SCSI", "capacity": 12884901888 }, "key": "2000" }, { "value": { "scsi": { "bus": 0, "unit": 11 }, "scsi_adapters": [ { "value": { "scsi": { "bus": 1, "unit": 7 }, "pci_slot_number": 32, "label": "SCSI controller 1", "type": "LSILOGIC", "sharing": "NONE" }, "key": "1001" }, { "value": { "scsi": { "bus": 0, "unit": 7 }, "pci_slot_number": 16, "label": "SCSI controller 0", "type": "LSILOGIC", "sharing": "NONE" }, "key": "1000" } ], "power_state": "POWERED_ON", "floppies": [], "name": "vcentersrv02.alex.local", "nics": [ { "value": { "start_connected": true, "pci_slot_number": 160, "backing": { "connection_cookie": 1788152499, "distributed_switch_uuid": "50 14 df fd 3e 62 45 e5-86 bb 10 3f d1 e3 88 c5", "distributed_port": "4", "type": "DISTRIBUTED_PORTGROUP", "network": "dvportgroup-21" }, "mac_address": "00:50:56:94:51:90", "mac_type": "ASSIGNED", "allow_guest_control": true, "wake_on_lan_enabled": true, "label": "Network adapter 1", "state": "CONNECTED", "type": "VMXNET3", "upt_compatibility_enabled": true }, "key": "4000" } ], "boot": { "delay": 0, "retry_delay": 10000, "enter_setup_mode": false, "type": "BIOS", "retry": false }, "serial_ports": [], "guest_OS": "OTHER_3X_LINUX_64", "boot_devices": [], "hardware": { "upgrade_policy": "NEVER", "upgrade_status": "NONE", "version": "VMX_10" |
8: Power state of a VM
You can query power state of a virtual machine using below query
# curl -sik -H ‘Accept: application/json’ -H ‘vmware-api-session-id: 50c05b3bd6d2b2493e59b44bb00ea421’ -X GET https://vcentersrv01.alex.local/rest/vcenter/vm/vm-57/power
|
1 2 3 4 5 6 7 |
HTTP/1.1 200 OK Date: Sun, 18 Dec 2016 15:55:54 GMT Content-Type: application/json Transfer-Encoding: chunked {"value": {"state":"POWERED_ON"} } |
9: Reset a powered-on VM
You can restart a powered on VM using a post call against the VM id as shown below:
# curl -sik -H ‘Accept: application/json’ -H ‘vmware-api-session-id: 50c05b3bd6d2b2493e59b44bb00ea421’ -X POST https://vcentersrv01.alex.local/rest/vcenter/vm/vm-57/power/reset
The list is long and its not possible for me to test each and every query in lab and paste the output here. So I have compiled a list of various options that you can test in your environment.
=============================================================
POWER
=============================================================
Resets a powered-on virtual machine.
POST https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/power/reset
Powers off a powered-on or suspended virtual machine.
POST https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/power/stop
Powers on a powered-off or suspended virtual machine.
POST https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/power/start
Suspends a powered-on virtual machine.
POST https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/power/suspend
Returns the power state information of a virtual machine.
GET https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/power
===============================================================
Boot
===============================================================
Returns the boot-related settings of a virtual machine
GET https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/hardware/boot
Returns an ordered list of boot devices for the virtual machine. If the list is empty, the virtual machine uses a default boot sequence.
GET https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/hardware/boot/device
Updates the boot-related settings of a virtual machine.
PATCH https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/hardware/boot
Sets the virtual devices that will be used to boot the virtual machine.
The virtual machine will check the devices in order, attempting to boot from each, until the virtual machine boots successfully. If the list is empty, the virtual machine will use a default boot sequence.
There should be no more than one instance of Device.Entry for a given device type except ETHERNET in the list.
PUT https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/hardware/boot/device
=====================================================
VM HARDWARE
======================================================
Returns information about a virtual machine.
GET https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}
Deletes a virtual machine
DELETE https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}
Returns the virtual hardware settings of a virtual machine.
GET https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/hardware
Updates the virtual hardware settings of a virtual machine.
PATCH https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/hardware
Upgrades the virtual machine to a newer virtual hardware version.
POST https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/hardware/action/upgrade
Returns the memory-related settings of a virtual machine.
GET https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/hardware/memory
Updates the memory-related settings of a virtual machine.
PATCH https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/hardware/memory
Returns the CPU-related settings of a virtual machine.
GET https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/hardware/cpu
Updates the CPU-related settings of a virtual machine.
PATCH https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/hardware/cpu
========================================================
vNIC
========================================================
Returns information about the Ethernet adapters belonging to the virtual machine.
GET https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/hardware/ethernet
Returns information about a Ethernet adapter.
GET https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/hardware/ethernet/{nic}
Adds a Ethernet adapter to the virtual machine.
POST https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/hardware/ethernet
Removes a Ethernet adapter from the virtual machine.
DELETE https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/hardware/ethernet/{nic}
Updates the configuration of a Ethernet adapter.
PATCH https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/hardware/ethernet/{nic}
Connects a Ethernet adapter of a powered-on virtual machine.
For a powered-off virtual machine, the Ethernet.update operation may be used to configure the virtual Ethernet adapter to start in the connected state when the virtual machine is powered on
POST https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/hardware/ethernet/{nic}/connect
Disconnects a Ethernet adapter of a powered-on virtual machine.
The virtual device is still present and its backing configuration is unchanged, but from the perspective of the guest operating system, the Ethernet adapter is not connected to its backing resource.
For a powered-off virtual machine, the Ethernet.update operation may be used to configure the virtual Ethernet adapter to start in the disconnected state when the virtual machine is powered on.
POST https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/hardware/ethernet/{nic}/disconnect
=====================================================
Virtual disk
=====================================================
Returns information about the virtual disks belonging to the virtual machine.
GET https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/hardware/disk
Updates the configuration of a virtual disk.
An update operation can be used to detach the existing VMDK file and attach another VMDK file to the virtual machine.
PATCH https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/hardware/disk/{disk}
Returns information about a virtual disk.
GET https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/hardware/disk/{disk}
Adds a virtual disk to the virtual machine.
While adding the virtual disk, a new VMDK file may be created or an existing VMDK file may be used to back the virtual disk.
POST https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/hardware/disk
Removes a virtual disk from the virtual machine.
This operation does not destroy the VMDK file that backs the virtual disk. It only detaches the VMDK file from the virtual machine. Once detached, the VMDK file will not be destroyed when the virtual machine to which it was associated is deleted.
DELETE https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/hardware/disk/{disk}
=================================================
SATA Adapters
=================================================
Returns information about a virtual SATA adapter.
GET https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/hardware/adapter/sata/{adapter}
Returns information about SATA adapters belonging to the virtual machine.
GEThttps://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/hardware/adapter/sata
Adds a virtual SATA adapter to the virtual machine.
POST https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/hardware/adapter/sata
Removes a virtual SATA adapter from the virtual machine.
DELETE https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/hardware/adapter/sata/{adapter}
==============================================
SCSI Adapters
==============================================
Returns information about a virtual SCSI adapter.
GET https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/hardware/adapter/scsi/{adapter}
Returns information about the SCSI adapters belonging to the virtual machine.
GET https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/hardware/adapter/scsi
Adds a virtual SCSI adapter to the virtual machine.
POST https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/hardware/adapter/scsi
Removes a virtual SCSI adapter from the virtual machine.
DELETE https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/hardware/adapter/scsi/{adapter}
Updates the configuration of a virtual SCSI adapter.
PATCH https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/hardware/adapter/scsi/{adapter}
================================================
CD ROM
================================================
Returns information about a virtual CD-ROM device.
GET https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/hardware/cdrom/{cdrom}
Returns information about the virtual CD-ROM devices belonging to the VM.
GET https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/hardware/cdrom
Adds a virtual CD-ROM device to the virtual machine.
POST https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/hardware/cdrom
Removes a virtual CD-ROM device from the virtual machine.
DELETE https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/hardware/cdrom/{cdrom}
Updates the configuration of a virtual CD-ROM device.
PATCH https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/hardware/cdrom/{cdrom}
Connects a virtual CD-ROM device of a powered-on virtual machine.
Connecting the virtual device makes the backing accessible from the perspective of the guest operating system.
For a powered-off virtual machine, the Cdrom.update operation may be used to configure the virtual CD-ROM device to start in the connected state when the virtual machine is powered on.
POST https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/hardware/cdrom/{cdrom}/connect
Disconnects a virtual CD-ROM device of a powered-on virtual machine.
The virtual device is still present and its backing configuration is unchanged, but from the perspective of the guest operating system, the CD-ROM device is not connected to its backing resource.
For a powered-off virtual machine, the Cdrom.update operation may be used to configure the virtual CD-ROM device to start in the disconnected state when the virtual machine is powered on.
POST https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/hardware/cdrom/{cdrom}/disconnect
Unmounts a previously mounted CD-ROM using an ISO image as a backing.
POST https://vcentersrv01.alex.local/rest/com/vmware/vcenter/iso/image/id:{vm}?~action=unmount
===================================================
Serial Ports
===================================================
Returns information about a serial port.
GET https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/hardware/serial/{port}
Returns information about the serial ports belonging to the virtual machine.
GET https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/hardware/serial
Adds a virtual serial port to the virtual machine.
POST https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/hardware/serial
Removes serial port from the virtual machine.
DELETE https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/hardware/serial/{port}
Updates the configuration of a serial port.
PATCH https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/hardware/serial/{port}
Connects a virtual serial port of a powered-on virtual machine to its backing.
POST https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/hardware/serial/{port}/connect
Disconnects a virtual serial port of a powered-on virtual machine from its backing.
POST https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/hardware/serial/{port}/disconnect
=================================================
Parallel Ports
=================================================
Returns information about a virtual parallel port.
GET https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/hardware/parallel/{port}
Returns information about the parallel ports belonging to the virtual machine.
GET https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/hardware/parallel
Adds a virtual parallel port to the virtual machine.
POST https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/hardware/parallel
Removes parallel port from the virtual machine.
DELETE https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/hardware/parallel/{port}
Updates the configuration of a virtual parallel port
PATCH https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/hardware/parallel/{port}
Connects a parallel port of a powered-on VM.
POST https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/hardware/parallel/{port}/connect
Disconnects a virtual parallel port of a powered-on virtual machine from its backing.
POST https://vcentersrv01.alex.local/rest/vcenter/vm/{vm}/hardware/parallel/{port}/disconnect
I hope this post is informational to you. Feel free to share this on social media if it is worth sharing. Be sociable 
4 thoughts on “Exploring vSphere 6.5 API-Part 2: Virtual Machines”