Posted inVMware

Automating VMware Workstation with REST API: From Clicks to Code

VMware tutorial - IT technology blog
VMware tutorial - IT technology blog

Why You Should Stop Using GUI and Move to API?

Opening the VMware Workstation interface and clicking through each virtual machine is fine for 1-2 simple labs. However, imagine you are building a CI/CD pipeline. Every time code is pushed, the system needs a clean state VM to run tests for 5 minutes and then self-destruct to free up 8GB of RAM for other tasks. In such cases, manual intervention is impossible.

Many might think of PowerCLI. It’s powerful but tied to PowerShell and Windows. In contrast, the VMware Workstation REST API is much more flexible. You can control VMs from a Bash script on Linux, a Python application, or even Postman.

In large-scale projects, using the API can reduce environment setup time by 90%. Instead of spending 15 minutes preparing a lab, you only need a single command.

Quick Start: Enable the API Server in 2 Minutes

By default, VMware Workstation does not have the API server enabled. You need to start it manually via the vmrest.exe executable located in the installation directory.

Step 1: Set Up Credentials

First, open a Terminal (cmd or PowerShell) with Administrator privileges. Navigate to the C:\Program Files (x86)\VMware\VMware Workstation directory and run the command to create a user/pass:

vmrest.exe -u admin -p MySecretPassword

Note: This password will be used to authenticate future HTTP requests.

Step 2: Run the Server

Once configured, simply run the command:

vmrest.exe

If you see the line Served to http://127.0.0.1:8697, it means the server is ready to receive commands.

How the VMware REST API Works

This API operates as an internal web server listening on port 8697. All VM management tasks are performed through standard HTTP requests like GET, PUT, and POST.

Authentication

The system uses Basic Auth. You need to send the Base64-encoded User/Pass in the Header. If using Postman, just go to the Authorization tab, select Basic Auth, fill in the credentials, and you’re done.

Querying the VM List

To retrieve the IDs of existing virtual machines, send a GET request to the /api/vms endpoint.

Example using cURL:

curl -u "admin:MySecretPassword" -X GET http://127.0.0.1:8697/api/vms

The result is a JSON array. Save the id value as you will need it to control the VM in subsequent steps.

Hands-on: Controlling VMs via Command Line

Below are the 3 most common commands you will use frequently.

1. Check VM Status

Assuming the VM ID is ABC123XYZ, the check command is as follows:

curl -u "admin:MySecretPassword" -X GET http://127.0.0.1:8697/api/vms/ABC123XYZ/power

2. Power On VM

Use the PUT method and pass on as the body:

curl -u "admin:MySecretPassword" -X PUT http://127.0.0.1:8697/api/vms/ABC123XYZ/power -H "Content-Type: application/vnd.vmware.vmw.rest-v1+json" -d "on"

3. Graceful Shutdown

Instead of a hard power-off, use shutdown so the guest OS can shut down properly:

curl -u "admin:MySecretPassword" -X PUT http://127.0.0.1:8697/api/vms/ABC123XYZ/power -H "Content-Type: application/vnd.vmware.vmw.rest-v1+json" -d "shutdown"

Optimizing Bulk Management with Python

When the number of VMs reaches dozens, typing cURL for each command becomes time-consuming. Python is the perfect alternative for bulk processing.

import requests
from requests.auth import HTTPBasicAuth

BASE_URL = "http://127.0.0.1:8697/api"
AUTH = HTTPBasicAuth('admin', 'MySecretPassword')

def power_on_lab_vms():
    # Get the entire list of virtual machines
    vms = requests.get(f"{BASE_URL}/vms", auth=AUTH).json()
    
    for vm in vms:
        # Only power on virtual machines located in the Lab folder
        if "Lab" in vm['path']:
            url = f"{BASE_URL}/vms/{vm['id']}/power"
            headers = {'Content-Type': 'application/vnd.vmware.vmw.rest-v1+json'}
            requests.put(url, auth=AUTH, headers=headers, data="on")
            print(f"Sent power-on command for: {vm['path']}")

power_on_lab_vms()

Practical Experience and Tips

  • Data Security: Avoid exposing port 8697 to the internet. If remote control via LAN is needed, configure your firewall to allow access only from specific IP addresses.
  • Handling Port Conflicts: If port 8697 is already occupied by another application, change it using the command vmrest.exe -p 9000.
  • Mandatory Requirement: Features like shutdown or retrieving the VM’s IP address only work if VMware Tools is installed inside that VM.
  • Internal Documentation: VMware includes a built-in Swagger interface. Simply visit http://127.0.0.1:8697 in your browser to view the full API documentation and test it directly.

Mastering the REST API helps you transition toward an Infrastructure as Code (IaC) mindset. Instead of manual operations, let code run your lab environment automatically.

Share:
Tags: