From b4ef61b3334a062d870dca343861a4674bec86db Mon Sep 17 00:00:00 2001 From: gaelcolas Date: Tue, 13 Aug 2019 17:42:06 +0200 Subject: [PATCH 1/4] updating RFC with updated discussion/comments --- 1-Draft/RFCXXXX-RFC-Invoke-DscResource.md | 137 ++++++++++++++++++---- 1 file changed, 116 insertions(+), 21 deletions(-) diff --git a/1-Draft/RFCXXXX-RFC-Invoke-DscResource.md b/1-Draft/RFCXXXX-RFC-Invoke-DscResource.md index 61719c8a..6e739bc5 100644 --- a/1-Draft/RFCXXXX-RFC-Invoke-DscResource.md +++ b/1-Draft/RFCXXXX-RFC-Invoke-DscResource.md @@ -3,7 +3,7 @@ RFC: RFCXXXX Author: Gael Colas Status: Draft SupersededBy: N/A -Version: 0.8 +Version: 0.9 Area: Microsoft.PowerShell.DesiredStateConfiguration --- @@ -45,7 +45,7 @@ Specifically, we already know some features that **will not be supported** in th #### Syntax -As we don't plan on changing the usage, plus the functions is currently not available outside of PowerShell, and there is currently no command for PowerShell 7+, there is no need to change the Syntax found in Windows PowerShell 5.1. +As we don't plan on changing the usage much, plus the functions is currently not available outside of PowerShell, and there is currently no command for PowerShell 7+, so there is no need to change the Syntax found in Windows PowerShell 5.1. The increment in PowerShell [MAJOR](https://semver.org/#spec-item-8)'s version field is enough to indicate the change of public API (as per [Semantic Versioning](https://semver.org/)). @@ -58,7 +58,7 @@ Invoke-DscResource [-Name] [-Method] -ModuleName NOTES: We're avoiding to take dependencies on other technologies that would require extra configurations or permissions (such as remoting), or would not be available on other OSes. #### Independent and isolated execution -`Invoke-DscResource` in PowerShell 7+ will not be aware of other instances being executed, and as such it will be possible to execute several instances in parallel when isolated in their own runspaces, or run in parallel with the LCM. +`Invoke-DscResource` in PowerShell 7+ will not be aware of other instances being executed, and as such it will be possible to execute several instances in parallel when isolated in their own runspace, or run in parallel with the LCM. This means that it enables concurrent execution, but also risks conflict if two conflicting resources are run simultaneously. It is up to the user to sequence the execution safely, or to create appropriate resources. +#### Output & Types + +##### Get + +The `GET` function in DSC resources returns a Hashtable, and this will be the same +for `Invoke-DscResource` in PS7+. + +##### Test + +The `TEST` function in WMF 5.1 returns a CIM object, with a `[bool]` NoteProperty +`InDesiredState` that has the boolean result of the test. + +```PowerShell +InDesiredState +-------------- +True +``` + +In PS7+, `Invoke-DscResource -Method Test ...` will return an object (not CIM) +that has the same `InDesiredState` Property. + +##### Set + +The `SET` function in WMF 5.1 returns a CIM object, with a `[bool]` NoteProperty +`RebootRequired`, corresponding whether the `$global:DSCMachineStatus` has been +set to 1. + +```PowerShell +RebootRequired +-------------- +False +``` + +In PS7+, `Invoke-DscResource -Method Set ...` will return an object (not CIM) that +has the same `RebootRequired` Property, based on whether `$global:DSCMachineStatus` +has been set to 1. + # Out of Scope for initial work & other notes We're aware that some extra work or feature could be solved at the same time, but we're trying to have the MVP (minimum viable product) out as soon as possible, to help addressing the points raised in the [Motivation](#Motivation) section. +## DSC Resource Parameters & Supported Types + +As the `Invoke-DscResource` does not need to serialize and deserialize parameters +using CIM (via MOF objects), it is not limiting the types it can accept for the +DSC Resource functions (Get, Set, Test). + +In simple words, a resource could in theory accept an `[hashtable]` as a parameter +type, instead of a `[Microsoft.Management.Infrastructure.CimInstance[]]`. + +The downside here is that it's not backward compatible, for this reason, we +can't recommend any other type to be used for now. + +Also, not all types are easily serializable and deserializable, so be careful +when the Configuration Data has to be passed to the resource invocation over +the network. + +## PsDscRunAsCredential Support not built-in + +Here's why we've decided to not handle the `PsDscRunAsCredential` from the `Invoke-DscResource` +advanced function, and instead will try to publish a wrapper on the PS Gallery. + +To be truly cross platform and support invoking a resource's method under another +credential, Linux/Unix OSes creates another process under that user. In Windows +it is also possible to Impersonate a user, using `Win32.AdvApi32` for instance. + +In WMF 5.1, the LCM is in charge of this. But in PowerShell 7+, the only cross platform +way to do this is by using PowerShell Jobs, which are relatively slow, heavy, and +a bit more tricky to troubleshoot, as they need a way to serialize and deserialize +objects. + +In PowerShell, executing commands as job returns what we informally call "dead objects": +the object after it was serialized and then deserialized, pertaining most of its +properties but not an "live" object that still has its methods available. + +Here, we could have `Invoke-DscResource` to always use Jobs, but that would severely +impact performance, and would make troubleshooting difficult. + +We could, as initially thought, handle both case: directly as the current user when +`PsDscRunAsCredential` is not specified, and as Job when specified, but it would +then have two different behavior, depending on the `-Properties` value (and not +the command's actual signature), obfuscating the potential issue to the user. + +In the end, this is very much an Agent feature, and each agent author may want to +(and already do) support this themselves, so it's unnecessary code and complexity +for them. + +For those reasons, and with the possibility that an elegant or standardized solution +emerges from the community, we believe it's best to leave it outside the scope of +the `Invoke-DscResource` MVP. + +In order to enable existing users to support the same behavior than the LCM, +we will try to provide, separately, a function that wraps around this `Invoke-DscResource` +and creates a job when `PsRunAsCredential` is specified, but this won't be part +of the `PSDesiredStateConfiguration` module work. + ## Invoke-DscResource will not clear the Builtin Provider Cache The Built-in provider cache, located in `$env:ProgramData\Microsoft\Windows\PowerShell\Configuration\BuiltinProvCache`, is currently cleared by the LCM (in WMF 5.1). From 1ebe52f53db3d30cb70fc7df68d8e67c8437e131 Mon Sep 17 00:00:00 2001 From: Gael Date: Tue, 13 Aug 2019 19:18:44 +0200 Subject: [PATCH 2/4] Update 1-Draft/RFCXXXX-RFC-Invoke-DscResource.md Co-Authored-By: Travis Plunk --- 1-Draft/RFCXXXX-RFC-Invoke-DscResource.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/1-Draft/RFCXXXX-RFC-Invoke-DscResource.md b/1-Draft/RFCXXXX-RFC-Invoke-DscResource.md index 6e739bc5..afe90c5b 100644 --- a/1-Draft/RFCXXXX-RFC-Invoke-DscResource.md +++ b/1-Draft/RFCXXXX-RFC-Invoke-DscResource.md @@ -58,7 +58,7 @@ Invoke-DscResource [-Name] [-Method] -ModuleName Date: Tue, 13 Aug 2019 19:19:30 +0200 Subject: [PATCH 3/4] Update 1-Draft/RFCXXXX-RFC-Invoke-DscResource.md Co-Authored-By: Travis Plunk --- 1-Draft/RFCXXXX-RFC-Invoke-DscResource.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/1-Draft/RFCXXXX-RFC-Invoke-DscResource.md b/1-Draft/RFCXXXX-RFC-Invoke-DscResource.md index afe90c5b..36396c0e 100644 --- a/1-Draft/RFCXXXX-RFC-Invoke-DscResource.md +++ b/1-Draft/RFCXXXX-RFC-Invoke-DscResource.md @@ -70,7 +70,7 @@ This should run in the current session state where the command is invoked. #### PsDscRunAsCredential: throw exception if supplied After more discussions (with @Jaykul & @TravisEz13) and thinking this through, -it is not right to build the support for PsDscRunAsCredential in this command +it is **not** right to build the support for PsDscRunAsCredential in this command (more on why later in this RFC). It's the user's responsibility to wrap the call in the required user context From ec4ba142e5974cd684997a84457bbd91955e59ba Mon Sep 17 00:00:00 2001 From: gaelcolas Date: Tue, 13 Aug 2019 19:25:25 +0200 Subject: [PATCH 4/4] updating GET result as per Travis comment --- 1-Draft/RFCXXXX-RFC-Invoke-DscResource.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/1-Draft/RFCXXXX-RFC-Invoke-DscResource.md b/1-Draft/RFCXXXX-RFC-Invoke-DscResource.md index 36396c0e..407e314c 100644 --- a/1-Draft/RFCXXXX-RFC-Invoke-DscResource.md +++ b/1-Draft/RFCXXXX-RFC-Invoke-DscResource.md @@ -119,8 +119,8 @@ It is up to the user to sequence the execution safely, or to create appropriate ##### Get -The `GET` function in DSC resources returns a Hashtable, and this will be the same -for `Invoke-DscResource` in PS7+. +The `GET` function invoked via the LCM (WMF 5.1) returns a CIM representation of a hashtable, +and will be a `hashtable` for `Invoke-DscResource` in PS7+. ##### Test