Update documentation / release notes

3 files changed, 262 insertions, 0 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 016bde47f1..9221959e6f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -69,6 +69,7 @@
 
 ### Chef Contributions
 
+* Add `dsc_script` resource to Chef for PowerShell DSC support on Windows
 * Fixed Config[:cache_path] to use path_join()
 * Updated chef-zero to 3.0.
 * knife cookbook site download/list/search/share/show/unshare now uses
diff --git a/DOC_CHANGES.md b/DOC_CHANGES.md
index 1ef0a7830c..d421f7bf01 100644
--- a/DOC_CHANGES.md
+++ b/DOC_CHANGES.md
@@ -76,3 +76,251 @@ Note that the service resource will also continue to set the startup type to aut
 DSL method `data_bag_item` now takes an optional String parameter `secret`, which is used to interact with encrypted data bag items.
 If the data bag item being fetched is encrypted and no `secret` is provided, Chef looks for a secret at `Chef::Config[:encrypted_data_bag_secret]`.
 If `secret` is provided, but the data bag item is not encrypted, then a regular data bag item is returned (no decryption is attempted).
+
+
+### New dsc\_script resource
+
+The `dsc_script` resource for Windows systems that allows cookbook authors to embed [PowerShell Desired
+State Configuration](http://technet.microsoft.com/en-us/library/dn249912.aspx)
+(DSC) script code or re-use existing DSC script
+artifacts in a cookbook. It is similar to other Chef `script` resources like
+`powershell_script` in that it allows another language to be used from within
+the Chef Domain Specific Language (DSL). 
+
+#### DSC Prerequisites
+
+Use of the `dsc_script` resource requires the following components on a
+Windows system:
+
+* **PowerShell version 4.0**, which can be configured on the target system through Chef using the
+[PowerShell cookbook](https://supermarket.getchef.com/cookbooks/powershell)
+available at [Chef Supermarket](http://supermarket.getchef.com).
+* **WinRM** service enabled: The **WinRM** service can be enabled on the
+    system by executing the command
+
+    `winrm quickconfig`
+    
+
+#### What is DSC?
+
+DSC is described in detail at the [PowerShell DSC site](http://technet.microsoft.com/en-us/library/dn249912.aspx). In summary, DSC is a tool similar to Chef for describing the configuration of a system and enacting the configuration. DSC uses a DSL based on the concept of *resources*, which are conceptually the same as resources in the Chef DSL. Like Chef, DSC is idempotent. Because of these similarities, it natural and useful to be able to use DSC from Chef.
+
+Unlike Chef, DSC's DSL is embedded in the PowerShell language environment; Chef's is embedded in Ruby. DSC is exposed in PowerShell through the `Configuration` language element, which takes a PowerShell script block and other parameters similar to a PowerShell function. Within the script block are instances of resources, very much the way resources in Chef are given within a recipe.
+
+The `dsc_script` resource allows this PowerShell DSC code to be embedded within a Chef recipe.
+
+Many DSC resources are exact analogs of Chef resources (e.g. DSC's
+`File` resource); therefore, `dsc_script` is most useful in the context of Chef when it is utilized to manage
+resources that are *not* supported directly in Chef, such as DSC's `Archive`
+resource which decompresses **.zip** files. Another use case for `dsc_script`
+is the use in Chef of already-existing PowerShell DSC scripts that perform
+important tasks.
+
+#### `dsc_script` actions
+
+In addition to the standard `:nothing` action, this resource has the following action:
+
+|Action|Description|
+|------|-----------|
+|`:run`|This is the default action. This action triggers PowerShell DSC components of Windows to configure the system according to the configuration specified in `dsc_script`. |
+
+Note that since all DSC code is idempotent, use of guard expressions is not
+required with the `dsc_script` resource to implement idempotence. 
+
+#### `dsc_script` attributes
+
+`dsc_script` honors common Chef resource attributes in addition to the following:
+
+|Attribute|Description|
+|---------|-----------|
+|`code`|This attribute is a `String` that contains PowerShell DSC code for a configuration. If `code` is non-`nil`, it must be set to the value of a PowerShell script block (without enclosing braces) that be passed to a `Configuration` element of the PowerShell DSC DSL. This attribute **MUST NOT** be set to `nil` value if the `command` attribute is to anything other than `nil`. The default value is `nil`.|
+|`command`|Path to a .ps1 file containing PowerShell DSC script code with which to configure the node. This file must be capable of being executed as a script outside of Chef to generate a valid DSC configuration according to DSC documentation. This attribute **MUST NOT** be set `nil` if the `code` attribute is set non-`nil`. The default value is `nil`.|
+|`configuration_name`|This attribute is a `String` used to specify the name given to a `Configuration` element in the script code specified by `command` that identifies the configuration to apply. It **MUST NOT** be specified if `code` is non-`nil`. If `command` is specified and `configuration_name` is `nil`, then the configuration to be applied is specified by the `name` attribute.|
+|`configuration_data`|Used to specify [PowerShell DSC configuration data](https://supermarket.getchef.com/cookbooks/powershell). The attribute is a `String` that conforms to the [.psd1 format](http://msdn.microsoft.com/en-us/library/dd878337(v=vs.85).aspx). It **MUST** specify a node with a name of `localhost` to be used with the `dsc_script` resource|
+|`configuration_data_script`| This attribute is a `string` that is a path to a `.psd1` file that **MUST** contain a node named `localhost` to be used with `dsc_script`.|
+|`flags`|This attribute is a `Hash` that contains keys of type `:symbol`. This can be used to pass parameters to the script specified by the `command` attributes for DSC code with a `Configuration` element that takes parameters. The value of each key in the hash is the parameter value to pass. This value defaults to `nil` and should not be set if `code` is set -- it is only valid if `command` is non-`nil`.|
+|`cwd`|This attribute sets the current working directory of the process that executes the DSC code, which is useful for scripts that rely on the **cwd**. |
+|`environment`| This attribute is similar to the `environment` attribute for `script` resources -- it takes keys of type `string` that represent the names of environment variables to set when executing the specified DSC script code. The value of each key is the desired value of each environment variable.|
+
+#### `dsc_script` examples
+
+Here is a recipe fragment with a simple usage of DSC embedded in the Chef
+`dsc_script` resource:
+
+```ruby
+dsc_script 'emacs' do
+  code <<-EOH
+  Environment 'texteditor'
+  {
+    Name = 'EDITOR'
+    Value = 'c:\\emacs\\bin\\emacs.exe'
+  }
+EOH
+end
+```
+
+The same DSC content could be supplied by specifying a file that contains it
+within a PowerShell `Configuration` language element using the `command`
+attribute to specify a path to the DSC script file. When using `command`, you
+mest either set the `configuration_name` attribute to the value of the argument supplied to `Configuration` in the DSC script, or just set the `dsc_script` resource's `name` attribute to that value, like this:
+
+```ruby
+dsc_script `DefaultEditor` do
+  command 'c:\dsc_scripts\emacs.ps1'
+end
+```
+
+which assumes that `c:\dsc_scripts\emacs.ps1` contains a configuration called **DefaultEditor** as in the PowerShell DSC script below:
+
+```powershell
+Configuration 'DefaultEditor'  
+{
+    Environment 'texteditor'
+    {
+      Name = 'EDITOR'
+      Value = 'c:\emacs\bin\emacs.exe'
+    }
+}
+```
+
+##### Using the `configuration_name` attribute
+
+The `configuration_name` attribute may be used to allow the `name` attribute to be set to something other than the configuration in a DSC script. In this example, `configuration_name` is used to select one of the configurations in the DSC script:
+
+```ruby
+dsc_script `EDITOR` do
+  configuration_name 'vi'
+  command 'c:\dsc_scripts\editors.ps1'
+end
+```
+
+The content of `c:\dsc_scripts\editors.ps1` in this case was:
+
+```powershell
+Configuration 'emacs'  
+{
+    Environment 'TextEditor'
+    {
+      Name = 'EDITOR'
+      Value = 'c:\emacs\bin\emacs.exe'
+    }
+}
+
+Configuration 'vi'  
+{
+    Environment 'TextEditor'
+    {
+      Name = 'EDITOR'
+      Value = 'c:\vim\bin\vim.exe'
+    }
+}
+```
+
+##### Passing parameters to DSC configurations
+
+If a DSC script specified with the `command` attribute has a configuration that takes parameters, those may be passed using the `flags` attribute:
+
+```ruby
+dsc_script `DefaultEditor` do
+  flags { :EditorChoice => 'emacs', :EditorFlags => '--maximized' }
+  command 'c:\dsc_scripts\editors.ps1'
+end
+```
+
+This could be used with the following PowerShell DSC script content for `c:\dsc_scripts\editors.ps1`
+
+```powershell
+$choices = @{'emacs' = 'c:\emacs\bin\emacs';'vi' = 'c:\vim\vim.exe';'powershell' = 'powershell_ise.exe'}
+Configuration 'DefaultEditor' 
+{
+    [CmdletBinding()]
+    param
+    (
+        $EditorChoice,
+        $EditorFlags = ''
+    )
+    Environment 'TextEditor'
+    {
+        Name = 'EDITOR'
+        Value =  "$($choices[$EditorChoice]) $EditorFlags"
+    }
+}
+```
+
+##### Using configuration data
+
+DSC's [configuration data](http://technet.microsoft.com/en-us/library/dn249925.aspx)
+feature allows further customization of DSC scripts. In some cases, such as
+setting behavior for Powershell credential data types, its use in a DSC
+configuration is required. The configuration data supplied **MUST** contain an
+entry for a node name of `localhost` to be applied by `dsc_script`. 
+
+Configuration data may be supplied directly through the `configuration_data` attribute
+of `dsc_script` or the `configuration_data_script` or by specifying the path
+to a **.psd1** with the same contents that could be supplied to `configuration_data`.
+
+The following example demonstrates DSC's `User` resource using DSC configuration
+data to create a user using a plaintext specification of a password:
+
+```ruby
+dsc_script 'BackupUser' do
+  configuration_data <<-EOH
+@{
+AllNodes = @(
+             @{
+             NodeName = "localhost";
+             PSDscAllowPlainTextPassword = $true
+             })
+}
+EOH
+  code <<-EOH
+$user = 'backup'
+$password = ConvertTo-SecureString -String "YourPass$(random)" -AsPlainText -Force
+$cred = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $user, $password
+
+User $user
+{
+    UserName = $user
+    Password = $cred
+    Description = 'Backup operator'
+    Ensure = "Present"
+    Disabled = $false
+    PasswordNeverExpires = $true
+    PasswordChangeRequired = $false
+}
+EOH
+
+configuration_data <<-EOH
+@{
+AllNodes = @(
+             @{
+             NodeName = "localhost";
+             PSDscAllowPlainTextPassword = $true
+             })
+}
+EOH
+end
+```
+
+##### Using `dsc_script` with other Chef resources
+Like any other resource in Chef, `dsc_script` can be used in concert with
+other Chef resources -- here's an example that downloads a file using Chef's
+`remote_file` resource and uncompresses it using DSC's `Archive` resource via
+`dsc_script` into a target directory:
+
+```ruby
+remote_file "#{Chef::Config[:file_cache_path]}\\DSCResourceKit620082014.zip" do
+  source 'http://gallery.technet.microsoft.com/DSC-Resource-Kit-All-c449312d/file/124481/1/DSC%20Resource%20Kit%20Wave%206%2008282014.zip'
+end
+  
+dsc_script 'get-dsc-resource-kit' do
+  code <<-EOH
+Archive reskit
+{
+    ensure = 'Present'
+    path = "#{Chef::Config[:file_cache_path]}\\DSCResourceKit620082014.zip"
+    destination = "#{ENV['PROGRAMW6432']}\\WindowsPowerShell\\Modules"
+}
+EOH
+end
+```
diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
index 33e405d273..7b7f0b6e3b 100644
--- a/RELEASE_NOTES.md
+++ b/RELEASE_NOTES.md
@@ -224,3 +224,16 @@ work properly if the remote server implemented only the Chef 10 API.
 ## CookbookSiteStreamingUploader now uses ssl_verify_mode config option
 The CookbookSiteStreamingUploader now obeys the setting of ssl_verify_mode in the client config. Was previously ignoring the
 config setting and always set to VERIFY_NONE.
+
+## New dsc\_script resource for PowerShell DSC on Windows
+The `dsc_script` resource is new in Chef with this release. `dsc_script`
+allows the invocation of
+[PowerShell Desired State Configuration]((http://technet.microsoft.com/en-us/library/dn249912.aspx) (DSC) scripts
+from Chef recipes. The `dsc_script` resource is only available for systems
+running the Windows operating systtem with **PowerShell version 4.0 or later** installed. Windows systems may be
+updated to PowerShell version 4.0 or later using the [PowerShell cookbook](https://supermarket.getchef.com/cookbooks/powershell)
+available at [Chef Supermarket](http://supermarket.getchef.com). 
+
+The **WinRM** service required by PowerShell DSC must be enabled on the system as well in order to use
+the `dsc_script` resource -- this can be accomplished using the Windows OS `winrm quickconfig` command.
+