powershell / dsc Goto Github PK

This repo is for the DSC v3 project

License: MIT License

Rust 69.72% PowerShell 29.83% JavaScript 0.24% Shell 0.21%

dsc's Introduction

DSCv3

Note

This repo isn't accepting code contributions. It's public and open source to show progress and enable feedback. Once we're at a feature complete state, we can start taking code contributions.

What's DSCv3?

DSCv3 is the latest iteration of Microsoft's Desired State Configuration platform. DSCv3 is an open source command line application that abstracts the management of software components declaratively and idempotently. DSCv3 runs on Linux, macOS, and Windows without any external dependencies.

With DSCv3, you can:

Author resources to manage your systems in any language
Invoke individual resources
Create configuration documents that define the desired state of a system

Differences from PowerShell DSC

This project is the next generation of DSC and leverages the PSDesiredStateConfiguration module to maintain compatibility with existing PowerShell based resources.

DSCv3 differs from PowerShell DSC in a few important ways:

DSCv3 doesn't depend on PowerShell. You can use DSCv3 without PowerShell installed and manage resources written in bash, python, C#, Go, or any other language.
DSCv3 doesn't include a local configuration manager. DSCv3 is invoked as a command. It doesn't run as a service.
Non-PowerShell resources define their schemas with JSON files, not MOF files.
Configuration documents are defined in JSON or YAML files, not PowerShell script files.

Importantly, while DSCv3 represents a major change to the DSC platform, DSCv3 is able to invoke PowerShell DSC Resources, including script-based and class-based DSC Resources, as they exist today. The configuration documents aren't compatible, but all published PowerShell DSC Resources are. You can use PowerShell DSC resources in DSCv3 with both Windows PowerShell and PowerShell.

Installing DSCv3

To install DSC v3:

Download the latest release from this repository.
Expand the release archive.
Add the folder containing the expanded archive contents to the PATH.

Explore DSCv3

If you're new to DSC or configuration management, we recommend reviewing the documentation.

Learning and authoring tutorials

If you're already familiar with DSC or just want to start experimenting with v3, we recommend reviewing the Samples repository and the accompanying tutorial site. The Samples repo is ready to accept Pull Requests, which is a great way to contribute while v3 is in early phases of development.

Integrating with DSCv3

DSCv3 is a platform tool that abstracts the concerns for defining and invoking resources. Higher order tools, like Azure Machine Configuration, Azure Automanaged VM, and WinGet are early partners for DSCv3 as orchestration agents.

DSCv3 uses JSON schemas to define the structure of resources, configuration documents, and the outputs that DSCv3 returns. These schemas make it easier to integrate DSCv3 with other tools, because they standardize and document how to interface with DSCv3.

dsc's People

Contributors

Stargazers

Watchers

Forkers

michaeltlombardi tgauth stevel-msft anmenaga panjkov miroman9364 daxian-dbw mgreenegit computedocean jcza sciencebeyondtime dh-orko brwilkinson rockyshek

dsc's Issues

Make schema URL required

Summary of the new feature / enhancement

Needed for intellisense, but the static schema (embedded or via command) is needed during deployment, so we need to separate it in the resource manifest

Proposed technical implementation details (optional)

No response

Make merge to main upload the build(s) as artifacts

Summary of the new feature / enhancement

As an engineer interested in experimenting with dsc locally, I want to be able to download the latest build for the project instead of needing to setup my local development environment for Rust and this project.

Proposed technical implementation details (optional)

The Rust workflow already builds and tests the code for multiple platforms. With the actions/upload-artifact GitHub Action, the same workflow could also save the built binaries so that interested parties could download archives containing the artifacts.

We could document how to retrieve the artifacts from GitHub until we have a more reliable and friendly way to let people experiment with the applications.

Need a way to extract DSC resource schema for IntelliSense scenario

Prerequisites

Write a descriptive title.
Make sure you are able to repro it on the latest version
Search the existing issues.

Steps to reproduce

For configuration example below, there should be a way to call dsc.exe to request schema for types PowerShellGet/MSFT_PSRepository and TestFileDscResource/FileResource (that are handled by DSC/PowerShellGroup resource provider) to be used in IntelliSense when authoring configurations with these types.

- name: Get info from classic DSC resources
  type: DSC/PowerShellGroup
  properties:
    resources:
    - name: Get PS Repository Info
      type: PowerShellGet/MSFT_PSRepository
      properties:
        Name: PSGallery
    - name: Check File
      type: TestFileDscResource/FileResource
      properties:
        Path: C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe
        Ensure: Present

Expected behavior

`dsc.exe` should be able to return schema for resources that are processed by resource providers.

Actual behavior

Currently this is not implemented.

Error details

No response

Environment data

v1.

Version

Visuals

No response

Reccommend replacing `jsonschema` crate with `boon` for improved JSON Schema support

Summary of the new feature / enhancement

The DSC libraries and tools implemented in rust currently use the jsonschema v0.17.0 crate for their JSON Schema handling. However, this implementation only fully supports JSON Schema drafts 4-7. Support for 2019-09 and 2020-12 is only partial and requires enabling a feature. Further, according to the official test suite maintained and published in collaboration with the JSON Schema team and community, jsonschema currently has six errors and 17 invalid results from the test cases.

By contrast, the boon v0.5.0 crate has full support for JSON Schema drafts 4-7, as well as 2019-09 and 2020-12. That version successfully passes every test case for the supported dialects.

Migrating from the jsonschema crate to boon would make the JSON Schema validation and integration more reliable and enable us to fully use draft 2020-12 JSON Schemas, which have several authoring improvements over prior drafts and are much easier to extend. Further, boon has support for custom assertions of formats, content media types, and content encoding, all of which would be useful for DSC:

https://github.com/santhosh-tekuri/boon/blob/d466730e5e5c7c663bd6739e74e39d1e2f7baae4/tests/examples.rs#L64-L92

That being said, it looks like the schemars v0.8.12 crate doesn't support 2020-12 yet, though it does support 2019-09. The largest differences between JSON Schema draft 2019-09 and 2020-12 are:

2020-12 replaces items/additionalItems with prefixItems/items - this applies mostly to how you represent tuples - when items is an object instead of an array, the behavior is consistent for both dialects.
2020-12 replaces $recursiveRef/$recursiveAnchor with $dynamicRef/$dynamicAnchor - neither of which we seem to use in our current schemas, but which has a large impact on defining custom vocabularies, which we may find desirable in the future.
2020-12 updates the interactive behavior for the contains and unevaluatedItems keywords, but we don't use contains.

For our purposes, that means that exporting our schemas in the 2019-09 dialect will have no noticeable impact vs 2020-12.

Proposed technical implementation details (optional)

Migrate dependency/usage in the rust code for the various projects from jsonschema v0.17.0 to boon v0.5.0.

After migration: consider exporting schemas in the draft 2019-09 dialect instead of the draft 7 dialect.

Model Impact of `set` for a resource

Summary of the new feature / enhancement

Applying set is an impactful operation, however, we may want a way to standardize how to advertise this beyond documentation (similar to PowerShell's ConfirmImpact).

Updating firmware may automatically reset the device (like a router would disconnect all clients) or setting sshd config would restart the service.

This is probably most useful for WhatIf (#70) to understand what can happen when applying configuration across multiple resources.

Proposed technical implementation details (optional)

No response

Registry meta-resource

Summary of the new feature / enhancement

There may be a large set of applications on Windows that store their configuration in the registry. It may make sense to have the registry resource accept a file that maps registry locations to a resource definition.

Proposed technical implementation details (optional)

For example, PS7 uses two registry values to control Microsoft Update:

HKLM\Software\Microsoft\PowerShellCore\UseMU = 1
HKLM\Software\Microsoft\PowerShellCore\InstalledVersions\39243d76-adaf-42b1-94fb-16ecf83237c8\Install = 1

The first enables updating via MU and the second installs if not installed (update doesn't do anything if not installed).

The registry resource could have parameters like registry -resourceFile ps7.json which contains:

{
  "name": "PowerShellMicrosoftUpdate",
  "version": "1.0.0",
  "properties": {
    "automaticUpdates": {
        "key": "HKLM\Software\Microsoft\PowerShellCore",
        "name": "UseMU",
        "valueType": "DWORD",
        "values": [ 0, 1 ]
    },
    "automaticInstall": {
        "key": "HKLM\Software\Microsoft\PowerShellCore\InstalledVersions\39243d76-adaf-42b1-94fb-16ecf83237c8",
        "name": "Install",
        "valueType": "DWORD",
        "values": [ 0, 1 ]
    }
  }
}

This is hypothetical and the values property needs to be thought out on how to properly support this. Also, for the registry resource to synthesize a DSC resource, it would need to generate JSON schema or implement the validate subcommand and perform its own validation against the incoming JSON (this seems more feasible).

Each synthetic resource would need it's own resource manifest that uses the registry resource.
In this example, imagine a microsoft.powershell.microsoftupdate.dsc.json file in a location either the registry resource
is aware of or in the same location as registry.exe:

{
  "manifestVersion": "1.0",
  "type": "Microsoft.PowerShell/MicrosoftUpdate",
  "version": "0.1.0",
  "get": {
    "executable": "registry",
    "args": [
      "get",
      "--resourceFile",
      "microsoft.powershell.microsoftupdate.json"
    ],
    "input": "stdin"
  },
  "set": {
    "executable": "registry",
    "args": [
      "set",
      "--resourceFile",
      "microsoft.powershell.microsoftupdate.json"
    ],
    "input": "stdin"
  },
  "test": {
    "executable": "registry",
    "args": [
      "test",
      "--resourceFile",
      "microsoft.powershell.microsoftupdate.json"
    ],
    "input": "stdin"
  },
  "validate": {
    "executable": "registry",
    "args": [
      "validate",
      "--resourceFile",
      "microsoft.powershell.microsoftupdate.json"
    ],
    "input": "stdin"
  },
  "exitCodes": {
    "0": "Success",
    "1": "Invalid parameter",
    "2": "Invalid input",
    "3": "Registry error",
    "4": "JSON serialization failed"
  }
}

Implement `dsc` as a resource for assertion and groups

Summary of the new feature / enhancement

Enable configuration-and-resource schema to return json schema for the config fragment and specified resources

Proposed technical implementation details (optional)

No response

Handle resources that require restarts

Summary of the new feature / enhancement

Some changes to the system may require a reboot before additional changes can be applied. dsc itself shouldn't perform a reboot, but we may need a standardized way for resources to return that a reboot is required like _rebootRequested: true and then dsc just reports that as a standard result. Then something else performs the reboot when ready and re-runs the config until it completes or hits another reboot.

Proposed technical implementation details (optional)

No response

Implement expression functions

Summary of the new feature / enhancement

ARM has a specific set of functions that can be used within a configuration: https://learn.microsoft.com/en-us/azure/azure-resource-manager/templates/template-functions

Proposed technical implementation details (optional)

Array

CIDR

These aren't relevant to DSC

Comparison

Date

dateTimeAdd
dateTimeFromEpoch
dateTimeToEpoch
utcNow

Deployment

deployment?
environment*
parameters*
variables*

Logical

Numeric

Object

Resource

Subset needed for DSC

reference*
references
resourceId

Scope

Not applicable to DSC

String

Why is this DSCv3 or even PowerShell? (and other points)

Summary of the new feature / enhancement

I'm not trying to be the party pooper, but having no context, I think this could do with some clarifications.
Also, the name is not helping, it adds to the confusion and probably should be changed ASAP (before Microsoft teams create their own semantic that is unteachable or too far away from existing practices and tools once released).
I'm raising this as an issue (for lack of discussions) as it's not directly related to the PRs.
Feel free to enable discussions and move it there, I can create relevant issues as needed after an initial back and forth. I'll review the PRs separately, once I understand the purpose "enough".

1. Naming issue and missing context

It may seem too early to "care about trivial things such as name", but I think we need to be careful with the whole semantic here, and start being precise.

DSC is already a loaded term (and DSCv3 already refers to PSDSCv3), and the current reasoning transpiring from what I've read so far is yet another take on the good old Configuration Management paradigms...
Moreover, assuming I understand the thinking thus far, this would sit above PowerShell, so it's more of a meta-resource enacter, so let me try to define what I read is the intention, and please correct me…

Note:
configuration already refers to the PSDSC keyword
config is already used as a utility on Unix-like OSes.

Proposed technical implementation details (optional)

2. What is this repo about?

Create a utility (later refered as "the tool", think CLI to start with) built to:
1. Enact: Converge towards a state defined as a policy regardless of the current state (aka "Make it so" from declarative document).
1. Apply: Set more or less bluntly (relying on the resource) without validating state.
1. Validate: Test whether the current state is compliant with what's desired.
1. Query: Gather the current state of a configuration item, uniquely referenced for a given scope (to be defined later)

3. Why do we need this?

The WinGet folks were asked to "define a state of installed stuff and converge", and PowerShell has experience with DSC so we thought that could be the sponsor we needed to combine efforts [please correct me].

4. Who is asking for it?

Which team currently needs it and is potentially sponsoring/requesting?
WinGet/Internal to PS team?

5. What's the work item priority/agenda/ETA?

Executing against the current plan and hoping to have something to show publicly by Build, in May.

6. The runtime(s)

As the need for this tool is shared through different ecosystems (WinGet for machines, PowerShell, Python, binaries), the CLI tool should be runtime agnostic (standalone), and only call specific runtime implementations when asked to.
Those runtimes are plug-ins sharing the same interface, enabling support for resources written in their ecosystem/language.
We can imagine having a runtime for Python modules, PowerShell DSC Resources, binary tools like CLI commands, Puppet modules, bicep module and so on.
The current plan is limited to make WinGet and PowerShell DSC resources work from the same CLI tool.

7. The Resources: Contract for Config Items

A resource is a contract representing:
- How to uniquely address a configuration item for a given system.
- The different properties defining the state of a configuration item.
- The properties required to set a configuration item (i.e. write only such as Force: true).
- What to execute to apply/validate/query (actions or methods of the resource).

To allow for idempotent enactment, the resource must define the Apply/Validate/Query actions.
Instances of a resource (whether desired instances or current instances), can be uniquely addressed for a given system (target), while having different configuration item values.
Said differently, only one current resource instance exists for a given address (key) on a given system, and we can compare it with a desired resource instance with the same key.

8. Runtime Abstraction

The tool should be designed to work with any type of resource regardless of their runtime. For this, we need to create a common interface, that can be implemented in each runtime that needs to be supported.

This means it has a plug-in model to support different resource runtime, where plug-ins can be registered with the tool.
The focus would start with a CLI resource runtime plug-in, a PowerShell DSC Resource runtime plug-in… [please complete the initial plans].

Each runtime should be able to evolve at their own pace, and released independently (but default runtimes packaged with the tool).

9. De/Serialisation

Being language agnostic means only typeless/generic structured data can be transmitted between runtime and the tool, using a common format accessible to all: JSON.
Live objects cannot be passed accross, and for this reason the runtime implementation will have more value when integrated in other tools targeted to this language.
As an example, a DSC Resource may offer more (extra method, casting to another type...) when invoked through PowerShell than through this tool.

Enable view of rendered YAML to include JSON schema

Summary of the new feature / enhancement

To help users understand the resulting YAML better (without going to webpage or man page), we could take descriptions of JSON members from the JSON schema and put those as comments into the YAML.

Proposed technical implementation details (optional)

May make sense to have a switch to suppress assuming most people want to see it to explain what properties do but there could be lots of description being emitted.

Enable returning JSON schema for script function mof

Summary of the new feature / enhancement

dsc resource schema -r <psresource> returns JSON schema where is a script resource

Proposed technical implementation details (optional)

No response

Implement Parameters support

Summary of the new feature / enhancement

Enable passing parameters to a config via dsc. This simply might be a -parameters parameter that accepts JSON.

Proposed technical implementation details (optional)

No response

Implement `dependsOn` processing for config

Summary of the new feature / enhancement

Build execution graph for a config

Proposed technical implementation details (optional)

No response

DSC Registry Proposal

Summary of the new feature / enhancement

Working through the documentation and on the schemas, and considering the end-to-end workflow for developers, users, and integrating tools, I've been thinking about how we can make a DSC Resource manifest a useful source of truth/canonical contract.

One problem we have with the introduction of command-based DSC Resources is for how an entity can discover DSC Resources and pull them for use. We can't rely on a single generic mechanism, because the idiomatic publishing for command-based DSC Resources varies widely depending on the implementation language and supported operating systems.

I think the discover and pull operations can be bifurcated and that the discovery operation can be solved generically. In this proposed model, DSC Resource manifests are published to a registry, while DSC Resources (and/or their modules) are published to a repository, possibly multiple repositories.

Entities can discover available DSC Resources from a particular registry and retrieve their manifest independently of pulling the actual DSC Resource from its defined repository. In this model, the manifest is published to the registry independently. This proposal doesn't extend to enumerating the implementation of repository handling.

With a registry, developers and users could also publish DSC Configuration Documents as reusable artifacts, similar to how PSResourceGet users can publish and fetch scripts and modules independently.

This would make for a standardized way for entities to advertise and discover their reusable DSC Resources and Configuration Documents. Having a standardized model will also make it easier for organizations to manage their own mirrors and private registries.

Proposed technical implementation details (optional)

A DSC Resource registry could be implemented with ORAS or any other standardized package format. For this proposal, I'll use ORAS.

We would define a DSC Resource manifest as a unique artifact type and publish DSC Resources to an OCI Registry as that artifact, ideally with a dsc subcommand, like:

dsc registry publish resource ./foo.resource.json

Which would inspect the manifest and compose an ORAS push (with the Rust client, not the CLI) like:

oras push <RegistryURI>/<Type from manifest>:<Version from manifest> `
  --artifact-type application/vnd.microsoft.dsc.resource `
  foo.resource.json:text/json

DSC could handle adding any necessary annotations to the ORAS manifest, or dynamically adding the DSC Resource's instance schema as a separately-retrievable artifact to the manifest, etc.

In the same way, we would define a DSC Configuration Document as a unique artifact type to enable pushing and pulling those artifacts. While we haven't fully defined a model for DSC Resource modules that contain several resources with one source command (or in the case of DSC Resources implemented in an interpreted language, like Ruby, Python, and PowerShell, a gem or module), we could define a unique artifact type for DSC Resource Modules and publish them with their DSC Resources.

ORAS functionality is available in ACR in all public regions, though it's currently in preview.

Out of scope for this proposal, but technically possible, is actually using ORAS to simultaneously publish a DSC Resource manifest with the command it requires. For command-based DSC Resources, this would obviate the requirement for publishing to separate package repositories, like apt and winget. For PowerShell DSC Resources, which are always implemented in a PowerShell module, the module could be included as a layer artifact.

PowerShell resource

Summary of the new feature / enhancement

Instead of building PS resource support directly into dsc, perhaps we should have a powershellgroup resource which knows how to find and invoke PS based resources. Benefits:

can evolve independently of dsc
more natural to have it have a property to specify 5.1 vs 7 (default) as it's part of the schema rather than a meta-property
as a group based resource, it controls the lifetime of pwsh or powershell reusing it for the entire group. this also allows users who want process isolation to have multiple instances of this resource
create a pattern that may be useful for python, ruby, etc... in the future of having a long running instance rather than a new process for each one

Additional work in dsc to support this:

need a way for a resource to register in their json manifest that it's a "resource provider" so that dsc resource list knows to call it and add it's resources to the output, but the schema would change to indicate that resource needs to be used within a powershellgroup.

Proposed technical implementation details (optional)

No response

Invoke PowerShell Resources

Summary of the new feature / enhancement

Enable configuration using PS resource including validation

Proposed technical implementation details (optional)

No response

Need a way to support `export` scenario

Summary of the new feature / enhancement

Users want to manually configure an application/workload and get all the relevant configuration out and apply it to many other instances. Currently, get uses the supplied config as a filter. Also some resources like registry and file wouldn't make sense to enumerate the whole registry or filesystem.

Proposed technical implementation details (optional)

Propose an optional export method in addition to get, set, and test. dsc config export would ensure all the resources in the config support this method otherwise it fails.

Need a common way to declare a property is sensitive

Summary of the new feature / enhancement

There may be a need to pass sensitive information (like an api key) to a resource that may be retrieved from AKV, for example. DSC itself needs to know this is sensitive so it doesn't log it or emit to console and resources also need to know it's sensitive for the same reasons.

It could be as simple as a common prefix: _sensitive so resources can themselves decide if it's _sensitiveString, _sensitiveKey, etc...

Proposed technical implementation details (optional)

No response

Enable `ParallelGroup` resource

Summary of the new feature / enhancement

Enable -parallel switch for dsc

Proposed technical implementation details (optional)

No response

Should we use OpenAPI to describe resource's schema?

Summary of the new feature / enhancement

Should we use OpenAPI to describe a resource's schema? The advantages are:

Pervasive and widely understood
Lots of tooling available
Allows for different schema for different operations (Get, Set, Test can each have their own schema)
Allows for more than one resource type to be described by a single spec
Allows for documenting response codes

Cons:

Geared toward HTTP, so it requires things like paths that are not currently planned as part of DSC

Proposed technical implementation details (optional)

No response

`dsc resource list` for interactive display should be table

Summary of the new feature / enhancement

For interactive display, this should be a table showing type, requires and description

Proposed technical implementation details (optional)

No response

Implement RunAsGroup Resource

Summary of the new feature / enhancement

This GroupResource runs every resource within its config fragment under specified credentials. Need to determine if username/password is the right model and how it should be passed securely within the Config (via a variable?)

Proposed technical implementation details (optional)

No response

Enable progress reports during config execution

Summary of the new feature / enhancement

As resources get executed, need progress returned as JSON for agents to display. Consider how child processes can participate including resources.

Proposed technical implementation details (optional)

No response

Handle `WhatIf`

Summary of the new feature / enhancement

Need to have resources support this to work completely

Proposed technical implementation details (optional)

No response

VSCode extension for authoring configuration

Summary of the new feature / enhancement

Needs to call out to dsc.exe to get dynamic schemas at runtime to fulfill validation and intellisense

Proposed technical implementation details (optional)

No response

Enable direct invocation of PS resource

Summary of the new feature / enhancement

Enable dsc resource get -r <psresource> to invoke get, set, and test to a PS resource

Proposed technical implementation details (optional)

No response

Rename manifest extension to `.dscresource.json`

Summary of the new feature / enhancement

Currently, the manifest has the extension .resource.json, but this only makes sense for people using DSC. It's conceivable that this is too generic and used by other tooling. We should rename to .dscresource.json making it more specific and more self-describing.

Proposed technical implementation details (optional)

No response

Use long running PowerShell process

Summary of the new feature / enhancement

Use a single PowrShell process for all invocation and terminate the process when the config or resource call is complete

Proposed technical implementation details (optional)

No response

Enable way for resources and dsc.exe to provide verbose/debug information

Summary of the new feature / enhancement

Do we need both verbose and debug? Maybe start with just verbose.
Have a well defined JSONLINE schema for resources to output verbose information. Do we need to a way to turn on verbose for commands or just have it write it all the time and we throw it away if the user hasn't specified dsc --verbose?
What schema makes sense? Perhaps:

resourceType: <type name of the resource>
name: <friendly name if there are multiple instances of resources in config>
message: <open text>
timestamp: <filled in by dsc.exe>

It probably makes sense that resources only return the verbose message itself and dsc.exe fills in the rest. So an example JSON from a resource going to stderr could look like:

{
  "verbose": "this is my verbose message"
}

Implement InputKind Env

Summary of the new feature / enhancement

InputKind = Args is intended for simple cases like bash script resource where a flat JSON schema would result as name/value pairs sent as parameters and parameter values to the script:

{
  "property1": 1,
  "property2": "hello"
}

Would result in:

yourresource -property1 1 -property2 "hello"

Proposed technical implementation details (optional)

No response

Enable specifying WinPS5.1 to invoke a resource

Summary of the new feature / enhancement

Default to PS7 (if available), but allow invocation with 5.1 as a meta-property _powershell with allowed values 5.1 or 7

Proposed technical implementation details (optional)

No response

Fix Linux test failures for PSGroup resource

Prerequisites

Write a descriptive title.
Make sure you are able to repro it on the latest version
Search the existing issues.

Steps to reproduce

run CI, on Linux and Mac getting:
Error: Command: Resource 'DSC/PowerShellGroup' [Exit code 1] �[31;1mMethodInvocationException: �[31;1mException calling "LoadDefaultCimKeywords" with "2" argument(s): "Unable to load shared library 'libmi' or one of its dependencies.

Expected behavior

n/a

Actual behavior

n/a

Error details

n/a

Environment data

n/a

Version

n/a

Visuals

No response

Need a way to reference file paths relative to the config file

Summary of the new feature / enhancement

A winget configure scenario is that a git repo has a config.dsc.yaml which uses a resource that uses a file within the repo. Ask is to have a built-in variable similar to $PSScriptRoot like $DSCConfigRoot that contains the path to the config file.

Proposed technical implementation details (optional)

No response

`resource set` errors unexpectedly when `test` is undefined and `set.preTest` isn't explicitly `true` in resource manifest

Prerequisites

Write a descriptive title.
Make sure you are able to repro it on the latest version
Search the existing issues.

Steps to reproduce

When implementing a command-based DSC Resource without explicitly defining test, the dsc resource set command errors when the preTest key is undefined or is set to false in the resource manifest's set property.

dsc resource get and dsc resource test both work as expected.

I discovered this when working with the example implementations in #85.

This is the snippet of the resource manifest with the schema trimmed for readability:

{
    "manifestVersion": "1.0",
    "type": "TSToy.Example/gotstoy",
    "version": "0.1.0",
    "description": "The go implementation of a DSC Resource for the fictional TSToy application.",
    "get": {
        "executable": "gotstoy",
        "args": ["get"],
        "input": "stdin"
    },
    "set": {
        "executable": "gotstoy",
        "args": ["set"],
        "input": "stdin",
        "preTest": false,
        "return": "state"
    },
    "schema": {}
}

When preTest is removed, the command returns the same error. When preTest is set to true, the command runs without an error, but also without validating the state beforehand.

Expected behavior

Either of the following:

1. DSC calls the resource's `set` command if DSC's synthetic `test` for the resource indicates that the resource isn't in the desired state
1. DSC calls the resource's `set` command without checking if the resource is in the desired state.

Actual behavior

DSC returns the error message:


Error: Not implemented: test

Error details

No response

Environment data

N/A

Version

(build from main)

Visuals

No response

PowerShell resource discovery

Summary of the new feature / enhancement

Enable dsc resource list to find and show PS resources using Get-DscResource

Proposed technical implementation details (optional)

No response

DSCResourceManager (aka DSC Resource Resource)

Summary of the new feature / enhancement

Not sure of the name yet, maybe DSCResourceManager?

The purpose of this resource is to validate required resources or install resources. Installation needs to be OS specific:

all platforms use powershellget v3 for PS based resources
Windows use winget
Linux use apt/yum/etc...
macOS use homebrew

Needs to support validation of:

name
author
version (including range using nuget range syntax)
hash
signature (potentially GPG type on Linux?)

Proposed technical implementation details (optional)

No response

Implement `variables` support

Summary of the new feature / enhancement

Enable config to define and pass variables. Need to figure out how this is passed to group resources.

Proposed technical implementation details (optional)

No response

Add Tags and Description to resource manifest

Summary of the new feature / enhancement

Enable searching for resources based on tag or description

Proposed technical implementation details (optional)

No response

Enforce semver for `version` member in resource manifest

Summary of the new feature / enhancement

Enforce and rely on version to be semver when comparing versions of the same type found in PATH

Proposed technical implementation details (optional)

No response

Refactor code for ConfigSubCommands

Prerequisites

Write a descriptive title.
Make sure you are able to repro it on the latest version
Search the existing issues.

Steps to reproduce

3 subcomands ConfigSubCommand::Get/Set/Test use copies of mostly the same code; this should be refactored to reuse same piece of code.
This was brought up in PR review #82 .

Expected behavior

N/A

Actual behavior

N/A

Error details

No response

Environment data

N/A

Version

N/A

Visuals

No response

Deserialization into DscResource error should have more info

Prerequisites

Write a descriptive title.
Make sure you are able to repro it on the latest version
Search the existing issues.

Steps to reproduce

During resource list native resources and resource providers are expected to return json that exactly matches DscResource structure and can be deserialized into it.
However, this is not easy to come up with exact syntax that is getting accepted by deserializer.
The problem is that current error is too generic:
Error: Operation: Failed to parse resource from provider DSC/PowerShellGroup: <entire resource json>.

Need more detailed error message about syntax error.

Expected behavior

Error message that says exactly what is wrong in the json.

Actual behavior

`Error: Operation: Failed to parse resource from provider DSC/PowerShellGroup: <entire resource json>`.

Error details

No response

Environment data

any

Version

Visuals

No response

Standardize exit codes for resources and resource providers

Prerequisites

Write a descriptive title.
Make sure you are able to repro it on the latest version
Search the existing issues.

Steps to reproduce

There should be different exit codes for different types of errors common across resources and resource providers.

Expected behavior

NA

Actual behavior

NA

Error details

No response

Environment data

NA

Version

Visuals

No response

Failure to parse a single resource.json should Not abort resource enumeration

Prerequisites

Write a descriptive title.
Make sure you are able to repro it on the latest version
Search the existing issues.

Steps to reproduce

Create a .resource.json with non-compliant syntax, then run:
dsc.exe resource list

Expected behavior

all valid resources are listed;

Actual behavior

PS C:\DSCv3> dsc.exe resource list                                         
Error: Manifest: C:\DSCv3\bin\debug\testresource.resource.json
JSON: unknown field `customfield`, expected one of `manifestVersion`, `type`, `version`, `description`, `get`, `set`, `test`, `validate`, `provider`, `exitCodes`, `schema` at line 6 column 27

Error details

No response

Environment data

any

Version

1.0

Visuals

No response

Implement `parameters` support

Summary of the new feature / enhancement

Parameters will eventually become the way to have templates

Proposed technical implementation details (optional)

No response

Standardize on `DscProviderResource` as term for group/providers

Summary of the new feature / enhancement

This means requires in the resource manifest should be called requiredProvider and implementedAs should have a ProviderResource instead of Custom.

Proposed technical implementation details (optional)

No response

WindowsPowerShellGroup

Need to sort out the approach to using WindowsPSGroup.
The draft of resource is implemented: powershellgroup\windowspowershellgroup.resource.json_todo
However there are pending issues with PSDesiredStateConfiguration v2 module that prevent it from running in Windows PowerShell.

Enable schema validation for "DSC/PowerShellGroup"

Prerequisites

Write a descriptive title.
Make sure you are able to repro it on the latest version
Search the existing issues.

Steps to reproduce

Schema validation is currently skipped for all classic PS resources that are going through DSC/PowerShellGroup resource provider.
This needs to be enabled once schema extraction for such resources is implemented.

Expected behavior

N/A

Actual behavior

N/A

Error details

No response

Environment data

N/A

Version

Visuals

No response

Enable returning JSON schema for PS class resource

Summary of the new feature / enhancement

dsc resource schema -r <psresource> returns JSON schema for a PS class resource

Proposed technical implementation details (optional)

No response

Need release pipeline

Summary of the new feature / enhancement

Need compliant way to release alpha bits of DSC

Proposed technical implementation details (optional)

No response