The “Principles of Operation” in the title is in fact just an expensive expression for “How do I use this stuff ?”. In this post I will try to show you how you can use the vSphereDSC module, as a user, and as a contributing developer. On the side, it also shows you how you can use these vSphereDSC resources.
The vSphereDSC module contains a set of DSC resources to can be used to configure a vSphere environment. These DSC resources can be used against any vSphere Server, beit a vCenter or an ESXi node. On the condition of course that the selected resource is supported on the vSphere Server.
For “users” of the vSphereDSC resources, the post will show how to automate keeping the module up to date and how to manage the life cycle of the Configuration files that are build on the vSphereDSC resources.
For those of you that want to contribute to the development of the vSphereDSC module and it’s resources, this post will also show how you can automate the testing phase. In a first instance through a number of PowerShell scripts, in a later phase through the use of a build server.
The vSphereDSC module
The vSphereDSC is a module that contains a number of DSC resources, that you can use to configure your vSphere environment. To use the vSphereDSC resources, you will need to install the module on your systems.
The first place where you will need the module, is the station where you create and compile your DSC Configuration files.
The other place depends on which enacting method you select to use. With a Push setup, you will have to make sure the DSC Resource module is available on the target node. With a Pull setup, you will have to make the DSC Resource module available on the Pull server.
The following schema, which I shamelessly copied from Introducing PowerShell Desired State Configuration (DSC), shows a high-lelvel view of both methods.
There are some good overviews available on these two DSC methods. To name but a few:
- Getting Started with PowerShell Desired State Configuration (DSC), an MVA course with Jeffrey Snover and Jason Helmick
- Enacting configurations, in the Windows PowerShell Desired State Configuration Overview
- Pushing Configurations and Configuring a Pull Server, both in The DSC Book
- How to set up your first PowerShell DSC pull server from Adam Bertram
In my development and test environment, I use a Pull Server setup. Most of the scripts and procedures that are provided, are intended for a Pull Server setup. But the actions required for using a Push setup, are mostly the same, and simpler (fewer steps).
And one last remark, before we actually start doing things, I use the February 2016 WMF 5 release for creating the vSphereDSC classes.
Configuration files
In the vSphereDSC module, you will find a subfolder Configurations, in which there are several sample Configuration files. Let’s have a closer look at one of these files.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 |
enum Ensure { Absent Present } $tgtName = 'vEng.local.lab' $configName = 'vmw' Configuration $configName { param( [System.Management.Automation.PSCredential]$Credential ) Import-DscResource -ModuleName vSphereDSC Node $AllNodes.NodeName { $number = 0 foreach($datacenter in $Node.Datacenters) { $number++ $dcName = "Datacenter$number" VmwDatacenter $dcName { Name = $datacenter.DatacenterName Path = $datacenter.Path Ensure = $datacenter.Ensure vServer = $Allnodes.Server vCredential = $Allnodes.Credential } } } } #region VCSA Account $vcUser = '<your VCSA user>' $vcPswd = '<your VCSA user password>' $sVcCred = @{ TypeName = 'System.Management.Automation.PSCredential' ArgumentList = $vcUser,(ConvertTo-SecureString -String $vcPswd -AsPlainText -Force) } $vcCred = New-Object @sVcCred #endregion $ConfigData = @{ AllNodes = @( @{ NodeName = '*' Server = 'vcsa.local.lab' Credential = $vcCred PSDscAllowPlainTextPassword=$true PSDscAllowDomainUser = $true }, @{ NodeName = $configName Datacenters = @( @{ DatacenterName = 'DC1' Path = '/' Ensure = [Ensure]::Present } ) } ) } . "$(Split-Path $MyInvocation.MyCommand.Path)\..\..\Tools\Get-TargetGuid.ps1" $guid = Get-TargetGuid -TargetName $tgtName Invoke-Expression "$($configName) -ConfigurationData `$configData -OutputPath '.\DSC'" $pullShare = '\\pull\DSCService\Configuration\' $mof = ".\DSC\$($configName).mof" $tgtMof = "$pullshare\$guid.mof" Copy-Item -Path $mof -Destination $tgtMof New-DSCChecksum $tgtMof -Force # For testing with Start-DscCOnfiguration Copy-Item -Path $mof -Destination ".\DSC\$($tgtName.Split('.')[0]).mof" |
Annotations
Line 1-4: Enumerations that are used in the vSphereDSC Resources that are used in this Configuration file
Line 6: The hostname of the vEngine server
Line 7: The name we give to the Configuration, which will also be the name of the generated MOF file
Line 9-34,46-66: We separate the “What” and “Where” in the Configuration. The “What” is in this Configuration the way we define a vSphere Folder. The $ConfigData hash table, is the “Where”. See Separating “What” from “Where” in PowerShell DSC for some more information on this subject.
Line 36-44: In the current version of the vSphereDSC module, credentials still need to be in clear text. I plan to change that later on.
Line 68-69: The Servers that are managed by the Pull Server, need to be addressed by their unique GUID. I store those in a file, and use a short script to retrieve the GUID from that file.
Line 71: We “run” the Configuration. Note how we pass the Where via the ConfigurationData parameter. The resulting MOF file will be stored in a subfolder, named DSC, in the current folder.
Line 77: We copy the MOF file to the Pull server. During the copy, the MOF will be renamed to <GUID>.mof
Line 78: The Pull server needs to distinguish between successive versions of a Configuration file. For that reason we calculate a checksum file.
Line 81: We are going to use Start-DscConfiguration to test the Configuration, for that reason we rename the MOF file to the shortname of the vEngine Server. More on that later.
Apply the Configuration
Now that we have the MOF file, in the correct format, in place on the Pull Server, we can wait till the LCM on the vEngine Server “pulls” the Pull Server again. But we can also speed that up, by forcing the DSC Configuration to run. In the Tools folder, there is a sample script to do just that. The file is named Test-DscConfiguration.ps1.
1 2 3 4 5 |
$tgtName = 'vEng.local.lab' $configName = $tgtName.Split('.')[0] Start-DscConfiguration -ComputerName $configName -Wait -Verbose -Force -Path .\DSC |
The $tgtName variable is the name of the vEngine Server. We extract the first qualifier from the FQDN. And that was the name we gave to the MOF file in the last line of the previous script (veng.mof). The Start-DscConfiguration cmdlet will look for a MOF file in the location indicated by Path, and it will look for a MOF file with the name that is passed on the ComputerName parameter.
When all goes according to plan, you will see the Verbose messages scrolling through on the PS console. Have a look at this sample run in a short demo I recorded for the 24th VMUGBe+.
Development
During the development of the vSphereDSC module, I will regularly need to test the code I have written. In the previous section I described how you “force” your Configuration to run immediately. In this section, I’m going to describe what needs to be done to get the vSphereDSC module, in the correct format, on the Pull Server.
Scripted
This is the least advanced way of getting the vSphereDSC module to the Pull Server. It’s all done through a script. The script is provided as file vSphereDSC-Module-To-Pull-Server.ps1 in the Tools folder.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 |
$moduleName = 'vSphereDSC' $sourceFolder = "$($env:userprofile)\OneDrive\Github" $pullSrvName = 'pull.local.lab' $srcPath = "$($sourceFolder)\$($moduleName)" $pullSrv = "\\$($pullSrvName)\DscService\Modules" $localPath = $env:PSModulePath.split(';') | where{$_ -like "$($env:userprofile)*"} # Increment Version Build $modVersion = Test-ModuleManifest -Path "$($srcPath)\$($moduleName).psd1" | Select -ExpandProperty Version $newVersion = [Version]::new($modVersion.Major,$modVersion.Minor,$modVersion.Build + 1,$modVersion.Revision) Update-ModuleManifest -Path "$($srcPath)\$($moduleName).psd1" -ModuleVersion $newVersion # Copy new build to Pull server $compressedModuleName = "$($srcPath)\..\$($moduleName)_$($newVersion.Major).$($newVersion.Minor).$($newVersion.Build).$($newVersion.Revision).zip" Compress-Archive -Path "$($srcPath)\*" -DestinationPath $compressedModuleName Copy-item -Path "$($srcPath)\..\$($moduleName)_$($newVersion.ToString()).zip" -Destination $pullSrv New-DscChecksum -Path "$($pullSrv)\$($moduleName)*.zip" # Copy new build to local Modules folder if(Test-Path -Path "$localPath\$moduleName") { Get-ChildItem -Path "$localPath\$moduleName" -Recurse | Remove-Item -Recurse -Force -Confirm:$false -ErrorAction SilentlyContinue Remove-Item -Path "$localPath\$moduleName" -Recurse -Force -Confirm:$false -ErrorAction SilentlyContinue } Copy-Item -Path $srcPath -Destination $localPath -Recurse |
Annotations
Line 1-3: Specify the name of the module, the location of the module and the name of the Pull Server.
Line 5-6: Construct the source and destination paths
Line 8: To have the latest version of the vSphereDSC module on my station, I will also copy the latest version here.
Line 10-13: For each successive run of this script I increment the Build property of the Version by 1.
Line 16-19: The module needs to be stored on the Pull Server, zipped and with the Version in the filename. And again we need to create a checksum for the module file.
Line 22-27: Copy the new version locally
Once this is done, you start compiling and testing Configurations with the new version of the vSphereDSC module. See also the previous
Build Server
The automation of these steps will be automated. Documentation to follow !
With this information I hope it will be easy to start using and contributing to the vSphereDSC module !
Enjoy !