In Deploy Photon 2.0 – Part 1, we showed how to create a Template with the Photon 2.0 guest OS. In Part 2 we will introduce the New-PhotonVM function, which allows to create one or more VMs, based on the template created in Part 1.

The basic concept for the New-PhotonVM function is the same as for the New-PhotonTemplate function. The configuration for the VMs is driven by a JSON file that is passed as an argument to the function.
Create a Photon VM
This step is fully automated and driven by a JSON configuration file. In a matter of minutes you can create one or more Photon 2.0 VMs without even logging on to the machines!
The JSON Configuration file
The objective is again, as with the creation of the Template, to have all configuration parameters in a flat text file. This enables us to easily place the configuration of the VMs under version control and allows us to easily compare between versions.
The JSON file contains a number of Level-1 entries, each specifying part of the final configuration of the Photon VMs.

- vSphere: describes the Location for the template
- Code: a collection of customisation scripts.
- VM: an array of specifications for the VMs
vSphere

- VMHost: a cluster or an ESXi node where the VM will be installed. If you specify a cluster, the script takes a random ESXi node in that cluster.
- Storage: a datastorecluster or datastore where the VM will be installed.
Code

- Name: the name of this piece of code. Will be used later when creating VMs.
- Script: the customisation script, stored as an array of lines.
VM

- Name: the name of the VM to deploy
- Folder: a VM type folder where the VM shall stored in
- Deploy: a switch to define if this specific VM shall be created yes or no.
- TemplateName: the template from which the VM shall be created
- VMNote: content for the Note field of the VM. The #timestamp# field will be replaced by the actual date on which the VM is created
- NumCpu, MemeoryGB, HarddiskGB, GuestId: regular VM properties
- Network: a section with the network parameters for the VM
- Account: the root or administrator account to be used to login to the guest OS (as defined in the New-PhotonTemplate function).
- CustomisationCode: the names of the customisation scripts in the Code section that need to be executed inside the guest OS. The “reboot” entry is a reserved name, and will cause a reboot of the guest OS
Network

- Portgroup: the portgroup to which the vNic shall be connected
- IPAddress: the IP address
- Netmask: in CIDR notation
- Gateway: the gateway IP address
- DNSServers: one or more DNS servers. Multiple entries are separated with a space.
- Domain: the DNS domain to which the VM belongs
- NTPServers: one or more NTP servers. Multiple entries are separated with a space.
Account

- User, Password: the root credentials
The New-PhotonVM function
Before you can run the New-PhotonVM function, you will need two functions that are used in the function. These are
- Invoke-VMScriptPlus from my Invoke-VMScriptPlus v2 post.
You have multiple options to make this function available to the New-PhotonVM function.
- Add it to the .ps1 file where you copied the New-PhotonVM function
- Store the function in a separate .ps1 file, and dot-source that .ps1 files before calling the New-PhotonVM function
- Create a module, and add the function to that module
The Code
function New-PhotonVM {
<#
.SYNOPSIS
Create a Photon 2.0 VM from a template
.DESCRIPTION
This function will create a new VM from a Template with the Photon 2.0
guest OS. The parameters and the configuration scripts are passed via
a JSON file.
.NOTES
Author: Luc Dekens
Version:
1.0 11/08/18 Initial release
1.1 16/08/18 VMHost (in JSON file) accepts cluster of vmhost
Added 'reboot' option
Added 'Deploy' switch (in JSON file)
.PARAMETER JSONPath
The location of the JSON file with the configuration parameters
.PARAMETER LogFile
Optional file for capturing logging information.
This includes the output of the customisation scripts
.EXAMPLE
New-PhotonVM -JSONPath .\photon.json
.EXAMPLE
New-PhotonVM -JSONPath .\photon.json -LogFile .\photon.log
#>
[cmdletbinding()]
param(
[Parameter(Mandatory = $true)]
[string]$JSONPath,
[string]$LogFile
)
function Write-ToLog {
[CmdletBinding()]
param(
[string]$Category,
[string]$Text
)
$timeStamp = (Get-Date).ToString('yyyyMMddThhmmss')
$script = Split-Path -Path $myInvocation.ScriptName -Leaf
$user = $env:UserName
$line = "$timeStamp - $script - $user - [$Category] $Text"
if ($LogFile) {
$line | Out-File -FilePath $LogFile -Append
}
else {
$line
}
}
function Invoke-VMReboot {
[CmdletBinding()]
param(
[string]$VMName
)
$vmGuest = Get-VMGuest -VM $VMName
Stop-VMGuest -VM $vm -Confirm:$false | Out-Null
while ($vmGuest.VM.PowerState -ne 'PoweredOff') {
Start-Sleep 1
$vmGuest = Get-VMGuest -VM $vmGuest.VM
}
$vmGuest = Start-VM -VM $vmGuest.VM -Confirm:$false | Get-VMGuest
while ($vmGuest.VM.PowerState -ne 'PoweredOn' -or -not $vmGuest.ExtensionData.GuestOperationsReady) {
Start-Sleep 1
$vmGuest = Get-VMGuest -VM $vmGuest.VM
}
}
#region Get Parameters
$paramDataJSON = Get-Content -Path $JSONPath | Out-String
$paramData = ConvertFrom-Json -InputObject $paramDataJSON
# Determine location for VM
$obj = Get-Inventory -Name $paramData.vSphere.VMHost
if ($obj -is [VMware.VimAutomation.ViCore.Types.V1.Inventory.Cluster]) {
$obj = Get-VMHost -Location $obj | Get-Random
}
$esx = $obj
$dsc = Get-DatastoreCluster -Name $paramData.vSphere.Storage -ErrorAction SilentlyContinue
if ($dsc) {
$ds = Get-Datastore -RelatedObject $dsc | Get-Random
}
else {
$ds = Get-Datastore -Name $paramData.vSphere.Storage
}
foreach ($vmInfo in $paramData.VM) {
# Do we need to deploy this VM
if(-not $vmInfo.Deploy){
continue
}
# Clean up artifacts
if ($vm = Get-VM -Name $vmInfo.Name -ErrorAction SilentlyContinue) {
if ($vm.PowerState -eq [VMware.VimAutomation.ViCore.Types.V1.Inventory.PowerState]::PoweredOn) {
Stop-VM -VM $vm -Confirm:$false | Out-Null
}
Remove-VM -VM $vm -Confirm:$false -DeletePermanently
Write-ToLog -Category Info -Text "Removed VM $($vm.Name)"
}
# Create VM
$sVM = @{
Name = $vmInfo.Name
Template = $vmInfo.TemplateName
VMHost = $esx
Datastore = $ds
Notes = $vmInfo.VMNote.Replace('#timestamp#', (Get-Date -Format 'dd/MM/yyyy HH:mm'))
}
if($vmInfo.Folder){
$sVM.Add('Location',(Get-FolderByPath -Path $vmInfo.Folder))
}
$vm = New-VM @sVM
Write-ToLog -Category Info -Text "Created VM $($vmInfo.Name)"
# Configure VM
Write-ToLog -Category Info -Text "Configuring network for VM $($vmInfo.Name)"
Get-NetworkAdapter -VM $vm | Set-NetworkAdapter -NetworkName $vmInfo.Network.Portgroup -StartConnected:$true -Confirm:$false > $null
Write-ToLog -Category Info -Text "Starting VM $($vmInfo.Name)"
Start-VM -VM $vm > $null
while ($vm.ExtensionData.Guest.ToolsRunningStatus -ne [VMware.Vim.VirtualMachineToolsRunningStatus]::guestToolsRunning -or
$vm.ExtensionData.Runtime.PowerState -ne [VMware.Vim.VirtualMachinePowerState]::poweredOn) {
sleep 2
$vm.ExtensionData.UpdateViewData()
}
Write-ToLog -Category Info -Text "VM $($vmInfo.Name) started"
# Run all customisation scripts
foreach ($code in $vmInfo.CustomisationCode) {
if ($code -eq 'reboot') {
Write-ToLog -Category Info -Text "Rebooting VM $($vm.Name)..."
Invoke-VMReboot -VMName $vm.Name
Write-ToLog -Category Info -Text "Rebooted VM $($vm.Name)"
}
else {
$codeObj = $paramData.Code.Where{$_.Name -eq $code}
$sInvoke = @{
VM = Get-VM -Id $vm.Id
ScriptType = 'Bash'
ScriptText = $ExecutionContext.InvokeCommand.ExpandString(($codeObj.Script -join "rn"))
GuestUser = $vmInfo.Account.User
GuestPassword = ConvertTo-SecureString -String $vmInfo.Account.Password -AsPlainText -Force
GuestOSType = 'Linux'
}
if($codeObj.Environment){
$sInvoke.Add('ScriptEnvironment',$codeObj.Environment.foreach{$ExecutionContext.InvokeCommand.ExpandString($_)})
}
Write-ToLog -Category Info -Text "Running $code"
$result = Invoke-VMScriptPlus @sInvoke
if ($LogFile) {
$result | Out-File -FilePath $LogFile -Append
}
else {
$result
}
}
}
}
}
Annotations
Line 34-52: An inline function to have all messages in the same format.
Line 54-73: A reboot the guest OS function. Called when the “reboot” instruction is encountered. See later.
Line 77-78: These lines read the JSON file and convert the data to a PowerShell object
Line 82-86: The vSphere.VMHost field can contain a cluster or an ESXi node. These lines handle those options. In case of a cluster, the function selects a random ESXi node from the cluster.
Line 88-94: The vSphere.Storage field can contain a DatastoreCluster or a Datastore. These lines handle those options. In case of a datastorecluster, the function selects a random datastore from the datastorecluster.
Line 96: the function will run through all entries under the VM field
Line 100-102: Only deploy the VM when the Deploy field says true
Line 105-111: These lines check if there is already a VirtualMachine with the name as specified in VM.Name. If there is, the VirtualMachine is removed.
Line 114-132: The VM is created
Line 126: The Get-FolderByPath function can be found in Folder By Path
Line 133-139: The VM is powered on, and the function waits till the VMware Tools are available
Line 145-173: The function runs all the requested customisation scripts, as defined in the VM.CustomisationCode field.
Line 146-151: This handles the reserved “reboot” name, and restarts the guest OS. The inline function Invoke-VMReboot waits till the VMware Tools are available again.
Sample Run
The actual call to the New-PhotonVM function is quite simple. The function only has two parameters, the location of the JSON file (JSONPath), and optionally a file where the output of the function will be saved (LogFile). If no LogFile is given, the output will be shown in the console.
$logFile = 'C:\Temp\photon-template.log' $json = '.\LabPhoton.json' New-PhotonVM -JSONPath $json -LogFile $logFile
The logfile contains the key steps in the function, and also the output produced by the calls to Invoke-VMScriptPlus.
A sample extract of such a log file.

Files
Attached to this post is an empty, skeleton JSON file and to be used with the New-PhotonVM function.
Next
In Part 3 of this series I will be showing some examples of what you can do with such Photon 2.0 VMs, and more specifically containers.
Enjoy!
David S
Is part three of this series posted?
LucD
Not yet, coming shortly.
synth3tk
“The New-PhotonVM function” section mentions needing two functions, but fails to talk about the second one (Get-FolderByPath). I ran into errors because of it.