Hyper-V APIs: Taking Control of Windows Virtualization

Hyper-V is a popular virtualization system that ships with all Windows systems by default. It supports anything from running a single VM on a Windows machine to running thousands of VMs in an enterprise data center. As you expand your use of Hyper-V, you will need to customize its activity and integrate it with automated tools used by your organization. To this end, Microsoft provides a rich set of APIs that enable you to programmatically control every aspect of the Hyper-V system.

What is Hyper-V?

Hyper-V is a native hypervisor that enables you to create and run virtual machines (VMs) on Windows systems. It is a common alternative to VMware. A VM is a virtual compute system that runs programs in an isolated environment, on top of a host operating system. 

Each VM you create with Hyper-V runs in an isolated space, allowing you to run multiple VMs simultaneously on the same hardware. This capability enables you to isolate crashes to the space of origin and provision resources granularly. Hypervisors like Hyper-V are the basis for implementing cloud computing models such as private cloud and hybrid cloud.

Windows Virtualization: Windows 10 vs Windows Server

Hyper-V in Windows and Windows Server supersedes older hardware virtualization products, including Microsoft Virtual Server, Microsoft Virtual PC, and Windows Virtual PC. Hyper-V provides performance, security, networking, and storage features not accessible via the older products.  

It is important to understand the distinction between Hyper-V on Windows 10 compared to the version of Hyper-V that ships with Windows Server.

Here are some Hyper V-features available only on Windows Server: 

• Live migration of VMs from one host to another
• Hyper-V Replica
• Virtual Fiber Channel
• SR-IOV networking
• Shared .VHDX

Here are some Hyper-V features only available on Windows 10: 

• Quick Create and the VM Gallery
• Default network (NAT switch)

In addition, the memory management approach is different in Hyper-V on Windows. On a server, Hyper-V memory is handled based on the assumption that only VMs run on the server. In Hyper-V on Windows, memory is handled assuming that most client machines run additional software alongside VM workloads. 

Hyper-V APIs Tools

Hyper-V provides a range of APIs that allow users to create and manage virtual machines programmatically, and integrate virtualization with existing processes and tools. 

We’ll provide an overview of the most commonly used APIs. For more details see the Microsoft Hyper-V API documentation.

Hyper-V WMI Provider

The Windows Management Instrumentation (WMI) provider lets you build custom tools and utilities for Hyper-V. You can use WMI interfaces to manage all aspects of Hyper-V. It provides the following APIs:

• Application health monitoring API—monitor the health of applications running in virtual machines.
• Replication API—control replication and failover of virtual machines between hosts.
• Metrics API—collect metrics about applications running in a virtual machine for monitoring purposes.
• Networking API—control networking of Hyper-V VMs.
• Hyper-V migration API—manage storage and live migrations of VMs.
• Hyper-V virtual Fiber Channel API—control virtual fiber channel (VBC) adapters, which provide guest operating systems access to a SAN.
• Hyper-V VM placement API—access compatibility info for VMs or the hosts they are running on.

Host Compute System APIs

The Host Compute API lets you access VMs and containers running on Windows machines. The API uses the concept of a compute system, which represents a VM or a container you created via the API. All operations are performed against a handle that represents a compute system.

Compute systems have the following properties:

• They are ephemeral—once a compute system is stopped, it is cleaned up and you cannot perform additional operations on the same handle (except for viewing exit status).
• They support operations including creating, starting, and stopping a compute system. If the compute system is a VM, you can perform additional operations like pause, save, and restore. 

For containers, the Host Compute API is the main way applications on a host create containers and interact with container workloads.

Host Compute Network (HCN) Service API

The HCN Service API is a Win32 API that lets you manage virtual networks and associated policies. It provides secure connectivity and network segmentation for VMs and containers on Windows hosts, which is a critical part of a security strategy for virtualized environments. 

The HCN Service API is implemented in C and the API server is hosted by the Host Network Service on the OnCore VM.

The HCN Service API allows you to:

• Create, modify, enumerate, and delete networks, network endpoints, network policies, and namespaces. These objects are implemented via RPC context handles.
• Leverage strongly typed, versioned, well-documented schemas for API operations, with input and output defined as JSON documents.
• Use a subscription/callback model to register for notifications on events like network creation, network deletion, and network policy changes.
• Support Desktop Bridge (Centennial) applications, with the ability to check access control lists (ACL) by retrieving user tokens from callers.

Windows Hypervisor Platform API

The Hypervisor Platform API lets you integrate with the hypervisor running on a host machine, enabling third-party applications and virtualization stacks to:

• Create and manage virtual partitions
• Configure memory mappings for partitions
• Create virtual processors and control their execution

For example, you can use an open source virtualization system like QEMU with its configuration, drivers, and guest/host protocols, alongside a Hyper-V managed partition. 

Virtualization Developer Tools

Microsoft provides the following tools that can help you programmatically manage virtualized workloads:

• Virtual Hard Disk (VHD) Interface—VHD is a publicly available image format that encapsulates a virtual hard disk in a file. It lets you host a native file system in a VM, enabling standard file operations within the VM. The Windows SDK provides an API for creating and managing VHDs.
• Hypervisor Instruction Emulator API—for device emulations that are not provided directly by the Windows Hypervisor Platform, you can use these APIs to handle communication with accelerators.
• VM Saved State Dump Provider API—enables access to dumps of VM saved state. 

Conclusion

In this article, I explained the basics of Hyper-V virtualization, and described several APIs that can help you manage Hyper-V virtualized workloads from within your applications:

• Hyper-V WMI Provider—lets you programmatically control every aspect of a VM running on a host machine.
• Host Compute System APIs—primarily used by applications running on a host to create and control VMs and containers.
• Host Compute Network (HCN) Service API—lets you manage virtual networks, network endpoints, and network policies.
• Windows Hypervisor Platform API—provides programmatic control over the Hypervisor.
• Virtualization Developer Tools—includes APIs that lets you control VHDs, leverage Hypervisor emulation, and access saved state dumps.

I hope this will be useful as you build custom code and integrations for your Hyper-V systems.