PASS Data Community Summit logo

PASS Data Community Summit 2023

Get all the latest announcements direct to your inbox

PowerShell Desired State Configuration: Automating and Monitoring Pull mode

The Pull mode of Desired State Configuration (DSC) is more complicated to implement because you need to meticulously manage the MOF files and their naming conventions so as to ensure that you deploy your DSC configurations correctly. In this first article of a two-part series, Nicolas Prigent describes how you can best automate this, and then in a second part on monitoring DSC he describes techniques to help you to use the pull mode as a regular part of your admin work.

  • PowerShell Desired State Configuration – Part 1: The Basics
  • PowerShell Desired State Configuration – Part 2: LCM and Push Management Model
  • PowerShell Desired State Configuration – Part 3: Pull Mode
  • PowerShell Desired State Configuration – Part 4: Automating and Monitoring Pull Mode

The ‘pull’ mode of Desired State Configuration (DSC) is not so easy to implement as ‘push’ mode. Firstly, the architecture of this mode requires a ‘pull’ server to centralize the DSC configurations. Secondly, you should, before you start, have some skills in the file protocol used, either IIS or SMB, when setting up the pull server, or to acquire the expertise as time goes by. Finally, the naming of the MOF files is more complex because you need to use the GUID of each node instead of the hostname. In my opinion, it is the main difficulty when we switch from the Push mode to the Pull mode.

In the previous section, we talked about Pull mode implementation, but before you create your DSC configurations, I first need to explain how you can manage these MOF files. Then, in the second part, I will describe a rather obscure but useful component which is called ‘compliance server.’ This component monitors all your nodes.

MOF Files management

When you are managing a large number of machines, the Pull mode is a better technical choice. This method has many advantages but also some disadvantages. It is important to keep in mind that DSC is a new technology that will be set to grow in the coming months and subsequent versions of PowerShell. The DSC community grows day by day and the Microsoft PowerShell team provides a great deal of documentation. However, in my opinion, the management of the MOF files remains the difficult point to grasp when starting off with the PowerShell Desired State Configuration.

As I’ve explained in Part 3 of this series, the name of each MOF files no longer contain a hostname, but rather a GUID.

What is a GUID?

The GUID is a sequence of letters and numbers that are used as a unique reference. GUIDs are commonly displayed as 32 hexadecimal digits with groups separated by hyphens. As part of this series on PowerShell DSC, the GUID allows us to identify unambiguously each node via the “ConfigurationID” property located in the LCM. Once a node requests its configuration from the Pull server, it uses this property to identify and obtain its own configuration. You can get this parameter via the “Get-DscLocalConfigurationManager” cmdlet:

The simplest way to create a GUID is to use the NET method NewGuid():

Remember that it is possible to indicate the GUID that you want. We will see later that it is very useful in the MOF files management.

It is also possible to convert the GUID into a string:

Finally, you can create an empty GUID:

This GUID is then used in the DSC configuration to ensure that a node gets only its configuration.

Several questions arise at this point, the most obvious being ‘Where and how do we store the GUIDs for each node?’, and ‘How do we link a GUID and a node?’

The first answer to these two questions that occurs to most of us is to create a text file or CSV file and insert a line for each node, as in the example below:

You will obtain a CSV file similar to this one:

2427-image1.png

Figure1 – CSV file

This technique, based on a single file, is, simple and effective. It lets you manage Windows and Linux machines in the same way. Furthermore, you will be able to query this file and retrieve the GUID of a node.

However, the major drawback as it stands is that it isn’t yet automated. You need to create a new GUID and then insert it into the file. Fortunately, PowerShell can automate these actions. In the example below, I created a script that accepts several parameters:

  • The name of the CSV file
  • The name of the node to insert
  • The GUID to insert
  • And what to do: create the file or update it

The CreateCSVFile function will create the CSV file.

Then the AddContentToCSVFile function updates the file.

Finally, according to the desired action, the previous functions are called.

Now, we can simply run the following command to create the CSV file:

Then this command adds content to the file:

You are probably wondering why you would need to automate this. These functions will be highlighted once we go on to automate the deployment of DSC configuration on the pull server. We will be easily able to query this CSV file.

However, there are other methods for storing the “Hostname=GUID” pair and so overcome the need for the CSV file. Depending on your environment and your technical constraints, there are three other relevant methods:

The first is based on Active Directory. In fact, each computer object in Active Directory has several properties of which one of them is called “ObjectGUID“. This therefore means that each object is uniquely identified. It is therefore possible to take this property that is created by default when a server (or a workstation) joined an Active Directory domain. This method offers several advantages:

  • Auto-generate GUID for each node.
  • No duplications are possible.
  • The link between the GUID andthe node is established simply and unambiguously.

But this also imposes some constraints:

  • To have an Active Directory domain in your environment.
  • To mainly manage Windows machines. It is quite possible to integrate Linux machines in an Active Directory, but for some of you, this may be technically impossible. To work around this, creating a computer object can be done manually.
  • It is Difficult to manage Windows machines that are not integrated with Active Directory (workgroup).

If these limitations are acceptable to you, then here’s how to get the GUID of an object using the graphical interface “Active Directory Users and Computers“. Select “View” and then “Advanced Features“. Once selected, hidden containers, tabs and attributes can be seen when editing object properties.

2427-image2.png

Figure 2: ObjectGUID property

PowerShell allows you to automate this action via the “Get-ADComputer” cmdlet:

The second method that seems interesting is to use the ID of the Hyper-V or VMWare virtual machines. As with Active Directory objects, each virtual machine has a GUID to identify it uniquely. The main disadvantage of this method is the requirement to have a fully virtualized environment, which is not necessarily the case for everyone. It will not be possible to manage the GUID of physical machines via this method. To implement it, the “Get-VM” cmdlet retrieve the GUID of a Hyper-V virtual machine:

In a VMware environment, it is possible to use the Uuid or InstanceUuid. This requires the use of PowerCLI and to enter the following commands:

Finally, the last method is to store the information in a SQL Server database. A table will thus contain two columns: “Name” and “GUID” into which the name of the node and its associated GUID will be inserted as per the example below:

2427-image3.png

Figure 3: Sample SQL Table

To generate a new GUID, you must use the “NEWUID ()” function in this way:

2427-image4.png

Figure 4: Generate GUID in SQL Server

If you want to go further in this method, I recommend starting with another article here on Simple-Talk: Practical PowerShell for SQL Server Developers and DBAs by Michael Sorens.

Automating deployment

We now have three different methods to generate a GUID, to associate it with its node and store it permanently. The idea is to get this information and to automate the publication of the MOF files on the Pull Server. We saw in the previous chapter the steps required to publish these files:

  1. Create a DSC configuration
  2. Generate the MOF files
  3. Create the “Checksum” files
  4. Finally, copy all files to the pull server

This article is aimed at being as generic as possible for all readers, so I have chosen to detail the first method which seems to me accessible to everyone. For this, I have automated the deployment process of a MOF file with the following script. This is pretty basic and is divided into four sections:

  • # PART1: Contains parameters that will be passed to the script: the filename and path of the CSV file, what to do (create, add, or publish) and finally the name of the node.
  • # PART2: Contains the DSC configuration to be applied to the node.
  • # PART3: Contains the “Create / Add / Publish” functions used in the following section.
  • # PART4: Contains the available actions that the user indicates via the script parameter. It can create the CSV file, update it or publish the DSC configuration on the node.

In order not to use the CSV file, the script should be modified to search the GUID either in the Active Directory, Hyper-V or in the SQL Server database. This script is a very basic example. Of course this can be improved or optimized its content, but the goal was to give you a start in automating a deployment.

Monitor your nodes

It is important to monitor progress in order to anticipate potential problems. DSC PowerShell is no exception to the rule. It is important to follow the deployment of your configurations and especially the compliance of your nodes. How would you know if a node has recovered its configuration, or the time at which the node queried the Pull server? Well, that is the role of the compliance server to notify you with this sort of information.

To get started, you’ll need to know the address to access the compliance server. Here is the URL structure: http://<computername>:<portnumber>/PSDSCComplainceServer.svc. To adapt it to your network environment, you must read the section on DSC configuration of the previous article. Herewith is the extract:

So, in my environment, the URL is: http://DSC01:9090/PSDSCComplianceServer.svc and you will get the following result:

2427-image5.png

Figure 5: Compliance Server Web Access

Note: If you get “Access Denied” message, try this cmdlet followed by a reboot:

If it’s still not working, then enable anonymous authentication in IIS:

2427-image6.png

Figure 6: Enable Anonymous Authentication

The “Status” method provides the status of each node that downloads its configuration from the pull service. Thus, via the following URL, you will get all the nodes in the inventory Pull service: http://DSC01:9090/PSDSCComplianceServer.svc/Status

2427-image7.png

Figure 7: The status method

It is possible to obtain more information about each node with the following properties:

  • TargetName: Node name.
  • ConfigurationID: Configuration ID associated with the node.
  • StatusCode: The status of very last pull operation on the node.
  • NodeCompliant: Chck if the node configuration is in sync with the Pull server or not.
  • ServerCheckSum: Checksum of the configuration mof file stored on the pull server.
  • TargetCheckSum: Checksum of the configuration mof file that was applied on the code.
  • LastComplianceTime: Last time the node ran the configuration successfully.
  • LastHeartbeatTime: Last time the node connected to Pull server/
  • Dirty: True if node status was recorded in the datatse, and false if not.

How to get these properties? Just use $metadata : http://DSC01:9090/PSDSCComplianceServer.svc/$metadata

2427-image8.png

Figure 8: The status properties

Note: $metadata is case sensitive.

With these few commands lines published on the Windows PowerShell Blog, it is easy to get the information about nodes:

I can now obtain the status of my two nodes:

Note: “StatusCode=0” means “Pull operation was successful”.

Now let your creative imagination run free, and you can easily format your results in HTML:

2427-image9.png

Figure 9: HTML output

Conclusion

This article was intended to highlight that the management of MOF files is the most difficult part of the pull mode. To deal with this, you can use a basic method (CSV file) or more advanced technique (Active Directory, SQL, Virtual Machine) based on your technical environment. The important thing is to use a method that works for you and with which you are comfortable.

On the other hand, it is important to follow the deployment of your DSC configurations and the compliance of your nodes. For this, the “Compliance server” component must be checked regularly to get the deployment status of your nodes.

Keep in mind that DSC is a recent technology, and that certain aspects are more complex than others to use. However, several scripts and tools are appearing that simplify its management.