org.jenkinsci.plugins.vsphere.tools

Class VSphere

java.lang.Object

org.jenkinsci.plugins.vsphere.tools.VSphere

public class VSphere
extends Object

Method Summary

Modifier and Type	Method and Description
void	cloneOrDeployVm(String cloneName, String sourceName, boolean linkedClone, String resourcePoolName, String cluster, String datastoreName, String folderName, boolean useCurrentSnapshot, String namedSnapshot, boolean powerOn, Map<String,String> extraConfigParameters, String customizationSpec, PrintStream jLogger) Creates a new VM by cloning an existing VM or Template.
void	cloneVm(String cloneName, String sourceName, boolean linkedClone, String resourcePoolName, String cluster, String datastoreName, String folderName, boolean powerOn, String customizationSpec, PrintStream jLogger) Clones a new VM from an existing (named) VM.
static VSphere	connect(String server, boolean ignoreCert, String user, String pw) Deprecated. Use connect(VSphereConnectionConfig) instead.
static VSphere	connect(VSphereConnectionConfig connectionDetails) Initiates Connection to vSphere Server
int	countVms()
int	countVmsByPrefix(String prefix)
void	deleteSnapshot(String vmName, String snapName, boolean consolidate, boolean failOnNoExist)
void	deployVm(String cloneName, String sourceName, boolean linkedClone, String resourcePoolName, String cluster, String datastoreName, String folderName, boolean powerOn, String customizationSpec, PrintStream jLogger) Deploys a new VM from an existing (named) Template.
void	destroyVm(String name, boolean failOnNoExist) Destroys the VM in vSphere
void	disconnect() Disconnect from vSphere server.
Boolean	folderExists(String folderPath)
com.vmware.vim25.CustomizationSpecItem	getCustomizationSpecByName(String customizationSpecName)
com.vmware.vim25.mo.ManagedEntity[]	getDatastores()
com.vmware.vim25.mo.DistributedVirtualPortgroup	getDistributedVirtualPortGroupByName(com.vmware.vim25.mo.VirtualMachine virtualMachine, String name) Find Distributed Virtual Port Group name in the same Datacenter as the VM
com.vmware.vim25.mo.DistributedVirtualSwitch	getDistributedVirtualSwitchByPortGroup(com.vmware.vim25.mo.DistributedVirtualPortgroup distributedVirtualPortgroup) Find Distributed Virtual Switch from the provided Distributed Virtual Portgroup
com.vmware.vim25.mo.Folder	getFolder(String folderPath)
String	getIp(com.vmware.vim25.mo.VirtualMachine vm, int timeout) Asks vSphere for the IP address used by a VM.
com.vmware.vim25.mo.Network	getNetworkPortGroupByName(com.vmware.vim25.mo.VirtualMachine virtualMachine, String name) Find Distributed Virtual Port Group name in the same Datacenter as the VM
com.vmware.vim25.mo.VirtualMachineSnapshot	getSnapshotInTree(com.vmware.vim25.mo.VirtualMachine vm, String snapName)
com.vmware.vim25.mo.VirtualMachine	getVmByName(String vmName)
void	markAsTemplate(String vmName, String snapName, boolean force)
void	markAsVm(String name, String resourcePool, String cluster)
void	powerOffVm(com.vmware.vim25.mo.VirtualMachine vm, boolean evenIfSuspended, boolean shutdownGracefully) Deprecated. This method has been superseded by powerOffVm(VirtualMachine, boolean, int), which allows setting an arbitrary grace period.
void	powerOffVm(com.vmware.vim25.mo.VirtualMachine vm, boolean evenIfSuspended, int gracefulShutdownSeconds) Power off the given virtual machine, optionally waiting a while for its operating system to shut down.
void	reconfigureVm(String name, com.vmware.vim25.VirtualMachineConfigSpec spec)
void	renameVm(String oldName, String newName) Renames the VM vSphere
void	renameVmSnapshot(String vmName, String oldName, String newName, String newDescription) Renames a VM Snapshot
void	revertToSnapshot(String vmName, String snapName)
void	setExtraConfigParameters(String vmName, Map<String,String> parameters) Passes data to a VM's "extra config" object.
void	startVm(String name, int timeoutInSeconds)
void	suspendVm(com.vmware.vim25.mo.VirtualMachine vm)
void	takeSnapshot(String vmName, String snapshot, String description, boolean snapMemory)
boolean	vmToolIsEnabled(com.vmware.vim25.mo.VirtualMachine vm)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

connect

public static VSphere connect(@NonNull
                              VSphereConnectionConfig connectionDetails)
                       throws VSphereException

Initiates Connection to vSphere Server

Parameters:

connectionDetails - Contains all the details we need to connect.

Returns:

A connected instance.

Throws:

VSphereException - If an error occurred.

connect

@Deprecated
public static VSphere connect(@NonNull
                                          String server,
                                          boolean ignoreCert,
                                          @NonNull
                                          String user,
                                          @CheckForNull
                                          String pw)
                                   throws VSphereException

Deprecated. Use connect(VSphereConnectionConfig) instead.

Initiates Connection to vSphere Server

Parameters:

server - Server URL

ignoreCert - If true then we disable certificate verification, allowing the use of untrusted certificates but risk man-in-the-middle attacks.

user - Username.

pw - Password.

Returns:

A connected instance.

Throws:

VSphereException - If an error occurred.

disconnect

public void disconnect()

Disconnect from vSphere server.

Note: This logs any Exception it encounters - it does not pass them to get to the calling method.

deployVm

public void deployVm(String cloneName,
                     String sourceName,
                     boolean linkedClone,
                     String resourcePoolName,
                     String cluster,
                     String datastoreName,
                     String folderName,
                     boolean powerOn,
                     String customizationSpec,
                     PrintStream jLogger)
              throws VSphereException

Deploys a new VM from an existing (named) Template.

Parameters:

cloneName - - name of VM to be created

sourceName - - name of VM or template to be cloned

linkedClone - - true if you want to re-use disk backings

resourcePoolName - - resource pool to use

cluster - - ComputeClusterResource to use

datastoreName - - Datastore to use

folderName - - Folder name or path to use

powerOn - - If true the VM will be powered on.

customizationSpec - - Customization spec to use for this VM

jLogger - - Where to log to.

Throws:

VSphereException - If an error occurred.

cloneVm

public void cloneVm(String cloneName,
                    String sourceName,
                    boolean linkedClone,
                    String resourcePoolName,
                    String cluster,
                    String datastoreName,
                    String folderName,
                    boolean powerOn,
                    String customizationSpec,
                    PrintStream jLogger)
             throws VSphereException

Clones a new VM from an existing (named) VM.

Parameters:

cloneName - - name of VM to be created

sourceName - - name of VM or template to be cloned

linkedClone - - true if you want to re-use disk backings

resourcePoolName - - resource pool to use

cluster - - ComputeClusterResource to use

datastoreName - - Datastore to use

folderName - - Folder name or path to use

powerOn - - If true the VM will be powered on.

customizationSpec - - Customization spec to use for this VM

jLogger - - Where to log to.

Throws:

VSphereException - If an error occurred.

cloneOrDeployVm

public void cloneOrDeployVm(String cloneName,
                            String sourceName,
                            boolean linkedClone,
                            String resourcePoolName,
                            String cluster,
                            String datastoreName,
                            String folderName,
                            boolean useCurrentSnapshot,
                            String namedSnapshot,
                            boolean powerOn,
                            Map<String,String> extraConfigParameters,
                            String customizationSpec,
                            PrintStream jLogger)
                     throws VSphereException

Creates a new VM by cloning an existing VM or Template.

Parameters:

cloneName - The name for the new VM.

sourceName - The name of the VM or Template that is to be cloned.

linkedClone - If true then the clone will be defined as a delta from the original, rather than a "full fat" copy. If this is true then you will need to use a snapshot.

resourcePoolName - (Optional) The name of the resource pool to use, or null.

cluster - (Optional) The name of the cluster, or null.

datastoreName - (Optional) The name of the data store, or null.

folderName - (Optional) The name or path of the VSphere folder, or null

useCurrentSnapshot - If true then the clone will be created from the source VM's "current" snapshot. This means that the VM must have at least one snapshot.

namedSnapshot - If set then the clone will be created from the source VM's snapshot of this name. If this is set then useCurrentSnapshot must not be set.

powerOn - If true then the new VM will be switched on after it has been created.

extraConfigParameters - (Optional) parameters to set in the VM's "extra config" object. This data can then be read back at a later stage.In the case of parameters whose name starts "guestinfo.", the parameter can be read by the VMware Tools on the client OS. e.g. a variable named "guestinfo.Foo" with value "Bar" could be read on the guest using the command-line vmtoolsd --cmd "info-get guestinfo.Foo".

customizationSpec - (Optional) Customization spec to use for this VM, or null

jLogger - Where to log to.

Throws:

VSphereException - if anything goes wrong.

reconfigureVm

public void reconfigureVm(String name,
                          com.vmware.vim25.VirtualMachineConfigSpec spec)
                   throws VSphereException

Throws:

VSphereException

startVm

public void startVm(String name,
                    int timeoutInSeconds)
             throws VSphereException

Parameters:

name - - Name of VM to start

timeoutInSeconds - How long to wait for the VM to be running.

Throws:

VSphereException - If an error occurred.

getSnapshotInTree

public com.vmware.vim25.mo.VirtualMachineSnapshot getSnapshotInTree(com.vmware.vim25.mo.VirtualMachine vm,
                                                                    String snapName)

revertToSnapshot

public void revertToSnapshot(String vmName,
                             String snapName)
                      throws VSphereException

Throws:

VSphereException

deleteSnapshot

public void deleteSnapshot(String vmName,
                           String snapName,
                           boolean consolidate,
                           boolean failOnNoExist)
                    throws VSphereException

Throws:

VSphereException

takeSnapshot

public void takeSnapshot(String vmName,
                         String snapshot,
                         String description,
                         boolean snapMemory)
                  throws VSphereException

Throws:

VSphereException

markAsTemplate

public void markAsTemplate(String vmName,
                           String snapName,
                           boolean force)
                    throws VSphereException

Throws:

VSphereException

markAsVm

public void markAsVm(String name,
                     String resourcePool,
                     String cluster)
              throws VSphereException

Throws:

VSphereException

getIp

public String getIp(com.vmware.vim25.mo.VirtualMachine vm,
                    int timeout)
             throws VSphereException

Asks vSphere for the IP address used by a VM.

Parameters:

vm - VirtualMachine name whose IP is to be returned.

timeout - How long to wait (in seconds) for the IP address to known to vSphere.

Returns:

String containing IP address.

Throws:

VSphereException - If an error occurred.

getVmByName

public com.vmware.vim25.mo.VirtualMachine getVmByName(String vmName)
                                               throws VSphereException

Parameters:

vmName - - name of VM object to retrieve

Returns:

- VirtualMachine object

Throws:

VSphereException - If an error occurred.

countVms

public int countVms()
             throws VSphereException

Throws:

VSphereException

countVmsByPrefix

public int countVmsByPrefix(String prefix)
                     throws VSphereException

Throws:

VSphereException

folderExists

public Boolean folderExists(String folderPath)
                     throws VSphereException

Throws:

VSphereException

getFolder

public com.vmware.vim25.mo.Folder getFolder(String folderPath)
                                     throws VSphereException

Throws:

VSphereException

getCustomizationSpecByName

public com.vmware.vim25.CustomizationSpecItem getCustomizationSpecByName(String customizationSpecName)
                                                                  throws VSphereException

Throws:

VSphereException

getDatastores

public com.vmware.vim25.mo.ManagedEntity[] getDatastores()
                                                  throws VSphereException

Returns:

- ManagedEntity array of Datastore

Throws:

VSphereException - If an error occurred.

destroyVm

public void destroyVm(String name,
                      boolean failOnNoExist)
               throws VSphereException

Destroys the VM in vSphere

Parameters:

name - - VM object to destroy

failOnNoExist - If true and the VM does not exist then a VSphereNotFoundException will be thrown.

Throws:

VSphereException - If an error occurred.

renameVmSnapshot

public void renameVmSnapshot(String vmName,
                             String oldName,
                             String newName,
                             String newDescription)
                      throws VSphereException

Renames a VM Snapshot

Parameters:

vmName - the name of the VM whose snapshot is being renamed.

oldName - the current name of the VM's snapshot.

newName - the new name of the VM's snapshot.

newDescription - the new description of the VM's snapshot.

Throws:

VSphereException - If an error occurred.

renameVm

public void renameVm(String oldName,
                     String newName)
              throws VSphereException

Renames the VM vSphere

Parameters:

oldName - the current name of the vm

newName - the new name of the vm

Throws:

VSphereException - If an error occurred.

vmToolIsEnabled

public boolean vmToolIsEnabled(com.vmware.vim25.mo.VirtualMachine vm)

powerOffVm

@Deprecated
public void powerOffVm(com.vmware.vim25.mo.VirtualMachine vm,
                                   boolean evenIfSuspended,
                                   boolean shutdownGracefully)
                            throws VSphereException

Deprecated. This method has been superseded by powerOffVm(VirtualMachine, boolean, int), which allows setting an arbitrary grace period.

Power off the given virtual machine, optionally waiting 180 seconds for its operating system to shut down.

Parameters:

vm - The virtual machine to power off.

evenIfSuspended - If false, a suspended VM is left as it was. If true, a suspended VM gets fully powered off.

shutdownGracefully - If false, the VM is powered off immediately. If true (and VMware tools is installed), the guest operating system is given a grace period of 180 seconds to shut down.

Throws:

VSphereException

powerOffVm

public void powerOffVm(com.vmware.vim25.mo.VirtualMachine vm,
                       boolean evenIfSuspended,
                       int gracefulShutdownSeconds)
                throws VSphereException

Power off the given virtual machine, optionally waiting a while for its operating system to shut down.

Parameters:

vm - The virtual machine to power off.

evenIfSuspended - If false, a suspended VM is left as it was. If true, a suspended VM gets fully powered off.

gracefulShutdownSeconds - The number of seconds to wait for the guest operating system to shut down. If the passed value is zero or less (or if VMware tools is not installed on the VM), the VM is powered off immediately.

Throws:

VSphereException

suspendVm

public void suspendVm(com.vmware.vim25.mo.VirtualMachine vm)
               throws VSphereException

Throws:

VSphereException

getNetworkPortGroupByName

public com.vmware.vim25.mo.Network getNetworkPortGroupByName(com.vmware.vim25.mo.VirtualMachine virtualMachine,
                                                             String name)
                                                      throws VSphereException

Find Distributed Virtual Port Group name in the same Datacenter as the VM

Parameters:

virtualMachine - - VM object

name - - the name of the Port Group

Returns:

returns DistributedVirtualPortgroup object for the provided vDS PortGroup

Throws:

VSphereException - If an error occurred.

getDistributedVirtualPortGroupByName

public com.vmware.vim25.mo.DistributedVirtualPortgroup getDistributedVirtualPortGroupByName(com.vmware.vim25.mo.VirtualMachine virtualMachine,
                                                                                            String name)
                                                                                     throws VSphereException

Find Distributed Virtual Port Group name in the same Datacenter as the VM

Parameters:

virtualMachine - - VM object

name - - the name of the Port Group

Returns:

returns DistributedVirtualPortgroup object for the provided vDS PortGroup

Throws:

VSphereException - If an error occurred.

getDistributedVirtualSwitchByPortGroup

public com.vmware.vim25.mo.DistributedVirtualSwitch getDistributedVirtualSwitchByPortGroup(com.vmware.vim25.mo.DistributedVirtualPortgroup distributedVirtualPortgroup)
                                                                                    throws VSphereException

Find Distributed Virtual Switch from the provided Distributed Virtual Portgroup

Parameters:

distributedVirtualPortgroup - - DistributedVirtualPortgroup object for the provided vDS PortGroup

Returns:

returns DistributedVirtualSwitch object that represents the vDS Switch

Throws:

VSphereException - If an error occurred.

setExtraConfigParameters

public void setExtraConfigParameters(String vmName,
                                     Map<String,String> parameters)
                              throws VSphereException

Passes data to a VM's "extra config" object. This data can then be read back at a later stage. In the case of parameters whose name starts "guestinfo.", the parameter can be read by the VMware Tools on the client OS.

e.g. a variable named "guestinfo.Foo" with value "Bar" could be read on the guest using the command-line vmtoolsd --cmd "info-get guestinfo.Foo".

Parameters:

vmName - The name of the VM.

parameters - A Map of variable name to variable value.

Throws:

VSphereException - If an error occurred.