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

SHORT DESCRIPTION

        Custom resources are binary files that can be deployed into virtual machines' VHD(X) disk file.

LONG DESCRIPTION

        Most lab environments require additional binary resources to be able to provision them end-to-end. These
        resources may include .EXE, .MSI, .ISO and/or .ZIP files.

        Custom resources are defined in the NonNodeData section of the PowerShell DSC configuration document (.psd1)
        and then referenced within each node where the resource is required. This process permits injecting a
        resource into more than a single virtual machine if required.

        When defining custom resources, the Uri property can point to a http://, https:// or file:// location.

        NOTE: BE CAREFUL WHEN DISTRIBUTING LAB CONFIGURATION DOCUMENTS THAT CONTAIN FILE URIS.

        @{
            AllNodes = @(
                @{
                    NodeName = 'ResourceExample';

                    ## Specify the resource identifiers all of the resources to be copied to the target node during
                    ## VM creation.
                    Lability_Resource = @('MyCustomResource');
                }
            )

            NonNodeData = @{
                Lability = @{

                    Resource = @(

                        @{
                            ## Resource identifier. If the resource is to be expanded (ZIP or ISO), it will also be
                            ## expanded into the \Resources\<ResourceID> folder on the target node.
                            Id = 'MyCustomResource';

                            ## When the file is downloaded, it will be placed in the host's 'ResourcePath' folder
                            ## using this filename.
                            Filename = 'MyCustomResource.zip';

                            ## The source URI to download the file from if it is not present in the host's Resources
                            ## folder. This can be a http, https or file URI. If the path includes spaces, they must
                            ## be URL encoded.
                            Uri = 'http://mybucket.s3.amazon.com/MyCustomFile.zip'

                            ## If you want the module to check the downloaded file, you can specify a MD5 checksum.
                            ## If you do specify a checksum you HAVE to ensure it's correct otherwise it will
                            ## continuously attempt to download the resource!
                            Checksum = '';

                            ## If the resource is a .ZIP or .ISO file, it can be expanded/decompressed when copied
                            ## into the node's \Resources\<ResourceID> folder. If not specified, this value defaults
                            ## to False.
                            Expand = $true;

                            ## If specified, overrides the default \Resources destination path.
                            DestinationPath = '\ProgramData\VirtualEngine';
                        }

                    )
                }
            }
        }

RESOURCE DOWNLOAD

        When a lab configuration is started, Lability will automatically download all missing media and custom
        resources. In some scenarios you may need to download all required resources in advance, e.g. where internet
        access is not readily available or permitted. The `Invoke-LabResourceDownload` cmdlet can be used to manually
        download all required resources.

        All downloaded resources are cached in the host's 'ResourcePath'. This path can be found by running the
        following command:

            PS C:\> Get-LabHostDefault

        Use the `Set-LabHostDefault` cmdlet to set the host's 'ResourcePath' property. For example

COMPRESSED RESOURCES

        Custom resources/media may be downloaded in a compressed format, i.e. ZIP files. Lability supports
        decompressing or expanding .ISO and .ZIP resources into a node's VHD(X) file when the VM is created. To expand
        a resource you need to set the 'Expand' property on the resource to '$true'. By default no resources are
        automatically expanded.

        When expanding .ISO and .ZIP resources, they are placed into the \Resources\<ResourceId> folder. For example,
        an .ISO resource with the Id of 'MyCustomIso' when set to expand, would be expanded into the
        C:\Resources\MyCustomIso folder of the target node.

        NOTE: THE COMPRESSED RESOURCE IS STILL DOWNLOADED AND STORED ON THE HOST MACHINE.

LOCAL RESOURCES

        Resources that you don't want to be downloaded or are retrieved by other means, e.g. via version control,
        can be flagged with the 'IsLocal' property.

        NOTE: THE URI AND CHECKSUM PROPERTIES ARE NOT USED FOR LOCAL RESOURCES.

        @{
            NonNodeData = @{
                Lability = @{

                    Resource = @(

                        @{
                            Id = 'MyCustomResource';

                            ## The IsLocal property is used to flag "internal" resources. These resources are typically
                            ## stored in version control along with the Lability configuration.
                            IsLocal = $true;

                            ## Relative paths are supported. The file system provider location will need to be set
                            ## accordingly.
                            Filename = '.\MyCustomResource.xml';
                        }

                    )
                }
            }
        }

MANUAL RESOURCE DOWNLOAD

        It is also possible to manually prestage resources by placing them in the host's 'ResourcePath' directory.
        If an existing filename (and checksum) already matches a resource definition, Lability will not attempt to
        download it again.

        For example, when using the above configuration, manually placing a 'MyCustomResource.zip' file in the host's
        'ResourcePath' directory will ensure that the file will not be downloaded (as there is no checksum). However,
        if a MD5 checksum is defined, only if the MD5 checksum matches, it will won't be downloaded again.

        NOTE: IF A MD5 CHECKSUM IS INCORRECT, LABILITY WILL CONTINUOUSLY ATTEMPT TO DOWNLOAD A RESOURCE.

KEYWORDS
        Compressed resource
        Custom resource
        Media download

SEE ALSO
        CustomResources.psd1
        Invoke-LabResourceDownload
        Get-LabHostDefault