Configuring Windows with Chef and the PowerShell Resource

The PowerShell Resource in Chef is very powerful and versatile for configuring Windows. It essentially exposes all of the power of PowerShell to Chef. And since in PowerShell v.4, most Server Manager functionality is exposed via PowerShell cmdlets, there isn’t a lot you can’t configure in Windows with PowerShell.

The following recipe demonstrates some of the server configuration functionality via Chef’s PowerShell resource by performing the following actions:

  1. Timestamp: A Windows Event is created and an environmental variable is updated to show the last time this recipe was executed on the server.
  2. Enable Remote Desktop: The Remote Desktop (RDP) functionality is enabled.
  3. Disable Windows Updates: Windows automatic updates are disabled (use with caution – unless you have another update process, don’t do this).
  4. Enable Windows Remote Management: The Windows Remote Management functionality is enabled.
  5. Install IIS: The Application Server and Web Server roles are installed and enabled.

Chef Recipe:

# Leaves a timestamp indicating the last time this recipe was run on the node (this resource in intentionally not idempotent)
powershell_script "leave-timestamp" do
  code <<-EOH
    $currentTime = Get-Date
    $currentTimeString = $currentTime.ToUniversalTime().ToString()
    [Environment]::SetEnvironmentVariable("ChefClientRun","Last Chef-Client run (UTC): $currentTimeString","Machine")
    eventcreate /t INFORMATION /ID 1 /L APPLICATION /SO "Chef-Client" /D "Last Chef-Client run (UTC): $currentTimeString"
  EOH
end
 
# Enables remote desktop access to the server
powershell_script "enable-remote-desktop" do
  guard_interpreter :powershell_script
  code <<-EOH
    Set-ItemProperty -Path 'HKLM:\\System\\CurrentControlSet\\Control\\Terminal Server' -name "fDenyTSConnections" -Value 0
    Enable-NetFirewallRule -DisplayGroup "Remote Desktop"
    Set-ItemProperty -Path 'HKLM:\\System\\CurrentControlSet\\Control\\Terminal Server\\WinStations\\RDP-Tcp' -name "UserAuthentication" -Value 1
    eventcreate /t INFORMATION /ID 2 /L APPLICATION /SO "Chef-Client" /D "Enabled Remote Desktop access"
  EOH
  only_if <<-EOH
    if ((Get-ItemProperty -Path 'HKLM:\\System\\CurrentControlSet\\Control\\Terminal Server').fDenyTSConnections -ne "0") {
      $true
    } elseif ((Get-NetFirewallRule -Name "RemoteDesktop-UserMode-In-TCP").Enabled -ne "True") {
      $true
    } elseif ((Get-ItemProperty -Path 'HKLM:\\System\\CurrentControlSet\\Control\\Terminal Server\\WinStations\\RDP-Tcp').UserAuthentication -ne "1") {
      $true
    } else {
      $false
    }
  EOH
end
 
# Disables checking for updates
powershell_script "disable-update-checking" do
  guard_interpreter :powershell_script
  code <<-EOH
    $WUSettings = (New-Object -com "Microsoft.Update.AutoUpdate").Settings
    $WUSettings.NotificationLevel = 1
    $WUSettings.save()
    eventcreate /t INFORMATION /ID 3 /L APPLICATION /SO "Chef-Client" /D "Disabled Checking for Updates"
  EOH
  only_if <<-EOH
    $WUSettings = (New-Object -com "Microsoft.Update.AutoUpdate").Settings
    if ($WUSettings.NotificationLevel -ne "1") {
      $true
    } else {
      $false
    }
  EOH
end
 
# Verifies Windows Remote Management is Configured or Configures it
powershell_script "check-winrm" do
  guard_interpreter :powershell_script
  code <<-EOH
    Set-WSManQuickConfig -Force -SkipNetworkProfileCheck
    eventcreate /t INFORMATION /ID 4 /L APPLICATION /SO "Chef-Client" /D "Enabled Windows Remote Management"
  EOH
  not_if <<-EOH
    # $wsmanOutput isn't used here, just a placeholder for possible use in the future
    try {
      # Use to remove a listener for testing
      # Remove-WSManInstance winrm/config/Listener -selectorset @{Address="*";Transport="http"
      $wsmanOutput = Get-WsmanInstance winrm/config/listener -selectorset @{Address="*";Transport="http"}
      $true
    } catch {
      $wsmanOutput = "WinRM doesn't seem to be configured or enabled."
      $false
    }
  EOH
end
 
# Installs the Application-Server Role
powershell_script "install-application-server" do
  guard_interpreter :powershell_script
  code <<-EOH
    $installResult = Add-WindowsFeature Application-Server,AS-Web-Support
    foreach ($result in $installResult) {
      if ($result.RestartNeeded -eq "Yes") {
        eventcreate /t INFORMATION /ID 5 /L APPLICATION /SO "Chef-Client" /D "Restart is required."
      }
    }
    eventcreate /t INFORMATION /ID 6 /L APPLICATION /SO "Chef-Client" /D "Installed Role: Applicaiton-Server"
  EOH
  not_if <<-EOH
    if ((Get-WindowsFeature -Name Application-Server).Installed) {
      $true
    } else {
      $false
    }
  EOH
 end
Your output should look something like this (although I ran this with Test-Kitchen rather than ‘chef-client’ directly):

Note: The check-winrm script did not execute because it was already configured on the node (server).

Chef-PowerShell-1

New Windows Events should be logged to the configured node (server):

Chef-PowerShell-2

And the following web page should be viewable on the node (server):

Chef-PowerShell-3

The following practices are leveraged in this recipe:

  • A time stamp is logged on the server in order to track every time the recipe is executed. This might be helpful for troubleshooting issues by correlating with the recipe execution timestamp.
  • A Windows Event is logged every time a resource is executed on the server. Event IDs are unique to the resource function.
  • All resources (except the timestamp resource) are idempotent. In other words, logic is in place to insure the resource is not executed if it doesn’t need to be. For example, if IIS has already been installed, then there should be no attempt to install it again. This is a ‘best practice’ for writing recipes.

The following PowerShell functionality is exercised by this recipe:

  • An Environmental Variable is created/updated
  • Events are created with the ‘eventcreate’ command. The PowerShell ‘New-Event’ is not used because for Windows Server (not client) you need to register your custom event source with the server, so ‘eventcreate’ is simpler.
  • A Registry Key is added/updated
  • The Enable-FirewallRule cmdlet is used
  •  A COM object is accessed and/or updated
  • The Set-WsmanQuickConfig cmdlet is used
  • The Get-WsmanInstance cmdlet is used
  • The Add-WindowsFeature cmdlet is used

Idempotency:

Notice that nearly all the resources implement PowerShell script logic in order to make their resources follow idempotent best practices. The logic implemented is a reasonable attempt to determine if action is necessary, while not covering every possible permutation that might exist for a misconfigured server. Also notice how either $true or $false is passed back to the resource. Both conditions need to be addressed by the Guard. Also notice where ‘not_if’ and ‘only_if’ are used.

Enjoy!

Advertisements