Leveraging Powershell DSC in Chef Habitat Templates

Powershell DSC (Desired State Configuration) is a small configuration management engine that ships with modern versions of Windows and can be installed on older versions via the Windows Management Framework (WMF) version 5.1. Many larger scale Configuration management systems like Chef and others now wrap their own resources around Powershell DSC.

To leverage DSC in a Chef Habitat plan, you need to do two things:

  • Create a DSC Configuration file in the plan's config directory
  • Declare a runtime dependency on the core/dsc-core package and use its Start-DscCore command to apply the above configuration.

Our DSC Configuration

Add the following code to a file named website.ps1 in the config directory of your plan.

Configuration NewWebsite
{
Import-DscResource -Module xWebAdministration
Node 'localhost' {
xWebAppPool {{cfg.app_pool}}
{
Name = "{{cfg.app_pool}}"
Ensure = "Present"
State = "Started"
}
xWebsite {{cfg.site_name}}
{
Ensure = "Present"
Name = "{{cfg.site_name}}"
State = "Started"
PhysicalPath = Resolve-Path "{{pkg.svc_path}}"
ApplicationPool = "{{cfg.app_pool}}"
BindingInfo = @(
MSFT_xWebBindingInformation
{
Protocol = "http"
Port = {{cfg.port}}
}
)
}
xWebApplication {{cfg.app_name}}
{
Name = "{{cfg.app_name}}"
Website = "{{cfg.site_name}}"
WebAppPool = "{{cfg.app_pool}}"
PhysicalPath = Resolve-Path "{{pkg.svc_var_path}}"
Ensure = "Present"
}
}
}

This is going to configure all application specific IIS entities (app pool, website, app folder) so that the web server points to our application directory and listens on the configured port. The net result is that when DSC finishes applying this configuration, our web site should be browsable.

Chef Habitat Templating

Note that all files in your plan's config or hooks directories are processed by the Chef Habitat Supervisor's template rendering system at runtime before they are ever interpreted by Powershell. Chef Habitat templates use Handlebars syntax to manipulate the final template content and pull in values at runtime that reflect the state of the Supervisor ring environment. The Handlebars syntax uses double curly braces {{ }} for including templating logic.

Using runtime settings in templates

Chef Habitat allows you to reference configuration values set at runtime. These can be helpful in your templates if you need to reference port numbers, IP addresses, or other values when performing business logic during the lifecycle of your running service.

You can use runtime configuration settings in your templates. These include user-created configuration settings defined by you in your config file, or built-in values defined by Chef Habitat.

Applying the DSC Configuration

As long as the $pkg_deps of our plan.ps1 include core/dsc-core, we can call the Start-DscCore function it exports from the Powershell module included in the dsc-core package.

Start-DscCore (Join-Path {{pkg.svc_config_path}} website.ps1) NewWebsite

We will include this in our run hook explained later, but this essentially hides the complexity involved in applying a DSC configuration from the Powershell Core runtime bundled with the Supervisor.

Hooks as templates and using helper functions

Like the files in your config directory, hooks are also rendered by the Supervisor as templates using Handlebars syntax. In all templates, not only do you have acces to runtime values, you can also use custom helper functions.

For the complete list of helper functions, see Handlebars Helpers.

Next: Define Hooks