en-us/about_PSAutoLab.help.txt
|
TOPIC
about_PSAutoLab SHORT DESCRIPTION This project serves as a set of "wrapper" commands that utilize the Lability module which is a terrific tool for creating a lab environment of Windows based systems. The downside is that it is a difficult module for less experienced PowerShell users. The configurations and control scripts for the Hyper-V virtual machine's are written in PowerShell using Desired State Configuration (DSC) and deployed via Lability. If you feel sufficiently skilled, you can skip using this project and use the Lability module on your own. You can run Open-PSAutoLabManual to view a PDF of documentation, including much of the content in this file. LONG DESCRIPTION SETUP The first time you use this module, you will need to configure the local machine or host. Open an elevated PowerShell session and run: Setup-Host This will install and configure the Lability module and install the Hyper-V feature if it is missing. By default, all AutoLab files will be stored under C:\AutoLab, which the setup will create. If you prefer to use a different drive, you can specify it during setup. Setup-Host -DestinationPath D:\AutoLab You will be prompted to reboot, which you should do, especially if setup had to add Hyper-V. CREATING A LAB Lab information is stored under the AutoLab Configurations folder, which is C:\AutoLab\Configurations by default. Open an elevated PowerShell prompt and change location to the desired configuration folder. View the Instructions and/or readme files in the folder to learn more about the configuration. The first time you setup a lab, Lability will download evaluation versions of required operating systems in ISO format. This may take some time depending on your Internet bandwidth. The downloads only happen when the required ISO is not found. When you wipe and rebuild a lab it won't download files a second time. Once the lab is created you can use the module commands for managing it. Or you can manage individual virtual machines using the Hyper-V manager or cmdlets. It is assumed that you will only have one lab configuration created at a time. MANUAL SETUP Most, if not all, configurations should follow the same manual process. Run each command after the previous one has completed. Setup-Lab Run-Lab Enable-Internet To verify that all virtual machines are properly configured you can run Validate-Lab. This will invoke a set of tests and loop until everything passes. Due to the nature of DSC and complexity of some configurations this could take 60-90 minutes. You can use Ctr+C to break out of the testing loop at any time. You can manually run the test one time to see the current state of the configuration. Invoke-Pester VMValidate.test.ps1 This can be useful for troubleshooting. An Important Pester Note If you are running Pester v5.x you need to be running at least version 4.11.0 of this module. The validation tests for each configuration are written for the Pester module. This is a widely adopted testing tool. In June of 2020, Pester version 5 was released. This version of Pester introduced a number of breaking changes to how tests are written. The tests in this module are **incompatible** with Pester 5.0 and will need to be re-written. As an interim step, this module will test for Pester v 4.10.1. If you don't have that version it will be installed when you run Setup-Host. Or if you've already setup Autolab you can run Refresh-Host. If you have Pester 5.x, it will not be uninstalled, but it will be removed from the current PowerShell session. UNATTENDED SETUP As an alternative, you can setup a lab environment with minimal prompting. Unattend-Lab Assuming you don't need to install a newer version of nuget, you can leave the setup alone. It will run all of the manual steps for you. STOPPING A LAB To stop the lab VMs, change to the configuration folder in an elevated Windows PowerShell session and run: Shutdown-Lab You can also use the Hyper-V manager or cmdlets to shut down virtual machines. If your lab contains a domain controller such as DOM1 or DC1, that should be the last virtual machine to shut down. STARTING A LAB The setup process will leave the virtual machines running. If you have stopped the lab and need to start it, change to the configuration folder in an elevated Windows PowerShell session and run: Run-Lab You can also use the Hyper-V manager or cmdlets to start virtual machines. If your lab contains a domain controller such as DOM1 or DC1, that should be the first virtual machine to start up. LAB CHECKPOINTS You can snapshot the entire lab very easily. Change to the configuration folder in an elevated Windows PowerShell session and run: Snapshot-Lab To quickly rebuild the labs from the checkpoint, run: Refresh-Lab TO REMOVE A LAB To destroy the lab completely, change to the configuration folder in an elevated Windows PowerShell session and run: Wipe-Lab This will remove the virtual machines and DSC configuration files. If you intend to rebuild the lab or another configuration, you can keep the LabNat virtual switch. WINDOWS UPDATES When you build an lab, you are creating Windows virtual machines based on evaluation software. You might still want to make sure the virtual machines are up to date with security patches and updates. You can use Update-Lab to invoke Windows update on all lab members. This can be a time consuming process, so you have an option to run the updates as a background job. Be sure not to close your PowerShell session before the jobs complete. PS C:\AutoLab\Configurations\PowerShellLab\> update-lab -AsJob Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- 18 WUUpdate RemoteJob Running True DOM1 WUUpdate 21 WUUpdate RemoteJob Running True SRV1 WUUpdate 24 WUUpdate RemoteJob Running True SRV2 WUUpdate 27 WUUpdate RemoteJob Running True SRV3 WUUpdate 30 WUUpdate RemoteJob Running True WIN10 WUUpdate PS C:\AutoLab\Configurations\PowerShellLab\> receive-job -id 27 -Keep [11/22/2019 12:05:43] Found 5 updates to install on SRV3 [11/22/2019 12:25:13] Update process complete on SRV3 WARNING: SRV3 requires a reboot Run the update process as a background job. Use the PowerShell job cmdlets to manage. UPDATING THE MODULE As this module is updated over time, new configurations may be added, or bugs fixed in existing configurations. There may also be new Lability updates. Use PowerShell to check for new versions: Find-Module PSAutoLab Beginning in v4.8.0., the module will check for a new version when the module is imported. If an update is required, you will see a message. To update the module you run: Update-Module PSAutoLab If you update, it is recommended that you update the computer running AutoLab by running this command: Refresh-Host This will update Lability if required and copy all new configuration files to your AutoLab\Configurations folder. It will NOT delete any files. TROUBLESHOOTING The commands and configurations in this module are not foolproof. During testing a lab configuration will run quickly and without error on one Windows 10 desktop but fail or take much longer on a different Windows 10 desktop. Most setups should be complete in under an hour. If validation is failing, manually run the validation test in the configuration folder. Invoke-Pester VMValidate.test.ps1 Take note of which virtual machines are generating errors. Verify the virtual machine is running in Hyper-V. On occasion for reasons still undetermined, sometimes a virtual machine will shutdown and not reboot. This often happens with the client nodes of the lab configuration. Verify that all virtual machines are running and manually start those that have stopped using the Hyper-V manager or cmdlets. Sometimes even if the virtual machine is running, manually shutting it down and restarting it can resolve the problem. Remember to wait at least 5 minutes before manually running the validation test again when restarting any virtual machine. As a last resort, manually break out of any testing loop, wipe the lab and start all-over. If you still are having problems, wipe the lab and try a different configuration. This will help determine if the problem is with the configuration or a larger compatibility problem. At this point, you can open an issue in this module's GitHub repository. Open an elevated PowerShell prompt and rGet-PSAutoLabSett which will provide useful information. Copy and paste the results into a new issue along with any error messages you are seeing. CUSTOMIZING CONFIGURATIONS The expectation is that one of the included configurations will meet your needs or has been specified by a Pluralsight author. However, you are free to modify or create your own configuration. This process assumes you have experience with writing Desired State Configuration (DSC) scripts, including the use of configuration data files (*.psd1) and Pester. Because configurations might be updated in future versions of the PSAutoLab module, you are encouraged to create a new configuration and not edit existing files. Find a configuration that is close to your needs and copy it to a new folder under AutoLab\Configurations.Technically, you can put the configuration folder anywhere but it is easier if all of your configurations are in one location. Once the files have been copied, use your script editor to modify the files. Don't forget to update the Pester test. Keep the same file names. KNOWN ISSUES Due to what is probably a bug in the current implementation of Desired State Configuration in Windows, if you have multiple versions of the same resource, a previous version might be used instead of the required on. You might especially see this with the xNetworking module and the xIPAddress resource. If you have any version older than 5.7.0.0 you might encounter problems. Run this command to see what you have installed: PS C:\> Get-DSCResource xIPAddress If you have older versions of the module, uninstall them if you can. PS C:\> Uninstall-Module xNetworking -RequiredVersion 3.0.0.0 It is recommended that you restart your PowerShell session and try the lab setup again. SEE ALSO https://github.com/pluralsight/PS-AutoLab-Env KEYWORDS * AutoLab * psAutoLab |