DSC icon indicating copy to clipboard operation
DSC copied to clipboard

Simplify implementing DSC Group and Provider Resources

Open michaeltlombardi opened this issue 8 months ago • 0 comments

Summary of the new feature / enhancement

As a DSC Resource author, I want to be able to implement group and provider resources as simply and maintainably as possible.

Currently, implementing a group or provider resource requires an author to emit the same data structure to DSC that DSC automatically generates from the returned instance data for normal resources. The group/provider resource is responsible for returning get, test, and set output objects.

This means that the group/provider resource:

  1. Has to collect the result for every nested instance, then emit them together at the end. The resource can't stream the results back to DSC as JSONLINEs.
  2. Has to return the desired state, actual state, and differing properties for every nested instance during test operations. It can't hand off that processing to DSC. This means that the resource is responsible for handling synthetic testing and generating the list of differing properties itself.
  3. Has to return the before state, after state, and changed properties for every nested instance during set operations. It can't hand off that processing to DSC. This means that the resource is responsible for calculating the changed property list and any other necessary munging.

Proposed technical implementation details (optional)

Instead, group and provider resources should be responsible for:

  1. Returning the actual state of nested instances from a get operation as JSONLINEs.
  2. If the resource implements test, it must return the actual state of nested instances with the _inDesiredState property set to true or false as a JSONLINE. If the resource defines the return kind as stateAndDiff, it must also return the array of differing properties. Otherwise, DSC calculates the differing properties.
  3. If the resource doesn't implement test, DSC should perform synthetic testing for its nested resources.[^1]
  4. If the resource implements set, it must return the after state of nested instances as JSONLINEs. If the resource defines the return kind as stateAndDiff, it must also return the array of changed properties. Otherwise, DSC calculates the changed properties.

In short, group and provider resources should functionally pass the individual resource outputs back to DSC, like any other resource. They need to do so in a deterministic order so that DSC can associate the return data to the correct nested instance in the configuration.

This would greatly simplify and clarify the contract for implementing group and provider resources. It would also ensure that the shape of the output results adheres to the schema DSC defines, instead of drifting depending on how up-to-date the group or provider resource implementation is.

[^1]: An edge case is when the provider or group needs to support both synthetic testing and per-resource testing. I think in this case, it's okay to require the resource to implement its own synthetic testing. Alternatively, it could return an empty JSON object to indicate that the nested instance should be synthetically tested by DSC.

michaeltlombardi avatar Nov 09 '23 20:11 michaeltlombardi