dsc_from_configuration

Compile and apply a given DSC configuration defined by a ps1 file.

⚙️ Compatible targets: Windows

Parameters

NameDocumentation
tagName of the configuration, for information purposes.

This parameter is required.
config_fileAbsolute path of the .ps1 configuration file.

This parameter is required.

Outcome conditions

You need to replace ${tag} with its actual canonified value.

  • ✅ Ok: dsc_from_configuration_${tag}_ok
    • ☑️ Already compliant: dsc_from_configuration_${tag}_kept
    • 🟨 Repaired: dsc_from_configuration_${tag}_repaired
  • ❌ Error: dsc_from_configuration_${tag}_error

Example

method: dsc_from_configuration
params:
  config_file: VALUE
  tag: VALUE

Documentation

Compile and apply a given DSC configuration. The DSC configuration must be defined within a .ps1 file, and is expected to be "self compilable". A configuration data file (.psd1) containing variables can also be referenced by the ps1 script, by referring to it in the Configuration call.

The method will try to compile the configuration whenever the policies of the nodes are updated of if the previous compilation did not succeed.

All the Rudder variables are usable in your configuration.

Also the current method only allows DSC configurations to be run on the localhost target node, and when using a DSC push setup. Note that it may conflict with already existing DSC configurations not handled by Rudder.

Example 1 - without external data

Here is a configuration named EnsureWebServer.ps1 with simple Windows feature management:

Configuration EnsureWebServer {
 Node 'localhost' {
   # Install the IIS role
   WindowsFeature IIS {
       Ensure       = 'Present'
       Name         = 'Web-Server'
   }

   # Install the ASP .NET 4.5 role
   WindowsFeature AspNet45 {
       Ensure       = 'Present'
       Name         = 'Web-Asp-Net45'
   }
 }
}

EnsureWebServer

Example 2 with external data

Dsc configurations can be fed with external data, here is an example using a datafile Data.psd1 containing:

 @{
     AllNodes = @();
     NonNodeData =
     @{
       ConfigFileContents = "Hello World! This file is managed by Rudder"
     }
 }

Used to feed the HelloWorld.ps1 Contents key:

Configuration HelloWorld {
  Import-DscResource -ModuleName 'PSDesiredStateConfiguration'

  Node 'localhost' {
    File HelloWorld {
        DestinationPath = "${RudderBase}\HelloWorld.txt"
        Ensure          = "Present"
        Contents        = $ConfigurationData.NonNodeData.ConfigFileContents
    }
  }
}

HelloWorld -ConfigurationData /path/to/Data.psd1

Please note that the reference to the data file is done inside the configuration file.