Series: Desired State Configuration – Part 4 : Anatomy of DSC Resource

DSC Resources are one of the most important component on the overall architecture of DSC. DSC resources are the key components that are monitored, interacted with and change its state if required depending upon its deviation compared to DSC configuration. Resources are used within the DSC configuration scripts for configuring the environment.

Microsoft already provides out of the box some of the DSC resources like

  1. Environment
  2. File
  3. Group
  4. Log
  5. Package
  6. Process
  7. Registry
  8. Role
  9. Script
  10. Service
  11. User
  12. Archive

However, new DSC resources can also be created. To create a new resource, we need to first understand the building blocks of a resource. We need to know and understand the different components are semantics used to build a new DSC resource.

In this post, we will look into the details of the building blocks of DSC resource.

All the DSC resources are available at following location where the drive could be different in your system. We can also see the out-of –the-box provides resources are also available here.

Even the custom DSC resources needs to be installed here in this directory location before they can be used within DSC configuration script. As visible above, I have created couple of resources for firewall.

For creating custom DSC resource, we need to create a new folder in above location with the name of the Resource represented for example “CheckFirewall”.

For understanding purpose, we can look into any of the out-of-the-box folders and investigate further. For example, if we look into “MSFT_UserResource, we see the following

p4-2

Here, there is a folder named “en-US” reflecting and containing locale specific information like strings, error message etc. This is an optional component that is needed for multi-lingual development of custom DSC resources. It contains 2 files as shown below, though there can be multiple Powershell data files.

The MFL file is the essentially MOF files that are used in Web based enterprise management (WBEM). If we are not using WBEM, this file is also optional.

The psd1 file is used to store name value pairs of localized data. This file is also optional if localization is not implemented.

p4-4

If we go back to “MSFT_UserResource”, we can see that there three more files and all these files are important to be implemented for a custom resource.

These files are

  1. <<ResourceName>>.MOF file
  2. <<ResourceName>>.PSM1 file
  3. <<ResourceName>>.PSD1 file

MOF file are Management object notation used with WMI to define the properties of the custom resource.

Below is the example from the MSFT_UserResource

p4-5

Version reflects the version of the class and FriendlyName reflects the name that should be used within the DSC configuration scripts.

We have to define the class reflecting the resource we want to create. This class is derived from MSFT_BaseResourceConfiguration, base class for all resources. It contains some of the important properties and custom resource must inherit this class.

Within the class, we define the properties that are important for a resource to be tracked including some of the DSC needed properties like

  1. Ensure
  2. Credentials
  3. Password etc.

[Key] reflects that the property value must be provided and should be unique.

[Write] reflects that the property can be written into.

[ValueMap] and [Values] are similar to Enumerations reflects certain valid values. For example Ensure Property can contain “Present” or “Absent” only.

Essentially, the file is based on MOF standards and needs to be saved as <<ResourceName>>.Schema.Mof

The second important file needed is the <<ResourceName>>.psm1 file. This file is the Powershell Script module file that can contain functions and cmdlets among other artifacts.

DSC requires that all the resources must implement at least three functions named

  1. Get-TargetResource
  2. Set-TargetResource
  3. Test-TargetResource

The above three functions needs to be implemented within the psm1 file and should be named as mentioned above although the parameters within these functions should reflect the ones provided within the MOF file. For example, if we have defined a property named Description, we should include it as parameter in Set-TargetResource function such that it can be modified. All the three functions should reflect the parameters defined in the MOF file.

Similarly, the GET function should return a HashTable containing all the values provided by the MOF file.

The TEST function should return true or false.

The SET function should create, update or delete a resource depending on the values provided in Configuration script for “ENSURE” property. If the Ensure property is “Absent”, the resource should be deleted whereas if the Ensure Property is “Present”, the resource should be either provisioned or updated.

The third important file needed is the <<ResourceName>>.psd1. This is the Powershell manifest file containing information about the corresponding module.

This file can be created by coping some existing file and then changing some of its value or can be generated through Powershell cmdlets. For creating a new Manifest file, we can use New-ModuleManifest cmdlet.

The important parameters to be provided to above cmdlets are

Path : reflects the path to generate the new module manifest file at. Filename including extension should be part of the Path.

NestedModule: reflects the name of the module that we want to run in the module session state. We can provide the name of our ps1 file here

ModulesToProcess: reflects the name of the module that we want to run in the global session state. We should provide the name of our psm1 file here.

PowershellVersion:  should be set to 4.0 or 3.0

FunctionsToExport: The value could be “*” means all functions within the module or can specify the names of the specific functions to be visible. We need to ensure that the value is either “*” or all the above mentioned three functions names are provided here in an array format.

Rest of the values can be set but are also optional. A typical PSD1 file looks like below.

p4-6

Once the PSD1 file is generated, we can use the resource in our Configuration scripts.

In the next post we will create a new resource using the above provided information.

Cheers!!!!

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s