PowerShell / PowerShell/DSC

Support enhanced export with `dsc config export`

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

Nobody has claimed this yet.

Issue-Enhancement Need-Review
Dominant language
Rust
Stars
523
Forks
75
Avg merge
3d 16h
Merged PRs (30d)
24

Description

Summary of the new feature / enhancement

As an operator generating an exportable configuration from an existing system, I want more control over the generation for my exported configuration document. I want to be able to specify whether specific instances should be passed through to the generated document, even if they don't exist on the current system, are in the incorrect state, or are instances of non-exportable resources.

For example, a user might want to generate a configuration that:

  • Creates a file instance using the existing contents of a file, even thought the Microsoft/File resource isn't exportable.
  • Defines a set of registry keys, even though they don't exist on the current system.
  • Retrieves and enumerates every instance of the Microsoft.IIS/WebServer resource in the output document.

Currently, only the last use case is supported.

Proposed technical implementation details (optional)

Add an export keyword to the resource instance schema that takes an enumeration:

  • passthru (default for non-exportable resources) - indicates that the instance will be added to the output document exactly as it's defined in the input document.
  • current - indicates that the instance will be added to the output document using its full current state. In this case, the required properties for the instance are used to get the current state of the instance instead of being ignored.
  • all (default for exportable resources) - indicates that the any defined properties for the instance will be ignored and every instance of the resource should be exported to the output document.

This would better support generative configuration with less work for the end user. This would also enable reliable deterministic behavior for including any instances in the input document, instead of throwing an error for resources that don't support the export operation.

For non-export operations, the keyword should be ignored.

[!NOTE]
An optional future extension to this model could be supporting the export value as an object that has the kind and properties keywords, where kind maps to the enums above and properties is an array of properties to keep for the output document. I bring this up to write it down somewhere, not to include it in the initial scope for this feature.

Alternative implementation: group resources

Instead of extending the keywords for the configuration, the same functionality could be accomplished by one or more group resources:

  • A single DSC/Export group resource with properties for each kind of export: passthru, current, and all. Possible later support for filtered.
  • A collection of DSC.Export/* resources, like DSC.Export/PassThru, one per kind of export.

This implementation might be a good alternative that modularizes the implementation and functionality for exporting away from core DSC, so it can use its own release cadence and be modified without affecting the versioning of DSC itself. I'm not sure whether this ends up being more work to maintain or roughly equivalent, but it does seem like it might be more resilient. I think there could be tradeoffs for UX here, but I haven't considered them deeply.

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 at the dsc config export command and read docs/reference/schemas/config/resource.md, then trace how resource instances are currently handled during export. Compare the proposed passthru, current, and all behaviors with the existing implementation and decide between the keyword and group-resource approaches; done means the selected behavior works for export while non-export operations ignore it.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
cli, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.