PSHVTag

I have written the PSHVTag Module because I am using many Hyper-V virtual machines in my lab environments. And I have to start and stop the different labs very often. A VM usually needs some time to fully start up before I can start the next one. For example, my Gateway VM has to be up and running before I can start the Domain Controller behind it. And the DC has to be up and running before I can start the ConfigMgr server etc..

Instead of creating a complex database his I wanted to make it very simple to describe a service hierarchy. Therefore, I thought it would be very simple to do this just by adding a simple tag line to the notes filed of every VM in such an environment.

With this module it is very easy to start a complex VM-Service like SCCM with all its dependencies with just a simple PowerShell command.
You can also use the VM Topology object to select virtual machines and use them with any other Hyper-V PowerShell command like Export-VM.

While creating the module I thought it would be nice to have a graph of my lab environments. Consequently, I added a function based on the PSGraph module to it, which allows you to map your environments (see example below).

VMTopology

What is a VM-Topology

A VM-Topology is represented by a custom PowerShell class. An instance is built from all virtual machines of one host with a tag line in their notes field.

It can comprise multiple VM-Environments in which virtual machines can provide VM-Services. The environment also reflects the dependencies between these services.

Example Graph

This graph shows a simple VM-Topology containing one environment, one service provided by one VM and one required service provided by one VM.

VMTopology

The Tag

The Tag, used to create a VM-Topology consists of three elements and is stored as a single line in the notes field of a Hyper-V VM. Only one tag line is allowed per VM.

Elements

Environment

This tag element defines the VM-Environment the virtual machine belongs to. One VM has to belong to one environment and can belong to multiple environments. But it has to provide the same services in all environments and it has to depend on the same services in all environments.

Service

The service element defines the services provided by the VM for the environments it belongs to. A virtual machine can provide one or more services.

DependsOn

The DependsOn element includes all services a VM requires to be up in running before it can fully operate. For example, an Azure AD Connect server depends on the domain and internet access.

Syntax

The syntax is similar to HTML tags. The tag element name (Env, Service, DependsOn) is put between angle brackets to indicate the start of the tag and is closed by the tag element name prefixed with a / between angle brackets.

Multiple instances of an element are separated by a comma.

A tag line looks like the example below.

<Env>Environment1,Environment</Env><Service>Service1,Service2</Service><DependsOn>RequiredService1,RequiredService2</DependsOn>

You can create a tag by using the Set-VMTag command.

Start a VM-Service with all dependencies

The main reason for me writing this module was starting virtual machines in a dedicated order. Therefore, I wrote the function Start-VMService.

For instance to start the DefGateway01, DomainController01, DomainController02, AzureADConnect01 and AzureADConnect02 virtual machines from the example topology in the picture at the beginning of this article on the localhost in this order you can use the following command:

Stop a VM-Service

It is also possible to stop a VM-Service and all its dependencies with the Stop-VMService function.

For examplem in order to stop the five virtual machines for AzureAD, Domain and Gateway you can use the following command:

How to use a VM-Topology with other commands

You can use the VM-Topology to select virtual machines by VM-Service or VM-Environment and use them with commands like Export-VM.

For example, in order to export all virtual machines from the VM-Environment LAB on the localhost use the following:

Installing the Module

The module is available in the PowerShell Gallery or on GitHub.

Inspect

Install

Future Updates

  • When I started this module I wanted to create a GUI which shows the state of the different objects in real time and allows you to start and stop services with a click on a button. I think this will be one of the next additions to this module.
  • I am also planning to add functions to manipulate single tag items instead of setting or replacing the whole tag at once.
  • Furthermore, I want to add support for multiple Hyper-V hosts to allow spanning VM-Topologies over several hosts.
  • …

Feedback

Hopefully some of you will find this module as useful as I do. And maybe you will have some good ideas for new features. Please let me know and use the project page on Github for feedback.