en-US/about_Lability.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
TOPIC
        about_Lability

SHORT DESCRIPTION

        Lability is a local Hyper-V lab provisioning framework.

LONG DESCRIPTION

        The Lability module enables simple provisioning of local Windows Hyper-V development and testing lab
        environments. The intended purpose is to enable the sharing and collaboration of lab environment
        configurations in a standardised format.

        It uses a declarative document for machine configuration. However, rather than defining configurations in an
        external custom domain-specific language (DSL) document, Lability extends existing PowerShell Desired State
        Configuration (DSC) configuration .psd1 documents with metadata that can be interpreted by the module.

        By using this approach, it allows the use of a single configuration document to describe all properties for
        provisioning Windows-centric development and/or test environments.

        The Lability module will parse the DSC configuration document and provision Hyper-V virtual machines according
        to the metadata contained within. When invoked, Lability will parse a DSC configuration document and
        automagically provision the following resources:

            * Virtual machine disk images
                - Download required evaluation Operating System installation media.
                - Expand Windows Image (WIM) image files into Sysprep'd virtual machine parent disks.
                - Apply required/recommended DSC Windows updates.

            * Virtual networks
                - Create internal and external Hyper-V switches.

            * Virtual machines
                - Connect to the correct virtual switches.
                - Inject DSC resources from the host machine.
                - Inject a dynamically created Unattend.xml file.
                - Inject external ISO, EXE and ZIP resources.
                - Inject the virtual machine's DSC document.
                - Invoke the Local Configuration Manager (LCM) after Sysprep.

DSC CONFIGURATIONS

        An example DSC configuration document might look the following.

            @{
                AllNodes = @(
                    @{
                        NodeName = 'DC1';
                    },
                    @{
                        NodeName = 'APP1';
                    }
                )
                NonNodeData = @{

                }
            }

        This exact same document can be extended with specific properties which the Lability module can interpret.
        NOTE: this is still a valid PowerShell DSC configuration (.psd1) document that can be supplied to an
        existing PowerShell DSC configuration.

            @{
                AllNodes = @(
                    @{
                        NodeName = '*';
                        Lability_SwitchName = 'CORPNET';
                        Lability_Media = '2012R2_x64_Standard_EN_Eval';
                    },
                    @{
                        NodeName = 'DC1';
                        Lability_ProcessorCount = 2;
                    },
                    @{
                        NodeName = 'APP1';
                        Lability_ProcessorCount = 1;
                    }
                )
                NonNodeData = @{
                    Lability = @{
                        Network = @(
                            @{
                                Name = 'CORPNET';
                                Type = 'Internal';
                            }
                        )
                    }
                }
            }

        When Start-LabConfiguration is invoked with the above configuration document, it will:

            * Create an internal Hyper-V virtual switch named 'CORPNET'.
            * Download required Server 2012 R2 Standard Edition evaluation media.
            * Create a Sysprep'd Server 2012 R2 Standard Edition parent VHDX file.
            * Install required/recommended DSC hotfixes.
            * Provision two Hyper-V virtual machines called 'DC1' and 'APP1'.
            * Each VM will be given 2GB RAM (configurable default).
            * 'DC1' will be assigned 2 virtual CPUs.
            * 'APP1' will be assigned 1 virtual CPU.
            * Attach each virtual machine to the 'CORPNET' virtual switch.
            * Create differencing VHDX for each VM.
            * Inject a dynamically created Unattend.xml file into the differencing VHDX.

        For a full list of supported metadata, see about_ConfigurationData.

SETTING UP LABILITY

        Initiating a lab deployment requires a number of prerequisites:

            * The Lability module must be running with administrative credentials
                - Creating virtual machines requires administrative permissions.

            * Installation of the Hyper-V role and PowerShell management cmdlets
                - Lability will take care of the local host configuration.
                - Manually installing the Hyper-V role will remove the need to reboot the host.

        To start the configuration of the Lability host, run the following command at an elevated PowerShell prompt:

            PS C:\> Start-LabHostConfiguration

        If a reboot is required, the module will produce an error. Reboot the host and run the command again.

        For more detailed information about the progress or what the command is doing, you can supply the -Verbose
        switch:

            PS C:\> Start-LabHostConfiguration -Verbose

        If you wish to check the status of the current host, use the `Test-LabHostConfiguration` cmdlet.

CONFIGURING HOST DEFAULT VALUES

        Lability uses numerous defaults for all virtual machines that are created. These default values include the
        location of the parent virtual disk files, the location of differencing virtual disk files and the default
        location searched for PowerShell DSC .mof files etc.

        To view the current host configuration settings, run the following command:

            PS C:\> Get-LabHostDefault

        By default, Lability stores all media and virtual machine disk files on the host's system drive. If any of the
        default values need changing to reflect your particualar environment or configuration, it is recommended that
        you set these default before creating any virtual machines.

        To change any of the default values, use the `Set-LabHostDefault` cmdlet. For example, to set the location of
        all .ISO files to `D:\Lability\ISOs` run the following command:

            PS C:\> Set-LabHostDefault -IsoPath D:\Lability\ISOs

        For more information about setting the host's default values run the following command:

            PS C:\> Get-Help -Name Set-LabHostDefault

CONFIGURING VIRTUAL MACHINE DEFAULT VALUES

        Lability applies numerous default values to a virtual machine if they are not explicitly specified, for example
        the number of processors to assign or the virtual switch to attach the VM to.

        The default values can always be overridden within the PowerShell DSC configuration document (.psd1). There is
        a order of precedence that is applied when evaluating the effective setting. The value is applied to the
        virtual machine in the following order of precedence:

            1. The node's configuration hashtable.
            2. The default/wildcard node's configuration hashtable.
            3. The LabVMDefaults value.

        To view the current virtual machine default settings, run the following command:

            PS C:\> Get-LabVMDefault

        To change any of the default values, use the following command:

            PS C:\> Set-LabVMDefault

        For more information about setting the virtual machines' default values run the following command:

            PS C:\> Get-Help -Name Set-LabVMDefault

RUNNING LABILITY

        Once the Lability host is configured, the host default values and the virtual machine defaults set, you can
        initiate a lab deployment. In order to successfully deploy a lab, you will need to following prerequisites in
        place:

            * A PowerShell DSC configuration (.ps1) file and an associated PowerShell DSC configuration (.psd1)
               document.
                - The configuration document (.psd1) should be annotated with the Lability metadata to ensure that the
                  correct settings will be applied to each virtual machine.
                - If an option is not defined on a node within the configuration (.psd1) document, the Lability VM
                  default value will be used.

            * Have already run the required PowerShell DSC configuration on the Lability host.
                - The configuration (.ps1) file must have already been run successfully and generated the required
                  .mof files.
                - This will ensure that all the .mof files are available locally.
                - This also ensures that all the PowerShell DSC resources are located on the host.
                - The .mof files will be injected into the relevant VM during creation.

        After you have confirmed that all the prerequisites are in place, you can invoke the lab deployment using the
        `Start-LabConfiguration` cmdlet.

            PS C:\> Start-LabConfiguration -ConfigurationData .\MyLab.psd1 -Path .\MyMofFiles `
                     -Credential (Get-Credential Administrator)

        This will apply the configuration defined in the `MyLab.psd1` configuration file and a virtual machine created
        for each node defined. The `MyMofFiles` directory will be searched for the corresponding .mof files.

        NOTE: IF ANY .MOF FILES CANNOT BE LOCATED, AN ERROR WILL BE SHOWN AND THE CONFIGURATION ABORTED.

        Once all prerequisite checks have passed, Lability will perform the following actions for each node within the
        configuration (.psd1) document:

            * Create a virtual machine
                - Any values specified will be used, e.g. Media (Operating System).
                - If a value is not specified, the Lability VM defult value will be used.

            * Create the VM's differencing VHD(X) file:
                - If the master VHD(X) file has not been created, Lability will dynamically create it.
                - If the required media (.ISO) file is not available, Lability will attempt to download it.

            * Inject required resources into the VM's VHD(X) file:
                - Copy all local PowerShell DSC resources.
                - Copy the VM's .mof and .meta.mof file(s).
                - Copy the Lability certificate and bootstrap files.
                - Copy a unattend.xml file that will configure the virtual machine as required and invoke the DSC
                  configuration after the Sysprep process has completed.
                    - The local Administrator password will be set to the value supplied
                      via the `Credential` parameter.

        For more information on Operating System media and custom resources see the following help topics:

            PS C:\> Get-Help -Name Start-LabConfiguration
            PS C:\> Get-Help -Name Media
            PS C:\> Get-Help -Name CustomResources

CONTRIBUTE

        Lability is open source on GitHub:

        https://github.com/VirtualEngine/Lability

        As you run Lability and find what you believe to be are bugs, please submit them to:

        https://github.com/VirtualEngine/Lability/issues

        Better yet, fix the bug and submit a pull request.

SEE ALSO
        Start-LabConfiguration
        about_ConfigurationData
        about_Bootstrap
        about_Media
        about_CustomResources