Recently I needed to script some actions for a VM on Nutanix AHV.
I wanted to share with you some of the commands I found and used.
I created a small function (Wait-NTNXTask) that verifies the task and waits until the task is finished.
Pleas note that this is optional and not required to run the commands specified in this blog.
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 | function Wait-NTNXTask { [cmdletbinding()] Param( # taskUuid returned from Nutanix commands [Parameter(Mandatory=$true, ValueFromPipeline=$true)] [ValidateNotNullOrEmpty()] [string]$taskUuid, # If you don't want any data returned, specify this parameter [Parameter(Mandatory=$false)] [switch]$silent ) Begin { if ([string]::IsNullOrEmpty($(Get-PSSnapin -Name NutanixCmdletsPSSnapin -Registered))) { Add-PSSnapin NutanixCmdletsPSSnapin } $task = [PSCustomObject]@{ status = $null taskUuid = $taskUuid } try { [System.Guid]::Parse($taskUuid) | Out-Null $valid=$true } catch { $valid=$false } $notFinished = $true $i=0 } Process { if($valid) { do { try { $taskData = Get-NTNXTask -Taskid $task.taskUuid $task.status = $taskData.progressStatus Write-Verbose "Task: $($taskData | Format-List | Out-String)" if ($taskData.progressStatus -eq "Queued") { Write-Verbose "Waiting for task to complete. Status: $($taskData.progressStatus)" Write-Progress -Activity "Waiting for task to complete" -Status "Task $($taskData.progressStatus)" -PercentComplete 1 Start-Sleep -Seconds 1 } if ($taskData.progressStatus -eq "Running") { Write-Verbose "Waiting for task to complete. Status: $($taskData.progressStatus)" Write-Progress -Activity "Waiting for task to complete" -Status "Task $($taskData.progressStatus)" -PercentComplete 50 Start-Sleep -Seconds 1 } if ($taskData.progressStatus -in "Succeeded","Aborted","Failed") { Write-Verbose "Status: $($taskData.progressStatus)" Write-Progress -Activity "Waiting for task to complete" -Status "Task $($taskData.progressStatus)" -PercentComplete 100 -Completed $notFinished = $false } if ([string]::IsNullOrEmpty($taskData.progressStatus)) { Write-Verbose "Unknown status. Status: `"$($taskData.progressStatus)`"" $task.status = "Unknown" if($i -gt 10) { Break } else { $i++ } Start-Sleep -Seconds 1 } } catch { Write-Warning "Caught an error: $($_.Exception.Message | Out-String)" Break } } while ($notFinished) } } End { if (-Not $Silent) { Return $task } } } |
To start with Nutanix AHV and PowerShell you need to install the PowerShell Cmdlets. You can find the snap-ins when you click on your name and select “Download Cmdlets Installer”
Add the snap-ins to your script or session:
1 2 3 4 5 6 7 8 9 10 11 | if ([string]::IsNullOrEmpty($(Get-PSSnapin -Name NutanixCmdletsPSSnapin -Registered -ErrorAction SilentlyContinue))) { if (Test-Path "C:\Program Files (x86)\Nutanix Inc\NutanixCmdlets\powershell\import_modules\ImportModules.PS1") { . "C:\Program Files (x86)\Nutanix Inc\NutanixCmdlets\powershell\import_modules\ImportModules.PS1" } else { Write-Error "Could not load NutanixCmdletsPSSnapin" } } else { if ([string]::IsNullOrEmpty($(Get-PSSnapin -Name NutanixCmdletsPSSnapin -ErrorAction SilentlyContinue))) { Add-PSSnapin NutanixCmdletsPSSnapin } } |
If you want to view all the commands associated to “NutanixCmdletsPSSnapin” run the following command:
1 | Get-Command -PSSnapin NutanixCmdletsPSSnapin | Group-Object Noun | Select-Object Count,Name,@{Name="Verb"; Expression = {$_.Group.Verb -join ","}} | Sort-Object Name |
View the Cmdlet (version) information:
1 | Get-NTNXCmdletsInfo |
Before we can make changes we need to create a connection:
1 2 3 4 5 6 7 8 9 | $hypervisorURI = "nutanixcluster.domain.local" $userName = "john" $password = ConvertTo-SecureString -String "SuperSecretP@ssw0rd" -AsPlainText -Force # Ensure previous Nutanix Sessions are disconnected Disconnect-NTNXCluster * #Connect a new Nutanix Session $connection = Connect-NutanixCluster -Server $hypervisorURI -UserName $username -Password $password -AcceptInvalidSSLCerts -ForcedConnection |
NOTE: If you receive the following error “The remote server returned an error: (401) Unauthorized.” You will need to reconnect. May be that the connection has timed out.
Get the VM so we can use the ID’s:
1 | $vm = Get-NTNXVM -SearchString $vmName |
Create a new snapshot for a given VM:
1 2 3 4 5 6 | $snapshotName = "SnapshotName" $newSnapshot = New-NTNXObject -Name SnapshotSpecDTO $newSnapshot.vmuuid = $vm.uuid $newSnapshot.snapshotname = $snapshotName $task = New-NTNXSnapshot -SnapshotSpecs $newSnapshot Wait-NTNXTask -taskUuid $task.taskUuid -silent |
Retrieve all the available snapshots for a given VM:
1 | $snapshots = Get-NTNXSnapshot | Where-Object {$_.vmUuid -eq $vm.uuid} |
Get a particular snapshot for a given VM, if there are multiple snapshots with the same name all will be returned. In this example we will retrieve the last available snapshot:
1 2 | $snapshotName = "SnapshotName" $snapshot = Get-NTNXSnapshot | Where-Object {($_.vmUuid -eq $vm.uuid) -and ($_.snapshotname -eq $snapshotName)} | Select-Object -Last 1 |
Revert back to a snapshot for a given VM:
1 2 3 4 | $snapshotName = "SnapshotName" $snapshot = Get-NTNXSnapshot | Where-Object {($_.vmUuid -eq $vm.uuid) -and ($_.snapshotname -eq $snapshotName)} | Select-Object -First 1 $task = Restore-NTNXVirtualMachine -Vmid $vm.vmId -SnapshotUuid $snapshot.uuid Wait-NTNXTask -taskUuid $task.taskUuid -silent |
Removing one or more snapshots for a given VM:
1 2 3 4 5 6 7 | $snapshotName = "SnapshotName" $snapshots = Get-NTNXSnapshot | Where-Object {($_.vmUuid -eq $vm.uuid) -and ($_.snapshotname -eq $snapshotName)} Foreach ($snapshot in $snapshots){ Write-Verbose "Removing snapshot:$($snapshot | Select-Object snapshotName,uuid | Format-List | Out-String)" -Verbose $task = Remove-NTNXSnapshot -Uuid $snapshot.uuid Wait-NTNXTask -taskUuid $task.taskUuid -silent } |
You can also add or remove disk to a given VM. Below is a working example how to remove disks and add them again with the same parameters:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 | $CurrentDisks = Get-NTNXVMDisk -Vmid $vm.vmId -IncludeDiskSizes | Where-Object {$_.isCdrom -eq $false} $CurrentDisks = $CurrentDisks | Sort-Object id If(-not [string]::IsNullOrEmpty($CurrentDisks)) { #Remove Disk(s) Foreach ($CurrentDisk in $CurrentDisks){ Write-Verbose "Removing disk: $($CurrentDisk.id) with size: $($CurrentDisk.vmDiskSize / 1GB)GB" -Verbose $task = Remove-NTNXVMDisk -Vmid $vm.vmId -Diskaddress $CurrentDisk.id Wait-NTNXTask -taskUuid $task.taskUuid -silent } #Add (new) disks with the same specification Foreach ($CurrentDisk in $CurrentDisks){ Write-Verbose "Creating disk specification. Disksize: $($CurrentDisk.vmDiskSize / 1GB)" -Verbose $diskSpecCreate = New-NTNXObject -Name VmDiskSpecCreateDTO $diskSpecCreate.containerid = $CurrentDisk.containerId $diskSpecCreate.size = $CurrentDisk.vmDiskSize Write-Verbose "Specification:$($diskSpecCreate | Select-Object containerId,size | Format-List | Out-String)" -Verbose $newVMDisk = New-NTNXObject –Name VMDiskDTO $newVMDisk.vmDiskCreate = $diskSpecCreate $task = Add-NTNXVMDisk -Vmid $vm.vmId -Disks $newVMDisk Wait-NTNXTask -taskUuid $task.taskUuid -silent } } |
You can also manipulate the CD-ROM drive attached to your VM to mount or un-mount an ISO file.
First we need to retrieve the details for the CD-ROM drive attached to a given VM:
1 | $isoDisk = Get-NTNXVMDisk -Vmid $vm.vmId | Where-Object {$_.isCdrom -eq $true} |
It can be that you have multiple CD-ROM drives attached to a given VM. Make sure you have selected only one.
In the next example we will check if there are multiple drives, if so we’ll select the first one. (You can make your selection as you see fit)
1 | $isoDisk = Get-NTNXVMDisk -Vmid $vm.vmId | Where-Object {$_.isCdrom -eq $true} | Select-Object -First 1 |
To check if a CD-ROM drive already contains an image or is empty:
1 | $isoDisk.isEmpty |
To list and get the names of all the available ISO files uploaded you can run the following command
1 | Get-NTNXImage | Where-Object {$_.imageType -eq "ISO_IMAGE"} | Select-Object name |
To mount an ISO to a (existing) CD-ROM drive.
1 2 3 4 5 6 7 8 9 10 11 12 13 | #Specify the name of the ISO and retrieve the object $isoImageName = "Windows 10 Business Editions 1803 EN" $isoImage = (Get-NTNXImage | Where-Object {$_.name -eq $isoImageName}) #Create new objects with the required changes $diskSpecClone = New-NTNXObject -Name VMDiskSpecCloneDTO $diskSpecClone.vmDiskUuid = $isoImage.vmDiskId $diskUpdateSpec = New-NTNXObject -Name VMDiskUpdateSpecDTO $diskUpdateSpec.vmDiskClone = $diskSpecClone #Write the changes to the VM $task = Set-NTNXVMDisk -Vmid $vm.vmId -Diskaddress $isoDisk.id -UpdateSpec $diskUpdateSpec Wait-NTNXTask -taskUuid $task.taskUuid -silent |
To un-mount an ISO attached the CD-ROM drive:
1 2 3 4 | $diskUpdateSpec = New-NTNXObject -Name VMDiskUpdateSpecDTO $diskUpdateSpec.isEmpty = $true $task = Set-NTNXVMDisk -Vmid $vm.vmId -Diskaddress $isoDisk.id -UpdateSpec $diskUpdateSpec Wait-NTNXTask -taskUuid $task.taskUuid -silent |
If you want NIC details, for example if you want to know the MAC Address of a given VM:
1 | Get-NTNXVMNIC -Vmid $vm.vmId |
And finally how to turn on or off a given VM.
Power on a given VM:
1 2 | $task = Set-NTNXVMPowerOn -Vmid $vm.vmId Wait-NTNXTask -taskUuid $task.taskUuid -silent |
Power off a given VM:
1 2 | $task = Set-NTNXVMPowerOff -Vmid $vm.vmId Wait-NTNXTask -taskUuid $task.taskUuid -silent |
Specifying the transition, for example to nicely shutdown a given VM:
1 2 | $task = Set-NTNXVMPowerState -Vmid $vm.vmId -Transition ACPI_SHUTDOWN Wait-NTNXTask -taskUuid $task.taskUuid -silent |
The following Transitions can be specified:
- ACPI_REBOOT
- ACPI_SHUTDOWN
- OFF
- ON
- PAUSE
- POWERCYCLE
- RESET
- RESUME
- SUSPEND
Recently Kees Baggerman informed me that Nutanix was working on some new PowerShell Cmdlets. Unfortunately I didn’t had the time to look at them.
Hope this will help you.
TY! This will probably save me a few hours of pull all of this stuff together and looks like most of the items I’ll need to create my automation scripts 😀
You’re welcome
Hi – All I’m trying to do is automate snapshots and I am just not getting it. I can connect to cluster fine, but when i run:
$snapshotName = “SnapNameHere”
$newSnapshot = New-NTNXObject -Name SERVERNAME-HERE
$newSnapshot.vmuuid = $vm.uuid
$newSnapshot.snapshotname = $snapshotName
$task = New-NTNXSnapshot -SnapshotSpecs $newSnapshot
I get errors like ‘vmuuid’ cannot be found on this object.
The Property ‘snapshotname’ cannot be found on this object.
snapshot spec must be specified.
I am sorry for not following any established guidelines for posting code, I could not find them.
Hi Deniece,
Looks like you forgot to retrieve the VM first. Can you try with the following code?
$vmName = "SERVERNAME-HERE"$snapshotName = "SnapNameHere"
$vm = Get-NTNXVM -SearchString $vmName
$newSnapshot = New-NTNXObject -Name SnapshotSpecDTO
$newSnapshot.vmuuid = $vm.uuid
$newSnapshot.snapshotname = $snapshotName
$task = New-NTNXSnapshot -SnapshotSpecs $newSnapshot