PowerShell / PowerShell/DSC

Simplify implementing DSC group and adapter resources

Open
#267 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Issue-Enhancement WG-Reviewed
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:

  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.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.