summaryrefslogtreecommitdiff
path: root/RELEASE_NOTES.md
diff options
context:
space:
mode:
authorJay Mundrawala <jdmundrawala@gmail.com>2015-03-19 18:20:39 -0700
committerJay Mundrawala <jdmundrawala@gmail.com>2015-03-20 14:26:00 -0700
commit0242b50af29236e8ad7d63ac23a8a6ae377b93b0 (patch)
treeddba16c2c28ce3fe72950b054e037358f952e807 /RELEASE_NOTES.md
parent56c6e6474416946d65dfa306edd89f076d5b3b7d (diff)
downloadchef-0242b50af29236e8ad7d63ac23a8a6ae377b93b0.tar.gz
Release notes for dsc_resourcejdm/dsc-rel-notes
Diffstat (limited to 'RELEASE_NOTES.md')
-rw-r--r--RELEASE_NOTES.md244
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