Exploring vSphere 6.5 API-Part 2: Virtual Machines

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: List all VM’s in all datacenter

Output of above query will give you VM ID, cpu/memory stats, VM name and their power status.

all-vm

2: List Powered off VM’s

You can list all powered off VM’s in datacenter using the filter power_states in above query.

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:

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.

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.

vm-on-a-host

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

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

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

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

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 🙂