Day 40: Troubleshooting PowerShell DSC Failures with the DSC Windows Event Logs

Welcome to Day 40 of the “100 Days of DevOps with PowerShell”! For background on our goals in this series, see Announcing the “100 Days of Devops with PowerShell” Series here at SCC.

Today, I am going to call attention to a simple, but powerful bit of information that will help you troubleshoot issues when PowerShell DSC does NOT work like you expect it should.

  • For example, if you were configuring automatic deployment of DSC modules to your managed nodes  (like in Day 21 – Deploying Modules via Pull Server), you will find an event in the DSC Windows Event Log on the managed node.
  • Likewise, if you failed to install a DSC module on the DSC Pull Server, you can find an error message in a different DSC-related Windows Event Log on the Pull Server.

Like other Windows Event Logs, DSC Windows event log messages are split over the three types of logs (operational, analytic and debug). As you will see in a minute, DSC event messages are structured so that every event message begins with a job ID that represents a DSC operation. The same PowerShell cmdlets (Get-WinEvent -LogName “Microsoft-Windows-DSC/Operational”) and command line techniques (like Wevutil) you use to retrieve errors can be used here as well, though this is not how I most often leverage PowerShell DSC event logs.

You could even use System Center 2012 Operations Manager (SCOM) to watch for events in the PowerShell DSC Windows Event Logs to proactively identify DSC issues….a homegrown DSC management pack of sorts.

Sample Environment (for this tutorial)

The sample environment used in this tutorial consists of two machines:

  • SERVER1.contoso.com – A Windows Server 2012 R2 system with 2 GB RAM that is configured as a DSC HTTPS Pull Server. This system is domain-joined to the Contoso.com domain.
  • SERVER3.contoso.com – A Windows 2012 R2 system that is a workgroup member. The server will serve as a managed system (node) that will retrieve its configuration file from the pull server.

For today, we’ll not overthink it. We will keep our discussion simple and focused. Let’s take a quick look at a couple of common failures when you are configuring PowerShell DSC and see how quickly and easily we can spot the root cause.

Troubleshooting PowerShell DSC Nodes (Managed Computers) 

The log for identifying problems on the DSC nodes can be found in the following tree in the Event Viewer:

Applications and Services Logs –> Microsoft –> Windows –> Desired State Configuration

I can force SERVER3 to evaluate its configuration and retrieve and apply its configuration mof file by running this code:

The resulting event (a success event) in the Desired State Configuration Event Log is as follows:

image

As you can see, the DSC event messages begins with a job ID.

Identifying Failures

To simulate a failure, I am going to stop the PSDSCPullServer web site in IIS Manager on the DSC Pull Server.

Now, when I run the same PowerShell snippet on SERVER3 to force the node to evaluate its configuration, I get a different result in the Desired State Configuration Event Log. Note the Configuration ID you see in the URL in this event is the Guid of your managed node.

image

The resulting event in this case clearly identifies a failed call to the DSC Pull Server. This is the same event you would see if a firewall rule were blocking calls to the Pull Server. You can identify myriad configuration issues in this same fashion.

Troubleshooting DSc Pull Server Issues

The Desired State Configuration Event Log exists on the DSC Pull Server as well (for issues related to it’s local configuration), but there is an event log specific to the DSC Pull Server role. This log appears in the following location in the Event Viewer tree:

Applications and Services Logs –> Microsoft –> Windows –> PowerShell-DesiredStateConfiguration-PullServer

In this case, I forgot to install the xWebAdministration module on the DSC Pull Server, and I see the following event:

image

As you can see, you can find root cause of most issues related to PowerShell DSC using the default DSC logging levels with no additional configuration.

Conclusion

I hope today filled in another piece of the puzzle in your PowerShell DSC journey.  Please post comments and errata in the Comments section below.

Previous Installments

To see the previous installments in this series, visit “100 Days of DevOps with PowerShell”.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.