RPS Configuration Management (DSC) Software Design
Last updated on January 13, 2021.
Last Reviewed and Approved on PENDING REVIEW
This guide shows the underlying RPS framework to specify, setup and maintain a desired machine configuration for the Windows computers, including RPS itself, through the RPS API and Desired State Configuration (DSC).
Configuration Management using DSC
PowerShell Desired State Configuration (DSC) is a built-in capability of most Windows devices used to manage discrete configuration of a device or system. Additionally, it has direct support for Linux systems and non-OS devices by proxy of a Windows Device (e.g. Routers).
RPS facilitates a process in which DSC configurations can be correlated to devices. This allows for the management of configurable devices in a consistent manner.
This section will outline the suggested structure for authoring DSC configurations.
| Term | Definition |
|---|---|
| RPS Node | A running instance of the RPS system. |
| DSC | Microsoft PowerShell Desired State Configuration. |
DSC Partial Configurations
DSC allows for configurations to be structured as Partial Configurations which represent small configurations for individual pieces of configuration data. By authoring DSC configurations for delivery in RPS into smaller Partial configurations, they can be pieced together and rearranged in new ways for delivery in multiple configuration sets. This modular approach greatly improves the reusability of individual configurations.
The following link provides additional information on DSC Partial Configurations: https://docs.microsoft.com/en-us/powershell/scripting/dsc/pull-server/partialconfigs?view=powershell-7.1
DSC Resources
If a DSC partial configuration contains the information of what the configuration will be, a DSC resource contains the information of how the configuration is set. RPS uses DSC resources from the open-source community and the RPS team itself.
Note
The RPS documentation includes information on authoring or adding new DSC resources to the solution. This documentation can be found at $/Documents/Operations/Authoring DSC Resources.docx.
The RPS DSC Structure
The RPS API structure used by DSC is shown below in a distilled format. This structure allows us to develop generic DSC partial configurations that can be combined in many ways using resource groups and applied to any number of target items.
Each target item configured by DSC is required to be of type VirtualMachine. The property ConfigurationName is used to associate the target item with a resource group by the same name. Resource items within the group are the DSC partial configurations applied to the target item when Start-Dsc or Start-DscOffline is called. The property ComputerName is used by the DSC push process described below to connect to the target machine.
The resource group of type DscConfigurationGroup is used to group multiple partial configurations into groups for application to target items. This group type has a single optional property named Dependency. This is a semi-colon separated set of comma separated pairs naming the dependencies between DSC partial configurations.
For example, if the dependency property is “Certificate,OSCore;SQL,OSCore” a dependency for both the Certificate and SQL partial would be set on the OSCore partial.
The resource items of type DscPartial represent individual DSC partial configurations. Two of the properties, PartialConfigurationName and Path, are required with Resources being optional. Any resources used by the DSC partial listed as a comma separated list within the Resources property will be copied to the target item computer by the Start-Dsc Runbook or the Start-DscOffline script.
Finally, the resource item of type DscResource represents the DSC resources used by the partial configurations. Only the Path property is required.
Nearly all the DSC partial configurations have specific required parameters. Each of these expected parameters should be a property on all the target items using the partial configuration.
Start-Dsc and Start-DscOffline will use the properties on the target item as the parameters for call the DSC partial configurations. If the target item is missing a required property, the scripts will check higher memory scopes (This allows for temporary development environments with modified settings). If no property or variable is found matching all required parameters an exception will be thrown.
Compiling and Pushing Partial Configurations
When utilizing the DSC solution described in this document, there is a difference between how these DSC configurations can be used in an offline (RPS is not yet installed) scenario versus an “Online” (RPS is present) scenario.
The reason for this is, the same process used by RPS to push and configure DSC routines is the same process used to install RPS. By building the system this way it creates a circular flow that is self-supporting. This section will describe the differences between the online and offline implementations of RPS pushing DSC configurations. Simply put, the differences in functionality reside simply in where configuration data is sourced from.
Online
The “Online” version of pushing DSC with RPS consists of a series of Powershell runbooks (workflows) authored as Task Items in RPS. These runbooks are:
- Start-Dsc
- Test-Dsc
When Start-DSC is assigned to a TargetItem through the normal processes of RPS, the configurations are pulled and compiled as described previously in this document . By creating those groups of partials, the system can pair up TargetItem property data with required parameters from the database directly and execute the DSC push. The location in which the push is targeted is defined by the TargetItem referenced.
Currently, each targeted item used in this process must have a ComputerName property with appropriate data to supply connectivity information (such as an IP address, or host name).
In this mode, the data is sourced straight from the RPS Node CMDB database that is pushing the Start-DSC Task as an executed item.
The Test-Dsc Runbook is used to provide information on the current state of the DSC configuration on the target computer.
Offline
The “Offline” version of pushing DSC with RPS consists of a series of scripts that execute in the same manner described in the Online mode, however they source their data from local files. The scripts in this use case are:
- Start-DSCOffline
- Invoke-RpsInitialization
The XML files supplied to this process are serialized using the built in RPS Commands for serialization. These XML files are created using another existing RPS installation or using the Rps-ApiMock module.
A series of XML files must be exported to support an Offline DSC operation. They must include all required data by the RPS DSC Process including:
- ResourceItem data
- ResourceGroup data
- TargetItem data
By exporting this data into XML files, Start-DSCOffline can parse them and utilize the information to execute the same way the Online use case is executed.
Invoke-RpsInitialization provides a wrapper mechanism to ensure proper files, supporting content, and metadata is present at appropriate locations before DSC Scripts are applied and begin executing the configuration process.
Building the processes this way enables RPS to self-replicate new copies to new servers, which can also maintain their own health, self-recovery and report the state of configuration.
The offline initialization process supports XML files encrypted with the Rps-Encryption module as well as plain text files.