Windows ChefNodeCmdlet

Get-ChefNode

This cmdlet allows PowerShell scripts to query for current machine state from the Chef node which is currently used by RightLink. Of course there are other sources of machine state in PowerShell (e.g. WMI), but some of the information you need may be retrieved from the Chef node with a quick cmdlet call. In addition to containing details about the local machine state, the Chef node can also preserve details discovered by PowerShell scripts for use by other recipes (see Set-ChefNode). As a general rule, you have to know what to ask for before you ask for it in the course of writing an action script. The trick is knowing what to ask for. If you request a node path which is not valid in the Chef node, a $NULL will be returned. It is possible to distinguish between an unknown value and a value which is set to null by testing the parent hash to see if the key exists (i.e. get the parent hash and call .Contains("<key name>")) See below for tips on exploring the node tree in debug mode.

Set-ChefNode

It can be useful to persist both static and dynamic information in a convenient form for future recipes to query. Doing so will allow those recipes to execute faster and make it easier for the scripts to be idempotent. The alternative would be to query needed information directly from the machine each time, which could present a bottleneck for getting an instance online quickly if the same-named resource is referenced to perform multiple actions. For example, it is much quicker to check a stored list of databases and their backup/restore history than to get a database connection and make a SQL query for the appropriate records. The speed advantage of using cached information which may become stale over querying machine state directly each time load_current_resource is called depends on the problem being solved. If your script relies on cached information, then it will need to be more robust in handling errors which result from using stale information.

The Set-ChefNode cmdlet solves this problem by giving the PowerShell script a convenient tool for persisting any needed information. A variety of basic data types are supported which include arrays and hashes that allow for building complex data structures in the Chef node. When the Path parameter indicates a deep path (i.e. multiple array elements in Path), then a hierarchy of hashes is implied and will be automatically created during the Set-ChefNode operation if it does not already exist. If a similarly named hash already exists, then it is extended by insertion or replacement of value. If a similarly named non-hash value exists, then it is replaced by a new hash containing only the value to be set. There is no warning for replacing an existing non-hash value. It is poor practice to replace any of the pre-existing Chef node values, so be sure to use only unique hash keys for storing your custom node information.

Although the value type can be inferred in many cases by Set-ChefNode, it is best practice to explicitly qualify value type when setting a value retrieved by function call to ensure the retrieved value matches your expected type. If you were to rely on inference for brevity in these cases then automatic type coercion might result in an unexpected type being stored in the Chef node, leading to failures in other scripts (on either the Ruby or PowerShell side). As any type may be safely coerced to string type, explicit use of -StringValue will not provide extra protection and so string values can always be abbreviated. If you require type checking on strings, then you must write an if-check surrounding the Set-ChefNode call.

Example:

$foo = FunctionCall()
if ($foo -and ($foo.GetType() -eq [System.Type]::GetType("System.String")))
{ set-chefnode x,y,z $foo }
else
{ Write-Error 'not a string' }

The value type parameters (-StringValue, -Int32Value, etc.) are mutually exclusive; you can only declare one type per value, per call to Set-ChefNode. Although none of the type parameters are required, it is required that exactly one type parameter be used in each call to Set-ChefNode.

Example:

Here is an example of combining Get-ChefNode and Set-ChefNode using hash values:

set-chefnode my_hash @{x="X";y="Y"}      # effect on Ruby side: @node["my_hash"] = {"x" => "X", "y" => "Y"}
$myHash = get-chefnode my_hash           # retrieve hash stored on Ruby side
$myHash.y = @{a="A";b="B"}               # alter the y value from string value "Y" to a subhash locally
$myHash.z = 123                          # insert and set the z value to 123 locally
set-chefnode my_hash -HashValue $myHash  # effect on Ruby side: @node["my_hash"] = {"x" => "X", "y" => {"a" => "A", "b" => "b"}, "z" = 123}
set-chefnode my_hash,y,c C               # effect on Ruby side: @node["my_hash"]["y"]["c"] = "C"

Get-NewResource

When a recipe references a resource and invokes an action upon it, a resource object is created and passed to the action for execution. The resource contains attributes which the action needs to reference during execution. PowerShell scripts also need to reference the resource object's attributes in order to function. The mechanism provided for this is the Get-NewResource cmdlet.

The lifetime of each new_resource object in Chef is the duration of the load_current_resource method plus the action method. The identity of the new_resource object is context-sensitive and the context will be maintained properly between invocations of PowerShell scripts (i.e. the new_resource context will change appropriately between invocations of the same action script).

The interface for Get-NewResource is identical to the Get-ChefNode cmdlet with the following differences:

• The Path parameter represents the name of a public attribute from the resource object. If the attribute is a hash, then the comma-delimited Path parameter represents an index into that hash beginning with the named hash attribute.
• The empty Path parameter will return a hash of all available attributes from the resource object.

Set-NewResource

A recipe may wish to alter specific attributes in the new_resource object between load_current_resource and the execution of an action script. The script may wish to supply default values, for example, for any value set to nil.

Note that any changes to new_resource are not persisted and are not available to other recipes;

The interface for Set-NewResource is identical to the Set-ChefNode cmdlet with the following differences:

• The Path parameter behaves as described in Get-NewResource.
• Setting values on the new_resource is subject to any validation behavior coded into the lightweight resource class. Validation errors will appear in the $Error list object in PowerShell as a result of attempting to set an invalid value on new_resource. It is standard practice to invoke $Error.Clear() on the list prior to making a call which may result in an error so that you can test if the error list is non-empty after the call.

Get-CurrentResource

Some providers may want to record the current state of a given resource in an object with the same set of attributes as the new_resource (but not necessarily the same values as new_resource). For this purpose, Chef providers maintain a temporary object known as current_resource between invocation of load_current_resource and the action methods. Chef does not initialize this object; it is the provider implementation (i.e. the PowerShell scripts) which must initialize this object (see Set-CurrentResource) or else ignore it entirely.

The lifetime of each current_resource object in Chef is the duration of load_current_resource method plus the action method. The identity of the current_resource object is context-sensitive and the context will be maintained properly between invocations of PowerShell scripts (i.e. the current_resource context will change appropriately between invocations of the same action script).

The interface for Get-CurrentResource is identical to the Get-NewResource cmdlet.

Set-CurrentResource

The load_current_resource script may wish to configure the current_resource object to represent the existing state of the resource. The Set-CurrentResource cmdlet provides this functionality.

Note that any changes to current_resource are not persisted and are not available to other recipes.

The interface for Set-CurrentResource is identical to the Set-NewResource cmdlet.

Get-NextAction

This cmdlet is used internally by RightLink to drive the PowerShell process. PowerShell scripts must avoid any attempt to invoke this cmdlet directly as this will lead to unexpected behavior.