Add support for reporting how a DSC Resource's state changed via the Set method

[michaeltlombardi]

As an operator and integrating vendor, I want to be able to rely on the DSC Resource to tell me not just that a resource has been set to the desired state but how by returning the list of properties and their prior and new states.

With the current implementation of DSC, after I call the Set method the only information I get back is a Boolean representation of whether the machine requires a reboot ($true) or not ($false). The only other information available to me is via the verbose and error streams.

In my experience as a vendor and operator in the configuration management space, a critical piece of information for auditing is not just when or that a resource was modified but also how. There is currently no defined way for a DSC Resource invoked with the Set method to report which properties were changed from what state to what state in a straightforwardly retrievable way.

This information is valuable both at the high-level/aggregate view (so patterns can be inspected and long-term reporting performed) and when an operator is interactively managing state (removing the need to call the Get method before and after Set to inspect state).

Vendor Context

When I wrote the puppet.dsc module and the Puppet-side integration for DSC, I had to retrieve the current state, compare it to the user's desired state, and then use those values in my reporting instead of relying on DSC itself. This was somewhat fragile as direct comparisons are not always possible and I had no sensible way to programmatically retrieve that information across thousands of differently implemented DSC Resources.

Proposal

For the sake of backwards-compatibility, I propose adding an optional switch parameter to return more detailed information when calling Invoke-DscResource with the Set method. Possible names for this parameter include Detailed and WithChangeReport.

However, as not all configuration items for a DSC Resource may be straightforwardly comparable to input values (e.g. when specifying the valid version range for a package), I further propose that this implementation use a new method in the class for a DSC Resource. For the sake of example, I'll refer to that method as SetDetailed from now on.

The SetDetailed method should perform the set operation and construct a hash table for the return (or, even better, return an instance of class defined for this purpose)

Example Return Objects

Enforced State

@{
  EnforcedDesiredState = $true
  EnforcedProperties = @{
    Foo = @{
      From = 'Bar'
      To   = 'Baz'
    }
  }
}

Already in Desired State

@{ EnforcedDesiredState = $false }

Failed to Enforce State

@{
  EnforcedDesiredState = $false
  Error = [ErrorRecord]
}

Alternative

As DSC v3 is already a strongly breaking change from prior versions and many resources will need to be rewritten, expect detailed information by default and fall back on the current return object if required.

[theJasonHelmick]

I always thought of this as something the Get should return, as you state, before and after Set. I see your point, but i'm struggling with the verb.

[michaeltlombardi]

That pattern is relatively common, calling Get -> Test -> Set -> Get to determine current state, whether current state matches desired state, enforce desired state, and retrieve new state. That still requires the higher order tool to attempt to diff the pre-and-post values, which is usually okay, if a little heavy on processing, especially across programming languages.

One thing that method can't tell you is the behavior of any write-only values (a change in the secret token used by the configured service, for example) or why a change was made (for example, upgrading a package because a newer version in the valid range exists now). That information is only available from inside the DSC Resource.

While this proposal focused on the utility of reporting the From and To information with the result, other metadata about the change can only be reported this way or by repurposing the [DSCProperty(ReadOnly)] attribute to turn a class property into a metadata reporter.