New adapter interface for resource invocation

[SteveL-MSFT]

Summary of the new feature / enhancement

The current adapter model currently expects adapters to implement the equivalent of dsc config ... where the original motivation was to only create a single hosting process that all the nested resources would execute within. However, there have been several problems from this:

• implicit use of adapted resources requires the engine to generate a nested config at runtime to pass to the adapter and this incurs another discovery (there's no clean way to resolve this since the nested one is deep in the runtime stack)
• users are more likely to use adapted resources implicitly than wrap them
• adapters need to understand and implement config level features

Proposed technical implementation details (optional)

We add a new resource adapter model that can be identified in the resource manifest as:

{
  "kind": "resourceAdapter"
}

This would require these kind of adapters to perform the equivalent as dsc resource .... Benefits:

• no extra discovery perf penalty when used implicilty
• process isolation is better for security and reliability reasons
• simpler for adapters to implement
• engine can resolve all expressions and pass context to this adapter which can pass to resources

[michaeltlombardi]

Related:

• Simplify implementing DSC group and adapter resources #267
• Passing params/references to groups/adapters #381
• Define model for handling configuration expressions for non-recursive DSC group and adapter resources #730
• differingProperties always propagated on adapter resource #849

Ideally, I would want to be able to both individually invoke a single resource with an adapter and handle n instances without being responsible for any configuration expressions or munging output as much as possible.

Does it make sense to support two different kinds of adapters, or can we find a way to extend/rework the current (data/manifest) model to support this?

Alternative ideas:

• Add the invoke field under adapter, which indicates direct invocation (with sub-properties for the operation commands) where the top-level fields are for the grouped form.
• As above, but make the top-level fields be for direct invocation of adapted resources and the nested fields be for the group form.
• Add a field to adapter to clarify whether the resource supports single or group invocation.
• Add a new argument object to operation fields to support passing a conditional discriminator argument, like --group.

[SteveL-MSFT]

I originally wanted to encapsulate it within the adapter kind, but I think it would actually make it more confusing since it has to default to current model which is why I went with an alternate kind instead. Multi is tricky without some look-ahead and then what if you have expressions that depend on previous execution first (like the output via reference()) via implied dependency order.

Adding invoke as a child means you'd still have get, set, test, and export under that. I think trying to incorporate resource and config adapters into one will make it complicated, because current model is the adapter receives the nested config as input that it processes. In the resource case, I imagine the args would be the resourceTypeName and resourceInput instead of a single JSON object.

[michaeltlombardi]

A few more design options worth considering might be:

1. To add a kind discriminator to adapter, like this:

   kind:
     title: Adapter kind
     description: >-
       Defines whether the adapter invokes resources as a group or individually.
     type: string
     enum:
       - resource
       - group
     default: group # For compatibility with existing adapters

   Where when kind is group we ignore (or forbid) the config field. Under this model, we would still expect the adapter to receive the instance struct (type, properties, etc), with resolved functions when kind is resource. The resource otherwise behaves as a group resource, except it only supports implicitly adapted instances.

2. To add a new capability for resources that support group operations, like groupedInstances - this could be more broadly useful for resources that need to support being invoked for multiple instances for performance reasons, not just adapters. We could add a group field at the top-level for grouped operations.

   We could require any non-group resource to support the same operations for groups as individual resources. This makes grouped handling opt-in for any resource. We would still need to resolve the expression/dependency problem in this case (rather than have the resource author hand-implement the handling). I'm not sure what that looks like yet, but it's a problem we eventually need to solve for non-recursive group resources anyway.

   This would probably apply well to the PSResourceGet resources where we're needing to have two manifests for grouped/ungrouped instance declarations.

   A resource supporting this model would have a JSON Schema that looks something like:

   type: object
   oneOf:
   - $ref: https://aka.ms/dsc/schemas/v3/resource/properties/group.json
   - properties:
       path:
         type: string
       _exist:
        $ref: https://aka.ms/dsc/schemas/v3/resource/properties/exist.json

   Where the referenced subschema specifies that the instance defines the resources property as an array of resource instances and so on.

3. If we're going to create the resourceAdapter kind, we should consider renaming adapter to groupAdapter. In the eventual resource authoring guide, we can direct resource authors to choose whether they want to support one model or both and give recommendations for naming and so on.