From 7090197bca3e8e281178f6603821817f05a6f352 Mon Sep 17 00:00:00 2001 From: Brandon Poe Date: Fri, 10 Mar 2023 14:58:34 -0800 Subject: [PATCH 01/10] Initial PRD --- docs/Product Requirements.md | 199 +++++++++++++++++++++++++++++++++++ 1 file changed, 199 insertions(+) create mode 100644 docs/Product Requirements.md diff --git a/docs/Product Requirements.md b/docs/Product Requirements.md new file mode 100644 index 00000000..ee6a1e4f --- /dev/null +++ b/docs/Product Requirements.md @@ -0,0 +1,199 @@ +# Desired State Configuration Modernization - Product Requirements + +## Overview +Today, DSC resources and configurations can only be written in PowerShell. In order to meet our customers where they are and allow them to gain more value from DSC (and by extension, Azure Machine Configuration) more quickly, we want to allow resources to be written in any language, even shell scripts. Configurations should be able to be authored easily in familiar and pervasive JSON/YAML syntax. + +Support for Linux is a must. MOF and WMI/OMI dependencies are relics of the past Windows centric world of DSC, only cause complications and do not bring any benefits. We want to remove reliance on these technologies to make DSC more portable, more powerful, and more useful. + +## Goals +### Goals +- Make authoring DSC resources easy using any language. + - Create native APIs and commands to invoke the Get/Set/Test methods of the DSC resources. + - Define a Json manifest to describe how to invoke the new DSCv3 resources. + - Define the contract between DSC and the resources for passing input and output. + - Continue to provide support for existing PowerShell script and class-based resources. +- Make authoring DSC Configurations quicker and easier. + - Define a new schema for creating DSC Configurations in JSON/YAML. + - Eliminate the need for a configuration to be compiled. + - Make configurations more dynamic with support for variables, conditions, and other functions. + - Create native APIs and commands to invoke DSC Configurations +- Make it easy to use DSC Configurations in Azure. + - New, non-PowerShell resources must be able to be retrieved from PowerShell Gallery and private repositories (including folder/share repos). + - Linux and Windows support is a must. + +### Non-Goals +- The PowerShell team will no longer provide an LCM. + - Continous application of Configurations and storage of results can be provided by other tools, such as Azure Machine Configuration. + +## Background +There has been a lot of changes in the Configuration Management/Infrastructure as Code space since DSC first came out. Our competitors are the market leaders and we have not been playing catch-up. Ansible is a notable leader in this space and the ability to author "playbooks" in YAML is appealing to many of its users. It also provides a way to simply run its playbooks without havine to compile, pull/push the playbook to the target machine's LCM and have it execute in the background. + +The lack of notable improvements in DSC have caused many potential users to feel that it is dead/abonanded technology. + +Additionaly, recent research completed by the Machine Configuration team shows that there is a longer need to ramp up on DSC/Machine Config before enough value can be garnered for adoption. We need to make it easier for customers to use DSC and Machine Config. + +## Requirements +- As a resource author, it is easy for me to write and share resources. + - I can use any languague I'm confortabe with to author my resource. + - I can easily find and implement the input contract for my resource because input is JSON sent to stdin. + - I can easily find and implement the output contract for my resource because it is JSON sent to stdout. + - I can easily implement my resource because the contracts are lightweight. + - I can easily define my manifest that instructs DSC how to call my resource. + - I can publish my resource at PowerShell Gallery. + - I do not need to make any changes to my existing PowerShell script and class based resources for them to be continued to be used. + - I can easily test my resources by using a native command to invoke it. + - I can write cross plaform resources. + - I can write resources that are not cross-platform. +- As a configuration author, its easy for me to write and test configurations. + - I do not need to know a programming language or custom DSL to write a configuration. + - I can write configurations in JSON or YAML. + - I do not need to compile or convert my JSON or YAML configuration before it can be invoked. + - I can discover and use existing resources written by Microsoft and the community on PowerShell Gallery. + - I can write configurations the same way and utilize the same tools for Windows and Linux. +- As a configuration author, its easy for me to use my configurations in Azure. + - I can write configuration using knowledge that I already have about Azure because configurations look just like ARM Templates. + - I can easily start using Azure since ARM Templates look and work like my DSC Configurations. + + +## Assumptions, Constraints, Dependencies +### Assumptions +- The PowerShell team will deliver the native APIs and command that are equivelant to `Invoke-DscResource`. This work requires that the details of the manifest and resource input/output contract are defined. +- The goal "Eliminate the need for a configuration to be compiled" does not preclude implementing the ability later to enable other means of writing Configurations that would then be "compiled" into JSON (such as Bicep, PowerShell, HCL, etc.). + +## User Interface and Design +The user interface will consist of command line tools and schema for configurations and resource manifests. +### **config.exe** +This command will invoke DSC resources for ad-hoc use and testing. +``` +Usage: config [subcommand] [options] +Subcommands: + get - invoke `get` on a resource + set - invoke `set` on a resource + test - invoke `test` on a resource +Options: + -h, --help +``` + +### **Configuration Schema** +The configuration schema is the format of the document used to author configurations. It should be easy enough to author by hand without any special authoring tools. + +For the schema, we will use the same schema that is used for Azure (ARM) Templates. Most of the same functions should be available to make configurations dynamic enough to be easily re-usable and adaptable. + +JSON +``` +{ + "parameters": { + "timeZone": { + "type": "string", + "defaultValue": "Pacific Standard Time" + } + }, + "variables": { + "userName": "TestUser", + "groupName": "TestGroup", + "foo": { + "bar": "baz" + } + }, + "resources": [ + { + "name": "test-user", + "type": "PSDscResources/User", + "properties": { + "UserName": "$(variables('userName'))" + } + }, + { + "name": "test-group", + "type": "PSDscResources/Group", + "properties": { + "GroupName": "$(variables('groupName'))", + "MembersToInclude": [ + "$($(reference('test-user')).UserName)" + ] + } + }, + { + "condition": "$(not(equals($(variables('foo')).bar, 'baz')))", + "name": "spooler-service", + "type": "PSDscResources/Service", + "properties": { + "Name": "Spooler" + } + }, + { + "name": "timezone", + "type": "xTimeZone/xTimeZone", + "properties": { + "TimeZone": "$(parameters('timeZone'))", + "IsSingleInstance": "yes" + } + }, + { + "name": "securityoption", + "type": "SecurityPolicyDsc/SecurityOption", + "properties": { + "Name": "SecurityOption", + "Accounts_Guest_account_status": "Disabled" + } + } + ] +} +``` + +YAML +``` +parameters: + timeZone: + type: string + defaultValue: Pacific Standard Time + +variables: + # Simple variables + userName: TestUser + groupName: TestGroup + + foo: # Variable with a value that is a hashtable + bar: baz + +resources: + - name: test-user # The results of the Get method are stored in a variable named 'test-user'. Get is called after Set. When name contains a special character, use ${test user} + type: PSDscResources/User + properties: + UserName: $(variables('userName')) # This is an example of how to use a simple variable + + - name: test-group + type: PSDscResources/Group + properties: + GroupName: $(variables('groupName')) + MembersToInclude: + - $($(reference('test-user')).UserName) + + - condition: $(not(equals($(variables('foo')).bar, 'baz'))) # Conditions must return $true or else this task will be skipped + name: spooler-service + type: PSDscResources/Service + properties: + Name: Spooler + + - name: timezone + type: xTimeZone/xTimeZone + properties: + TimeZone: $(parameters('timeZone')) + IsSingleInstance: yes + + - name: securityoption + type: SecurityPolicyDsc/SecurityOption + properties: + Name: SecurityOption + Accounts_Guest_account_status: Disabled + +``` + +## Risks +- Skills of working in languages that compile to native are in short supply on our dev teams. This may require some initial ramp up in the required languages for existing devs. + +## Open Items +- Details about how native DSC resources will be made available in PowerShell Gallery. +- Native commands/APIs for finding and retrieving native resources from PowerShell Gallery. + +## References \ No newline at end of file From 70182da4054535899b015cd1f0f76e9df5e5e146 Mon Sep 17 00:00:00 2001 From: Brandon Poe Date: Fri, 10 Mar 2023 15:04:49 -0800 Subject: [PATCH 02/10] fixing functions --- docs/Product Requirements.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/Product Requirements.md b/docs/Product Requirements.md index ee6a1e4f..81951bac 100644 --- a/docs/Product Requirements.md +++ b/docs/Product Requirements.md @@ -100,21 +100,21 @@ JSON "name": "test-user", "type": "PSDscResources/User", "properties": { - "UserName": "$(variables('userName'))" + "UserName": "[variables('userName')]" } }, { "name": "test-group", "type": "PSDscResources/Group", "properties": { - "GroupName": "$(variables('groupName'))", + "GroupName": "[variables('groupName')]", "MembersToInclude": [ - "$($(reference('test-user')).UserName)" + "[reference('test-user').UserName]" ] } }, { - "condition": "$(not(equals($(variables('foo')).bar, 'baz')))", + "condition": "[not(equals(variables('foo').bar, 'baz'))]", "name": "spooler-service", "type": "PSDscResources/Service", "properties": { @@ -125,7 +125,7 @@ JSON "name": "timezone", "type": "xTimeZone/xTimeZone", "properties": { - "TimeZone": "$(parameters('timeZone'))", + "TimeZone": "[parameters('timeZone')]", "IsSingleInstance": "yes" } }, @@ -157,19 +157,19 @@ variables: bar: baz resources: - - name: test-user # The results of the Get method are stored in a variable named 'test-user'. Get is called after Set. When name contains a special character, use ${test user} + - name: test-user # The results of the Get method are stored in a variable named 'test-user'. Get is called after Set. type: PSDscResources/User properties: - UserName: $(variables('userName')) # This is an example of how to use a simple variable + UserName: "[variables('userName')]" # This is an example of how to use a simple variable - name: test-group type: PSDscResources/Group properties: - GroupName: $(variables('groupName')) + GroupName: "[variables('groupName')]" MembersToInclude: - - $($(reference('test-user')).UserName) + - "[reference('test-user').UserName]" - - condition: $(not(equals($(variables('foo')).bar, 'baz'))) # Conditions must return $true or else this task will be skipped + - condition: "[not(equals(variables('foo').bar, 'baz'))]" # Conditions must return $true or else this task will be skipped name: spooler-service type: PSDscResources/Service properties: @@ -178,7 +178,7 @@ resources: - name: timezone type: xTimeZone/xTimeZone properties: - TimeZone: $(parameters('timeZone')) + TimeZone: "[parameters('timeZone')]" IsSingleInstance: yes - name: securityoption From c9c227454324a0805e31eaaa4834eddb1a8eb65e Mon Sep 17 00:00:00 2001 From: Brandon Poe Date: Mon, 20 Mar 2023 11:39:21 -0700 Subject: [PATCH 03/10] linting and update UX section --- docs/Product Requirements.md | 58 ++++++++++++++++++++++++------------ 1 file changed, 39 insertions(+), 19 deletions(-) diff --git a/docs/Product Requirements.md b/docs/Product Requirements.md index 81951bac..f59701e5 100644 --- a/docs/Product Requirements.md +++ b/docs/Product Requirements.md @@ -1,12 +1,15 @@ # Desired State Configuration Modernization - Product Requirements ## Overview + Today, DSC resources and configurations can only be written in PowerShell. In order to meet our customers where they are and allow them to gain more value from DSC (and by extension, Azure Machine Configuration) more quickly, we want to allow resources to be written in any language, even shell scripts. Configurations should be able to be authored easily in familiar and pervasive JSON/YAML syntax. Support for Linux is a must. MOF and WMI/OMI dependencies are relics of the past Windows centric world of DSC, only cause complications and do not bring any benefits. We want to remove reliance on these technologies to make DSC more portable, more powerful, and more useful. ## Goals + ### Goals + - Make authoring DSC resources easy using any language. - Create native APIs and commands to invoke the Get/Set/Test methods of the DSC resources. - Define a Json manifest to describe how to invoke the new DSCv3 resources. @@ -22,19 +25,22 @@ Support for Linux is a must. MOF and WMI/OMI dependencies are relics of the past - Linux and Windows support is a must. ### Non-Goals + - The PowerShell team will no longer provide an LCM. - Continous application of Configurations and storage of results can be provided by other tools, such as Azure Machine Configuration. ## Background -There has been a lot of changes in the Configuration Management/Infrastructure as Code space since DSC first came out. Our competitors are the market leaders and we have not been playing catch-up. Ansible is a notable leader in this space and the ability to author "playbooks" in YAML is appealing to many of its users. It also provides a way to simply run its playbooks without havine to compile, pull/push the playbook to the target machine's LCM and have it execute in the background. -The lack of notable improvements in DSC have caused many potential users to feel that it is dead/abonanded technology. +There has been a lot of changes in the Configuration Management/Infrastructure as Code space since DSC first came out. Our competitors are the market leaders and we have not been playing catch-up. Ansible is a notable leader in this space and the ability to author "playbooks" in YAML is appealing to many of its users. It also provides a way to simply run its playbooks without having to compile, pull/push the playbook to the target machine's LCM and have it execute in the background. + +The lack of notable improvements in DSC have caused many potential users to feel that it is dead/abandoned technology. -Additionaly, recent research completed by the Machine Configuration team shows that there is a longer need to ramp up on DSC/Machine Config before enough value can be garnered for adoption. We need to make it easier for customers to use DSC and Machine Config. +Additionally, recent research completed by the Machine Configuration team shows that there is a longer need to ramp up on DSC/Machine Config before enough value can be garnered for adoption. We need to make it easier for customers to use DSC and Machine Config. ## Requirements + - As a resource author, it is easy for me to write and share resources. - - I can use any languague I'm confortabe with to author my resource. + - I can use any language I'm comfortable with to author my resource. - I can easily find and implement the input contract for my resource because input is JSON sent to stdin. - I can easily find and implement the output contract for my resource because it is JSON sent to stdout. - I can easily implement my resource because the contracts are lightweight. @@ -42,7 +48,7 @@ Additionaly, recent research completed by the Machine Configuration team shows t - I can publish my resource at PowerShell Gallery. - I do not need to make any changes to my existing PowerShell script and class based resources for them to be continued to be used. - I can easily test my resources by using a native command to invoke it. - - I can write cross plaform resources. + - I can write cross platform resources. - I can write resources that are not cross-platform. - As a configuration author, its easy for me to write and test configurations. - I do not need to know a programming language or custom DSL to write a configuration. @@ -54,33 +60,45 @@ Additionaly, recent research completed by the Machine Configuration team shows t - I can write configuration using knowledge that I already have about Azure because configurations look just like ARM Templates. - I can easily start using Azure since ARM Templates look and work like my DSC Configurations. - ## Assumptions, Constraints, Dependencies + ### Assumptions -- The PowerShell team will deliver the native APIs and command that are equivelant to `Invoke-DscResource`. This work requires that the details of the manifest and resource input/output contract are defined. + +- The PowerShell team will deliver the native APIs and command that are equivalent to `Invoke-DscResource`. This work requires that the details of the manifest and resource input/output contract are defined. - The goal "Eliminate the need for a configuration to be compiled" does not preclude implementing the ability later to enable other means of writing Configurations that would then be "compiled" into JSON (such as Bicep, PowerShell, HCL, etc.). ## User Interface and Design + The user interface will consist of command line tools and schema for configurations and resource manifests. -### **config.exe** -This command will invoke DSC resources for ad-hoc use and testing. -``` -Usage: config [subcommand] [options] + +### **dsc.exe** + +```text +DSC is a desired state configuration tool. + +Usage: dsc subcommand + Subcommands: - get - invoke `get` on a resource - set - invoke `set` on a resource - test - invoke `test` on a resource -Options: - -h, --help +config - Invoke DSC configurations +module - Find and install DSC modules +repo - Add, update or remove module repositories +resource --property +dsc.exe repo set --name Contoso --url https://gallery.contoso.com/api/v2 +dsc.exe repo remove --name Contoso +dsc config test --file test.json --parameter-file test.parameters.json --output test.output.json --parameter ``` ### **Configuration Schema** + The configuration schema is the format of the document used to author configurations. It should be easy enough to author by hand without any special authoring tools. For the schema, we will use the same schema that is used for Azure (ARM) Templates. Most of the same functions should be available to make configurations dynamic enough to be easily re-usable and adaptable. JSON -``` +```JSON { "parameters": { "timeZone": { @@ -142,7 +160,7 @@ JSON ``` YAML -``` +```YAML parameters: timeZone: type: string @@ -190,10 +208,12 @@ resources: ``` ## Risks + - Skills of working in languages that compile to native are in short supply on our dev teams. This may require some initial ramp up in the required languages for existing devs. ## Open Items + - Details about how native DSC resources will be made available in PowerShell Gallery. - Native commands/APIs for finding and retrieving native resources from PowerShell Gallery. -## References \ No newline at end of file +## References From 013bf22576e4dc2b641253d59f68723e8f5caf47 Mon Sep 17 00:00:00 2001 From: Brandon Poe Date: Mon, 20 Mar 2023 19:38:10 -0700 Subject: [PATCH 04/10] Adding dsc cli help --- docs/cli-help.md | 259 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 259 insertions(+) create mode 100644 docs/cli-help.md diff --git a/docs/cli-help.md b/docs/cli-help.md new file mode 100644 index 00000000..78783881 --- /dev/null +++ b/docs/cli-help.md @@ -0,0 +1,259 @@ +# DSC Cli Help + +C:\git\Microsoft.Dsc\dsc\bin\Debug\net7.0> .\dsc.exe --help + +```output +Description: + Command line interface for working with Desired State Configuration. + +Usage: + dsc [command] [options] + +Options: + --version Show version information + -?, -h, --help Show help and usage information + +Commands: + config Invoke desired state configurations. + module Manage modules. + repo Manage repositories. + resource Invoke and find resources. +``` + +C:\git\Microsoft.Dsc\dsc\bin\Debug\net7.0> .\dsc.exe config --help + +```output +Description: + Invoke desired state configurations. + +Usage: + dsc config [command] [options] + +Options: + -?, -h, --help Show help and usage information + +Commands: + test test a machine's desired state configuration. + set Set a machine's desired state configuration. +``` + +C:\git\Microsoft.Dsc\dsc\bin\Debug\net7.0> .\dsc.exe config set --help + +```output +Description: + Set a machine's desired state configuration. + +Usage: + dsc config set [options] + +Options: + -f, --file (REQUIRED) The configuration file. + -?, -h, --help Show help and usage information +``` + +C:\git\Microsoft.Dsc\dsc\bin\Debug\net7.0> .\dsc.exe config test --help + +```output +Description: + test a machine's desired state configuration. + +Usage: + dsc config test [options] + +Options: + -f, --file (REQUIRED) The configuration file. + -?, -h, --help Show help and usage information + +``` + +C:\git\Microsoft.Dsc\dsc\bin\Debug\net7.0> .\dsc.exe module --help + +```output +Description: + Manage modules. + +Usage: + dsc module [command] [options] + +Options: + -?, -h, --help Show help and usage information + +Commands: + find Find modules + install install modules + +C:\git\Microsoft.Dsc\dsc\bin\Debug\net7.0> .\dsc.exe module find --help +```output +Description: + Find modules + +Usage: + dsc module find [options] + +Options: + -n, --name (REQUIRED) The name of the module + -v, --version The version of the module + -r, --repo The repo that contains the module + -?, -h, --help Show help and usage information + + +``` + +C:\git\Microsoft.Dsc\dsc\bin\Debug\net7.0> .\dsc.exe module install --help + +```output +Description: + install modules + +Usage: + dsc module install [options] + +Options: + -n, --name (REQUIRED) The name of the module + -v, --version The version of the module + -r, --repo The repo that contains the module + -?, -h, --help Show help and usage information +``` + +C:\git\Microsoft.Dsc\dsc\bin\Debug\net7.0> .\dsc.exe resource --help + +```output +Description: + Invoke and find resources. + +Usage: + dsc resource [command] [options] + +Options: + -?, -h, --help Show help and usage information + +Commands: + get Get the current state of a resource + test Test the state of a resource + set Set the state of a resource + find Find a resource + +``` + +C:\git\Microsoft.Dsc\dsc\bin\Debug\net7.0> .\dsc.exe resource get --help + +```output +Description: + Get the current state of a resource + +Usage: + dsc resource get [options] + +Options: + -n, --name (REQUIRED) The name of the resource + -m, --module (REQUIRED) The module that contains the resource + -v, --version The version of the module to use + -p, --properties Property of the resource. Format as key:value + -j, --jsonProperties A JSON string that will be passed as input to the resource + -?, -h, --help Show help and usage information + + +``` + +C:\git\Microsoft.Dsc\dsc\bin\Debug\net7.0> .\dsc.exe resource set --help + +```output +Description: + Set the state of a resource + +Usage: + dsc resource set [options] + +Options: + -n, --name (REQUIRED) The name of the resource + -m, --module (REQUIRED) The module that contains the resource + -v, --version The version of the module to use + -p, --properties Property of the resource. Format as key:value + -j, --jsonProperties A JSON string that will be passed as input to the resource + -?, -h, --help Show help and usage information + + +``` + +C:\git\Microsoft.Dsc\dsc\bin\Debug\net7.0> .\dsc.exe resource test --help + +```output +Description: + Test the state of a resource + +Usage: + dsc resource test [options] + +Options: + -n, --name (REQUIRED) The name of the resource + -m, --module (REQUIRED) The module that contains the resource + -v, --version The version of the module to use + -p, --properties Property of the resource. Format as key:value + -j, --jsonProperties A JSON string that will be passed as input to the resource + -?, -h, --help Show help and usage information + + +``` + +C:\git\Microsoft.Dsc\dsc\bin\Debug\net7.0> .\dsc.exe resource find --help + +```output +Description: + Find a resource + +Usage: + dsc resource find [options] + +Options: + -v, --version The version of the module to use + -?, -h, --help Show help and usage information + + +C:\git\Microsoft.Dsc\dsc\bin\Debug\net7.0> .\dsc.exe repo --help +```output +Description: + Manage repositories. + +Usage: + dsc repo [command] [options] + +Options: + -?, -h, --help Show help and usage information + +Commands: + set Add or update a repository + remove Remove a repository + +``` + +C:\git\Microsoft.Dsc\dsc\bin\Debug\net7.0> .\dsc.exe repo set --help + +```output +Description: + Add or update a repository + +Usage: + dsc repo set [options] + +Options: + -n, --name (REQUIRED) The name of the repository + -u, --uri (REQUIRED) The uri of the repository + -?, -h, --help Show help and usage information + + +``` + +C:\git\Microsoft.Dsc\dsc\bin\Debug\net7.0> .\dsc.exe repo remove --help + +```output +Description: + Remove a repository + +Usage: + dsc repo remove [options] + +Options: + -n, --name (REQUIRED) The name of the repository + -?, -h, --help Show help and usage information + +``` From 82213b695c77a33cb9cf387c213c6286dc274992 Mon Sep 17 00:00:00 2001 From: Brandon Poe Date: Mon, 20 Mar 2023 20:33:04 -0700 Subject: [PATCH 05/10] Update cli-help.md --- docs/cli-help.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/cli-help.md b/docs/cli-help.md index 78783881..41bf0f2d 100644 --- a/docs/cli-help.md +++ b/docs/cli-help.md @@ -208,6 +208,7 @@ Options: -v, --version The version of the module to use -?, -h, --help Show help and usage information +``` C:\git\Microsoft.Dsc\dsc\bin\Debug\net7.0> .\dsc.exe repo --help ```output From 6bf7142ccb89c49d0a9775bdfc1d75ca87bb5b8c Mon Sep 17 00:00:00 2001 From: Brandon Poe Date: Mon, 20 Mar 2023 20:35:51 -0700 Subject: [PATCH 06/10] Update cli-help.md --- docs/cli-help.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/cli-help.md b/docs/cli-help.md index 41bf0f2d..3c7211d0 100644 --- a/docs/cli-help.md +++ b/docs/cli-help.md @@ -82,6 +82,8 @@ Commands: find Find modules install install modules +``` + C:\git\Microsoft.Dsc\dsc\bin\Debug\net7.0> .\dsc.exe module find --help ```output Description: @@ -96,7 +98,6 @@ Options: -r, --repo The repo that contains the module -?, -h, --help Show help and usage information - ``` C:\git\Microsoft.Dsc\dsc\bin\Debug\net7.0> .\dsc.exe module install --help @@ -172,7 +173,6 @@ Options: -j, --jsonProperties A JSON string that will be passed as input to the resource -?, -h, --help Show help and usage information - ``` C:\git\Microsoft.Dsc\dsc\bin\Debug\net7.0> .\dsc.exe resource test --help @@ -192,7 +192,6 @@ Options: -j, --jsonProperties A JSON string that will be passed as input to the resource -?, -h, --help Show help and usage information - ``` C:\git\Microsoft.Dsc\dsc\bin\Debug\net7.0> .\dsc.exe resource find --help From b95bd6d41d683ddf42b4ede406d259deb638ad68 Mon Sep 17 00:00:00 2001 From: Brandon Poe Date: Tue, 21 Mar 2023 09:57:56 -0700 Subject: [PATCH 07/10] removing prompt/path --- docs/cli-help.md | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/cli-help.md b/docs/cli-help.md index 78783881..fba8bcd9 100644 --- a/docs/cli-help.md +++ b/docs/cli-help.md @@ -1,6 +1,6 @@ # DSC Cli Help -C:\git\Microsoft.Dsc\dsc\bin\Debug\net7.0> .\dsc.exe --help +dsc.exe --help ```output Description: @@ -20,7 +20,7 @@ Commands: resource Invoke and find resources. ``` -C:\git\Microsoft.Dsc\dsc\bin\Debug\net7.0> .\dsc.exe config --help +dsc.exe config --help ```output Description: @@ -37,7 +37,7 @@ Commands: set Set a machine's desired state configuration. ``` -C:\git\Microsoft.Dsc\dsc\bin\Debug\net7.0> .\dsc.exe config set --help +dsc.exe config set --help ```output Description: @@ -51,7 +51,7 @@ Options: -?, -h, --help Show help and usage information ``` -C:\git\Microsoft.Dsc\dsc\bin\Debug\net7.0> .\dsc.exe config test --help +dsc.exe config test --help ```output Description: @@ -66,7 +66,7 @@ Options: ``` -C:\git\Microsoft.Dsc\dsc\bin\Debug\net7.0> .\dsc.exe module --help +dsc.exe module --help ```output Description: @@ -82,7 +82,7 @@ Commands: find Find modules install install modules -C:\git\Microsoft.Dsc\dsc\bin\Debug\net7.0> .\dsc.exe module find --help +dsc.exe module find --help ```output Description: Find modules @@ -99,7 +99,7 @@ Options: ``` -C:\git\Microsoft.Dsc\dsc\bin\Debug\net7.0> .\dsc.exe module install --help +dsc.exe module install --help ```output Description: @@ -115,7 +115,7 @@ Options: -?, -h, --help Show help and usage information ``` -C:\git\Microsoft.Dsc\dsc\bin\Debug\net7.0> .\dsc.exe resource --help +dsc.exe resource --help ```output Description: @@ -135,7 +135,7 @@ Commands: ``` -C:\git\Microsoft.Dsc\dsc\bin\Debug\net7.0> .\dsc.exe resource get --help +dsc.exe resource get --help ```output Description: @@ -155,7 +155,7 @@ Options: ``` -C:\git\Microsoft.Dsc\dsc\bin\Debug\net7.0> .\dsc.exe resource set --help +dsc.exe resource set --help ```output Description: @@ -175,7 +175,7 @@ Options: ``` -C:\git\Microsoft.Dsc\dsc\bin\Debug\net7.0> .\dsc.exe resource test --help +dsc.exe resource test --help ```output Description: @@ -195,7 +195,7 @@ Options: ``` -C:\git\Microsoft.Dsc\dsc\bin\Debug\net7.0> .\dsc.exe resource find --help +dsc.exe resource find --help ```output Description: @@ -209,7 +209,7 @@ Options: -?, -h, --help Show help and usage information -C:\git\Microsoft.Dsc\dsc\bin\Debug\net7.0> .\dsc.exe repo --help +dsc.exe repo --help ```output Description: Manage repositories. @@ -226,7 +226,7 @@ Commands: ``` -C:\git\Microsoft.Dsc\dsc\bin\Debug\net7.0> .\dsc.exe repo set --help +dsc.exe repo set --help ```output Description: @@ -243,7 +243,7 @@ Options: ``` -C:\git\Microsoft.Dsc\dsc\bin\Debug\net7.0> .\dsc.exe repo remove --help +dsc.exe repo remove --help ```output Description: From cffeaaebaa77eaadb33af47e40b9647647e5aa66 Mon Sep 17 00:00:00 2001 From: Brandon Poe Date: Tue, 4 Apr 2023 11:44:06 -0700 Subject: [PATCH 08/10] Update docs/Product Requirements.md Co-authored-by: Steve Lee --- docs/Product Requirements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Product Requirements.md b/docs/Product Requirements.md index f59701e5..e2c600f4 100644 --- a/docs/Product Requirements.md +++ b/docs/Product Requirements.md @@ -14,7 +14,7 @@ Support for Linux is a must. MOF and WMI/OMI dependencies are relics of the past - Create native APIs and commands to invoke the Get/Set/Test methods of the DSC resources. - Define a Json manifest to describe how to invoke the new DSCv3 resources. - Define the contract between DSC and the resources for passing input and output. - - Continue to provide support for existing PowerShell script and class-based resources. + - Continue to support existing PowerShell script and class-based resources. - Make authoring DSC Configurations quicker and easier. - Define a new schema for creating DSC Configurations in JSON/YAML. - Eliminate the need for a configuration to be compiled. From b48dfc464f7bef728d3d7b487a4e20d0fca1aae6 Mon Sep 17 00:00:00 2001 From: Brandon Poe Date: Tue, 4 Apr 2023 11:51:05 -0700 Subject: [PATCH 09/10] Addressing PR feedback --- docs/Product Requirements.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/Product Requirements.md b/docs/Product Requirements.md index e2c600f4..4fcc036a 100644 --- a/docs/Product Requirements.md +++ b/docs/Product Requirements.md @@ -2,7 +2,7 @@ ## Overview -Today, DSC resources and configurations can only be written in PowerShell. In order to meet our customers where they are and allow them to gain more value from DSC (and by extension, Azure Machine Configuration) more quickly, we want to allow resources to be written in any language, even shell scripts. Configurations should be able to be authored easily in familiar and pervasive JSON/YAML syntax. +Today, DSC resources and configurations can only be written in PowerShell. In order to meet our customers where they are and allow them to gain more value from DSC (and by extension, Azure Machine Configuration) more quickly, we want to allow resources to be written in any language, even shell scripts. Configurations should be able to be authored easily in familiar and pervasive JSON/YAML syntax. Also, applying configurations should not require PowerShell unless the resources being invoked are PowerShell resources. Support for Linux is a must. MOF and WMI/OMI dependencies are relics of the past Windows centric world of DSC, only cause complications and do not bring any benefits. We want to remove reliance on these technologies to make DSC more portable, more powerful, and more useful. @@ -23,6 +23,7 @@ Support for Linux is a must. MOF and WMI/OMI dependencies are relics of the past - Make it easy to use DSC Configurations in Azure. - New, non-PowerShell resources must be able to be retrieved from PowerShell Gallery and private repositories (including folder/share repos). - Linux and Windows support is a must. +- Enable partner teams to utilize DSC for cloud, on-prem, and hybrid configuration related scenarios as the "standard" Microsoft configuration management tool. ### Non-Goals From 60485f6855436b925926c88ea4e6dbf0028c039f Mon Sep 17 00:00:00 2001 From: Brandon Poe Date: Tue, 4 Apr 2023 12:55:23 -0700 Subject: [PATCH 10/10] Updating cli syntax --- docs/Product Requirements.md | 25 +++++++++++++++---------- 1 file changed, 15 insertions(+), 10 deletions(-) diff --git a/docs/Product Requirements.md b/docs/Product Requirements.md index 4fcc036a..c9c0d443 100644 --- a/docs/Product Requirements.md +++ b/docs/Product Requirements.md @@ -70,25 +70,30 @@ Additionally, recent research completed by the Machine Configuration team shows ## User Interface and Design -The user interface will consist of command line tools and schema for configurations and resource manifests. +The user interface will consist of command line tools and schema for configurations and resource manifests. ### **dsc.exe** +The `dsc.exe` tool will be the primary interface for working with DSC. It will have options for finding and invoking resources and for invoking configurations. ```text -DSC is a desired state configuration tool. +Apply configuration or invoke specific DSC resources -Usage: dsc subcommand +Usage: dsc.exe [OPTIONS] -Subcommands: -config - Invoke DSC configurations -module - Find and install DSC modules -repo - Add, update or remove module repositories -resource [possible values: json, pretty-json, yaml] + -h, --help Print help + -V, --version Print version Examples: dsc.exe resource set --name user --module PSDscResources --version 1.1.0 --property --property -dsc.exe repo set --name Contoso --url https://gallery.contoso.com/api/v2 -dsc.exe repo remove --name Contoso dsc config test --file test.json --parameter-file test.parameters.json --output test.output.json --parameter ```