vSphereDSC – VmwFolder

In this post I’ll introduce the first DSC resource from the vSphereDSC module, the VmwFolder resource. Since this is the first post in the series, I will also expand a bit on how the vSphereDSC module is set up and which conventions I’m using.

A vSphere Folder is a resource which can exist rather independently in an existing vSphere environment. You can easily create some test Folders to get the hang and feel of the vSphereDSC module and play with DSC Configurations based on this vSphereDSC resource.

Lay of the Land

In the Intro of this series I already mentioned some of the issues I encountered, and how these had impact on the vSphereDSC module setup. It is my intention to gradually build up the vSphereDSC module, meaning that I will keep adding DSC Resources in future posts, but I will also be providing Unit and Integration tests (with Pester) and automate the module’s build process with Appveyor.

The posts will be primarily based on a DSC Pull Server set up. This because that corresponds with what I use in my test environment, but also because I consider that architecture as the “automated” version of a DSC setup. That’s the one that you will be using in a real environment later on. This doesn’t mean that you can not test resources and Configurations without having to wait for the LCM interval to expire, as I will show later in this post.

The vSphereDSC module uses class-based DSC resources, that means you need to have WMF 5 to use the module. All my tests have been done with the WMF 5 February 2016 build on the Pull and vEngine servers, so you will need to install that version as a minimum. On the Pull server and the vEngine server, which are Windows 2012 R2 servers, I have build 5.0.10586.117.

On the Windows 10 station, that I use to write the Configuration files, I have 5.0.10586.122. Note that WMF 5 on Windows 10 is an official release, not a preview.

As a side note, there is a Wiki page (maintained by Jan Egil Ring) that lists the PowerShell builds.

Until now I have been doing my development of the vSphereDSC module from a private BitBucket repository. But as of this post, the documented parts of the vSphereDSC module will be available on Github, and from the PSGallery.

The Layout

As I already described in the Intro, the file structure of the vSphereDSC module is quite straightforward. Some design decisions were dictated by the issues that I encountered. The structure on Github now looks like this

The reason why the Helper function are in a separate file and why this is not a nested module were already explained in the Intro. In short, we need to keep the PowerCLI cmdlets outside the class methods, and due to PowerCLI PSSnapin we can not use a module. As a bypass, the vSphereDSCHelper.ps1 file is dot-sourced in the vSphereDSC.psm1 file. This looks something like this

The Code

If we look at the VmwFolder class, we can distinguish three distinct areas. Note that I use the Region directive to organise my code. This also allows me to show/hide the individual parts.

Class Properties

The Class Properties are just that, the properties that will be present in the VmwFolder class. But it is also the location where you specify the attributes of these properties. The most important one being the Key attribute. In fact all properties marked with the Key attribute will be taken together to form the “key” for a specific instance of the VmwFolder class. This “key” shall uniquely identify each instance of the VmwFolder class.

In the case of VmwFolder, the properties Path and Name are not sufficient to uniquely identify a VmwFolder instance. The reason is that we can have “Yellow” and “Blue” folders with the same name, who appear to be in the same location. The reason they appear to be in the same location is due to the hidden folders that exist in a vSphere environment.

Take for example the following situation where we seem to have a folder with the name Folder2, located under the Datacenter Homelab. From the Web Client we see the following. Is this one object or are these two different objects ?

The old C# Client, where the “Yellow” and “Blue” foldernames originated, seems to say it are two different objects, provided we take the colour as a distinghuising characteristic.

The answer, these are two different objects. And it is all due to the “hidden” folders that we could be confused. In a Datacenter object, there are pointers to the Hosts and Clusters view and the VM and Templates view. These pointers go to the hidden folders “host” and “vm” which are the respective parents for these two Folder objects that have the same name.

And that is why the Type property is a Key property for the VmwFolder class.

DSC Methods

With this I mean the three methods that DSC requires to be present in each DSC class-based resource: Test, Set and Get.

As a general rule, I try to keep the code in these methods limited to the actual function of these three methods. For example, in the Test method, the code first checks of the folder exists (line 76), then depending on the desired state ($this.Ensure), the code returns $true or $false.

Note how on line 72, the vSphereDSCHelper.ps1 file is dot-sourced. This file contains all the code where we use PowerCLI cmdlets. In this particular case we needed to that, because in line 74 we call the Helper function Connect-VmwVIServer, which uses PowerCLI cmdlets.

Class Helper Methods

In this region we code all the methods that contain the more advanced code. While the Test, Set and Get methods were limited to their basic functionality logic, these Class Helper methods contain the “deeper” code. As an example, let’s have a look at the TestVmwFolder method.

In lines 106-111 we handle the logic that composes that path to the node, in this case a Folder, that we are looking for. This path is composed of the Path and the Name property. We need to code the special case where the node could be located in the RootFolder.

When the node is found, we need to check if the type corresponds with the Type of the Folder we are looking for (lines 114-115)

It’s this kind of logic that we want to keep out of the standard Test, Set and Get methods.

Note that there are quite a bit of Write-Verbose lines in the code. This use of the Write-Verbose cmdlet is indispensable when developing DSC resources in my opinion.

External Helper Functions

These are all the functions that use PowerCLI. As already explained, we can’t use PowerCLI inside the class methods. The solution I have chosen is to keep these functions outside of the class in a separate .ps1 file.

Most of the functions in there are rather straight-forward PowerCLI-based functions. Some of these were in fact already discussed in some other posts on this blog. See Universal PowerCLI Loader, Get-InventoryPlus – Inventory of all vSphere objects and vSphere Object by Path.

Verbosity

Perhaps an interesting point to make in relation to the Write-Verbose I made earlier. We do want to see “verbose” output from the class methods and the Helper functions, but we don’t really want to see “verbose” output from all the PowerCLI cmdlets.

Instead of suppressing the verbosity on each individual cmdlet where we don’t want it, I opted for using the $PSDefaultParameterValues at the in the module.

That way I avoid the many lines that would scroll by during the loading of the PowerCLI modules and PSSnapin.

Tools

In the Tools folder I will include some scripts that I use during the development/test phase of the vSphereDSC module. The purpose and the proper use of these scripts will be explained in a separate post on the Principles of Operations.

Examples

PowerCLI

To start working with the vSphereDSC module we need to deploy PowerCLI on the vEngine Server. And obviously we are going to do that with a DSC Configuration file. The sample file is named pcli01-PowerCLI.ps1.

The Configuration I provide to push PowerCLI to the vEngine server, is similar to what Vinith Menon posted in his Automate PowerCLI Install across your Windows Environment using PowerShell DSC post. Note that the Configuration file uses the Start-DscConfiguration cmdlet to immediately start the installation of PowerCLI on the vEngine server.

If all goes well you should see “PowerCLI installed” in the verbose output.

VmwFolder

In the vSPhereDSC module a number of Configuration sample files are included.

Note that in this stage you will still need to provide the credentials of the vCenter account in clear text !

The samples are rather straight-forward. In the Principles of Operations I will show how you can organise smooth testing of your Configurations.

Filename	Target	Description
cf01-vCenter-Folder.ps1	vCenter	Create a folder
cf02-vCenter-Folder.ps1	vCenter	Create two folders
cf03-vCenter-Folder.ps1	vCenter	Create two folders with the same name, but of different type

This concludes the introduction of the VmwFolder resource.

 

Since this is the first actual vSphereDSC resource that is made public, I would love to hear your feedback. Use the Issues option on the Github repository to report feedback, bug requests, feature request…

Enjoy!