Nik Charlebois is a Premier Field Engineer based out of Canada. He is the author of several books on SharePoint automation, and he writes blog posts on a regular basis about all things PowerShell. You can find out more about his work here.
PowerShell Desired State Configuration (DSC) has been around for a few years now, and many organizations are using it to help them automate parts of their DevOPS pipeline. There are now several hundred DSC modules available in the PowerShell Gallery. This enables organizations to create a complex automation solution that allows them to manage, via DSC, different components of their technology stacks.
One of the most complex solutions out there to manage via DSC is certainly SharePoint. While the SharePointDSC module is very mature, having been around for almost 3 years, it still represents a fair investment for clients to re-write their Imperative deployment script into DSC. Some of the most complex SharePoint environments I have seen being deployed with PowerShell DSC exceed the 150,000 lines of code. So how can an organization that has an existing SharePoint footprint get started with DSC, without spending months re-writing their configuration? It can simply use ReverseDSC.
What on earth is ReverseDSC?
Most organizations already have an existing investment in technology solutions, and rewriting their imperative set of scripts into a declarative DSC configuration script is not a project everyone is willing to undertake. ReverseDSC is a module that provides a set of functions that can be used to reverse engineer an existing environment into a DSC script. That’s right, you can simply run a script against your existing complex environment, such as SharePoint, and automatically generate these 150,000 lines of DSC code that represent your environment. You don’t need to do this manually.
What software is supported by ReverseDSC?
ReverseDSC, at its core, is an extensible solution that you can use to extract your existing environment as a Desired State Configuration (DSC) script. As long as there is a DSC Module for the technology component, you can use ReverseDSC to extract its current configuration. While ReverseDSC core is technology agnostic, and it provides interfaces to extract current configurations into DSC scripts, it does require a technology-specific component to be able to properly extract information from the existing environment.
These technology-specific scripts are referred to as Orchestrator Scripts, and include logic that is specific to the current piece of technology being extracted. We currently have the following official ReverseDSC Orchestrator Scripts available on GitHub:
- ReverseDSC Core https://www.GitHub.com/Microsoft/ReverseDSC
- SharePoint https://www.GitHub.com/Microsoft/SharePointDSC.Reverse
- SQLServer https://www.GitHub.com/Microsoft/SQLServerDSC.Reverse
- PSDesiredStateConfiguration https://www.GitHub.com/Microsoft/PSDesiredStateConfiguration.Reverse (files and registry)
Each Orchestrator Script release is closely aligned with the release of its associated DSC Module. For example, the SQLServer.Reverse script will have major releases that are aligned with major version releases of the xSQLServer DSC module.
How does it work?
Before I even attempt to answer that question, let us start by defining the following two terms:
- Desired State: How the host should be configured
- Current State: How the host is currently configured
Let’s look at an example to illustrate this concept. If you were to ask my wife what my desired state should be, it would be something like:
ValueInFeet = 6.3
Ensure = “Present”
WeightInPounds = 175
Ensure = “Present”
However, as much as it saddens me to admit it, the result of Test-DSCConfiguration -Detailed on this “Desired State” would be False for both resources. I am just short of 5’9″, and just shy of 180 pounds. That is my Current State. The goal of DSC is to make sure the Current State of an environment matches its Desired State. Unfortunately for me, DSC is not going to help me with the example above.
For the Local Configuration Manager (LCM) to check if the environment is configured as defined or not, we need a way to obtain information about both the Current State and the Desired State of each resource defined within the DSC configuration. By default, the LCM knows about the Desired State. It has that information on disk in the Current.mof file. What we are missing is information about the Current State.
Every DSC resource needs to define three core functions: Get, Set and Test. The Get method is the one responsible for obtaining information about the Current State of a given resource. The Set method is responsible for bringing the environment into its Desired State. It is where the configuration happens. And the Test method obtains information about the Current State by making a call into the Get function and compares it against the Current State.
In the case where we have configured the LCM in ApplyAndAutocorrect mode, upon detecting that the Current State and Desired State do not match, it will make a call back into the Set function and attempt to bring the environment back in its Desired State. The following diagram shows the relations among these functions of a DSC resource:
ReverseDSC, along with the technology-specific Orchestrator Scripts, simply makes use of the Get functions of the resources to retrieve information about the environment’s Current State. Then it generates a DSC configuration script that represents that Current State.
For example, the SQLServerDSC.Reverse Orchestrator Script, responsible for reverse engineering an existing SQL Server environment into a DSC configuration script, calls into the xSQLServerMaxDop resource’s Get function. The Orchestrator Script extracts information about the current server’s maximum degree of parallelism settings, converting that information into a DSC configuration output. A fully implemented Orchestrator can call into the Get function of every resource offered by its associated DSC module.
The ReverseDSC process and related Orchestrator Scripts are only as good as their associated DSC module. If the module doesn’t support a certain feature, the ReverseDSC process won’t be able to extract it.
There are dozens of potential reasons an organization would want to invest into ReverseDSC. Here is a short list of some of the most popular ones we have seen in the industry.
If you have an existing investment in a technology, and you want to replicate that exact environment elsewhere (in the cloud or on-premises), you can use ReverseDSC. With ReverseDSC, system administrators can now extract a DSC configuration from an on-premises environment, and replicate it in Azure within minutes, all while automating their processes. Disaster recovery is another reason to replicate environments, to ensure we have failover environments that match the original one.
Isn’t it every organization’s dream to have their developers write and test code on an environment that is an exact replica of the production environment? This helps ensure that there are no unwanted behaviors once the code hits general release. ReverseDSC makes this very simple to do. Simply extract the DSC configuration of your production environment, and use the output DSC script to generate dozens of developer environments matching its exact configuration. Your organization could even run a regular ReverseDSC exercise against the production environment (for example, every week or month). You can put that latest extract onto a DSC pull server, for all developers’ workstations to automatically get updated with the delta of whatever changed in production since the last extract.
Another usage scenario is where an organization simply wants to on-board their existing systems onto DSC. Perhaps the organization wants to benefit from the DSC’s monitoring capabilities (ApplyAndMonitor) and self-attempt at preserving its configuration (ApplyAndAutocorrect). An organization can now run ReverseDSC against an existing environment, extract the DSC configuration script that represent it, and push it right back at its LCM for it to start monitoring any changes done to it. This is basically saying to the environment: “Tell me how you are currently configured, and by the way your current configuration is now also becoming your Desired State from now on.”
Documentation and auditing
Organizations that have already invested time and money in writing deployment scripts to build their environments most likely are not thrilled about having to re-write the whole thing as a DSC configuration script to leverage DSC’s monitoring feature. Instead of having to rewrite all their scripts, they can now simply build a base environment that use these “imperative scripts,” and then run ReverseDSC on the resulting environment. While this does not directly convert deployment scripts into DSC, it provides the organization with the same results in the end.
Last but not least, documenting and comparing changes in time for an existing environment is another very popular scenario. Organizations can run ReverseDSC against their environment at frequent intervals, generate the output, and compare it with the output from the last extract to see if anything has changed. Using side-by-side comparison tools allows organizations to easily audit what changes have happened to an environment over a given period of time.
Several other scenarios, such as using the output DSC configuration script to analyze an environment against best practices, have also been considered. Currently there are no formal plans to embed such logic into the Orchestrator Scripts.
We are thrilled to see all the excitement from the community around the concept of ReverseDSC, and we encourage you to get involved in the projects by contributing on GitHub. Please take the time to try out the various Orchestrator Scripts that are already being offered, and take the time to log issues and feature requests.
Next time, we will dive into the process of using ReverseDSC to help you migrate a SharePoint on-premises farm into Azure infrastructure-as-a-service.
Premier Field Engineer, SharePoint