powercli extensions v2 - vmware · pdf filepowercli extensions documentation powercli...

For use only by VMware and VMware Solution Providers

Not a Customer Deliverable

PowerCLI Extensions v2.0

PowerCLI Extensions Documentation


of 13

Version History

Date Doc Ver Author Description

3 Aug 2015 1.2 Alan Renouf Various feedback and changes

19 June 2015 1.1 Alan Renouf Reviewers Comments

18 June 2015 1.0 Alan Renouf Initial doc for 2.0 version of PowerCLI Extensions



of 13

Contents

1. Overview .......................................................................................... 4

1.1 Description of solution .................................................................................................... 4

2. Installation ........................................................................................ 5

2.1 Prerequisites .................................................................................................................. 5

2.2 Installation process ........................................................................................................ 5

3. Listing all PowerCLI Extensions cmdlets .......................................... 5

4. Instant Clone Overview .................................................................... 6

5. Instant Clone Configuration .............................................................. 7

5.1 Operations supported on the parent VM ............................................................................ 7

5.2 Operations supported on the child VM ............................................................................... 8

5.3 For powered-on/off parent and child VMs .......................................................................... 8

6. Instant Clone Cmdlets ...................................................................... 8

7. Instant Clone Examples ................................................................... 8

8. Instant Clone Example script............................................................ 9

8.1 Example Linux Guest Post Script ................................................................................ 10

8.2 Example Windows Post Script ..................................................................................... 11

9. vSphere Flash Read Cache Overview ........................................... 11

10. vSphere Flash Read Cache Cmdlets ............................................ 12

11. vFlash Read Cache Examples ..................................................... 12



of 13

1. Overview

1.1 Description of solution PowerCLI Extensions gives PowerCLI users access to early access functionality by extending the core

PowerCLI cmdlets to include new experimental features and gives PowerCLI customers the ability to

provide early feedback.

In the current version (2.0) this fling allows you to manage the following features:

Instant Clone

vSphere Flash Read Cache



of 13

2. Installation

2.1 Prerequisites The following is a list of prerequisites needed for using PowerCLI Extensions, please ensure you meet these requirements as other versions may not have been tested and cannot be guaranteed to work.

VMware vSphere PowerCLI 6.0 R1 or higher

PowerShell V2 or higher

2.2 Installation process Please follow the below steps to ensure the PowerCLI Extensions is installed correctly in your environment:

1. Install PowerCLI (Latest release recommended)

2. Download the PowerCLI Extensions module from the download button on the left.

3. Right Click the zip file and go to properties, if you have an Unblock button at the bottom press it to

unblock the file to prevent a Security Warning when importing the module.

4. To install the PowerShell module - extract the downloaded ZIP file to your modules directory, for

example (C:\Users\MyUser\Documents\WindowsPowerShell\Modules). For additional information on

how to install a PowerShell module, see here.

5. Verify that in the above folder there is a sub-folder called VMware.VimAutomation.Extensions. The

full path

is: C:\Users\MyUser\Documents\WindowsPowerShell\Modules\VMware.VimAutomation.Extensions

3. Listing all PowerCLI Extensions cmdlets

Once installed you can list all cmdlets available as part of PowerCLI Extensions by using the following command: PS C:\Users\MyUser> Get-command -Module VMware.VimAutomation.Extensions CommandType Name ModuleName ----------- ---- ---------- Cmdlet Enable-InstantCloneVM VMware.VimAutomation.Extensions Cmdlet Get-HardDiskVFlashConfiguration VMware.VimAutomation.Extensions Cmdlet Get-InstantCloneVM VMware.VimAutomation.Extensions Cmdlet Get-VMHostVFlashConfiguration VMware.VimAutomation.Extensions Cmdlet New-InstantCloneVM VMware.VimAutomation.Extensions Cmdlet Set-HardDiskVFlashConfiguration VMware.VimAutomation.Extensions Cmdlet Set-VMHostVFlashConfiguration VMware.VimAutomation.Extensions

If you do not see this response please ensure you have installed the module in the correct place and your PSModulePath is correct by using the instructions and link in section 2 of this document.

http://msdn.microsoft.com/en-us/library/windows/desktop/dd878350%28v=vs.85%29.aspx



of 13

4. Instant Clone Overview

Instant Clone is a technology introduced in vSphere 6.0 which enables you to rapidly clone a running VM within seconds. What should be noted here of course is the fact that it is not a full clone, this is more of a fork of the current VM.

The “parent” virtual machine is setup as a normal virtual machine and loaded with all applications and configuration desired to be available in the child VMs, then the VM is quiesced and forked and a “child” VM is born. This child VM is leveraging the disk and memory of the parent (for reads), this is why it is so extremely fast to instantiate. The reason it is so fast is that it only needs to create empty delta files, create a VMX and instantiate the process and run the customization script to make the VM unique.

The child VM starts where the parent VM left off, so there is no boot process it is instant on! (Just like you suspend and resume it) With this in mind you can imagine that any running applications which were started before the enablement of the Instant Clone are instantly also running on the Child VMs, this can be beneficial for ensuring child VMs are in the exact state needed to instantly provide value.

Setting up an Instant Clone has two main components.

1. Setting up the parent -- bring the parent VM to the desired state and make a call to the hypervisor from inside the guest to fork via the Enable-InstantCloneVM cmdlet. The parent VM is then quiesced and present in the background as a powered-on template VM. – Note you will not see a change in the vSphere Web Client.

2. Setting up the children – Using the New-InstantCloneVM cmdlet will create a new VM from where the parent left off and run the post customization script defined during the Enable-InstantCloneVM Cmdlet, after this you power on the VM, which causes them to start executing right at the point the parent was cloned.

For more information on Instant Clones please read the great blog by Duncan Epping here: http://www.yellow-bricks.com/2014/10/07/project-fargo-aka-vmfork-what-is-it/

For example scripts please see below.

4.1 Setting up the Parent Workflow 1. Deploy a VM that will be a parent template via normal means, e.g. deploy from template, clone,

or create new

2. Install all needed applications on the VM.

3. If you want to create a persistent child from the parent rather than a non-persistent child create

a snapshot of the VM

4. Launch any applications that you want pre-loaded in the child VMs

5. Run the Enable-InstantCloneVM with pre scripts to remove the machine identity and get it ready

to create children and post scripts which will run when a child VM is created and apply

customization to the new Child VM.

6. The VM will now become a Parent VM and be Quesced, the VM will now act as a live template

and through the vSphere Web-Client you will notice most VM operations are not supported. Its

purpose is to spawn children.

7. You are now ready to create clones with the New-InstantCloneVM cmdlet as per the instructions

below.

4.2 Child VM Configuration

Child VMs can only be created on the same host as where the Parent currently resides.

http://www.yellow-bricks.com/2014/10/07/project-fargo-aka-vmfork-what-is-it/

http://www.yellow-bricks.com/2014/10/07/project-fargo-aka-vmfork-what-is-it/



of 13

All child configuration is completed as part of the Post Clone Script which is specified when enabling the

Instant Clone VM as a Parent VM, this is important to realize as you will want to ensure the Child VMs all

have a unique identities including Mac Addresses, IP address, hostname, hostkeys and other unique

configuration that may identify the machine and its running applications. It is important to ensure the

Pre Quiesce Script contains scripts which will clean the parent machine of its unique data and then the

Post Clone Script will apply the data for the machines unique identity. Examples of these can be seen in

section 8 of this document.

5. Instant Clone Configuration

Only limited operations will be supported on both the parent and child VMs. Support is

dependent on whether the VM is a parent VM or a child VM and whether it's powered-on/off

5.1 Operations supported on the parent VM

If powered-off all operations are allowed as long as no children are powered-on. If any children

are powered-on they must first be powered-off before we can power-on the parent. However

the following operations while not explicitly disallowed will not be recommended if the VM has

child VMs.

VMotion/SVMotion/Move to change the host only for the parent VM: This is because this will cause

the parent VM to be on a different host than the child VMs which is a fundamental requirement for

Instant Clone.

Delete: If the parent VM has child VMs this will cause them to become orphaned and no further

operations can be performed on them other than delete.

Unregister: If the parent VMs has child VMs this will cause them to become orphaned and no further

operations can be performed on them unless they are re-registered.

If powered on and has been enabled ready for cloning:

Clone to add more children to this VM is supported.

Power-off is supported on the parent VM but reset is not supported. A parent cannot be powered-

on if any of its children are powered on.

All other operations are disallowed.



of 13

5.2 Operations supported on the child VM

Can be powered-off, on, reset.

Can be deleted if powered-off.

Can be reconfigured to add disks only. Other reconfigure operations may be supported in the future.

Can be unregistered.

5.3 For powered-on/off parent and child VMs

DRS does not try to move powered-off VMs but we will disallow DRS trying to move the parent VM

to a different host as part of power-on.

HA should ignore parent and child VMs irrespective of power state.

Cannot be FT enabled.

6. Instant Clone Cmdlets

Once the module has been installed we can see the cmdlets for working with Instant Clones, these are

listed below:

Enable-InstantCloneVM

New-InstantCloneVM

Get-InstantCloneVM

7. Instant Clone Examples

Enable MyVM for instant clone (The Enable-InstantCloneVM Cmdlet works for VMs with VMTools installed and supported guests are: Linux, Windows and ESXi) Enable-InstantCloneVM -VM "MyVM" -GuestUser "MyUserName" -GuestPassword "MyPass" Enable MyVM for instant clone uploading a customization script which will be execute in the clone children $guestCredential = Get-Credential Get-VM "MyVM" | Enable-InstantCloneVM -GuestCredential $guestCredential -PostCloneScript c:\myScripts\customize.sh Enables MyVM for instant clone performing preparation script before VM to become instant clone template and specifying customization script for the clone children. Get-VM "MyVM" | Enable-InstantCloneVM -GuestUser "guestUser" -GuestPassword "guestPass" -PreQuiesceScript c:\myScripts\prepare.sh –PostCloneScript c:\myScripts\customize.sh



of 13

Retrieve all instant clone virtual machines whose names starting with "MyVM". Get-InstantCloneVM -Name MyVM* Retrieves all child instant clone virtual machines of "MyParentVM" Get-InstantCloneVM MyParentVM | Get-InstantCloneVM Retrieves all instant clone virtual machines that are children of "MyParentVM" Get-InstantCloneVM -ParentVM MyParentVM Creates an instant clone child VM of "MyParentVM" passing IPAddress as a configuration parameter Creates an instant clone child VM of MyParentVM on MyDatastore The ConfigParams create VM Advanced Settings with keys guestinfo.fork.<config key> and value <config value>. The customization/post script that is used in Enable-InstantCloneVM cmdlet should be written in such a fashion to read those settings through the VMTools rpc tool as shown in the example guest scripts in section 10.1 and 10.2 of this document. Get-InstantCloneVM "MyParentVM" | New-InstantCloneVM -Name 'MyInstantCloneChild' -ConfigParams @{'ipaddress' = 10.23.83.55} $parentVM = Get-InstantCloneVM "MyParentVM" $datastore = Get-Datastore "MyDatastore" New-InstantCloneVM -VM $parentVM -Name 'MyInstantCloneChild' -Datastore $datastore

8. Instant Clone Example script

The following script is written to show the Instant Clone features and shows how to create 5 cloned VMs, how to create a persistent child and how to work with the cmdlets to retrieve information about the parent and children VMs. The script also gives examples of how to start these and also remove them. Import-Module VMware.VimAutomation.Extensions Connect-VIServer vc-01a.corp.local -User [email protected] -Password VMware1! # Get the VM we want to make a parent $parentVm = Get-VM -Name 'Ubuntu Server 14.04.1 LTS' # Enable InstantClone on the ParentVM and specify a local script to use for customization $parentforkVm = Enable-InstantCloneVM -VM $parentVm -GuestUser "root" -GuestPassword 'VMware1!' -PostCloneScript "C:\InstantClone\post.sh" –preQuiesceScript “c:\InstantClone\pre.sh” # List the Parent and show its enabled Get-InstantCloneVM | Where { $_.InstantCloneParent } # Create 5 instant clone VMs 1..5 | Foreach { $configSettings = @{ 'ipaddress' = "192.168.100.11$_"; 'netmask' = '255.255.255.0';



of 13

'gateway' = '192.168.100.1'; } Write-Host "Creating Clone$($_)..." $childForkVm = New-InstantCloneVM -ParentVM $parentforkVm -Name "Clone$_" -ConfigParams $configSettings $childForkVm | Start-Vm -RunAsync | Out-Null } # List the VMs and their IP addresses Get-VM Clone* | Get-VMGuest | Select VM, IPAddress # Create a one off persistent VM as an example $OneOffconfigSettings = @{ 'ipaddress' = "192.168.100.119"; 'netmask' = '255.255.255.0'; 'gateway' = '192.168.100.1'; } New-InstantCloneVM -ParentVM $parentforkVm -Name "Persistent" -ConfigParams $OneOffconfigSettings -Persistent Start-VM Persistent # List the parents and children Get-InstantCloneVM # List the Instant Clone Children Get-InstantCloneVM | Where { $_.InstantCloneChildType } # List the Instant Clone Parents Get-InstantCloneVM | Where { $_.InstantCloneParent } # List the children of our ParentVM $ParentVM = Get-InstantCloneVM | Where { $_.InstantCloneParent } $ParentVM | Get-InstantCloneVM # List the ParentVM of a child Get-InstantCloneVM "Clone1" | Select Name, ParentInstantCloneVM # Delete the Clone VMs Get-InstantCloneVM | Where { $_.InstantCloneChildType } | Stop-VM -Confirm:$false | Remove-VM -DeletePermanently -Confirm:$false # Disable the InstantClone Parent $ParentVM = Get-InstantCloneVM | Where { $_.InstantCloneParent } $parentVm | Stop-VM -Confirm:$false $parentVm | Start-VM

8.1 Example Linux Guest Pre Script

The following script was tested on Ubuntu 14.04

pre.sh set -x # Removing any existing DHCP leases



of 13

rm -f /var/lib/dhcp/dhclient.* # Stop Networking /etc/init.d/networking stop

8.2 Example Linux Guest Post Script

The following script was tested on Ubuntu 14.04

post.sh set -x echo "Customization started" HOSTNAME=$(vmware-rpctool "info-get guestinfo.fork.hostname") IP_ADDRESS=$(vmware-rpctool "info-get guestinfo.fork.ipaddress") NETMASK=$(vmware-rpctool "info-get guestinfo.fork.netmask") GATEWAY=$(vmware-rpctool "info-get guestinfo.fork.gateway") MAC_ADDRESS=$(vmware-rpctool "info-get guestinfo.fork.ethernet0.address") echo "Updating MAC Address ..." ifconfig eth0 hw ether ${MAC_ADDRESS} echo "Updating IP Address ..." ifconfig eth0 ${IP_ADDRESS} netmask ${NETMASK} gateway ${GATEWAY} echo "Updating Hostname ..." echo ${HOSTNAME} > /etc/hostname hostame ${HOSTNAME} echo "Enabling networking ..." /etc/init.d/networking start

8.3 Example Windows Post Script "%programfiles%\vmware\vmware tools\rpctool" "info-get guestinfo.fork.ipaddress" > c:\ip.txt set /p ip=<c:\ip.txt netsh interface ip set address name="Local Area Connection" static %ip% 255.255.252.0 10.23.83.253

9. Instant Clone Known Issues

ISSUE #1

If you delete a child VM directly on an ESXi host via command line tools/API or Windows Client, The

parent’s VMDK is deleted resulting in the parent having a missing file when next powered on. Please

make sure all instant clone and VM operations are performed through the vCenter APIs or Web Client.

10. vSphere Flash Read Cache Overview

VMware vSphere Flash Read Cache virtualizes server side flash providing a high performance read cache layer that dramatically lowers application latency. The caching is fully transparent to the VM without requiring any guest agents. Flash Read Cache enables allocation of flash resources at a per-VMDK granularity providing VMware vSphere vMotion consistent read caching and integration with VMware vSphere Distributed Resource Scheduler for initial placement. - See more at: http://www.vmware.com/products/vsphere/features/flash#sthash.FhdeDHSb.dpuf



of 13

11. vSphere Flash Read Cache Cmdlets

Once the module has been installed we can see the cmdlets for working with vFRC, these are listed

below:

Get-HardDiskVFlashConfiguration

Get-VMHostVFlashConfiguration

Set-HardDiskVFlashConfiguration

Set-VMHostVFlashConfiguration

12. vFlash Read Cache Examples

Retrieve the vFlash configuration for all hard disks associated with a specified virtual machine.

$vm = Get-VM "MyVM"

$disk = Get-HardDisk -VM $vm

Get-HardDiskVFlashConfiguration -Disk $disk

Retrieve the vFlash configuration for a specified host.

Get-VMHostVFlashConfiguration -VMHost "MyVMHost"

Retrieve the vFlash configuration for all hosts in a specified cluster.

$hosts = Get-VMHost -Location "MyCluster"

Get-VMHostVFlashConfiguration -VMHost $hosts

Enable vFlash on a specified hard disk using vSphere default values.

$configuration = Get-HardDiskVFlashConfiguration -Disk $disk

Set-HardDiskVFlashConfiguration -VFlashConfiguration $configuration

Enable vFlash cache with a specified size on a specified hard disk.


Set-HardDiskVFlashConfiguration -VFlashConfiguration $conf -CacheSizeGB 1

Disable the vFlash cache on a specified hard disk.


Set-HardDiskVFlashConfiguration -VFlashConfiguration $configuration -CacheSizeGB 0

Modify the size of the vFlash swap cache for the host associated with the specified vFlash

configuration.



of 13

Set-VMHostVFlashConfiguration -Configuration $vFlashConfig -SwapCacheReservationGB 1

Disable the vFlash swap cache for the host associated with the specified vFlash configuration.

Set-VMHostVFlashConfiguration -Configuration $vFlashConfig -SwapCacheReservationGB 0

Remove all vFlash resources from the specified vFlash host configuration.

Set-VMHostVFlashConfiguration -Configuration $vFlashConfig -RemoveVFlashResource