Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/plagueho/labbuilder

PowerShell Module for building a Hyper-V Lab environment from a simple XML configuration file.
https://github.com/plagueho/labbuilder

dsc dsc-resource-kit hyper-v lab powershell windows

Last synced: 1 day ago
JSON representation

PowerShell Module for building a Hyper-V Lab environment from a simple XML configuration file.

Host: GitHub
URL: https://github.com/plagueho/labbuilder
Owner: PlagueHO
License: mit
Created: 2015-08-20T06:25:14.000Z (over 9 years ago)
Default Branch: main
Last Pushed: 2024-06-10T03:02:22.000Z (8 months ago)
Last Synced: 2025-01-13T19:13:49.483Z (8 days ago)
Topics: dsc, dsc-resource-kit, hyper-v, lab, powershell, windows
Language: PowerShell
Homepage:
Size: 3.15 MB
Stars: 226
Watchers: 26
Forks: 38
Open Issues: 67
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md

Awesome Lists containing this project

README

# LabBuilder PowerShell Module

[![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/PlagueHO/LabBuilder/blob/dev/LICENSE)
[![Documentation](https://img.shields.io/badge/Docs-LabBuilder-blue.svg)](https://github.com/PlagueHO/LabBuilder/wiki)
[![PowerShell Gallery (with prereleases)](https://img.shields.io/powershellgallery/vpre/LabBuilder?label=LabBuilder%20Preview)](https://www.powershellgallery.com/packages/LabBuilder/)
[![PowerShell Gallery](https://img.shields.io/powershellgallery/v/LabBuilder?label=LabBuilder)](https://www.powershellgallery.com/packages/LabBuilder/)
[![Minimum Supported PowerShell Version](https://img.shields.io/badge/PowerShell-5.1-blue.svg)](https://github.com/PlagueHO/LabBuilder)
[![Join the chat at https://gitter.im/PlagueHO/LabBuilder](https://badges.gitter.im/PlagueHO/LabBuilder.svg)](https://gitter.im/PlagueHO/LabBuilder?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)

## Module Build Status

| Branch | Azure Pipelines | Automated Tests | Code Quality |
| ------ | ---------------------------------- | ---------------------------------- | -------------------------------------- |
| main | [![ap-image-main][]][ap-site-main] | [![ts-image-main][]][ts-site-main] | [![cq-image-main][]][cq-site-main] |

## Summary

This module will build a multiple machine Hyper-V Lab environment from an XML
configuration file and other optional installation scripts.

## Introduction

While studying for some of my Microsoft certifications I had a need to quickly
and easily spin up various Hyper-V Lab environments so that I could experiment
with and learn the technologies involved.

Originally I performed this process manually, creating Hyper-V VM's and environments
to suit. But as the complexity of the Lab environment increased (e.g. take
multi-tier PKIs) manually building these Labs became unmanageable. Also, if I
wanted to repeat a particular process multiple times I would have to either
snapshot multiple VMs or manually back them all up. This quickly became
unsupportable as snapshots slows VMs down and constant backups of large Hyper-V
environments was slow and also limited by space. This gave me a basic set of
requirements for this module.

So as a solution to these problems I decided that I wanted a declarative
approach to automating the process of building a Lab environment.

This had the following advantages:

- Building a new Lab with multiple VMs was automated.
- Creation of the actual Lab VMs could be done without supervision.
- Once a basic Lab was created more complex Lab environments could be created by
cloning the original XML configuration and tailoring it.
- Configuration files could be distributed easily.
- Because the post setup configuration of the Lab VM machines was performed via
DSC this gave me an opportunity to work with DSC to a greater depth.
- The configuration files could be created by people without knowledge of PowerShell
or DSC.
- UI based applications could be easily created to generate the configuration XML.

## Goals

The general goals of this module are:

- **One-Click Create**: Enable "one-click" creation of a Hyper-V Lab environment.
- **Easy Configuration**: Enable non-developers to easily define Lab environments.
- **Multiple Labs**: Support multiple Lab environments on the same Hyper-V host.
- **Stretched Labs**: Allow a Lab environment to span or be installed on a remote
Hyper-V host.
- **Lab Isolation**: Ensure that multiple Lab environments are completely isolated
from each other.
- **Minimal Disk Usage**: Minimize Lab footprint by utilizing differencing disks
where possible.
- **Configuration Flexibility**: Allow GUI based tools to be easily created to
create Lab configurations.
- **Extensible**: Enable new Lab VM machine types to be configured by supplying
different DSC library resources.

## Requirements

To use this Module you will require on your Lab Host:

1. Operating Systems supported and automatically tested:

- Windows Server 2019

1. Operating Systems that should work but are not automatically tested:

- Windows Server 2012
- Windows Server 2012 R2
- Windows Server 2016
- Windows Server 2016, version 1709
- Windows Server 2016, version 1803
- Windows Server 2022
- Windows 8.0
- Windows 8.1
- Windows 10

1. **Windows Management Framework 5.1 (WMF5.1)** installed.

_WMF 5.1 is installed on Windows 10 and Windows Server 2016 out of the box,
but for Windows Server 2012/R2 and Windows 8/8.1 it will need to be
installed separately._
_WMF 5.1 can be downloaded from [here](https://www.microsoft.com/en-us/download/details.aspx?id=54616)._

1. **PowerShell Core 6/PowerShell 7**: Untested, but may work.

1. **Hyper-V** available (which requires intel-VT CPU support).
1. To use labs that contain Nested Hyper-V hosts only Windows 10 built 10586
or later and Windows Server 2016 TP3 or later are supported.
1. Copies of the **Windows installation media** for any Operating Systems
that will be used in your Labs.
_Note: Most Lab configuration files can contain a URL where the relevant
trial media can be downloaded from, but you can use any Windows Install
Media source you choose (including custom built ISOs)._
1. An **internet connection** to download the WMF 5.1 MSU and any other
optional MSU packages required by the Lab.
_Note: This only needs to be done during the Install-Lab phase and can
be disabled after this phase is complete._
1. **WS-Man** enabled to allow communication with the Lab Virtual Machines.
_Note: if WS-Man is not enabled, the Install-Lab cmdlet will attempt to
install it with confirmation being required from the user.
Confirmation can be suppressed using the -force option._

## Contributing

If you wish to contribute to this project, please read the [Contributing.md](/.github/CONTRIBUTING.md)
document first. We would be very grateful of any contributions.

## Basic Usage Guide

The use of this module is fairly simple from a process standpoint with the bulk
of the work creating a Lab going into the creation of the configuration XML that
defines it. But if there is a Lab configuration already available that fits your
needs then there is almost nothing to do.

A Lab consists of the following items:

- A configuration XML file that defines the Virtual Machines, Switches, the DSC
config files and anything else related to how the Lab is set up.
- Copies of the Windows Operating System Images used in the Lab which are:
- Either VHDs containing Syspreped Windows images.
- Or Windows Installation media ISO files (these will be automatically converted
to VHDs for you during Lab creation).
- Any DSC configuration files that are used to configure the Lab VMs after the OS
initial start up has completed.

There are a library of DSC configuration files for various machine types already
defined and available for you to use in the **DSCLibrary** folder.

## Installing the LabBuilder Module

The easiest way to download and install the LabBuilder module is using PowerShell
Get to download it from the [PowerShell Gallery](https://www.powershellgallery.com/packages/LabBuilder/):

```powershell
Install-Module -Name LabBuilder
```

PowerShell Get is built into Windows Management Framework 5.1, which is a
requirement of this project, so it should already be installed onto your host.
If it is not installed, download it from [here](https://www.microsoft.com/en-us/download/details.aspx?id=50395).

## Installing a Lab

Once the Lab files are available the process of installing the Lab is simple.

1. Make a folder where all your Lab files will go (e.g. VMs, VHDs, ISOs,
scripts) - e.g. c:\MyLab
1. Copy the Lab Configuration XML file into that folder (try one of the sample
configurations in the **Samples** folder).
1. Edit the Lab Configuration XML file and customize the Settings to suit
(specifically the LabPath setting).
1. Make a folder in your Lab folder for your Windows ISO files called
**isofiles** - e.g. c:\MyLab\ISOFiles
1. Copy any ISO files into this folder that your lab will use.
1. Make a folder in your Lab folder for your VHD boot templates (converted from
the ISO files) **vhdfiles** - e.g. c:\MyLab\VHDFiles
1. Run the following command in an Administrative PowerShell window:

```powershell
Install-Lab -ConfigPath 'c:\MyLab\Configuration.xml'
```

This will create a new Lab using the c:\MyLab\Configuration.xml file.

If you want more verbose output of what is happening during the Lab Install
process, use the -verbose parameter:

```powershell
Install-Lab -ConfigPath 'c:\MyLab\Configuration.xml' -Verbose
```

## Stopping a Lab

Once the Lab has been installed, it can be stopped using this PowerShell command:

```powershell
Get-Lab -ConfigPath 'c:\MyLab\Configuration.xml' | Stop-Lab
```

This will shutdown any running Virtual Machines in the Lab in **Reverse Boot Order**,
starting with Virtual Machines that have no boot order defined.
LabBuilder will wait for all machines with the same Boot Order to be shut down
before beginning shut down of VMs in the next lowest Boot Order.
Any Lab Virtual Machine that has already been stopped will be ignored.

_Note: Boot Order is an optional attribute defined in the Lab Configuration that
controls the order Lab Virtual Machines should be booted in._

You can of course just shut down the Virtual Machines in a Lab yourself via
Hyper-V (or some other mechanism), but using Stop-Lab ensures the Virtual Machines
are shutdown in a specific order defined in the Lab (e.g. Domain Controllers shut
down last).

## Starting a Lab

Once the Lab has been installed and then stopped, it can be started back up using
this PowerShell command:

```powershell
Get-Lab -ConfigPath 'c:\MyLab\Configuration.xml' | Start-Lab
```

This will start up any stopped Virtual Machines in the Lab in **Boot Order**,
with Virtual Machines that have no boot order defined being started last.
LabBuilder will wait for all machines with the same Boot Order to be started up
fully before beginning start up of VMs in the next highest Boot Order.

_Note: Boot Order is an optional attribute defined in the Lab Configuration that
controls the order Lab Virtual Machines should be booted in._

You can of course just start up the Virtual Machines in a Lab yourself via
Hyper-V (or some other mechanism), but using Start-Lab ensures the Virtual Machines
are started up in a specific order defined in the Lab (e.g. Domain Controllers
started up first).

## ISO Files

During the Install process of a Lab, if the template VHD files to use as boot
disks for your VMs, LabBuilder will attempt to convert the required ISO files
into VHD boot disks for you.
This will only occur if the ISO files required to build a specific VHD file are
found in the ISO folder specified by the Lab.

By default LabBuilder will look in the **isofiles** sub-folder of your Lab folder
for any ISO files it needs.
You can change the folder that a Lab looks in for the ISO files by
changing/setting the _isopath_ attribute of the __
node in the configuration
If it can't find an ISO file it needs, you will be notified of an official
download location for trial or preview editions of the ISO files (as long as
the LabBuilder configuration you're using contains the download URLs).

Some common ISO download locations:

- Windows Server 2012 R2: [https://www.microsoft.com/en-us/evalcenter/evaluate-windows-server-2012-r2](https://www.microsoft.com/en-us/evalcenter/evaluate-windows-server-2012-r2)
- Windows 10 Enterprise: [https://www.microsoft.com/en-us/evalcenter/evaluate-windows-10-enterprise](https://www.microsoft.com/en-us/evalcenter/evaluate-windows-10-enterprise)
- Windows Server 2016: [https://www.microsoft.com/en-us/evalcenter/evaluate-windows-server-2016](https://www.microsoft.com/en-us/evalcenter/evaluate-windows-server-2016)
- Windows Server 2019: [https://www.microsoft.com/en-us/evalcenter/evaluate-windows-server-2019](https://www.microsoft.com/en-us/evalcenter/evaluate-windows-server-2019)

**Important**: If you are converting Windows Server 2016 ISO files or adding
packages to VHDs please see the [Windows Server 2016](#Windows Server 2016) section.

Multiple VHD templates may use the same ISO file in a Lab.
For example, if multiple editions of an Operating system are used in the same lab.

Once an ISO has been converted to an VHD, it will be stored in the VHDFiles
folder in your lab folder.
However, if you are using multiple Labs on the same machine you might want to
share these VHD files between mutlpile Lab projects to save having to build
and store copies for each Lab.
In that case, you can set the `vhdpath` attribute of the `` node
in the configuration to a different relative or absolute path.

The conversion process for a single ISO to VHD can take 10-20 minutes depending
on your machine.
For this reason multiple Labs can be configured to use the same path to store
these VHDs by changing the `vhdpath` attribute of the `` node
in the configuration.

## Windows Server 2016

If you are converting a Windows Server 2016 image and your Lab Host is running either:

- Windows Server 2012 R2 or older
- Windows 8.1 or older

**Important:** Only Windows Server 2016 Technical Preview 5 and above are
supported with LabBuilder.

You will need to install an updated version of the DISM before you will be able
to add any packages to a Windows Server 2016 ISO.
This includes building Nano Server Images.

You can get the latest version of the DISM by downloading and installing the
[Windows ADK](http://go.microsoft.com/fwlink/?LinkId=293394).
After installing the Windows ADK, you can force LabBuilder to use this version
by configuring the "dismpath" attribute in the "settings" element of your
LabBuilder configuration file:

```xml

My Lab

```

## Lab Installation Process in Detail

When a new Lab is installed onto a Lab Host from a configuration file, LabBuilder
performs the following tasks (in order):

1. **Load Config**: The Lab configuration file is Loaded and validated.
_If the Lab Configuration file is invalid it will be rejected and the Lab
will not be installed._
1. **Create Lab Folder**: A folder on the Lab Host is created to store the Lab
files (VM Templates, VMs, Resources etc.).
_The user specifies the location of this folder in the Lab Configuration file
or by passing the LabPath parameter to the Install-Lab cmdlet._
1. **Download Modules**: All Module Resources listed in the Lab Configuration
are downloaded to the PowerShell Modules folder if they don't already exist.
1. **Download MSUs**: All MSU Resources listed in the Lab Configuration are
downloaded to the Resources folder in the Lab folder if they don't already
exist.
1. **Create Lab Switches**: Each Virtual Switch specified in the Lab
Configuration is created or updated in Hyper-V.
1. **Create Management Switch**: A Management Internal Virtual Switch is created
in Hyper-V for this Lab.
_Each Lab has it's own Management Internal Virtual Switch which will be named
"Lab Management" with the Lab ID prepended to it._
_It will be assigned a VLAN Id of 99, which can be overridden in the Lab
Configuration file._
_The Lab Management switch is for the Lab Host to communicate with the Lab
Guest Virtual Machines so must not be removed._
1. **Create Template VHDs**: Any Template VHD files that don't exist but should
are created from the appropriate ISO files.
_A Lab Configuration file may not list any Template VHD files, or it may list
them but not specify source ISO files to create the VHD files from._
_Instead the Templates may directly link to a VHD file or an existing Hyper-V
Virtual Machine._
1. **Create VHD Templates Folder**: A folder within the Lab folder will be
created to store the Virtual Hard Disk Template files.
_This folder is usually called 'Virtual Hard Disk Templates'._
_This folder will be used to store Template VHD files or Differencing Disk
Parent VHD files for use as a Boot Disk for Lab Virtual Machines._
_A VHD file in this folder can be used as a Template or a Differencing Disk
Parent or both._
1. **Copy VHD Templates**: Get the list of Templates in the Lab Configuration
and copy the VHD specified to the Lab Virtual Hard Disk Templates folder.
_Any packages listed in the Template will be applied to the Template at this point._
_A Template VHD file will only be copied into this folder if it does not already
exist._
_The Template VHD file will also be optimized in this folder and then marked as
Read Only to ensure it is not changed (as it may be used as a Differencing Disk
Parent)._
1. **Create Virtual Machines**: Create the Lab Virtual Machines, one at a time,
for each one performing the following steps:
1. **Create Hyper-V VM**: Create the Virtual Machine and attach any Network
Adapters listed in the Lab Configuration with it.
1. **Create Boot VHD**: Copy (if not using a Differencing Boot VHD) the Boot
VHD from the Virtual Hard Disk Templates folder and attach it to the VM.
1. **Add Packages**: Add any listed packages to the VM.
1. **Create Data VHDs**: Copy/Create and attach any Data VHDs listed in the
Lab Configuration with the VM.
1. **Create Config Files**: Create any VM configuration files required for
first boot of the VM (e.g. Unattend.xml, SetupComplete.cmd) and copy them
into the Boot VHD.
1. **Boot VM**: Boot the VM for the first time and wait for Initial Setup of
the VM to complete.
1. **Create Certificate**: A Self-Signed certificate will be created by the
VM and made available on the VM Boot VHD.
1. **Download Certificate**: The Self-Signed certificate will be downloaded
by the Lab Host and used to encrypt the credentials in the DSC MOF file
that will be created.
1. **Create DSC Configuration**: The DSC Configuration file will be assembled
from the speficied DSC Configuration and the required networking information.
1. **Compile DSC Configuration**: The DSC Configuration file will be compiled
and a MOF file produced.
1. **Upload DSC Files**: This DSC MOF file, DSC LCM (Meta) MOF File and any
DSC Resource Modules required will be uploaded into the VM.
1. **Start DSC**: DSC configuration will be started on the VM.
_Note: The LCM is configured to re-apply DSC every 15 minutes, so changing
any settings managed by DSC on the server will be reverted within 15 minutes
of them being changed._

The entire process above is automated.
As long as you a valid Lab Configuration file and any required Windows Installation
Media ISO files then the Lab will be installed for you.
Depending on the size of the Lab you are building and whether or not the ISO files
need to be converted to VHD files, this could take from 5 minutes to many hours.
For example, an Lab containing eight Windows Server 2012 R2 Virtual Machines
configured as an AD Domain containing various services installed on a Host with
four CPU cores, 32 GB RAM and an SSD will take about 45 minutes to install.

## Windows Management Framework 5.1 (WMF 5.1)

All Lab Guest Virtual Machines must have WMF 5.1 installed onto them before they
are first booted in a Lab environment. This is to ensure the Self-Signed certificate
can be generated and returned to the host for DSC MOF encryption.

If WMF 5.1 is not installed before the Lab VM Guest first boot then DSC
configuration will not proceed, and the Lab Guest VM will boot with a clean OS,
but none of the specific features installed or configured (e.g. DC's not promoted).

WMF 5.1 is only required to be installed onto Windows 7, 8 and 8.1 or Windows
Server 2008 R2, Windows Server 2012 and Windows Server 2012 R2. Windows 10 and
Windows Server 2016 already include WMF 5.1 so it doesn't need to be installed.

_Most Labs_ are configured to install WMF 5.1 **completely automatically** so you
don't need to install worry about it.

Note: It is possible to change a Lab Configuration file to prevent automatic
installation of the WMF 5.1 MSU package onto Guest Lab VM's, but this is not
recommended unless there is a good reason for doing so.

LabBuilder supports automatically installing any MSU package that can be downloaded
from the internet onto the Lab Guest VMs during installation of the Lab.
These MSU packages can be installed during any of the following phases of Lab installation:

- Convert Windows Install Media ISO to Template VHD.
- Copy Template VHD to ParentVHD folder in Lab.
- Create new VM Boot VHD from ParentVHD folder in Lab.

By default, Lab configuration files are configured to ensure WMF 5.1 is installed
at each of the above phases.

The WMF 5.1 MSU package is controlled by adding a new MSU element to the
<Resources> element in a Lab Configuration.
E.g.

```xml

```

This defines the name of the MSU package and the Download location.
The package can then be added to the <Template>, <TemplateVHD> or
<VM> element in the **Packages** attribute.
E.g.

```xml

```

Other MSU packages can also be installed in the same way.
Multiple MSU Packages can be installed to the same VHD by comma delimiting the
Packages attribute.

## Configuration XML

Documentation for the LabBuilder Configuration XML can be found in the file [docs/about_LabBuilderSchema.md](docs/about_LabBuilderSchema.md).

## Cmdlets

Complete documentation for the LabBuilder Lab Cmdlets can be found in the file [docs/cmdlets-lab.md](LabBuilder/docs/cmdlets-lab.md).

A list of Cmdlets in the LabBuilder module can be found by running the following
PowerShell commands:

```PowerShell
Import-Module LabBuilder
Get-Command -Module LabBuilder
```

Help on individual Cmdlets can be found in the built-in Cmdlet help:

```PowerShell
Get-Help -Name Install-Lab
```

## Change Log

For a list of changes to versions, see the [CHANGELOG.md](CHANGELOG.md) file.

## Project Management Dashboard

[![Throughput Graph](https://graphs.waffle.io/PlagueHO/LabBuilder/throughput.svg)](https://waffle.io/PlagueHO/LabBuilder/metrics/throughput)

## Links

- [GitHub Repository](https://github.com/PlagueHO/LabBuilder/)
- [Blog](https://dscottraynsford.wordpress.com/)

[ap-image-main]: https://dev.azure.com/dscottraynsford/GitHub/_apis/build/status/PlagueHO.LabBuilder.main?branchName=main
[ap-site-main]: https://dev.azure.com/dscottraynsford/GitHub/_build/latest?definitionId=39
[ts-image-main]: https://img.shields.io/azure-devops/tests/dsccommunity/FileContentDsc/31/main
[ts-site-main]: https://dev.azure.com/dscottraynsford/GitHub/_test/analytics?definitionId=39&contextType=build
[cq-image-main]: https://codecov.io/gh/PlagueHO/LabBuilder/branch/main/graph/badge.svg
[cq-site-main]: https://codecov.io/gh/PlagueHO/LabBuilder/branch/main