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!!!!

Series: Desired State Configuration – Part 2 : Configuration internals

This is the second part of the series Desired State Configuration.

In this post we will look into some of the internal details about the configuration we created in the previous post.

In the last post, we talked about the some of the fundamentals of desired state configuration. We talked about what DSC is all about and a sample DSC script and the way Powershell has been extended to include the capabilities of DSC.

DSC is semantically equal to a Powershell function not only in terms of invoking it but it is also treated as a function. To prove it run the following command with Powershell ISE. Here “EnableFeatures” is the name of the configuration created in the earlier blog post

a

Within the output from the above command, look for the key called PSDrive, PSPath and PSProvider.

b

 The values for all the above three keys reflect that the created configuration called “EnableFeatures” reflect that indeed the configuration is nothing more than a function.

Also, if you change the drive and change it to function drive, the configuration “EnableFeatures” would be visible within the list of functions. To prove type the following command within Powershell ISE.

c

The prompt would change to

d

Type Dir in Powershell ISE.

Within the result, “EnableFeatures” would be available within the list of functions obviously with commandtype of type “Configuration”.

 e

Now, let’s focus towards MOF files that are generated when the Configuration is invoked. We will look into details about how to invoke the configuration in future post but in short invoking a configuration with Powershell ISE is nothing more than dot-sourcing the configuration file and calling the configuration by name.

Management Object Format (MOF) files are generated when Configuration is invoked.

A MOF file is generated for each Node within the configuration file.

We have saved the Configuration as Test.ps1 at C:\

f

We will then dot-source the powershell script such that “EnableFeatures” configuration is available in the global scope.

g

Once the script and its artifacts are loaded, “EnableFeatures” configuration should be invoked.

h

And the following is the output.

i

In the above image, there are few important information provided like

A directory created with the name of the configuration called “EnableFeatures” within the user’s local directory.

Within this directory 2 MOF are generates one for each target server. In this the example they are “WIN-PETR4TD7LAA” and “SCR2i”.

The .mof files looks like below.

j

The important thing to note here is that the information is collected from the Configuration file and this MOF file is created. This MOF file is needed for pushing the configuration information to the target server.

Powershell adds a new Command type called Configuration to differentiate between function and Configuration. When you run the above Get-command command, there is another key-value pair called CommandType available as output which reflects that it is of type “Configuration”.

k

In next post, we will look into end to end process of executing a DSC configuration file.

Hope you are finding these posts useful.

Cheers!!