Powershell Nugget : DSC ISE Snippet

One of cmdlet available within Powershell ISE is New-ISESnippet. This snippet allows us to add new code snippets to the ISE environment which can be used later at multiple places thereby saving overall development time as well as ensuring standards.

Desired State configuration provides a new snippet called “DSC Resource Provider”

On the Script tab of Powershell ISE, Press “Control + J”. A suggestion box appears containing all the registered Powershell snippets on the machine. Alternatively, you can also click on Edit menu and then “Start Snippets” sub-menu item to get the same suggestion box.

pn-01

You can go to “DSC resource provider” and click on it. It provides a templates for creating custom resources. It provides the template for all the three functions namely: Get-TargetResource, Set-TargetResource and Test-TargetResource.

pn-02

Makes life a bit easier by not remembering the name of the mandatory DSC functions.

Cheers!

Advertisements

Series: Desired State Configuration – Part 5 : Creating Custom Resources

In this post of the Desired State Configuration series we will look at creating new custom DSC Resource. If you are reading this post and have not read the precious blog post titled “Anatomy of DSC Resource”, I would highly recommend to read that first. It will provide you enough insight on what DSC resources are and the things to be taken care off while creating custom DSC resources.

We will be creating a new custom DSC resource related to Windows Firewall. Firewall is a feature of Windows providing rules that can be enabled and disabled. This custom resource is called “CheckFirewall” and would be responsible for managing the firewall rules i.e. enabling and disabling firewall rules.

The DSC resource would perform the following actions

  1. Check the value within Configuration and call the function Test-TargetResource.
  2. If the value is ‘Absent’, then return ‘True’ if firewall is not already enabled else return ‘False’.
  3. If the value is ‘Present’, then return ‘True’, if the firewall is already enabled else return ‘False’.
  4. If the value returned by Test-TargetResource is “False”, DSC would call “Set-TargetResource” function of the Resource whereas if the Test-TargetResource function returns “True”, DSC would call “Get-TargetResource” function of the resource.
  5. The “Set-TargetResource” function of the resource is generally responsible for checking each property of the target resource and update it according to the provided configuration. However, in our case, we are either enabling or disabling a firewall rule and hence would not be checking any properties provided by Firewall rules.

Create a Resource Provider Folder

Create a Folder called “CheckFirewall” at “<<Your Drive>>\Windows\System32\WindowsPowershell\v1.0\Modules\PSDesiredStateConfiguration\PsProviders\”. In my case the drive is C:\

5-1

Create MOF file

The first step in creating the Resource is to create its MOF file. For more details about MOF files, refer to earlier post.

We have named the MOF file as CheckFirewall.Schema.mof and the name of the class is CheckFirewall. Its version number is “1.0.0” and friendly name is also “CheckFirewall”.  Please note that it is this friendly name that is referred within the DSC configuration script. There are just 2 properties for this class

  1. DisplayName: referring to the display name of the firewall rule that needs to be enabled or disabled.
  2. Ensure: flag referring to whether the firewall rule should be enabled or disabled.

5-2

The MOF file can also be copied from some existing resource and modified as shown above and this is definitely more convenient and easier.

Create the Powershell Script Module file

In this step, we would create the script file that is the crux of creating the custom resource. The entire brains of the resource lies within this script file because it is here that all the DSC related mandatory functions are implemented namely Set-TargetResource, Get-TargetResource and Test-TargetResource.

Open Powershell ISE and implement the above mentioned three function and save it in CheckFirewall Directory created above as CheckFirewall.psm1 file.

We will use Windows Firewall Powershell cmdlets to determine the current state of the firewall rule and also for enabling and disabling it.

The Test-TargetResource function looks like below. We have used the Get-NetFirewallRule cmdlet for retrieving the details of firewall rule. The name of the firewall rule comes for the DSC configuration script as argument to this function.

5-3

The Get-TargetResource function looks like below. Again, we have used the Get-NetFirewallRule cmdlet for retrieving the details of firewall rule. The name of the firewall rule comes for the DSC configuration script as argument to this function. Here, we also check its current status to toggle the Ensure property.

5-41

The Set-TargetResource function looks like below. Again, we have used the Get-NetFirewallRule cmdlet for retrieving the details of firewall rule. The name of the firewall rule comes for the DSC configuration script as argument to this function. Here, we also check its current status to toggle the Ensure property.

5-5

Additionally, we also enable or disable the firewall rule using “Enable-NetFirewallRule” or “Disable-NetFirewallRule” depending upon the value of the configuration.

Above, notice that all the three functions defines parameters related to the properties available in the MOF file. Also, some can be mandatory while others could be optional.

Also, both Set-TargetResource and Get-TargetResource returns back a hashtable containing all the properties defined in the MOF file.

Generate the PSD1 file

We can either generate a new PSD1 file using “New-ModuleManifest” or copy some existing psd1 file for existing resource and modify accordingly. I recommend using the first approach of using the “New-ModuleManifest” since this would be less error prone provided you provide correct values. The details about generating this file is available in earlier blog post.

The name of the file should be “CheckFirewall” and should be generated within the above created folder. The sample content looks like below.

5-6

Now, this resource can be used in any DSC configuration script. An example is provided below. We have a Configuration node containing a Node for the Server name which in turn contains our new custom resource “CheckFirewall” and is named as “SQLFirewallPresent”. It is setting two available resource property i.e. DisplayName and Ensure. You would see that these are the two properties we have defined in our MOF file.

5-7

This concludes the creation of a custom resource for DSC. This is a simplified way of creating of DSC resource and many more aspects like localization and error handling should be part of the overall script.

Hope you liked this post.

Cheers!!!

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 3 : Pushing Configuration to Targets

This is the third part of the Series on Desired State Configuration. In this part we will look at how to create a configuration and push the same to the target servers. In the part, we will look at steps for bringing a target server to the expected state using the configuration.

We will use the same configuration that we created during the first part of the series. For sake of recalling, adding the same Configuration script below.

p3-1

In the above Configuration script, I have the top level Configuration element named “EnableFeatures”. Within this parent node, I have two nodes namely “WIN-PETR4TD7LAA” and “SCR2i”. These are the two servers which I want bring them into expected state i.e. to enable “Web-Server” feature on “WIN-PETR4TD7LAA” and “XPS-Viewer” on “SCR2i”. Above within the server nodes we have resource type “WindowsFeature” named “web-server” and “XPS”. These names could be any name that logically identifies it. Name within the resource reflects the name of the resource that we want to either add/remove from the environment or change its existing state if already added. “Ensure” reflects whether the resource should be installed or uninstalled depending on its value i.e. “Present” or “Absent”.

I would reflect the initial state of both the server with regard to their windows features and Roles.

Within the above Configuration, Server WIN-PETR4TD7LAA should have “Web-Server” Feature/Role available as its desired state and Server SCR2i should have “XPS-Viewer” Feature/Role removed from the server if it is already available.

Below is the screenshot for the server “WIN-PETR4TD7LAA” where Web Server is not installed

p3-2

And the screenshot for the server “SCR2i” where XPS-Viewer is already installed.

p3-3

So far we were looking at the environment that needs to adhere to the expected Configuration and also looked at the Configuration that needs to be reflected on the target servers. Now, we will look at steps to make the magic happens i.e. to run the configuration on individual target servers and change their state based on the configuration.

Step 1: Create the Configuration File.

We have already created this step and do not need to do it again. We will use the above Configuration file.

Step 2: Save the Configuration File to an appropriate location on file system.

Within Powershell ISE, while the configuration script is visible, select Menu-> Save as and save the configuration as ps1 file on file system. In my case, I have stored the file at “C:\“.

p3-4

 Step 3: dot-source ps1 file and load it in current session.

This step will enable to load the Test.ps1 file and keep in its scope the configuration data and function. If we do not dot-source it, the configuration would be loaded and unloaded immediately and would not be available to use in subsequent steps.

p3-5

Step 4: Execute the Configuration

In last step we loaded the file containing the configuration script “EnableFeatures”. In this step, we will execute the same configuration “EnableFeatures” to generate the Management Object Format (MOF) files one for each server.

Executing a Configuration is similar to executing a cmdlet or calling a function. Just call it by its name!

p3-6

Executing the Configuration would result in creating of one MOF file for each server containing all of its related resource types and configuration like name, ensure etc. These MOF Files would be generated within a folder created by executing the above configuration. The name of the folder is same of that of the configuration.

Step 5: Push the Configuration to the target server and execute

 p3-7

Start-DscConfiguration is a Powershell cmdlet provided by the Desired State Configuration module installed with Powershell 4.0. This Cmdlet is responsible for pushing the configuration to the target machines.

-wait lets the Powershell host wait until the cmdlet has finished executing

-verbose provides detailed actions executed by desired state configuration engine.

-force is self-explanatory.

Below is the screenshot while DSC Engine is bringing the target machine according to its configuration file.

And below is the verbose output while executing the configuration through Start-DscConfiguration.

p3-9

Now, let’s check the result of executing the configuration.

p3-10

p3-11

Note: If you have different servers in your configuration either you can use the credentials property of individual resource or use the credential property of Start-DscConfiguration to run the configuration remotely.

In the next part, we will look into the anatomy of creating a new DSC resources.

Cheers!!