Processing module. Hyper-V

The Hyper-V processing module manages Microsoft Hyper-V virtual machines (VMs) through the WinRM protocol in the BILLmanager platform.

Module features:

• support for Linux and Windows operating systems, Hyper-V generations 1 and 2;
• VM lifecycle management:
  • creation with automatic resource rollback on error;
  • deletion;
  • pause and forced pause;
  • resume;
  • reboot with final state confirmation;
• CPU, RAM, and VHDX disk size configuration from tariff resources, while preserving the original measurement precision (bytes, KiB, MiB, GiB).
• network configuration:
  • getting an IPv4 address via DHCP through the Hyper-V KVP mechanism;
  • passing the fully qualified domain name (FQDN) of the service to the initial setup file of the OS template;
  • manual tasks for adding and deleting additional IP addresses;
• syncing the OS template list.
• VMs with operating systems specified in the tariff ( ostempl) .

Requirements for the Hyper-V node

• Windows Server OS with the Hyper-V role and the PowerShell module;
• the WinRM remote management service enabled and configured to accept connections from the BILLmanager server;
• a virtual switch accessible from BILLmanager;
• free disk space for OS template and VM directories;
• a service account with local Administrator, Hyper-V Administrators, and Remote Management Users rights;
• prepared VHDX templates according to the guide for preparing templates.

Network behavior

The processing module gets the main IPv4 address through DHCP. BILLmanager reads this address from the Hyper-V node and stores it in the database. Adding and deleting additional IP addresses works only through manual tasks. The module creates a task in BILLmanager when the addip or delip commands are run. The platform administrator must complete this task manually after configuring or removing the address inside the VM.

The processing module determines VM readiness through the Hyper-V KVP (key-value pair) mechanism. Inside the guest operating system, start the following services:

• for Linux OS: hv_kvp_daemon;
• for Windows OS: Hyper-V Data Exchange (vmickvpexchange).

After receiving the readiness marker (the BILLmanager service record Provisioning=vm_<id>, which the guest OS creates through KVP after setup is complete), the processing module:

1. removes the service initial setup ISO image (seed.iso or unattend.iso).
2. records the DHCP IP address in BILLmanager (without reservation on the DHCP server).
3. changes the service status to "Active".

Hyper-V-side configuration

Before configuring the integration on the Hyper-V side:

1. Create a service account.
2. Configure the WinRM service.
3. Prepare the file system.

Service account

Create a service account. Run the PowerShell commands as an administrator.

$password = Read-Host 'Password' -AsSecureString
New-LocalUser -Name 'billmgr-hyperv' -Password $password `
    -Description 'BILLmanager Hyper-V processing module'
$account = "$env:COMPUTERNAME\billmgr-hyperv"
$groupSids = @(
    'S-1-5-32-544', # Administrators
    'S-1-5-32-578', # Hyper-V Administrators
    'S-1-5-32-580'  # Remote Management Users
)
foreach ($sid in $groupSids) {
    $group = Get-LocalGroup -SID $sid
    Add-LocalGroupMember -Group $group -Member $account -ErrorAction SilentlyContinue
}

WinRM service

Do the following to configure remote management:

1. Enable the WinRM remote management service.
2. Ensure security: 
   1. Use a listener with a certificate over HTTPS.
   2. In the firewall settings, allow access only from the BILLmanager server.
3. Specify in the winrm_host parameter the certificate domain name, and in the winrm_port parameter — port 5986 .
4. Use port 5985 for an unsecured connection and disable the use_ssl parameter.

5. Enable the cert_validation parameter so that the system checks:

   • certificate authenticity (signatures of all certification authorities);
   • certificate validity period;
   • matching of the winrm_host domain name with the name in the certificate.
6. Install a trusted root or intermediate certification authority on the BILLmanager server.
7. By default, the system disables verification for compatibility. If you leave verification disabled, restrict access to WinRM to a trusted network or firewall rules.

Directories

Prepare the file system:

1. Make sure there is enough free disk space to copy the VHDX file of each machine.
2. Create root directories for OS templates and VMs:

   New-Item -ItemType Directory -Path 'D:\Templates' -Force
   New-Item -ItemType Directory -Path 'D:\VM' -Force

3. Grant the service account read access to the templates directory (templates_dir) and full access to the VM directory (vms_dir).

BILLmanager-side settings

The integration is configured while creating the processing module in BILLmanager.

To create a processing module, go to Integration → Processing modules → click Add:

1. Product type — select "VPS".
2. Processing module — select "Hyper-V".
3. Integration settings Specify integration data:
   1. In the Processing module settings block:
      1. Use SSL (WinRM HTTPS) — enable the option if the processing module uses a secure connection. If the option is enabled, specify whether to Verify WinRM HTTPS certificate. Certificate verification confirms host authenticity. A valid certificate must be installed on the Hyper-V host.
      2. IP address of the Hyper-V host — the domain or public address of the Hyper-V server.
      3. WinRM service port — the port for connecting the processing module to the Hyper-V node (it must be open on the Hyper-V node). Specify the value depending on the connection type:
         • 5985 — for an unsecured connection;
         • 5986 — for a secure connection (HTTPS).
      4. Username — the name of a local or domain Windows account with administrator rights on the Hyper-V host.
      5. Password.
      6. VM templates directory — path on the Hyper-V host. For example, C:\Templates.
      7. VM directory  — path on the Hyper-V host. For example, C:\VMs.
   2. In the Network settings block:
      1. Hyper-V virtual switch — select the previously configured Hyper-V virtual switch. If the required switch is not shown in the list, click Refresh list.
4. Processing module parameters. Configure internal (within BILLmanager) processing module parameters:

   • Data center — the name of the data center in BILLmanager to which the processing module will be connected;

     The data center must not have an External data center id.
   • Name — the name of the processing module as shown in the BILLmanager interface;
   • Department — the department to which tasks from the processing module will be assigned;
   • Sorting — the processing module priority. If several processing modules are connected to the tariff, the one with the lowest priority is selected first when the service is created.

Changing processing module settings

To change the processing module settings, in the main menu go to Integration → Processing modules → select the processing module → click View → click Edit. See the article Managing service processing modules.

VM creation algorithm

1. The BILLmanager platform selects the processing module, tariff resources, and the ostempl template.
2. The processing module reads the <templates_dir>\<ostempl>\template.json.
   More details

   • <templates_dir> — a directory on the Hyper-V Windows host. For example, D:\Templates;
   • <ostempl> — the name of the template folder. For example, ubuntu-22.04
3. The platform selects a reserved IP address for the future DHCP address.
4. The processing module copies the VHDX disk to <vms_dir>\vm_<item>\disk.vhdx and resizes it to the exact size from the tariff.
   More details

   • <vms_dir> — a directory on the Hyper-V Windows host. For example, D:\VM;
   • <item> — the service ID in BILLmanager. For example, 697.
5. The processing module creates the VM and sets the CPU, memory, and virtual switch.
6. The processing module reads the selected template's bootstrap_file, substitutes service values, and creates the initial setup disk (seed.iso or unattend.iso);
   More details

   • bootstrap_file — the path to the initial setup configuration file relative to the template directory. For example, cloud-init/user-data or unattend/unattend.xml ;
   • seed.iso — the initial setup disk for Linux based on cloud-init;
   • unattend.iso — the initial setup disk for Windows based on unattend.xml;
   • service values — FQDN, local administrator password, IP address, and other parameters that are inserted into the configuration template before the ISO image is created.
7. The platform starts the VM, checks the DHCP address and the guest OS readiness marker through Hyper-V.
8. The processing module detaches and removes the initial setup disk.
9. The platform records the IP address in BILLmanager and calls the postopen procedure.
   
   More details

   • postopen — the final BILLmanager procedure that runs after the service is created successfully and informs the platform that the VM is ready for use.

If an error occurs before the operation is completed, the processing module removes the created machine, the VHDX disk, the initial setup disk, and the unassigned IP reservation.