Merge pull request #3117 from chef/jdm/dsc-rel-notes

DSC Resource release notes

1 files changed, 118 insertions, 126 deletions

diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
index 4d0a6cc7ef..2a59d97736 100644
--- a/RELEASE_NOTES.md
+++ b/RELEASE_NOTES.md
@@ -1,153 +1,145 @@
-# Chef Client Release Notes 12.1.0:
-
-# Internal API Changes in this Release
-
-## Experimental Audit Mode Feature
-
-This is a new feature intended to provide _infrastructure audits_.  Chef already allows you to configure your infrastructure
-with code, but there are some use cases that are not covered by resource convergence.  What if you want to check that
-the application Chef just installed is functioning correctly?  If it provides a status page an audit can check this
-and validate that the application has database connectivity.
-
-Audits are performed by leveraging [Serverspec](http://serverspec.org/) and [RSpec](https://relishapp.com/rspec) on the
-node.  As such the syntax is very similar to a normal RSpec spec.
-
-### Syntax
-
-```ruby
-control_group "Database Audit" do
-
-  control "postgres package" do
-    it "should not be installed" do
-      expect(package("postgresql")).to_not be_installed
-    end
-  end
-
-  let(:p) { port(111) }
-  control p do
-    it "has nothing listening" do
-      expect(p).to_not be_listening
-    end
-  end
-
-end
+# 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
 ```
 
-Using the example above I will break down the components of an Audit:
-
-* `control_group` - This named block contains all the audits to be performed during the audit phase.  During Chef convergence
- the audits will be collected and ran in a separate phase at the end of the Chef run.  Any `control_group` block defined in
- a recipe that is ran on the node will be performed.
-* `control` - This keyword describes a section of audits to perform.  The name here should either be a string describing
-the system under test, or a [Serverspec resource](http://serverspec.org/resource_types.html).
-* `it` - Inside this block you can use [RSpec expectations](https://relishapp.com/rspec/rspec-expectations/docs) to
-write the audits.  You can use the Serverspec resources here or regular ruby code.  Any raised errors will fail the
-audit.
-
-### Output and error handling
-
-Output from the audit run will appear in your `Chef::Config[:log_location]`.  If an audit fails then Chef will raise
-an error and exit with a non-zero status.
-
-### Further reading
-
-More information about the audit mode can be found in its
-[RFC](https://github.com/opscode/chef-rfc/blob/master/rfc035-audit-mode.md)
-
-# End-User Changes
-
-## OpenBSD Package provider was added
+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.
 
-The package resource on OpenBSD is wired up to use the new OpenBSD package provider to install via pkg_add on OpenBSD systems.
+### Usage
 
-## Case Insensitive URI Handling
+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`.
 
-Previously, when a URI scheme contained all uppercase letters, Chef
-would reject the URI as invalid. In compliance with RFC3986, Chef now
-treats URI schemes in a case insensitive manner.
+As an example, let's consider the `User` dsc resource. Start by taking a look
+at what a DSC `User` resource would look like
 
-## File Content Verification (RFC 027)
-
-Per RFC 027, the file and file-like resources now accept a `verify`
-attribute.  This attribute accepts a string(shell command) or a ruby
-block (similar to `only_if`) which can be used to verify the contents
-of a rendered template before deploying it to disk.
-
-## Drop SSL Warnings
-Now that the default for SSL checking is on, no more warning is emitted when SSL
-checking is off.
-
-## Multi-package Support
-The `package` provider has been extended to support multiple packages. This
-support is new and and not all subproviders yet support it. Full support for
-`apt` and `yum` has been implemented.
+```
+> Get-DscResource User
 
-## chef_gem deprecation of installation at compile time
+ImplementedAs   Name                      Module                         Properties
+-------------   ----                      ------                         ----------
+PowerShell      User                      PSDesiredStateConfiguration    {UserName, DependsOn, Descr...
 
-A `compile_time` flag has been added to the chef_gem resource to control if it is installed at compile_time or not.  The prior behavior has been that this
-resource forces itself to install at compile_time which is problematic since if the gem is native it forces build_essentials and other dependent libraries
-to have to be installed at compile_time in an escalating war of forcing compile time execution.  This default was engineered before it was understood that a better
-approach was to lazily require gems inside of provider code which only ran at converge time and that requiring gems in recipe code was bad practice.
+```
 
-The default behavior has not changed, but every chef_gem resource will now emit out a warning:
+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
 
 ```
-[2015-02-06T13:13:48-08:00] WARN: chef_gem[aws-sdk] chef_gem compile_time installation is deprecated
-[2015-02-06T13:13:48-08:00] WARN: chef_gem[aws-sdk] Please set `compile_time false` on the resource to use the new behavior.
-[2015-02-06T13:13:48-08:00] WARN: chef_gem[aws-sdk] or set `compile_time true` on the resource if compile_time behavior is required.
+> 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] ]
+}
 ```
 
-The preferred way to fix this is to make every chef_gem resource explicit about compile_time installation (keeping in mind the best-practice to default to false
-unless there is a reason):
+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
-chef_gem 'aws-sdk' do
-  compile_time false
+dsc_resource 'create foo user' do
+  resource :User
+  property :UserName, 'FooUser'
+  property :Password, ps_credential("P@ssword!")
+  property :Ensure, 'Present'
 end
 ```
 
-There is also a Chef::Config[:chef_gem_compile_time] flag which has been added.  If this is set to true (not recommended) then chef will only emit a single
-warning at the top of the chef-client run:
-
-```
-[2015-02-06T13:27:35-08:00] WARN: setting chef_gem_compile_time to true is deprecated
-```
-
-It will behave like Chef 10 and Chef 11 and will default chef_gem to compile_time installations and will suppress
-subsequent warnings in the chef-client run.
+#### 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
 
-If this setting is changed to 'false' then it will adopt Chef-13 style behavior and will default all chef_gem installs to not run at compile_time by default.  This
-may break existing cookbooks.
-
-* All existing cookbooks which require compile_time true MUST be updated to be explicit about this setting.
-* To be considered high quality, cookbooks which require compile_time true MUST be rewritten to avoid this setting.
-* All existing cookbooks which do not require compile_time true SHOULD be updated to be explicit about this setting.
-
-For cookbooks that need to maintain backwards compatibility a `respond_to?` check should be used:
-
-```
-chef_gem 'aws-sdk' do
-  compile_time false if respond_to?(:compile_time)
+```ruby
+dsc_resource 'create smb share' do
+  resource :xSmbShare
+  property :Name, 'Foo'
+  property :Path, 'C:\Foo'
 end
 ```
 
-## Knife Bootstrap Validatorless Bootstraps and Chef Vault integration
-
-The knife bootstrap command now supports validatorless bootstraps.  This can be enabled via deleting the validation key.
-When the validation key is not present, knife bootstrap will use the user key in order to create a client for the node
-being bootstrapped.  It will also then create a node object and set the environment, run_list, initial attributes, etc (avoiding
-the problem of the first chef-client failing and not saving the node's run_list correctly).
+This would execute 
 
-Also knife vault integration has been added so that knife bootstrap can use the client key to add chef vault items to
-the node, reducing the number of steps necessary to bootstrap a node with chef vault.
+```
+> Get-DscResource xSmbShare
 
-There is no support for validatorless bootstraps when the node object has been precreated by the user beforehand, as part
-of the process any old node or client will be deleted when doing validatorless bootstraps.  The old process with the validation
-key still works for this use case.  The setting of the run_list, environment and json attributes first via knife bootstrap
-should mitigate some of the need to precreate the node object by hand first.
+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.
 
-## Windows service now has a configurable timeout
+## Notes
 
-You can now set the amount of time a chef-client run is allowed when running the provided windows service. This can be configured by
-setting `windows_service.watchdog_timeout` in your `client.rb` to the number of seconds desired. The default value is 2 hours.
+- The implementation of `dsc_resource` is base on the experimental Invoke-DscResource cmdlet