diff options
Diffstat (limited to 'RELEASE_NOTES.md')
| -rw-r--r-- | RELEASE_NOTES.md | 145 |
1 files changed, 144 insertions, 1 deletions
diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index 5076ec0f4a..2a59d97736 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -1,2 +1,145 @@ -# Chef Client Release Notes 12.1.1: +# Chef Client Release Notes 12.2.0: +## Desired State Configuration (DSC) Resource + +If you are using `Windows Management Framework(WMF) 5`, you can now take advantage of the new `dsc_resource`. +This new functionality takes advantage of WMF 5's `Invoke-DscResource` cmdlet to +directly invoke resources. + +### Prerequisites + +To use this new resource, you must have the February preview of WMF 5. +This can be installed using the Powershell cookbook. It is also required that +the Local Configuration Manager(LCM) be configured with a `RefreshMode` of `Disabled`. +Doing this will preclude you from using `dsc_script`. Below we provide an example +DSC configuration: + +```powershell +# create a configuration command to generate a meta.mof to set Local Configuration Manager settings + +Configuration LCMSettings { + Node localhost { + LocalConfigurationManager { + RefreshMode = 'Disabled' + } + } +} + +# Run the configuration command and generate the meta.mof to configure a local configuration manager +LCMSettings +# Apply the local configuration manager settings found in the LCMSettings folder (by default configurations are generated +# to a folder in the current working directory named for the configuration command name +Set-DscLocalConfigurationManager -path ./LCMSettings +``` + +Running this script tells the LCM not to do document management, allowing Chef to +take over that role. While you may be able to switch this to other values mid-run, +you should not be doing this to run both `dsc_script` and `dsc_resource` resources. + +### Usage + +Once the LCM is correctly configured, you can begin using `dsc_resource` in your recipes. +You can get a list of available by running the `Get-DscResource` command. You will be +able to use any resource that does not have an `ImplementedAs` property with value +`Composite`. + +As an example, let's consider the `User` dsc resource. Start by taking a look +at what a DSC `User` resource would look like + +``` +> Get-DscResource User + +ImplementedAs Name Module Properties +------------- ---- ------ ---------- +PowerShell User PSDesiredStateConfiguration {UserName, DependsOn, Descr... + +``` + +We see here that is `ImplementedAs` is not equal to `Composite`, so it is a resource that can +be used with `dsc_resource`. We can what properties are accpeted by the `User` resource by +running + +``` +> Get-DscResource User -Syntax + +User [string] #ResourceName +{ + UserName = [string] + [ DependsOn = [string[]] ] + [ Description = [string] ] + [ Disabled = [bool] ] + [ Ensure = [string] { Absent | Present } ] + [ FullName = [string] ] + [ Password = [PSCredential] ] + [ PasswordChangeNotAllowed = [bool] ] + [ PasswordChangeRequired = [bool] ] + [ PasswordNeverExpires = [bool] ] +} +``` + +From above, the `User` resource has a require property `UserName`, however we're probably +also going to want to prover at the very least a `Password`. From above, we can see the `UserName` +property must be of type string, and `Password` needs to be of type `PSCredential`. Since there +is no native Ruby type that maps to a Powershell PSCredential, a dsl method `ps_credential` is +provided that makes creating this simple. `ps_credential` can be called as `ps_credential(password)` +or `ps_credential(username, password)`. Under the hood, this creates a +`Chef::Util::Powershell::PSCredential` which gets serialized into a Powershell PSCredential. + +The following type translations are supported: + +| Ruby Type | Powershell Type | +|-------------------------------------|-----------------| +| Fixnum | Integer | +| Float | Double | +| FalseClass | bool($false) | +| TrueClass | bool($true) | +| Chef::Util::Powershell:PSCredential | PSCredential | +| Hash | Hashtable | +| Array | Object[] | + +With this information in hand, we can now construct a Chef `dsc_resource` resource that creates +a user. + +```ruby +dsc_resource 'create foo user' do + resource :User + property :UserName, 'FooUser' + property :Password, ps_credential("P@ssword!") + property :Ensure, 'Present' +end +``` + +#### Third Party Resources +`dsc_resource` also supports the use of 3rd party DSC resources, for example the DSC Resource Kit. These +resources can be used just like you would use any `PSDesiredStateConfiguration` resource like `User`. Since +the implementation of `dsc_resource` knows how to talk to DSC resources that are visible through the +`Get-DscResource` cmdlet, it should just work. For example, if we wanted to use `xSmbShare`, we could +construct the powershell resource as + +```ruby +dsc_resource 'create smb share' do + resource :xSmbShare + property :Name, 'Foo' + property :Path, 'C:\Foo' +end +``` + +This would execute + +``` +> Get-DscResource xSmbShare + +ImplementedAs Name Module Properties +------------- ---- ------ ---------- +PowerShell xSmbShare xSmbShare {Name, Path, ChangeAccess, ... +``` + +to look up the module name, and in this case use `xSmbShare`. However, this lookup process can slow down +the process. It is also possible that there are multiple DSC resources with that name. To address these +cases, `dsc_resource` provides an aditional attribute `module_name`. You can pass the name of the module +that the resource comes from, and `dsc_resource` will make sure that it uses that module. This will +short-circuit any logic to lookup the module name, shortening the time it takes to execute the resource. + +## Notes + +- The implementation of `dsc_resource` is base on the experimental Invoke-DscResource cmdlet |