powershell / dsc Goto Github PK
View Code? Open in Web Editor NEWThis repo is for the DSC v3 project
License: MIT License
This repo is for the DSC v3 project
License: MIT License
Enforce and rely on version
to be semver when comparing versions of the same type
found in PATH
No response
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.
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.
Use a single PowrShell process for all invocation and terminate the process when the config or resource call is complete
No response
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.
Error message that says exactly what is wrong in the json.
`Error: Operation: Failed to parse resource from provider DSC/PowerShellGroup: <entire resource json>`.
No response
any
1
No response
Parameters will eventually become the way to have templates
No response
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.
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.
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:
Needs to support validation of:
No response
Need compliant way to release alpha bits of DSC
No response
Enable configuration-and-resource
schema to return json schema for the config fragment and specified resources
No response
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:
dsc
5.1
vs 7
(default) as it's part of the schema rather than a meta-propertypwsh
or powershell
reusing it for the entire group. this also allows users who want process isolation to have multiple instances of this resourceAdditional work in dsc
to support this:
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
.No response
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.
No response
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.
No response
Enable dsc resource get -r <psresource>
to invoke get
, set
, and test
to a PS resource
No response
There should be different exit codes for different types of errors common across resources and resource providers.
NA
NA
No response
NA
v1
No response
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
No response
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.
Need to have resources support this to work completely
No response
dsc resource schema -r <psresource>
returns JSON schema where is a script resource
No response
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"
}
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 .
N/A
N/A
No response
N/A
N/A
No response
Needs to call out to dsc.exe
to get dynamic schemas at runtime to fulfill validation and intellisense
No response
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?)
No response
dsc resource schema -r <psresource>
returns JSON schema for a PS class resource
No response
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...
No response
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
These aren't relevant to DSC
Subset needed for DSC
Not applicable to DSC
Enable dsc resource list
to find and show PS resources using Get-DscResource
No response
As resources get executed, need progress returned as JSON for agents to display. Consider how child processes can participate including resources.
No response
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".
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.
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)
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].
Which team currently needs it and is potentially sponsoring/requesting?
WinGet/Internal to PS team?
Executing against the current plan and hoping to have something to show publicly by Build, in May.
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.
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.
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).
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.
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.
N/A
N/A
No response
N/A
v1
No response
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"
No response
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.
No response
Should we use OpenAPI to describe a resource's schema? The advantages are:
Cons:
No response
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.
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.
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
`dsc.exe` should be able to return schema for resources that are processed by resource providers.
Currently this is not implemented.
No response
v1.
v1
No response
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.
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"
}
}
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.
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.
Enable configuration using PS resource including validation
No response
Enable searching for resources based on tag or description
No response
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.
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.
DSC returns the error message:
Error: Not implemented: test
No response
N/A
(build from main)
No response
Enable -parallel
switch for dsc
No response
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.
No response
Default to PS7 (if available), but allow invocation with 5.1 as a meta-property _powershell
with allowed values 5.1
or 7
No response
Enable config to define and pass variables. Need to figure out how this is passed to group resources.
No response
Enable passing parameters to a config via dsc
. This simply might be a -parameters
parameter that accepts JSON.
No response
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:
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:
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.$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.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.
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.
This means requires
in the resource manifest should be called requiredProvider
and implementedAs
should have a ProviderResource
instead of Custom
.
No response
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.
n/a
n/a
n/a
n/a
n/a
No response
For interactive display, this should be a table showing type
, requires
and description
No response
Create a .resource.json with non-compliant syntax, then run:
dsc.exe resource list
all valid resources are listed;
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
No response
any
1.0
No response
Build execution graph for a config
No response
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.