en-us/about_PSAutoLab.help.txt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
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 machines 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-Host
    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 your location to the desired configuration folder. View the
    Instructions.md and/or README.md files in the folder to learn more about
    the configuration.
 
    The first time you set up 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 the complexity of some configurations
    this could take 60-90 minutes. You can use Ctrl+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 several breaking changes to how tests are written. The tests in
    this module are incompatible with Pester 5.0 and will eventually 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 provider, 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 a 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/2020 12:05:43] Found 5 updates to install on SRV3
    [11/22/2020 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 shut down 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
    configuration, and start again.
 
    If you are still having problems, wipe the lab and try a different
    configuration. This will help determine if the problem is with a specific
    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 run Get-PSAutoLabSetting 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