Please refer to this document to assist in installing and setting up the PSAutolab module on your computer. Run all commands from an elevated Windows PowerShell session. In other words, run Windows PowerShell as administrator. You will know you are elevated if you see the word Administrator in the title bar of the PowerShell window. Do NOT run this module in PowerShell 7. It is assumed you are running this on Windows 10 Professional or Enterprise editions, or the Windows 11 equivalents.
It is also assumed that you have administrator rights to your computer and can make changes. If your computer is controlled by Group Policy, you may encounter problems. You should also be logged in with a local or domain user account. The setup process may not work properly if using an O365 or Microsoft account to logon to Windows.
It is possible to run this module with nested virtualization inside a Windows 10 Hyper-V virtual machine but it is not recommended. Some networking features may not work properly and overall performance will likely be reduced.
You can run these commands to verify your computer meets the minimum requirements. Run all PowerShell commands in an elevated session. If you can't even open a PowerShell prompt, this module definitely won't work on your computer.
PS C:\> Get-CimInstance -ClassName Win32_OperatingSystem |
Select-Object -property Caption,
@{Name="MemoryGB";Expression={$_.TotalVisibleMemorySize/1mb -as [int]}}
Caption MemoryGB
------- -----
Microsoft Windows 10 Pro 32If the Caption shows anything other than Pro or Enterprise this module may not work. Although it appears that Windows 10 Education might be supported.
The memory size should be at least 12GB. 16GB or greater is recommended. If the number is less than 12, STOP. It is unlikely you have enough installed memory. Depending on the configuration you want to run, it might be possible to proceed with less memory. Open an Issue and ask for guidance indicating your memory settings from this command:
PS C:\> Get-CimInstance Win32_OperatingSystem |
Select-Object -property FreePhysicalMemory,TotalVisibleMemorySize
FreePhysicalMemory TotalVisibleMemorySize
------------------ ----------------------
14357500 33442716Also indicate what lab configuration you are hoping to run.
You need to ensure you can run PowerShell scripts on your computer. Run Get-ExecutionPolicy to view your current settings. If it shows Restricted, then run this command in an elevated PowerShell session.
Set-ExecutionPolicy RemoteSigned -forceNote, that some organizations may have implemented a Group Policy to restrict this setting. If you can't change the policy to something other than Restricted you won't be able to use this or any PowerShell module. If the policy is AllSigned then you will have to sign the downloaded files with a code signing certificate trusted by your computer. If you are in a corporate environment, you may need to work with your IT department to sort that out.
The module relies on Windows PowerShell remoting which should be enabled before installing and using this module.
PS C:\> test-wsman
wsmid : http://schemas.dmtf.org/wbem/wsman/identity/1/wsmanidentity.xsd
ProtocolVersion : http://schemas.dmtf.org/wbem/wsman/1/wsman.xsd
ProductVendor : Microsoft Corporation
ProductVersion : OS: 0.0.0 SP: 0.0 Stack: 3.0This is what you should see as a result. Any errors mean that PowerShell remoting is disabled. Enable it from your elevated PowerShell session. This will fail if your only network connection is over a public network.
Enable-PSRemoting -forceIf this fails, STOP. Do not proceed with this module until this is working and Test-WSMan gives you a result. If you are running as Administrator and this command fails it is most likely because the related settings are controlled by a Group Policy or your network is public. Run Get-NetConnectionProfile and look at the NetworkCategory for the LabNet connection. If must be Private or DomainAuthenticated.
The module requires a lot of disk space for the virtual machines, snapshots and ISO files. Run this command to see how much free space you have.
PS C:\> Get-Volume
Drive SizeGB FreeGB PercentFree HealthStatus
----- ------ ------ ----------- ------------
D 477 183 38.41 Healthy
C 237 87 36.71 HealthyYou should have close to 100GB of free space on a fixed hard drive such as C or D. The module will setup an Autolab folder on drive C: by default, although you can specify an alternate drive. This module has not been tested running from an externally connected drive.
The module requires the Hyper-V feature on Windows 10. Please refer to the documentation for your computer hardware to determine if it supports virtualization. You may need to configure settings in your BIOS. You don't need to manually enable the Hyper-V feature now, although you are welcome to if you want to verify it is available.
The module uses a standard PowerShell tool called Pester to validate lab configurations. Without getting into technical details, if you are running the out-of-the-box version of Pester on Windows 10, you need to manually update Pester before attempting to install this module. In an elevated Windows PowerShell session run this command:
Get-Module Pester -ListAvailableIf the only result you get is for version 3.4.0, then you must run:
Install-Module Pester -Force -SkipPublisherCheckRe-run the Get-Module to verify version 5.5.0 or greater is installed. If you do not have an updated version of the Pester module, you will see a warning when you import this module.
If you are running a version of Pester greater than 3.4.0 but less than 5.5.0, you must update the Pester module.
Update-Module PesterIf you meet the requirements, you are ready to download and install this module. Do not download anything from this GitHub repository. In your PowerShell session run this command:
Install-Module PSAutolab -force -SkipPublisherCheckYou may be prompted to update to a newer version of nuget. Answer "yes". You might also be prompted about installing from an untrusted source. Again, you will need to say "yes". After installation you can verify using Get-Module.
PS C:\> Get-Module PSAutoLab -list
Directory: C:\Program Files\WindowsPowerShell\Modules
ModuleType Version Name ExportedCommands
---------- ------- ---- ----------------
Script 5.0.0 PSAutoLab {Enable-Internet, Invoke-RefreshLab, Invoke-Run...You may see a newer version number than what is indicated here. The README file in the GitHub repository indicates the current version in the PowerShell Gallery.
There is a one-time step to setup your computer for the AutoLab environment. In your elevated PowerShell session run this command:
Setup-HostThis command will create a directory structure for the module and all of its files. The default is C:\Autolab which you should be able to accept. If you are low on space or want to use an alternate drive, then you can specify an alternative top-level path.
Setup-Host -DestinationPath D:\AutolabIf you select a drive other than C:\ it is recommended you still use the Autolab folder name. The setup process will install additional modules and files. If necessary, it will enable the Hyper-V feature. If Hyper-V is enabled during the setup, please reboot your computer before proceeding.
To verify your configuration, run Get-PSAutolabSetting.
PS C:\> Get-PSAutoLabSetting
AutoLab : C:\Autolab
PSVersion : 5.1.22621.2506
PSEdition : Desktop
OS : Microsoft Windows 11 Pro
FreeSpaceGB : 365.45
MemoryGB : 3642
PctFreeMemory : 59.71
Processor : Intel(R) Core(TM) i9-10900T CPU @ 1.90GHz
IsElevated : True
RemotingEnabled : True
NetConnectionProfile : Private
HyperV : 10.0.22621.1
PSAutolab : 5.0.0
Lability : 0.25
Pester : {5.5.0, 5.4.1, 5.3.3, 5.3.1...}
PowerShellGet : 2.2.5
PSDesiredStateConfiguration : 1.1If Hyper-V is not installed you will see errors. Any errors indicate a problem with your setup. Please post this information when reporting an issue.
In an elevated PowerShell session, change directory to the configuration folder that you want to use.
PS C:\> cd C:\Autolab\Configurations\SingleServer-GUI-2016
PS C:\Autolab\Configurations\SingleServer-GUI-2016\>You can look at the instructions.md file in the folder to get more information about the configuration.
PS C:\Autolab\Configurations\SingleServer-GUI-2016\> get-content .\Instructions.mdOr open the file with Notepad.
Another option is to use the Get-LabSummary command. This will show you what computers will be created and how they will be created. The Computername will also be the virtual machine name.
You can run Unattend-Lab for a completely hands-free experience.
PS C:\Autolab\Configurations\SingleServer-GUI-2016\> unattend-labThe very first time you setup a lab, the command will download ISO images of evaluation software from Microsoft. These files will be at least 4GB in size. If you are setting up a domain-based configuration, this means you will be downloading ISO images for Windows Server and Windows 10. This download only happens once.
Note that during the validation phase you may see errors. This is to be expected until all of the configurations merge. You can press Ctrl+C to break out of the testing. The virtual machines will continue to prepare themselves. Later, you can manually validate the lab:
PS C:\Autolab\Configurations\SingleServer-GUI-2016\> Invoke-Pester .\vmvalidate.test.ps1If you encounter errors running an unattended setup, you should step through the process manually to identify where exactly an error is occurring. Make sure you are in an elevated PowerShell session and you have changed location to the configuration folder. If you have tried to setup the lab before run Wipe-Lab to remove previous set-up files. Then run each of these commands individually:
Setup-LabEnable-InternetRun-Lab
Errors that affect setup should happen in one of these steps. If so, open an issue with the configuration name, the command you were working on and the error message. Also include the output from Get-PSAutolabSetting.
After about 10 minutes, you can run the validation command:
Validate-LabThe Write-Progress display will provide feedback on the process.
💡 Run Validate-Lab -Verbose to get details on the process
Beginning with v4.21.0, the validation command will restart virtual machines that have stopped and restart-virtual machines that appear to be failing. You will see this as warning messages. Validation will abort after 65 minutes if it hasn't completed. At which point you can manually test to see if the configuration has converged.
Run-PesterDepending on the error, you might simply ignore it or manually attempt to resolve it. Often the best approach is to run Wipe-Lab -force and start all over.
All of the commands in this module have help and examples. You are also encouraged to read the about help topic.
help about_PSAutoLabIn the VMConfigurationData.psd1 file for each lab, you will see a commented out section for an environment prefix value. This value exists for special situations where you might have a virtual machine naming collision or want to be able to identify the virtual machines that belong to the AutoLab module. In a normal setup and for almost all users, the Hyper-V virtual machine name will be the same as the hostname (computer name) in the VM guest. If the lab creates a guest with a computer name of S1, the Hyper-V virtual machine will also be called S1. If you enable the prefix setting, the Hyper-V virtual machine name will use the prefix, but the guest computer name will not. For example, if you enable the default prefix (you can change it to anything you'd like), you will create a Hyper-V virtual machine with a VMName of Autolab-S1 but the actual computer name will still be S1. The validation tests will reference the guest computer name, not the Hyper-V virtual machine name.
If you must use this feature, open the VMConfigurationData.psd1 file in a text or code editor. Scroll down to the NonNodeData section.
NonNodeData = @{
Lability = @{
# You can uncomment this line to add a prefix to the virtual machine name.
# It will not change the guest computer name
# See https://github.com/pluralsight/PS-AutoLab-Env/blob/master/Detailed-Setup-Instructions.md
# for more information.
#EnvironmentPrefix = 'AutoLab-'Remove the # character before EnvironmentPrefix. If you want to change the value from Autolab- to something else go ahead. The prefix will be inserted before the computer name to create the virtual machine name.
This setting should only be used in special situations as it can be confusing. While every effort has been made to ensure compatibility with commands in this module, there is no guarantee of 100% success. Also note that any changes you make to the configuration files could be overwritten in future updates or when you run Refresh-Host.
Occasionally, things can go wrong for no apparent reason. If you ran through the manual steps to setup a lab but the validation tests are still failing, you may need to stop and restart the virtual machine that is causing problems. For example, sometimes the SRV2 member in the PowerShellLab configuration simply won't pass validation, often because it can't be connected to. The best solution is to shut down the virtual machine in either the Hyper-V Manager or from PowerShell.
Stop-VM srv2 -forceThen start it back up.
Start-VM srv2Wait about 5 minutes and then test again.
Another good test is to try an setup another simple configuration. Run Wipe-Lab -force from the configuration folder, then change to one of the simple configurations like SingleServer or Windows10 and see if that installs. This will help determine if the problem is isolated to a specific lab configuration or a larger issue with your environment.
As a last resort, you can try to manually re-apply a configuration to a virtual machine. If you run Run-Pester you be able to discover what virtual machine or test is failing. For the sake of demonstration let's say it is a virtual machine called WIN10. To re-apply the configuration, you need to create a remoting session to it.
First, you need the lab password to create a credential object.
$data = Import-PowerShellDataFile .\VMConfigurationData.psd1
$pass = ConvertTo-SecureString -AsPlainText -String $data.AllNodes.LabPassword -force
$cred = New-Object PSCredential -ArgumentList administrator, $passNote that if the lab has a mix of domain and workgroup machines, you will need to look at the VMConfigurationData file to discover the correct password. Almost always they will be same.
Next, create a CIMSession to the virtual machine.
$cim = New-CimSession -ComputerName win10 -Credential $credNow, you can apply the DSC configuration. You need run this from the lab configuration folder.
Start-DscConfiguration -CimSession $cim -Path . -wait -Force -verboseYou will be able to watch the process. Wait a minute or two for any background processing to finish and then test:
Test-DscConfiguration -CimSession $cim -DetailedIf all goes well, you should see something like this:
PSComputerName ResourcesInDesiredState ResourcesNotInDesiredState InDesiredState
-------------- ----------------------- -------------------------- --------------
win10 {[Registry]TLS, [xIPAddress... True
If there are resources not in the desired state, wait 10 minutes and test again. If there are still failures, wipe the lab and start all over. At which point, if you are still having failures, file an issue and we'll have to determine what is happening.
If encounter problems getting any of this to work, you are welcome to post an Issue. If you get the module installed, please include the results of Get-PSAutolabSetting. If your problem is meeting one of the requirements, we will do our best to help. Although if your computer is locked down or otherwise controlled by corporate policies there may not be much that we can do.