Copy loop iteration

[Gijsreyn]

Summary of the new feature / enhancement

As a user, I would expect you to be able to use the copy operation with a counter in the resource configuration document. This allows me to either drive resource configurations through the --parameters-file parameter or --path when doing an operation.

What I would expect is the following:

# test.parameters.yaml
parameters:
  applications:
      - name: PowerShell
        id: 'Microsoft.PowerShell.Preview'

# test.config.yaml
$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json
parameters:
  applications:
    type: object
resources:
  - name: Use class PowerShell resources
    type: Microsoft.DSC/PowerShell

    properties:
      copy:
        resources:
          - name: PowerShell 7 Preview
            type: Microsoft.WinGet.DSC/WinGetPackage
            properties:
              Id: "[parameters('applications.name').id]"
              Ensure: "Absent"

Other scenarios I'm thinking of, are the famously known DTAP street with configuration for Computer Management.

Imagine you want to add users/groups to the relevant groups like Adminstrator, or Remote Desktop Users. Organizations can follow naming conventions as `<groupname..', helping drive configurations from parameter files.

You will in turn get something like:

# dev.group.parameters.yaml
parameters:
 groups:
      - name: Admin Group
        groupName: 'Administrators'
        members: ['testuser1', 'testuser2']
      - name: 'Remote Users'
        # truncated

# group.config.yaml
$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json
parameters:
  groups:
    type: object

resources:
  - name: Use class PowerShell resources
    type: Microsoft.DSC/PowerShell
    properties:
      copy:
        resources:
          - name: PowerShell 7 Preview
            type: PSDscResources/GroupSet
            properties:
              GroupName "[parameters('name').groupName]"
              Members "[parameters('name').members]"
              Ensure: "Present"

It's a bit short, but if you want to expand on the idea, just give me a headsup.

You would then be able to call it with the command line as such:

dsc.exe config -f <environmentName>.groups.parameters.yaml set -p groups.config.yaml

Proposed technical implementation details (optional)

No response

[SteveL-MSFT]

If I understand what you're trying to do, you want to use a resource that takes a single value and be able to specify an array so that single resource gets used for each element in the array? Basically like a pipeline?

[Gijsreyn]

If I understand what you're trying to do, you want to use a resource that takes a single value and be able to specify an array so that single resource gets used for each element in the array? Basically like a pipeline?

Exactly, the copying part is the key here.

[michaeltlombardi]

I think this could potentially be solved with a group resource, rather than a configuration document engine feature. Something like...

$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json
resources:
  - name: Use class PowerShell resources
    type: Microsoft.DSC/PowerShell
    properties:
      resoureces:
      - name: Create several groups 
        type: MyPsDscResources/Multiple:
        properties:
          ResourceType: PSDscResources/Group
          SharedDefaultProperties:
            Ensure: Present
          InstanceProperties:
          - GroupName: Group1
            Members: User1, User2
          - GroupName: Group2
            Members: User1, User3, User4

To use a group like this with adapted resources, you would want an adapted group - otherwise you would end up generating multiple instances of the PowerShell adapter and incur that extra overhead.

But it could work similarly for non-adapted resources:

$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json
resources:
- name: Manage registry keys
  type: Microsoft.Dsc/MultiInstance:
  properties:
    type: Microsoft.Windows/Registry
    sharedDefaultProperties:
      _exist: true
      keyPath: HKCU\DSC\Test
    instanceProperties:
    - valueName: Foo
    - valueName: Bar
    - valueName: Baz
      valueData: { String: 'hello world' }
    - keyPath: HKCU\DSC\Test\OverrideDefault

[SteveL-MSFT]

The concept makes sense to me and the example from @michaeltlombardi makes sense to me to use a new Group resource. I don't think MultiInstance really describes the usage, maybe Microsoft.DSC/ForEach? Some naming suggestions:

$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json
resources:
- name: Manage registry keys
  type: Microsoft.Dsc/ForEach
  properties:
    type: Microsoft.Windows/Registry
    propertyDefaults:
      _exist: true
      keyPath: HKCU\DSC\Test
    instanceProperties:
    - valueName: Foo
    - valueName: Bar
    - valueName: Baz
      valueData: { String: 'hello world' }
    - keyPath: HKCU\DSC\Test\OverrideDefault

[Gijsreyn]

I get both the points and I definitely agree on the part that there shouldn't be too much overhead. If it solves the goal that the configuration document in itself can be dynamically filled and if it requires looping through the parameter keys to determine how many resources are required to be executed, I would be happy.

If you want me to explain it in more detail in DSC v2 concepts, I have a practical use case of what we've tried to achieve there.

@SteveL-MSFT , Microsoft.DSC/Foreach sounds good to me if it fits in the picture of ARM functionality, meaning if it cannot be solved from ARM functionality that's being built.

[SteveL-MSFT]

@Gijsreyn ForEach would probably fit more with Bicep that would generate ARM and eventually we'd like to explore a Bicep extension to output DSC configuration. However, I don't think it would be much effort to create this resource, so I might give it a shot between other work items.

[SteveL-MSFT]

Looking into ARM, I see I missed one important detail which is ARM currently supports the idea of copy which was the original request. So if we want to align with ARM, then we would use their syntax rather than invent something new (although the two aren't mutually exclusive). Looking at the ARM example for copy, it doesn't look very user friendly at all...

[Gijsreyn]

Looking into ARM, I see I missed one important detail which is ARM currently supports the idea of copy which was the original request. So if we want to align with ARM, then we would use their syntax rather than invent something new (although the two aren't mutually exclusive). Looking at the ARM example for copy, it doesn't look very user friendly at all...

I fully agree and it might be confusing on the naming when ForEach is used. Something to look into ...