Package org.jenkinsci.plugins.vsphere.tools

Class VSphere

java.lang.Object
org.jenkinsci.plugins.vsphere.tools.VSphere
public class VSphere extends Object

  • Method Details

    • 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.