> User Documentation Home

User Handbook
Tutorials
Resources

The following plugin provides functionality available through Pipeline-compatible steps. Read more about how to integrate steps into your Pipeline in the Steps section of the Pipeline Syntax page.

For a list of other such plugins, see the Pipeline Steps Reference page.

vSphere Plugin

View this plugin on the Plugins site

step([$class: 'DeleteSnapshot']): Delete a Snapshot

  • vm
    The name of the VM.
    • Type: String
  • snapshotName
    The name of the snapshot.
    • Type: String
  • consolidate
    Consolidate all redundant redo logs for this VM?
    • Type: boolean
  • failOnNoExist
    If the snapshot you are trying to delete doesnt exist, fail this build step. Sometimes, the job doesnt care if deletion was successful and only wants it gone---if this is the case, leave unchecked.
    • Type: boolean

step([$class: 'Deploy']): Deploy VM from template

  • template
    The name of the vSphere template to clone.
    • Type: String
  • clone
    The name of the cloned VM.
    • Type: String
  • linkedClone
    Linked clones will re-use any read-only disk backings (like snapshots) and create new children for your clone. This will drastically save time, but the disk backings will be shared.
    • Type: boolean
  • resourcePool
    The Resource Pool to be used by the VM. If no resource pool is being used, then leave blank.
    • Type: String
  • cluster
    The vCenter cluster to be used by the VM.
    • Type: String
  • datastore
    The data store to be used by the VM.
    • Type: String
  • folder
    (Optional) VSphere folder path or unique folder name where VM is going to be created.
    If blank, it will be created in the same folder as the original VM.
    • Type: String
  • customizationSpec
    • Type: String
  • timeoutInSeconds
    The length of time, in seconds, to wait for the new VirtualMachine to be assigned an IP address after it has been powered on. If this value is zero, no attempt will be made to determine the IP address.
    • Type: int
  • powerOn
    Specifies whether or not the new VirtualMachine should be powered on after creation.
    • Type: boolean

step([$class: 'ExposeGuestInfo']): Expose Guest Info

  • vm
    The name of the VM to expose guest info for.
    Variables IpAddress, Hostname, ToolsStatus, ToolsRunningStatus, ToolsVersion, ToolsVersionStatus, GuestState, GuestId, GuestFamily, GuestFullName, AppHeartbeatStatus, GuestOperationsReady, InteractiveGuestOperationsReady are exposed.
    • Type: String
  • envVariablePrefix
    Prefix for guest info environmental variables. E.g. for prefix VM1, variables would be VM1_IpAddress, VM1_HostName etc.
    • Type: String
  • waitForIp4
    • Type: boolean

step([$class: 'PowerOff']): Power-Off VM

  • vm
    The name of the VM to shut down.
    • Type: String
  • evenIfSuspended
    If the VM is currently suspended, it will still be shutdown.
    • Type: boolean
  • shutdownGracefully
    If the VM is powered on and VMware Tools is running, a graceful shutdown will be attempted by performing a Guest Shutdown. If the VM is still running after the timeout has been reached, a hard power off will be performed.
    • Type: boolean
  • ignoreIfNotExists
    • Type: boolean
  • gracefulShutdownTimeout (optional)
    The number of seconds after which the graceful shutdown attempt is abandoned, and hard power off is performed.
    • Type: int

step([$class: 'Reconfigure']): Reconfigure VM

  • vm
    The name of the VM or template to reconfigure.
    • Type: String
  • reconfigureSteps
      Array / List of Nested Choice of Objects
    • $class: 'ReconfigureAnnotation'
      • annotation (optional)
        The text that will be written into the "annotations" field on the VM. This typically shows up in the vSphere UI as the "Notes" for a VM.
        • Type: String
      • append (optional)
        If set then the text specified in this build step will be appended to the end of any existing text. If not set then the text specified will replace any existing text.
        • Type: boolean
    • $class: 'ReconfigureCpu'
      • cpuCores
        The number of CPU Cores.
        • Type: String
      • coresPerSocket
        The number of CPU Cores per Socket.
        • Type: String
    • $class: 'ReconfigureDisk'
      • diskSize
        • Type: String
      • datastore
        The data store to be used by the disk.
        • Type: String
    • $class: 'ReconfigureMemory'
      • memorySize
        The amount of memory (RAM) in megabytes.
        • Type: String
    • $class: 'ReconfigureNetworkAdapters'
      • deviceAction
        • Values: ADD, EDIT, REMOVE
      • deviceLabel
        The name of the network device, such as "Network adapter 1". If blank, the first network adapter will be used.
        • Type: String
      • macAddress
        The new MAC address for this network adapter. Leave blank to keep existing or default value.
        • Type: String
      • standardSwitch
        • Type: boolean
      • portGroup
        The name of the network port group to use. Leave blank to keep existing or default value.
        • Type: String
      • distributedSwitch
        • Type: boolean
      • distributedPortGroup
        Specifies the Distributed Switch Port Group.
        • Type: String
      • distributedPortId
        Port Id to be used from the specified Distributed Switch Port Group.
        • Type: String

step([$class: 'Rename']): Rename VM

  • oldName
    The old name of the VM or template to be renamed.
    • Type: String
  • newName
    The new name of the VM or template.
    • Type: String

step([$class: 'RenameSnapshot']): Rename Snapshot

  • vm
    The name of the VM or template.
    • Type: String
  • oldName
    The old name of the snapshot to be renamed.
    • Type: String
  • newName
    The new name of the snapshot.
    • Type: String
  • newDescription
    The new description of the snapshot.
    • Type: String

step([$class: 'RevertToSnapshot']): Revert to Snapshot

  • vm
    The name of the VM.
    • Type: String
  • snapshotName
    The name of the snapshot.
    • Type: String

step([$class: 'SuspendVm']): Suspend VM

  • vm
    The name of the VM to suspend.
    • Type: String

step([$class: 'TakeSnapshot']): Take Snapshot

  • vm
    The name of the VM you'd like to take a snapshot of.
    • Type: String
  • snapshotName
    The name of the snapshot.
    • Type: String
  • description
    The description to be saved with the snapshot.
    • Type: String
  • includeMemory
    Would you like to save the active memory in the snapshot?
    • Type: boolean

step([$class: 'VSphereBuildStepContainer']): vSphere Build Step

  • buildStep
      Nested Choice of Objects
    • $class: 'Clone'
      • sourceName
        The name of the vSphere VM or template to clone.
        • Type: String
      • clone
        The name of the cloned VM.
        • Type: String
      • linkedClone
        Linked clones will re-use any read-only disk backings (like snapshots) and create new children for your clone. This will drastically save time, but the disk backings will be shared.
        • Type: boolean
      • resourcePool
        The Resource Pool to be used by the VM. Leave it blank to use the same resource pool as the source VM. Must be specified if source VM is a template.
        • Type: String
      • cluster
        The vCenter cluster to be used by the VM.
        • Type: String
      • datastore
        The data store to be used by the VM.
        • Type: String
      • folder
        (Optional) VSphere folder path or unique folder name where VM is going to be created.
        If blank, it will be created in the same folder as the original VM.
        • Type: String
      • powerOn
        Specifies whether or not the new VirtualMachine should be powered on after creation.
        • Type: boolean
      • timeoutInSeconds
        The length of time, in seconds, to wait for the new VirtualMachine to be assigned an IP address after it has been powered on. If this value is zero, no attempt will be made to determine the IP address.
        • Type: int
      • customizationSpec
        The customization specification name, as defined under 'Policies and Profiles'
        • Type: String
    • $class: 'ConvertToTemplate'
      • vm
        The name of the VM to be converted to a template.
        • Type: String
      • force
        Check this if you want to force the conversion in the case where the VM is not already powered down.
        • Type: boolean
    • $class: 'ConvertToVm'
      • template
        The name of the template to be converted to a Virtual Machine.
        • Type: String
      • resourcePool
        The Resource Pool to be used by the VM.
        • Type: String
      • cluster
        The vCenter cluster to be used by the VM.
        • Type: String
    • $class: 'Delete'
      • vm
        The name of the VM to be destroyed. This is a destructive operation that cannot be undone!
        • Type: String
      • failOnNoExist
        If the VM you are trying to delete doesnt exist, fail this build step. Sometimes, the job doesnt care if deletion was successful and only wants it gone---if this is the case, leave unchecked.
        • Type: boolean
    • $class: 'DeleteSnapshot'
      • vm
        The name of the VM.
        • Type: String
      • snapshotName
        The name of the snapshot.
        • Type: String
      • consolidate
        Consolidate all redundant redo logs for this VM?
        • Type: boolean
      • failOnNoExist
        If the snapshot you are trying to delete doesnt exist, fail this build step. Sometimes, the job doesnt care if deletion was successful and only wants it gone---if this is the case, leave unchecked.
        • Type: boolean
    • $class: 'Deploy'
      • template
        The name of the vSphere template to clone.
        • Type: String
      • clone
        The name of the cloned VM.
        • Type: String
      • linkedClone
        Linked clones will re-use any read-only disk backings (like snapshots) and create new children for your clone. This will drastically save time, but the disk backings will be shared.
        • Type: boolean
      • resourcePool
        The Resource Pool to be used by the VM. If no resource pool is being used, then leave blank.
        • Type: String
      • cluster
        The vCenter cluster to be used by the VM.
        • Type: String
      • datastore
        The data store to be used by the VM.
        • Type: String
      • folder
        (Optional) VSphere folder path or unique folder name where VM is going to be created.
        If blank, it will be created in the same folder as the original VM.
        • Type: String
      • customizationSpec
        • Type: String
      • timeoutInSeconds
        The length of time, in seconds, to wait for the new VirtualMachine to be assigned an IP address after it has been powered on. If this value is zero, no attempt will be made to determine the IP address.
        • Type: int
      • powerOn
        Specifies whether or not the new VirtualMachine should be powered on after creation.
        • Type: boolean
    • $class: 'ExposeGuestInfo'
      • vm
        The name of the VM to expose guest info for.
        Variables IpAddress, Hostname, ToolsStatus, ToolsRunningStatus, ToolsVersion, ToolsVersionStatus, GuestState, GuestId, GuestFamily, GuestFullName, AppHeartbeatStatus, GuestOperationsReady, InteractiveGuestOperationsReady are exposed.
        • Type: String
      • envVariablePrefix
        Prefix for guest info environmental variables. E.g. for prefix VM1, variables would be VM1_IpAddress, VM1_HostName etc.
        • Type: String
      • waitForIp4
        • Type: boolean
    • $class: 'PowerOff'
      • vm
        The name of the VM to shut down.
        • Type: String
      • evenIfSuspended
        If the VM is currently suspended, it will still be shutdown.
        • Type: boolean
      • shutdownGracefully
        If the VM is powered on and VMware Tools is running, a graceful shutdown will be attempted by performing a Guest Shutdown. If the VM is still running after the timeout has been reached, a hard power off will be performed.
        • Type: boolean
      • ignoreIfNotExists
        • Type: boolean
      • gracefulShutdownTimeout (optional)
        The number of seconds after which the graceful shutdown attempt is abandoned, and hard power off is performed.
        • Type: int
    • $class: 'PowerOn'
      • vm
        The name of the VM to power on.
        • Type: String
      • timeoutInSeconds
        The maximum number of seconds to wait for the IP.
        • Type: int
    • $class: 'Reconfigure'
      • vm
        The name of the VM or template to reconfigure.
        • Type: String
      • reconfigureSteps
          Array / List of Nested Choice of Objects
        • $class: 'ReconfigureAnnotation'
          • annotation (optional)
            The text that will be written into the "annotations" field on the VM. This typically shows up in the vSphere UI as the "Notes" for a VM.
            • Type: String
          • append (optional)
            If set then the text specified in this build step will be appended to the end of any existing text. If not set then the text specified will replace any existing text.
            • Type: boolean
        • $class: 'ReconfigureCpu'
          • cpuCores
            The number of CPU Cores.
            • Type: String
          • coresPerSocket
            The number of CPU Cores per Socket.
            • Type: String
        • $class: 'ReconfigureDisk'
          • diskSize
            • Type: String
          • datastore
            The data store to be used by the disk.
            • Type: String
        • $class: 'ReconfigureMemory'
          • memorySize
            The amount of memory (RAM) in megabytes.
            • Type: String
        • $class: 'ReconfigureNetworkAdapters'
          • deviceAction
            • Values: ADD, EDIT, REMOVE
          • deviceLabel
            The name of the network device, such as "Network adapter 1". If blank, the first network adapter will be used.
            • Type: String
          • macAddress
            The new MAC address for this network adapter. Leave blank to keep existing or default value.
            • Type: String
          • standardSwitch
            • Type: boolean
          • portGroup
            The name of the network port group to use. Leave blank to keep existing or default value.
            • Type: String
          • distributedSwitch
            • Type: boolean
          • distributedPortGroup
            Specifies the Distributed Switch Port Group.
            • Type: String
          • distributedPortId
            Port Id to be used from the specified Distributed Switch Port Group.
            • Type: String
    • $class: 'Rename'
      • oldName
        The old name of the VM or template to be renamed.
        • Type: String
      • newName
        The new name of the VM or template.
        • Type: String
    • $class: 'RenameSnapshot'
      • vm
        The name of the VM or template.
        • Type: String
      • oldName
        The old name of the snapshot to be renamed.
        • Type: String
      • newName
        The new name of the snapshot.
        • Type: String
      • newDescription
        The new description of the snapshot.
        • Type: String
    • $class: 'RevertToSnapshot'
      • vm
        The name of the VM.
        • Type: String
      • snapshotName
        The name of the snapshot.
        • Type: String
    • $class: 'SuspendVm'
      • vm
        The name of the VM to suspend.
        • Type: String
    • $class: 'TakeSnapshot'
      • vm
        The name of the VM you'd like to take a snapshot of.
        • Type: String
      • snapshotName
        The name of the snapshot.
        • Type: String
      • description
        The description to be saved with the snapshot.
        • Type: String
      • includeMemory
        Would you like to save the active memory in the snapshot?
        • Type: boolean
  • serverName
    The vSphere configuration to use. Use ${VSPHERE_CLOUD_NAME} and create a vsphere selection parameter if you want to dynamically select the vSphere configuration.
    A vsphere selection parameter is the same as a string parameter named VSPHERE_CLOUD_NAME but allows easy selection of a vsphere cloud.
    • Type: String

vSphere: Invoke an vSphere action, exposing the VM IP under some actions

Execute vCenter actions. Reusing vSphereBuildStep forms, cut properly exposing VSPHERE_IP for PowerOn, Deploy and Clone options.
  • buildStep (optional)
      Nested Choice of Objects
    • $class: 'Clone'
      • sourceName
        The name of the vSphere VM or template to clone.
        • Type: String
      • clone
        The name of the cloned VM.
        • Type: String
      • linkedClone
        Linked clones will re-use any read-only disk backings (like snapshots) and create new children for your clone. This will drastically save time, but the disk backings will be shared.
        • Type: boolean
      • resourcePool
        The Resource Pool to be used by the VM. Leave it blank to use the same resource pool as the source VM. Must be specified if source VM is a template.
        • Type: String
      • cluster
        The vCenter cluster to be used by the VM.
        • Type: String
      • datastore
        The data store to be used by the VM.
        • Type: String
      • folder
        (Optional) VSphere folder path or unique folder name where VM is going to be created.
        If blank, it will be created in the same folder as the original VM.
        • Type: String
      • powerOn
        Specifies whether or not the new VirtualMachine should be powered on after creation.
        • Type: boolean
      • timeoutInSeconds
        The length of time, in seconds, to wait for the new VirtualMachine to be assigned an IP address after it has been powered on. If this value is zero, no attempt will be made to determine the IP address.
        • Type: int
      • customizationSpec
        The customization specification name, as defined under 'Policies and Profiles'
        • Type: String
    • $class: 'ConvertToTemplate'
      • vm
        The name of the VM to be converted to a template.
        • Type: String
      • force
        Check this if you want to force the conversion in the case where the VM is not already powered down.
        • Type: boolean
    • $class: 'ConvertToVm'
      • template
        The name of the template to be converted to a Virtual Machine.
        • Type: String
      • resourcePool
        The Resource Pool to be used by the VM.
        • Type: String
      • cluster
        The vCenter cluster to be used by the VM.
        • Type: String
    • $class: 'Delete'
      • vm
        The name of the VM to be destroyed. This is a destructive operation that cannot be undone!
        • Type: String
      • failOnNoExist
        If the VM you are trying to delete doesnt exist, fail this build step. Sometimes, the job doesnt care if deletion was successful and only wants it gone---if this is the case, leave unchecked.
        • Type: boolean
    • $class: 'DeleteSnapshot'
      • vm
        The name of the VM.
        • Type: String
      • snapshotName
        The name of the snapshot.
        • Type: String
      • consolidate
        Consolidate all redundant redo logs for this VM?
        • Type: boolean
      • failOnNoExist
        If the snapshot you are trying to delete doesnt exist, fail this build step. Sometimes, the job doesnt care if deletion was successful and only wants it gone---if this is the case, leave unchecked.
        • Type: boolean
    • $class: 'Deploy'
      • template
        The name of the vSphere template to clone.
        • Type: String
      • clone
        The name of the cloned VM.
        • Type: String
      • linkedClone
        Linked clones will re-use any read-only disk backings (like snapshots) and create new children for your clone. This will drastically save time, but the disk backings will be shared.
        • Type: boolean
      • resourcePool
        The Resource Pool to be used by the VM. If no resource pool is being used, then leave blank.
        • Type: String
      • cluster
        The vCenter cluster to be used by the VM.
        • Type: String
      • datastore
        The data store to be used by the VM.
        • Type: String
      • folder
        (Optional) VSphere folder path or unique folder name where VM is going to be created.
        If blank, it will be created in the same folder as the original VM.
        • Type: String
      • customizationSpec
        • Type: String
      • timeoutInSeconds
        The length of time, in seconds, to wait for the new VirtualMachine to be assigned an IP address after it has been powered on. If this value is zero, no attempt will be made to determine the IP address.
        • Type: int
      • powerOn
        Specifies whether or not the new VirtualMachine should be powered on after creation.
        • Type: boolean
    • $class: 'ExposeGuestInfo'
      • vm
        The name of the VM to expose guest info for.
        Variables IpAddress, Hostname, ToolsStatus, ToolsRunningStatus, ToolsVersion, ToolsVersionStatus, GuestState, GuestId, GuestFamily, GuestFullName, AppHeartbeatStatus, GuestOperationsReady, InteractiveGuestOperationsReady are exposed.
        • Type: String
      • envVariablePrefix
        Prefix for guest info environmental variables. E.g. for prefix VM1, variables would be VM1_IpAddress, VM1_HostName etc.
        • Type: String
      • waitForIp4
        • Type: boolean
    • $class: 'PowerOff'
      • vm
        The name of the VM to shut down.
        • Type: String
      • evenIfSuspended
        If the VM is currently suspended, it will still be shutdown.
        • Type: boolean
      • shutdownGracefully
        If the VM is powered on and VMware Tools is running, a graceful shutdown will be attempted by performing a Guest Shutdown. If the VM is still running after the timeout has been reached, a hard power off will be performed.
        • Type: boolean
      • ignoreIfNotExists
        • Type: boolean
      • gracefulShutdownTimeout (optional)
        The number of seconds after which the graceful shutdown attempt is abandoned, and hard power off is performed.
        • Type: int
    • $class: 'PowerOn'
      • vm
        The name of the VM to power on.
        • Type: String
      • timeoutInSeconds
        The maximum number of seconds to wait for the IP.
        • Type: int
    • $class: 'Reconfigure'
      • vm
        The name of the VM or template to reconfigure.
        • Type: String
      • reconfigureSteps
          Array / List of Nested Choice of Objects
        • $class: 'ReconfigureAnnotation'
          • annotation (optional)
            The text that will be written into the "annotations" field on the VM. This typically shows up in the vSphere UI as the "Notes" for a VM.
            • Type: String
          • append (optional)
            If set then the text specified in this build step will be appended to the end of any existing text. If not set then the text specified will replace any existing text.
            • Type: boolean
        • $class: 'ReconfigureCpu'
          • cpuCores
            The number of CPU Cores.
            • Type: String
          • coresPerSocket
            The number of CPU Cores per Socket.
            • Type: String
        • $class: 'ReconfigureDisk'
          • diskSize
            • Type: String
          • datastore
            The data store to be used by the disk.
            • Type: String
        • $class: 'ReconfigureMemory'
          • memorySize
            The amount of memory (RAM) in megabytes.
            • Type: String
        • $class: 'ReconfigureNetworkAdapters'
          • deviceAction
            • Values: ADD, EDIT, REMOVE
          • deviceLabel
            The name of the network device, such as "Network adapter 1". If blank, the first network adapter will be used.
            • Type: String
          • macAddress
            The new MAC address for this network adapter. Leave blank to keep existing or default value.
            • Type: String
          • standardSwitch
            • Type: boolean
          • portGroup
            The name of the network port group to use. Leave blank to keep existing or default value.
            • Type: String
          • distributedSwitch
            • Type: boolean
          • distributedPortGroup
            Specifies the Distributed Switch Port Group.
            • Type: String
          • distributedPortId
            Port Id to be used from the specified Distributed Switch Port Group.
            • Type: String
    • $class: 'Rename'
      • oldName
        The old name of the VM or template to be renamed.
        • Type: String
      • newName
        The new name of the VM or template.
        • Type: String
    • $class: 'RenameSnapshot'
      • vm
        The name of the VM or template.
        • Type: String
      • oldName
        The old name of the snapshot to be renamed.
        • Type: String
      • newName
        The new name of the snapshot.
        • Type: String
      • newDescription
        The new description of the snapshot.
        • Type: String
    • $class: 'RevertToSnapshot'
      • vm
        The name of the VM.
        • Type: String
      • snapshotName
        The name of the snapshot.
        • Type: String
    • $class: 'SuspendVm'
      • vm
        The name of the VM to suspend.
        • Type: String
    • $class: 'TakeSnapshot'
      • vm
        The name of the VM you'd like to take a snapshot of.
        • Type: String
      • snapshotName
        The name of the snapshot.
        • Type: String
      • description
        The description to be saved with the snapshot.
        • Type: String
      • includeMemory
        Would you like to save the active memory in the snapshot?
        • Type: boolean
  • serverName (optional)
    • Type: String

Was this page helpful?

Please submit your feedback about this page through this quick form.

Alternatively, if you don't wish to complete the quick form, you can simply indicate if you found this page helpful?

    


See existing feedback here.