draft of command based resources #2

SteveL-MSFT · 2022-11-29T20:37:17Z

command based resource for DSCv3 proposal

SteveL-MSFT · 2022-12-07T23:18:01Z

specs/Command-DSCResources.md

+
+### Module based resources
+
+Existing PowerShell class and script function resources packaged as a module will need the addition of a manifest file.


We may change this to NOT require a new JSON config file as most legacy modules authors will likely not make a change. Instead, we can have a meta property as part of the input JSON like _powershell that specifies powershell.exe or pwsh.exe to execute.

SteveL-MSFT · 2023-01-10T19:13:05Z

specs/Command-DSCResources.md

@@ -0,0 +1,377 @@
+# Command based resources for DSC v3
+
+Configuration is based on a declarative idempotent model that allows users to get, set, and test settings values.


Need to also expose API and not just cmdline tool

You start by describing "Configuration" that is the PoC you've built, shouldn't talk about the problem first?

Why an API is needed? If the tool/utility accepts JSON input, is an API needed and why? I guess showing the purpose first would help understand the why.
Creating an API for it means you already think about some use cases or integration you haven't described.

gaelcolas · 2023-01-20T21:24:40Z

specs/Command-DSCResources.md

@@ -0,0 +1,377 @@
+# Command based resources for DSC v3
+
+Configuration is based on a declarative idempotent model that allows users to get, set, and test settings values.


You start by describing "Configuration" that is the PoC you've built, shouldn't talk about the problem first?

Why an API is needed? If the tool/utility accepts JSON input, is an API needed and why? I guess showing the purpose first would help understand the why.
Creating an API for it means you already think about some use cases or integration you haven't described.

gaelcolas · 2023-01-20T21:35:11Z

specs/Command-DSCResources.md

+However, we still need to support the existing resources that are written in PowerShell including
+class based and script functions based resources.


Suggested change

However, we still need to support the existing resources that are written in PowerShell including

class based and script functions based resources.

I'd say you don't need this for the purpose of the tool.
You want this to be supported, so that motivation should be recorded in the context (Why such tool would be useful? What's the business case?)

gaelcolas · 2023-01-20T21:52:38Z

specs/Command-DSCResources.md

+Go, Rust, etc...
+
+Communication to and from the resource will be via STDIN or arguments for input and STDOUT for output along
+with using the exit code to indicate success or failure and STDERR for informative messages.


All output should be serialised structured data (JSON), with schema.

gaelcolas · 2023-01-20T21:57:17Z

specs/Command-DSCResources.md

+### Resource discovery
+
+Any "command" (which can be a script requiring a host runtime) that particpates would have a command manifest file with the name
+"<command>.dscresource.json" that would be found within the `PATH` environment variable.


With the plug-in model I described above, the discovery should be handled by that plug-in.
Having config resource manifest in the PATH would not make sense for DSC resources.
If the plug-ins implement a discovery method/action, then config can ask the plugins for their available resources.
The DSC Resource plug-in would do a Get-DscResource (no need for JSON manifest anymore, the plug-in would return the JSON manifest in some ways, from the DSC resources it found).

gaelcolas · 2023-01-20T22:02:37Z

specs/Command-DSCResources.md

+Any "command" (which can be a script requiring a host runtime) that particpates would have a command manifest file with the name
+"<command>.dscresource.json" that would be found within the `PATH` environment variable.
+
+PowerShell based resources can have an optional `.dscresource.json` file to indicate if the resource should be hosted by powershell.exe or pwsh.exe (see below).


PowerShell and pwsh should tell which DSC Resource is available, and the resource modules should say which one works and which one doesn't with a given version of PowerShell.
The plug-in specifies which version of WPS or pwsh it supports or not (i.e. pwsh_psdscv3 plug-in works with PS 7.3.1, so Get-DscResource in PS 7.3.1 won't show DSC Resources that are only supported in WPS such as SharePointDsc, because its Module manifest says so).
If a DSC Resource module "says" it supports both, then where to run it should be defined when declaring the configuration, similar to the "which user to run this config as" (PSDscRunAsCredential)...

gaelcolas · 2023-01-20T23:06:27Z

specs/Command-DSCResources.md

+## Resource input
+
+The JSON input to the resource will be just the `settings` for that resource.
+See https://microsoft.ghe.com/AzureCore-Compute/PowerShellTeam-Docs/pull/36/files for a higher level configuration example and the


I don't have access to that link, and I don't really understand :(

gaelcolas · 2023-01-20T23:07:58Z

specs/Command-DSCResources.md

+
+The exit code must be 0 for success.
+Legacy PowerShell resources don't set the exit code so will default to 0.
+Optional JSON output via STDOUT provides additional information and may be used by the orchestrator.


Suggested change

Optional JSON output via STDOUT provides additional information and may be used by the orchestrator.

Optional JSON output via STDOUT provides additional information and may be used by the `config` utility.

Changed for consistency.
Orchestrator is another loaded term.

gaelcolas · 2023-01-20T23:09:47Z

specs/Command-DSCResources.md

+
+### Failure output
+
+The exit code may be non-zero to indicate failure.


Exit code should be important for the config utility, not what it runs.
What it runs should return JSON.

gaelcolas · 2023-01-20T23:11:13Z

specs/Command-DSCResources.md

+> [TODO] Should define a common schema for error messages so an orchestrator can more easily parse
+> and report the errors to the user.


Suggested change

> [TODO] Should define a common schema for error messages so an orchestrator can more easily parse

> and report the errors to the user.

> [TODO] Should define a common schema for error messages so that the `config` utility, or higher level tools, can more easily parse

> and report the errors to the user.

gaelcolas · 2023-01-20T23:15:01Z

specs/Command-DSCResources.md

+
+For consistency, the following members are common to all configuration resource settings:
+
+`_ensure`: Used to specify if that setting should be `present` or `absent`.


In some rare occasions this does not make sense for some resources...
For instance, some resources are not installable/removable, they will always be present, but maybe with different values...

SteveL-MSFT · 2023-02-01T20:00:14Z

specs/Command-DSCResources.md

+
+Since STDERR is used for other types of output (verbose/debug messages), the top level member indicates failure.
+
+> [TODO] Should define a common schema for error messages so an orchestrator can more easily parse


Should have a _reason property that contains ErrorId and Message per property if there is a failure, like Access Denied, or Not Found

What if the Reason is not an error?
What if there's more than 1 reason per property? (User is not in group xyz and is also disabled)?

SteveL-MSFT · 2023-02-24T20:33:40Z

specs/Command-DSCResources.md

+      "2": "Invalid setting value",
+      "3": "Unknown setting"
+    },
+    "schema": "https://schemas.microsoft.com/configuration/myResource/20220621/schema.json"


Enable getting schema dynamically via the executable

SteveL-MSFT · 2023-02-24T20:37:10Z

specs/Command-DSCResources.md

+        "version": "1.2.3"
+      }
+    ],
+    "exitCodes": {


Allow way to execute command to get these, probably as JSON output making it easier to keep it all in the code rather than keeping code and manifest in sync

SteveL-MSFT · 2023-04-04T20:46:38Z

Closing this. Will draft a new spec based on changes and learnings we've had.

draft of command based resources

38f0429

SteveL-MSFT commented Dec 7, 2022

View reviewed changes

SteveL-MSFT commented Jan 10, 2023

View reviewed changes

gaelcolas reviewed Jan 20, 2023

View reviewed changes

SteveL-MSFT commented Feb 1, 2023

View reviewed changes

SteveL-MSFT commented Feb 24, 2023

View reviewed changes

anmenaga mentioned this pull request Apr 4, 2023

DSCResourceManager (aka DSC Resource Resource) #47

Open

SteveL-MSFT closed this Apr 4, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

draft of command based resources #2

draft of command based resources #2

SteveL-MSFT commented Nov 29, 2022

SteveL-MSFT Dec 7, 2022

SteveL-MSFT Jan 10, 2023

gaelcolas Jan 20, 2023 •

edited

Loading

gaelcolas Jan 20, 2023 •

edited

Loading

gaelcolas Jan 20, 2023

gaelcolas Jan 20, 2023

gaelcolas Jan 20, 2023

gaelcolas Jan 20, 2023

gaelcolas Jan 20, 2023

gaelcolas Jan 20, 2023

gaelcolas Jan 20, 2023

gaelcolas Jan 20, 2023

gaelcolas Jan 20, 2023

SteveL-MSFT Feb 1, 2023

gaelcolas Feb 2, 2023

SteveL-MSFT Feb 24, 2023

SteveL-MSFT Feb 24, 2023

SteveL-MSFT commented Apr 4, 2023


		### Module based resources

		Existing PowerShell class and script function resources packaged as a module will need the addition of a manifest file.

		@@ -0,0 +1,377 @@
		# Command based resources for DSC v3

		Configuration is based on a declarative idempotent model that allows users to get, set, and test settings values.

		However, we still need to support the existing resources that are written in PowerShell including
		class based and script functions based resources.

	Optional JSON output via STDOUT provides additional information and may be used by the orchestrator.
	Optional JSON output via STDOUT provides additional information and may be used by the `config` utility.


		### Failure output

		The exit code may be non-zero to indicate failure.

		> [TODO] Should define a common schema for error messages so an orchestrator can more easily parse
		> and report the errors to the user.


		For consistency, the following members are common to all configuration resource settings:

		`_ensure`: Used to specify if that setting should be `present` or `absent`.


		Since STDERR is used for other types of output (verbose/debug messages), the top level member indicates failure.

		> [TODO] Should define a common schema for error messages so an orchestrator can more easily parse

draft of command based resources #2

draft of command based resources #2

Conversation

SteveL-MSFT commented Nov 29, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gaelcolas Jan 20, 2023 • edited Loading

Choose a reason for hiding this comment

gaelcolas Jan 20, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

SteveL-MSFT commented Apr 4, 2023

gaelcolas Jan 20, 2023 •

edited

Loading

gaelcolas Jan 20, 2023 •

edited

Loading