Sunday, 3 September 2017

Learn PowerShell DSC - Part 3

Introduction

So, we’ve learnt a bit about the basics of DSC with a simple configuration using the File DSC resource in part 1 and then moved on to discuss other DSC resources you can find built into Windows in part 2.

In this post, I’ll show you how you can integrate parameters when creating DSC configurations and also how you can set up dependencies between different DSC resources in your configuration.

Other parts in the series can be found below:

PowerShell DSC parameters

Why are we doing this? Well, it allows you to specify variables which are used to generate the configuration which is then pushed out to the target machines.

In this example which uses the Registry DSC resource to create registry values, I have four parameters that I want to pass to the configuration:

  • ComputerName - this determines which target machines the configuration will be pushed out to
  • Key - this is the registry key
  • ValueName - this is the name of the value
  • ValueData - this is the data that goes in the registry value
  • ValueType - this is the type of value, e.g. string, binary, dword

You specify the parameters as you would normally when writing a script or a function so this section looks like this:

param
     (
         [Parameter(Mandatory=$true)]
         [string]$ComputerName,
         [Parameter(Mandatory=$true)]
         [string]$Key,
         [Parameter(Mandatory=$true)]
         [string]$ValueName,
         [Parameter(Mandatory=$false)]
         [string]$ValueData,
         [Parameter(Mandatory=$false)]
         [string]$ValueType
     )
    

Nothing earth shattering here so stay with me. Let’s now make a configuration using the Registry DSC resource but instead of specifying the key, value and other parameters, we’ll use variables:

configuration RegistryConfig
{
     param
     (
         [Parameter(Mandatory=$true)]
         [string]$ComputerName,
         [Parameter(Mandatory=$true)]
         [string]$Key,
         [Parameter(Mandatory=$true)]
         [string]$ValueName,
         [Parameter(Mandatory=$false)]
         [string]$ValueData,
         [Parameter(Mandatory=$false)]
         [string]$ValueType
     )         

    Import-DscResource -ModuleName PSDesiredStateConfiguration
     Node $ComputerName
     {       
         Registry CreateReg
         {
             Key = $Key
             ValueName = $ValueName
             ValueType = $ValueType
             ValueData = $ValueData
             Ensure = 'Present'
         }
     }
}

We can then generate the MOF file and specify what we need the key, value, value data and type to be and also which target machine to create the configuration for:

RegistryConfig -OutputPath C:\DSC\Registry -ComputerName contchidsc01 `
-Key HKEY_Local_Machine\Software\DSCTest -ValueName DSCTestGood -ValueData True -ValueType string

Now we have our MOF file, we can push it to our target machine contchidsc01:

Start-DscConfiguration -Computername contchidsc01 -Path C:\DSC\Registry -Wait -Verbose -Force

The full script is below:

configuration RegistryConfig
{
     param
     (
         [Parameter(Mandatory=$true)]
         [string]$ComputerName,
         [Parameter(Mandatory=$true)]
         [string]$Key,
         [Parameter(Mandatory=$true)]
         [string]$ValueName,
         [Parameter(Mandatory=$false)]
         [string]$ValueData,
         [Parameter(Mandatory=$false)]
         [string]$ValueType
     )         

    Import-DscResource -ModuleName PSDesiredStateConfiguration
     Node $ComputerName
     {       
         Registry CreateReg
         {
             Key = $Key
             ValueName = $ValueName
             ValueType = $ValueType
             ValueData = $ValueData
             Ensure = 'Present'
         }
     }
}

RegistryConfig -OutputPath C:\DSC\Registry -ComputerName contchidsc01 `
-Key HKEY_Local_Machine\Software\DSCTest -ValueName DSCTestGood -ValueData True -ValueType string
Start-DscConfiguration -Computername contchidsc01 -Path C:\DSC\Registry -Wait -Verbose -Force

image

When we run this, we can see that the HKEY_Local_Machine\Software\DSCTest key is created then the DSCTestGood value is created and set to True and the type is set to REG_SZ, (string).

image

So, there we have it. PowerShell parameters. Now, let’s say you need to deploy a number of different registry keys and values to a number of machines and you have it all in a CSV. Well, now you can do that quite easily - all using the same configuration.

PowerShell DSC DependsOn

Let’s say we need to copy a zip file to a target machine and then extract that zip file to a folder. Now, clearly we don’t want DSC to try extract a zip file before it’s been copied over because that would be rather dumb. Here’s where we can specify the order that DSC Resources are processed in a configuration - by using the DependsOn parameter which is built into DSC resources.

We’ll use the File DSC resource to copy the zip file over then we’ll use the Archive DSC resource to extract it but we’ll specify that the Archive DSC resource depends on the File DSC resource:

configuration Archive
{
     Import-DscResource -ModuleName PSDesiredStateConfiguration
     Node contchidsc01
     {       
         File CopyArchive
         {
             SourcePath = '\\contchisql01\Software\Docker.zip'
             DestinationPath = 'C:\Software\Docker.zip'
             Type = 'File'
             Ensure = 'Present'
         }

        Archive ExtractArchive
         {
             Path = 'C:\Software\Docker.zip'
             Destination = 'C:\Software\Docker'
             DependsOn = "[File]CopyArchive"
         }
     }
}

Archive -OutputPath C:\DSC\Archive
Start-DscConfiguration -Computername contchidsc01 -Path C:\DSC\Archive -Wait -Verbose -Force

image

When we run this configuration and push it out, we see that our zip file is copied then extracted:

image

We can also look at the output from Start-DscConfiguration and we’ll see that the File DSC resource is run before the Archive DSC resource:

image

So, now you can get your configuration to apply DSC resources in order and ensure dependencies are met.

Conclusion

That’s DSC working with parameters and dependencies. I hope you’re starting to get into PowerShell DSC as much as I am! Next up, we’ll look at how to find, install and use DSC modules that are not build into Windows.

No comments:

Post a Comment