Getting Started¶

About PowerShell Service¶

Powershell_script resource in a normal Chef run is limited to a single PowerShell runspace.
When the resource execution is completed, all variables and object are garbage collected and are not accessible anymore.
This has major affects on the way we write cookbooks using PowerShell: a PowerShell configuration script cannot be structured in multiple resources and/or files.
For extensive PowerShell scripting, this ends up to an unreadable and long scripts in a single powershell_script resource and/or using template for config scripts.
Also Ruby runtime is 32-bit which limits powershell_script to only 32-bit binaries and CmdLets, e.g. Microsoft Exchange Server and SharePoint.

Blu PowerShell service (a part of the blu cookbook) is meant to address both issues.
This Windows service which is installed automatically when you add blu cookbook to the node run_list, invokes a PowerShell runspace which is valid during the life cycle of the Windows service.
The objects are only garbage collected when it is specifically requested in the recipe.

The following code disposes Blu PowerShell runspace:

# Dispose Blu PowerShell Runspace
blu_script 'DisposeRunspace' do
    code 'DisposeRunspace'
action :run
end

The following screenshot illustrates how Blu PowerShell Service escapes the 32-bit Ruby/Chef boundary during Microsoft Exchange 2016 setup and runs ExSetup.exe in a 64-bit address space:

Using blu_script Chef resource¶

Chef defines a resource as follows:

A resource is a statement of configuration policy that:

• Describes the desired state for a configuration item
• Declares the steps needed to bring that item to the desired state
• Specifies a resource type—such as package, template, or service
• Lists additional details (also known as resource properties), as necessary
• Are grouped into recipes, which describe working configurations
• Where a resource represents a piece of the system (and its desired state), a provider defines the steps that are needed to bring that piece of the system from its current state into the desired state.

The blu_script resource inherits all behavior of a Chef resource and is defines in the blu cookbook in the script.rb file:

actions :run
actions :define
default_action :run
attribute :code, kind_of: String, required: true

The provider that supports this resource is also defined in the blu cookbook as follow:

action :run do
new_resource.updated_by_last_action(true)
execute "blu_script" do
    cwd node['blu']['root']
    command "#{node['blu']['root']}\\BluShell.exe -Command \"#{new_resource.code}\""
    only_if { ::Win32::Service.exists?('BluService') }
end
end

action :define do
new_resource.updated_by_last_action(true)
execute "blu_script" do
    cwd node['blu']['root']
    command "#{node['blu']['root']}\\BluShell.exe -Define \"#{new_resource.code}\""
    only_if { ::Win32::Service.exists?('BluService') }
end
end

You can use blu_script resource in recipe like the powershell_script resource. In the following example we load Active Directory management snap-in by the define action:

# Load AD module
blu_script 'Load AD module' do
code <<-EOF
    If (!(Get-module ActiveDirectory)) { Import-Module ActiveDirectory }
    If (!(Get-module ServerManager)) { Import-Module ServerManager }
EOF
action :define
end

A good practice is to define variables and snap-in by action :define and run PowerShell converge scripts by action :run so that PowerShell code is more readable and also you can take advantage of other mechanisms of define action like type conversion.
Marshalling between Ruby and PowerShell is covered later in this document.

Marshalling and Type conversion¶

Currently there are 4 new data types are added to the blu namespace, namely blu_true, blu_false, blu_nil and blu_array:

default['myapp']['attribute1'] = 'blu_true'
default['myapp']['attribute2'] = 'blu_false'

# Boolean attributes in PowerShell variables
blu_script 'boolean attributes in powershell variables' do
code <<-EOF
    $Attribute1  = '#{node['myapp']['attribute1']}'
    $Attribute2  = '#{node['myapp']['attribute2']}'
EOF
action :define
end

# Boolean attributes in PowerShell
blu_script 'boolean attributes in powershell' do
code <<-EOF
    if ($Attribute1)
    {
        # Do some work
    }

    if (!$Attribute2)
    {
        # Do some other works
    }
EOF
action :run
end

default['myapp']['attribute3'] = 'blu_nil'

# Null in PowerShell
blu_script 'null in powershell variable' do
code <<-EOF
    $Attribute3  = '#{node['myapp']['attribute3']}'
EOF
action :define
end

blu_script 'null in powershell' do
code <<-EOF
    if ($Attribute3 -eq $Null)
    {
        # Do some work
    }
EOF
action :run
end

my_array = "blu_array@('<string1>', '<string2>', '<string3>')"

default['myapp']['attribute4'] = "blu_array@('pizza', 'ravioli', 'macaroni')"

# Define array in PowerShell
blu_script 'array in powershell variables' do
code <<-EOF
    $Foods  = '#{node['myapp']['attribute4']}'
EOF
action :run
end

# Array in PowerShell
blu_script 'array in powershell' do
code <<-EOF
    foreach ($ItalianFood in $Foods) {
        # buon appetito
    }
EOF
action :run
end

Guards and interpreters¶

Because blu_script is a Chef LWRP, all the syntax and rules of a resource guard and interpreters are valid, example:

default['myapp']['guard'] = 'down'

# Guard in blu_script
blu_script 'guard example' do
code <<-EOF
    if ($Attribute3 -eq $Null)
    {
        # Do some work
    }
EOF
action :run
only_if { node['myapp']['guard'] == 'down' }
end

Notifiers¶

You can use blu_script notifiers like other resources in Chef, for example:

# Reboot handler
reboot 'if_pending' do
action :nothing
only_if { reboot_pending? }
end

# Notifier in blu_script
blu_script 'notifier example' do
code <<-EOF
    if ($Attribute3 -eq $Null)
    {
        # Do some work
    }
EOF
action :run
notifies :reboot_now, 'reboot[if_pending]'
end

About BluStation¶

BluStation.dll is currently an experimental library for Blu project which contains:

• A fully functional Chef API layer (BluApi.dll) written in C#
• A Chef DSL language transpiler to convert Ruby syntaxt to PowerShell (BluLang.dll)
• A GUI that can be started as a PowerShell CmdLet to interact wit BluApi and BluLang libraries in a graphical mode

Import BluStation to PowerShell¶

Copy BluStation.sll into C:\Blu folder and then import the module using:

cd C:\Blu
Import-Module .\BluStation.dll

To check if BluStation is loaded correctly, run:

Get-Module

Connect to Chef API¶

To connect to Chef API use Connect-Chef CmdLet:

Parameters:

Connect-Chef
    -Org <Chef Organization Uri>(Required)
    -Client <ClientName>(Required)
    -Node <NodeName>(Optional)

    -Validator <ValidatorName>(Optional)
    -KeyPath <drive:\path\to\validation_key.pem>(Optional)
    -Key <RSA key as string>(Optional)
    (either -Key or -Key file should be used and validated)

This CmdLet saves the configuration prvided by the above parameters to Windows registry in the below path:

HKEY_LOCAL_MACHINE\SOFTWARE\Blu\Config

Example:

Connect-Chef -Org https://chef.mycompany.com/organizations/myorganisation -Client Computer01 -KeyPath c:\chef\client.pem -Node Computer01

If all the configuration is ok, you will recieve a message as:

14-03-2016 16:11:54 | OK    | Using Organization Name: myorganisation and Uri: https://chef.mycompany.com/organizations/myorganisation
14-03-2016 16:11:54 | OK    | Using Client Name: Computer01
14-03-2016 16:11:54 | OK    | Using Node Name: Computer01
14-03-2016 16:11:54 | OK    | Using RSA Key : c:\chef\client.pem
14-03-2016 16:11:54 | API   | Method : GET
14-03-2016 16:11:54 | API   | Client : Computer01
14-03-2016 16:11:54 | API   | organizationUri : https://chef.mycompany.com/organizations/myorganisation
14-03-2016 16:11:54 | API   | resource : clients/Computer01
14-03-2016 16:11:54 | API   | getUri : https://chef.mycompany.com/organizations/myorganisation/clients/Computer01
14-03-2016 16:11:54 | API   | XOpsProtocol(Computer01, https://chef.mycompany.com/organizations/myorganisation/clients/Computer01);


 __          __    __
 \ \        / /_  / /_  __
  \ \      / __ \/ / / / /
   \ \    / /_/ / / /_/ /
    \_\  /_.___/_/\__,_/
═══════════════════════════════
14-03-2016 16:11:54 | OK    | Connected!
14-03-2016 16:11:54 | INFO  | Client Name: Computer01 / Organization: myorganisation
14-03-2016 16:11:54 | API   | Method : GET
14-03-2016 16:11:54 | API   | Client : Computer01
14-03-2016 16:11:54 | API   | organizationUri : https://chef.mycompany.com/organizations/myorganisation
14-03-2016 16:11:54 | API   | resource : nodes/Computer01
14-03-2016 16:11:54 | API   | getUri : https://chef.mycompany.com/organizations/myorganisation/nodes/Computer01
14-03-2016 16:11:54 | API   | XOpsProtocol(Computer01, https://chef.mycompany.com/organizations/myorganisation/nodes/Computer01);
14-03-2016 16:11:55 | OK    | Recieved Node json for: Computer01

Using Chef API¶

Access to Chef API from PowerShell namespace is provided by Use-ChefApi CmdLet:

Parameters:

Use-ChefAPI
    -Select <Chef endpoint>(Optional)
    -Path <Api Path>(Optional)
    -Node <NodeName>(Optional)
    -Format <data format>(optional) [json, dictionary]

In this example we request the number of CPUs for Computer01 from Ohai data:

Use-ChefAPI -Select nodes/SBPLT240 -Path automatic/cpu/total

API Graphical User Interface¶

To start the Chef API graphical user interface, use Show-UI CmdLet without any parameters:

Show-UI

This UI provides a configurable GUI to Chef API (all configuration are saved and loaded from the same registry key) and an interface to experimental DSL transpiler.

Screenshots:¶

Chef API interface:

Transpiler interface:

BluAPI¶

BluLang¶

BluIpc¶

BluService¶

BluShell¶