Simplify implementing DSC group and adapter resources
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 523
- Forks
- 75
- Avg merge
- 3d 16h
- Merged PRs (30d)
- 24
Description
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:
- 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.
- Has to return the desired state, actual state, and differing properties for every nested instance during
testoperations. 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. - Has to return the before state, after state, and changed properties for every nested instance during
setoperations. 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:
- Returning the actual state of nested instances from a
getoperation as JSONLINEs. - If the resource implements
test, it must return the actual state of nested instances with the_inDesiredStateproperty set totrueorfalseas a JSONLINE. If the resource defines the return kind asstateAndDiff, it must also return the array of differing properties. Otherwise, DSC calculates the differing properties. - If the resource doesn't implement
test, DSC should perform synthetic testing for its nested resources.[^1] - If the resource implements
set, it must return the after state of nested instances as JSONLINEs. If the resource defines the return kind asstateAndDiff, 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.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reading the linked DSC get, test, and set output schemas, then trace how group and provider resources currently handle nested resource results. Compare that flow with the proposed JSONL behavior and deterministic ordering. Done means nested get, test, and set outputs follow the standard resource contract while DSC handles synthetic testing and differing or changed properties where specified.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- devops
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 28/100