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 : String
    The name of the VM.
  • snapshotName : String
    The name of the snapshot.
  • consolidate : boolean
    Consolidate all redundant redo logs for this VM?
  • failOnNoExist : boolean
    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.

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

  • template : String
    The name of the vSphere template to clone.
  • clone : String
    The name of the cloned VM.
  • linkedClone : boolean
    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.
  • resourcePool : String
    The Resource Pool to be used by the VM. If no resource pool is being used, then leave blank.
  • cluster : String
    The vCenter cluster to be used by the VM.
  • datastore : String
    The data store to be used by the VM.
  • folder : String
    (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.
  • customizationSpec : String
  • timeoutInSeconds : int
    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.
  • powerOn : boolean
    Specifies whether or not the new VirtualMachine should be powered on after creation.
  • host : String (optional)
    (Optional) Pins the clone to this specific ESXi host, by name, within the configured cluster.

    When set, this always wins over "Host Selection Mode" below, which is then ignored. Leave blank to use vCenter's own default placement (unchanged legacy behaviour), or to let "Host Selection Mode" choose automatically.

    Works on any vSphere edition/license, and with any permission setup - including a service account that can only write to a single host. This is usually the right choice for small/test labs, or whenever you want full manual control over where clones land.

    Example: esx-rack3-host07.example.com
  • hostSelectionCandidates : Array / List of String (optional)
    • hostSelectionCandidatesAsString : String (optional)
      (Optional) Comma-separated list of host names that "Host Selection Mode" above is allowed to consider, e.g. esx01.example.com, esx02.example.com, esx03.example.com. Any other host in the cluster is ignored by automatic selection, even if it would otherwise be a better pick.

      In a pipeline or Configuration-as-Code YAML, you can use this same comma-separated string form under the name hostSelectionCandidatesAsString, or instead give a native list of individual host names under hostSelectionCandidates, e.g. hostSelectionCandidates: ['esx01.example.com', 'esx02.example.com'] - whichever is more convenient. Both end up stored the same way; use only one of the two per template/step.

      Not every host visible in a cluster is necessarily usable by the vCenter account running this connection - a vCenter admin may restrict provisioning permission to a subset of hosts. This field is the only mechanism this plugin offers to keep automatic selection within permitted hosts.

      This is not verified live against actual vCenter permissions: an incorrect entry, or a host the account cannot actually write to, only surfaces as a vCenter-side error when a clone is attempted, not as a validation error here.

      Leaving this blank inherits the cloud's own default candidate list (configured on the vSphere Cloud itself), if any; if the cloud has no default either, every (usable) host in the configured cluster is a candidate. To explicitly override the cloud's default to "no restriction" for this call site specifically - rather than inheriting whatever the cloud has configured - enter a single comma (,): this is not blank, so it is treated as a deliberate override, but it still parses to zero host names.

    • hostSelectionMode : String (optional)
      (Optional) How to automatically pick a placement host when "Host" above is left blank. Without this, clones land wherever vCenter's own default logic decides - in practice, often the same host the source VM/template is registered on, which can unbalance load across a cluster over time.

      Which mode fits best depends on your VMware license/edition and local preference, not just mechanics:

      • (none) - inherits this cloud's own default hostSelectionMode (configured on the vSphere Cloud itself), if any; if the cloud has no default either, this is unchanged legacy behaviour. Safe default; existing jobs/pipelines are unaffected unless something opts in.
      • Explicitly none - overrides the cloud's default (if any) to force unchanged legacy behaviour for this call site specifically, even when the cloud itself has a default mode configured.
      • Least loaded host - this plugin reads current CPU/memory usage for each candidate host (see "Host Selection Candidates" below) and picks the least loaded one itself. No DRS feature or license is needed, so it works on Essentials/Standard editions, or on a cluster with DRS turned off. It does not know about VMware's own affinity/anti-affinity rules, HA reservations, or storage placement policies. Good default for quick/simple setups, or whenever DRS isn't available/licensed.
      • DRS recommendation - asks vCenter's own DRS engine for a placement recommendation, restricted to the candidate hosts. This honours the cluster's real DRS/HA/affinity/storage policies, but requires DRS to be enabled and licensed on the cluster (vSphere Enterprise Plus, or an equivalent edition/license). On editions or clusters without DRS, the request fails and this plugin automatically falls back to "Least loaded host" behaviour (logged as a warning), rather than failing the build. Recommended for enterprise environments that already rely on DRS, so that Jenkins agent placement follows the same policy as everything else in the cluster.

      Either automatic mode needs a cluster to search: if "Cluster" above is left blank, this plugin will use the only cluster in the vCenter's inventory if there is exactly one: otherwise (no clusters, or more than one) it logs a message and falls back to letting vCenter decide, exactly as if this field had been left blank.

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

    • vm : String
      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.
    • envVariablePrefix : String
      Prefix for guest info environmental variables. E.g. for prefix VM1, variables would be VM1_IpAddress, VM1_HostName etc.
    • waitForIp4 : boolean

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

    • vm : String
      The name of the VM to shut down.
    • evenIfSuspended : boolean
      If the VM is currently suspended, it will still be shutdown.
    • shutdownGracefully : boolean
      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.
    • ignoreIfNotExists : boolean
    • gracefulShutdownTimeout : int (optional)
      The number of seconds after which the graceful shutdown attempt is abandoned, and hard power off is performed.

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

    • vm : String
      The name of the VM or template to reconfigure.
    • reconfigureSteps
        Array / List of Nested Choice of Objects
      • $class: 'ReconfigureAnnotation'
        • annotation : String (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.
        • append : boolean (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.
      • $class: 'ReconfigureCpu'
        • cpuCores : String
          The number of CPU Cores.
        • coresPerSocket : String
          The number of CPU Cores per Socket.
      • $class: 'ReconfigureDisk'
        • diskSize : String
        • datastore : String
          The data store to be used by the disk.
      • $class: 'ReconfigureMemory'
        • memorySize : String
          The amount of memory (RAM) in megabytes.
      • $class: 'ReconfigureNetworkAdapters'
        • deviceAction
          • Values: ADD, EDIT, REMOVE
        • deviceLabel : String
          The name of the network device, such as "Network adapter 1". If blank, the first network adapter will be used.
        • macAddress : String
          The new MAC address for this network adapter. Leave blank to keep existing or default value.
        • standardSwitch : boolean
        • portGroup : String
          The name of the network port group to use. Leave blank to keep existing or default value.
        • distributedSwitch : boolean
        • distributedPortGroup : String
          Specifies the Distributed Switch Port Group.
        • distributedPortId : String
          Port Id to be used from the specified Distributed Switch Port Group.

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

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

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

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

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

    • vm : String
      The name of the VM.
    • snapshotName : String
      The name of the snapshot.
    • suppressPowerOn : boolean (optional)

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

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

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

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

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

    • buildStep
        Nested Choice of Objects
      • $class: 'Clone'
        • sourceName : String
          The name of the vSphere VM or template to clone.
        • clone : String
          The name of the cloned VM.
        • linkedClone : boolean
          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.
        • resourcePool : String
          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.
        • cluster : String
          The vCenter cluster to be used by the VM.
        • datastore : String
          The data store to be used by the VM.
        • folder : String
          (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.
        • powerOn : boolean
          Specifies whether or not the new VirtualMachine should be powered on after creation.
        • timeoutInSeconds : int
          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.
        • customizationSpec : String
          The customization specification name, as defined under 'Policies and Profiles'
        • useCurrentSnapshot : boolean
          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. If this is set then namedSnapshot must not be set. May impact the linkedClone behavior.
        • namedSnapshot : String
          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. May impact the linkedClone behavior.
        • extraConfigParameters
          (Optional) A Map of 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".
          • Type: java.util.Map<java.lang.String, java.lang.String>
        • host : String (optional)
          (Optional) Pins the clone to this specific ESXi host, by name, within the configured cluster.

          When set, this always wins over "Host Selection Mode" below, which is then ignored. Leave blank to use vCenter's own default placement (unchanged legacy behaviour), or to let "Host Selection Mode" choose automatically.

          Works on any vSphere edition/license, and with any permission setup - including a service account that can only write to a single host. This is usually the right choice for small/test labs, or whenever you want full manual control over where clones land.

          Example: esx-rack3-host07.example.com
        • hostSelectionCandidates : Array / List of String (optional)
          • hostSelectionCandidatesAsString : String (optional)
            (Optional) Comma-separated list of host names that "Host Selection Mode" above is allowed to consider, e.g. esx01.example.com, esx02.example.com, esx03.example.com. Any other host in the cluster is ignored by automatic selection, even if it would otherwise be a better pick.

            In a pipeline or Configuration-as-Code YAML, you can use this same comma-separated string form under the name hostSelectionCandidatesAsString, or instead give a native list of individual host names under hostSelectionCandidates, e.g. hostSelectionCandidates: ['esx01.example.com', 'esx02.example.com'] - whichever is more convenient. Both end up stored the same way; use only one of the two per template/step.

            Not every host visible in a cluster is necessarily usable by the vCenter account running this connection - a vCenter admin may restrict provisioning permission to a subset of hosts. This field is the only mechanism this plugin offers to keep automatic selection within permitted hosts.

            This is not verified live against actual vCenter permissions: an incorrect entry, or a host the account cannot actually write to, only surfaces as a vCenter-side error when a clone is attempted, not as a validation error here.

            Leaving this blank inherits the cloud's own default candidate list (configured on the vSphere Cloud itself), if any; if the cloud has no default either, every (usable) host in the configured cluster is a candidate. To explicitly override the cloud's default to "no restriction" for this call site specifically - rather than inheriting whatever the cloud has configured - enter a single comma (,): this is not blank, so it is treated as a deliberate override, but it still parses to zero host names.

          • hostSelectionMode : String (optional)
            (Optional) How to automatically pick a placement host when "Host" above is left blank. Without this, clones land wherever vCenter's own default logic decides - in practice, often the same host the source VM/template is registered on, which can unbalance load across a cluster over time.

            Which mode fits best depends on your VMware license/edition and local preference, not just mechanics:

            • (none) - inherits this cloud's own default hostSelectionMode (configured on the vSphere Cloud itself), if any; if the cloud has no default either, this is unchanged legacy behaviour. Safe default; existing jobs/pipelines are unaffected unless something opts in.
            • Explicitly none - overrides the cloud's default (if any) to force unchanged legacy behaviour for this call site specifically, even when the cloud itself has a default mode configured.
            • Least loaded host - this plugin reads current CPU/memory usage for each candidate host (see "Host Selection Candidates" below) and picks the least loaded one itself. No DRS feature or license is needed, so it works on Essentials/Standard editions, or on a cluster with DRS turned off. It does not know about VMware's own affinity/anti-affinity rules, HA reservations, or storage placement policies. Good default for quick/simple setups, or whenever DRS isn't available/licensed.
            • DRS recommendation - asks vCenter's own DRS engine for a placement recommendation, restricted to the candidate hosts. This honours the cluster's real DRS/HA/affinity/storage policies, but requires DRS to be enabled and licensed on the cluster (vSphere Enterprise Plus, or an equivalent edition/license). On editions or clusters without DRS, the request fails and this plugin automatically falls back to "Least loaded host" behaviour (logged as a warning), rather than failing the build. Recommended for enterprise environments that already rely on DRS, so that Jenkins agent placement follows the same policy as everything else in the cluster.

            Either automatic mode needs a cluster to search: if "Cluster" above is left blank, this plugin will use the only cluster in the vCenter's inventory if there is exactly one: otherwise (no clusters, or more than one) it logs a message and falls back to letting vCenter decide, exactly as if this field had been left blank.

        • $class: 'ConvertToTemplate'
          • vm : String
            The name of the VM to be converted to a template.
          • force : boolean
            Check this if you want to force the conversion in the case where the VM is not already powered down.
        • $class: 'ConvertToVm'
          • template : String
            The name of the template to be converted to a Virtual Machine.
          • resourcePool : String
            The Resource Pool to be used by the VM.
          • cluster : String
            The vCenter cluster to be used by the VM.
        • $class: 'Delete'
          • vm : String
            The name of the VM to be destroyed. This is a destructive operation that cannot be undone!
          • failOnNoExist : boolean
            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.
        • $class: 'DeleteSnapshot'
          • vm : String
            The name of the VM.
          • snapshotName : String
            The name of the snapshot.
          • consolidate : boolean
            Consolidate all redundant redo logs for this VM?
          • failOnNoExist : boolean
            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.
        • $class: 'Deploy'
          • template : String
            The name of the vSphere template to clone.
          • clone : String
            The name of the cloned VM.
          • linkedClone : boolean
            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.
          • resourcePool : String
            The Resource Pool to be used by the VM. If no resource pool is being used, then leave blank.
          • cluster : String
            The vCenter cluster to be used by the VM.
          • datastore : String
            The data store to be used by the VM.
          • folder : String
            (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.
          • customizationSpec : String
          • timeoutInSeconds : int
            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.
          • powerOn : boolean
            Specifies whether or not the new VirtualMachine should be powered on after creation.
          • host : String (optional)
            (Optional) Pins the clone to this specific ESXi host, by name, within the configured cluster.

            When set, this always wins over "Host Selection Mode" below, which is then ignored. Leave blank to use vCenter's own default placement (unchanged legacy behaviour), or to let "Host Selection Mode" choose automatically.

            Works on any vSphere edition/license, and with any permission setup - including a service account that can only write to a single host. This is usually the right choice for small/test labs, or whenever you want full manual control over where clones land.

            Example: esx-rack3-host07.example.com
          • hostSelectionCandidates : Array / List of String (optional)
            • hostSelectionCandidatesAsString : String (optional)
              (Optional) Comma-separated list of host names that "Host Selection Mode" above is allowed to consider, e.g. esx01.example.com, esx02.example.com, esx03.example.com. Any other host in the cluster is ignored by automatic selection, even if it would otherwise be a better pick.

              In a pipeline or Configuration-as-Code YAML, you can use this same comma-separated string form under the name hostSelectionCandidatesAsString, or instead give a native list of individual host names under hostSelectionCandidates, e.g. hostSelectionCandidates: ['esx01.example.com', 'esx02.example.com'] - whichever is more convenient. Both end up stored the same way; use only one of the two per template/step.

              Not every host visible in a cluster is necessarily usable by the vCenter account running this connection - a vCenter admin may restrict provisioning permission to a subset of hosts. This field is the only mechanism this plugin offers to keep automatic selection within permitted hosts.

              This is not verified live against actual vCenter permissions: an incorrect entry, or a host the account cannot actually write to, only surfaces as a vCenter-side error when a clone is attempted, not as a validation error here.

              Leaving this blank inherits the cloud's own default candidate list (configured on the vSphere Cloud itself), if any; if the cloud has no default either, every (usable) host in the configured cluster is a candidate. To explicitly override the cloud's default to "no restriction" for this call site specifically - rather than inheriting whatever the cloud has configured - enter a single comma (,): this is not blank, so it is treated as a deliberate override, but it still parses to zero host names.

            • hostSelectionMode : String (optional)
              (Optional) How to automatically pick a placement host when "Host" above is left blank. Without this, clones land wherever vCenter's own default logic decides - in practice, often the same host the source VM/template is registered on, which can unbalance load across a cluster over time.

              Which mode fits best depends on your VMware license/edition and local preference, not just mechanics:

              • (none) - inherits this cloud's own default hostSelectionMode (configured on the vSphere Cloud itself), if any; if the cloud has no default either, this is unchanged legacy behaviour. Safe default; existing jobs/pipelines are unaffected unless something opts in.
              • Explicitly none - overrides the cloud's default (if any) to force unchanged legacy behaviour for this call site specifically, even when the cloud itself has a default mode configured.
              • Least loaded host - this plugin reads current CPU/memory usage for each candidate host (see "Host Selection Candidates" below) and picks the least loaded one itself. No DRS feature or license is needed, so it works on Essentials/Standard editions, or on a cluster with DRS turned off. It does not know about VMware's own affinity/anti-affinity rules, HA reservations, or storage placement policies. Good default for quick/simple setups, or whenever DRS isn't available/licensed.
              • DRS recommendation - asks vCenter's own DRS engine for a placement recommendation, restricted to the candidate hosts. This honours the cluster's real DRS/HA/affinity/storage policies, but requires DRS to be enabled and licensed on the cluster (vSphere Enterprise Plus, or an equivalent edition/license). On editions or clusters without DRS, the request fails and this plugin automatically falls back to "Least loaded host" behaviour (logged as a warning), rather than failing the build. Recommended for enterprise environments that already rely on DRS, so that Jenkins agent placement follows the same policy as everything else in the cluster.

              Either automatic mode needs a cluster to search: if "Cluster" above is left blank, this plugin will use the only cluster in the vCenter's inventory if there is exactly one: otherwise (no clusters, or more than one) it logs a message and falls back to letting vCenter decide, exactly as if this field had been left blank.

          • $class: 'ExposeGuestInfo'
            • vm : String
              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.
            • envVariablePrefix : String
              Prefix for guest info environmental variables. E.g. for prefix VM1, variables would be VM1_IpAddress, VM1_HostName etc.
            • waitForIp4 : boolean
          • $class: 'PowerOff'
            • vm : String
              The name of the VM to shut down.
            • evenIfSuspended : boolean
              If the VM is currently suspended, it will still be shutdown.
            • shutdownGracefully : boolean
              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.
            • ignoreIfNotExists : boolean
            • gracefulShutdownTimeout : int (optional)
              The number of seconds after which the graceful shutdown attempt is abandoned, and hard power off is performed.
          • $class: 'PowerOn'
            • vm : String
              The name of the VM to power on.
            • timeoutInSeconds : int
              The maximum number of seconds to wait for the IP.
          • $class: 'Reconfigure'
            • vm : String
              The name of the VM or template to reconfigure.
            • reconfigureSteps
                Array / List of Nested Choice of Objects
              • $class: 'ReconfigureAnnotation'
                • annotation : String (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.
                • append : boolean (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.
              • $class: 'ReconfigureCpu'
                • cpuCores : String
                  The number of CPU Cores.
                • coresPerSocket : String
                  The number of CPU Cores per Socket.
              • $class: 'ReconfigureDisk'
                • diskSize : String
                • datastore : String
                  The data store to be used by the disk.
              • $class: 'ReconfigureMemory'
                • memorySize : String
                  The amount of memory (RAM) in megabytes.
              • $class: 'ReconfigureNetworkAdapters'
                • deviceAction
                  • Values: ADD, EDIT, REMOVE
                • deviceLabel : String
                  The name of the network device, such as "Network adapter 1". If blank, the first network adapter will be used.
                • macAddress : String
                  The new MAC address for this network adapter. Leave blank to keep existing or default value.
                • standardSwitch : boolean
                • portGroup : String
                  The name of the network port group to use. Leave blank to keep existing or default value.
                • distributedSwitch : boolean
                • distributedPortGroup : String
                  Specifies the Distributed Switch Port Group.
                • distributedPortId : String
                  Port Id to be used from the specified Distributed Switch Port Group.
          • $class: 'Rename'
            • oldName : String
              The old name of the VM or template to be renamed.
            • newName : String
              The new name of the VM or template.
          • $class: 'RenameSnapshot'
            • vm : String
              The name of the VM or template.
            • oldName : String
              The old name of the snapshot to be renamed.
            • newName : String
              The new name of the snapshot.
            • newDescription : String
              The new description of the snapshot.
          • $class: 'RevertToSnapshot'
            • vm : String
              The name of the VM.
            • snapshotName : String
              The name of the snapshot.
            • suppressPowerOn : boolean (optional)
          • $class: 'SuspendVm'
            • vm : String
              The name of the VM to suspend.
          • $class: 'TakeSnapshot'
            • vm : String
              The name of the VM you'd like to take a snapshot of.
            • snapshotName : String
              The name of the snapshot.
            • description : String
              The description to be saved with the snapshot.
            • includeMemory : boolean
              Would you like to save the active memory in the snapshot?
        • serverName : String
          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.

        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 : String
              The name of the vSphere VM or template to clone.
            • clone : String
              The name of the cloned VM.
            • linkedClone : boolean
              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.
            • resourcePool : String
              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.
            • cluster : String
              The vCenter cluster to be used by the VM.
            • datastore : String
              The data store to be used by the VM.
            • folder : String
              (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.
            • powerOn : boolean
              Specifies whether or not the new VirtualMachine should be powered on after creation.
            • timeoutInSeconds : int
              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.
            • customizationSpec : String
              The customization specification name, as defined under 'Policies and Profiles'
            • useCurrentSnapshot : boolean
              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. If this is set then namedSnapshot must not be set. May impact the linkedClone behavior.
            • namedSnapshot : String
              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. May impact the linkedClone behavior.
            • extraConfigParameters
              (Optional) A Map of 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".
              • Type: java.util.Map<java.lang.String, java.lang.String>
            • host : String (optional)
              (Optional) Pins the clone to this specific ESXi host, by name, within the configured cluster.

              When set, this always wins over "Host Selection Mode" below, which is then ignored. Leave blank to use vCenter's own default placement (unchanged legacy behaviour), or to let "Host Selection Mode" choose automatically.

              Works on any vSphere edition/license, and with any permission setup - including a service account that can only write to a single host. This is usually the right choice for small/test labs, or whenever you want full manual control over where clones land.

              Example: esx-rack3-host07.example.com
            • hostSelectionCandidates : Array / List of String (optional)
              • hostSelectionCandidatesAsString : String (optional)
                (Optional) Comma-separated list of host names that "Host Selection Mode" above is allowed to consider, e.g. esx01.example.com, esx02.example.com, esx03.example.com. Any other host in the cluster is ignored by automatic selection, even if it would otherwise be a better pick.

                In a pipeline or Configuration-as-Code YAML, you can use this same comma-separated string form under the name hostSelectionCandidatesAsString, or instead give a native list of individual host names under hostSelectionCandidates, e.g. hostSelectionCandidates: ['esx01.example.com', 'esx02.example.com'] - whichever is more convenient. Both end up stored the same way; use only one of the two per template/step.

                Not every host visible in a cluster is necessarily usable by the vCenter account running this connection - a vCenter admin may restrict provisioning permission to a subset of hosts. This field is the only mechanism this plugin offers to keep automatic selection within permitted hosts.

                This is not verified live against actual vCenter permissions: an incorrect entry, or a host the account cannot actually write to, only surfaces as a vCenter-side error when a clone is attempted, not as a validation error here.

                Leaving this blank inherits the cloud's own default candidate list (configured on the vSphere Cloud itself), if any; if the cloud has no default either, every (usable) host in the configured cluster is a candidate. To explicitly override the cloud's default to "no restriction" for this call site specifically - rather than inheriting whatever the cloud has configured - enter a single comma (,): this is not blank, so it is treated as a deliberate override, but it still parses to zero host names.

              • hostSelectionMode : String (optional)
                (Optional) How to automatically pick a placement host when "Host" above is left blank. Without this, clones land wherever vCenter's own default logic decides - in practice, often the same host the source VM/template is registered on, which can unbalance load across a cluster over time.

                Which mode fits best depends on your VMware license/edition and local preference, not just mechanics:

                • (none) - inherits this cloud's own default hostSelectionMode (configured on the vSphere Cloud itself), if any; if the cloud has no default either, this is unchanged legacy behaviour. Safe default; existing jobs/pipelines are unaffected unless something opts in.
                • Explicitly none - overrides the cloud's default (if any) to force unchanged legacy behaviour for this call site specifically, even when the cloud itself has a default mode configured.
                • Least loaded host - this plugin reads current CPU/memory usage for each candidate host (see "Host Selection Candidates" below) and picks the least loaded one itself. No DRS feature or license is needed, so it works on Essentials/Standard editions, or on a cluster with DRS turned off. It does not know about VMware's own affinity/anti-affinity rules, HA reservations, or storage placement policies. Good default for quick/simple setups, or whenever DRS isn't available/licensed.
                • DRS recommendation - asks vCenter's own DRS engine for a placement recommendation, restricted to the candidate hosts. This honours the cluster's real DRS/HA/affinity/storage policies, but requires DRS to be enabled and licensed on the cluster (vSphere Enterprise Plus, or an equivalent edition/license). On editions or clusters without DRS, the request fails and this plugin automatically falls back to "Least loaded host" behaviour (logged as a warning), rather than failing the build. Recommended for enterprise environments that already rely on DRS, so that Jenkins agent placement follows the same policy as everything else in the cluster.

                Either automatic mode needs a cluster to search: if "Cluster" above is left blank, this plugin will use the only cluster in the vCenter's inventory if there is exactly one: otherwise (no clusters, or more than one) it logs a message and falls back to letting vCenter decide, exactly as if this field had been left blank.

            • $class: 'ConvertToTemplate'
              • vm : String
                The name of the VM to be converted to a template.
              • force : boolean
                Check this if you want to force the conversion in the case where the VM is not already powered down.
            • $class: 'ConvertToVm'
              • template : String
                The name of the template to be converted to a Virtual Machine.
              • resourcePool : String
                The Resource Pool to be used by the VM.
              • cluster : String
                The vCenter cluster to be used by the VM.
            • $class: 'Delete'
              • vm : String
                The name of the VM to be destroyed. This is a destructive operation that cannot be undone!
              • failOnNoExist : boolean
                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.
            • $class: 'DeleteSnapshot'
              • vm : String
                The name of the VM.
              • snapshotName : String
                The name of the snapshot.
              • consolidate : boolean
                Consolidate all redundant redo logs for this VM?
              • failOnNoExist : boolean
                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.
            • $class: 'Deploy'
              • template : String
                The name of the vSphere template to clone.
              • clone : String
                The name of the cloned VM.
              • linkedClone : boolean
                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.
              • resourcePool : String
                The Resource Pool to be used by the VM. If no resource pool is being used, then leave blank.
              • cluster : String
                The vCenter cluster to be used by the VM.
              • datastore : String
                The data store to be used by the VM.
              • folder : String
                (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.
              • customizationSpec : String
              • timeoutInSeconds : int
                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.
              • powerOn : boolean
                Specifies whether or not the new VirtualMachine should be powered on after creation.
              • host : String (optional)
                (Optional) Pins the clone to this specific ESXi host, by name, within the configured cluster.

                When set, this always wins over "Host Selection Mode" below, which is then ignored. Leave blank to use vCenter's own default placement (unchanged legacy behaviour), or to let "Host Selection Mode" choose automatically.

                Works on any vSphere edition/license, and with any permission setup - including a service account that can only write to a single host. This is usually the right choice for small/test labs, or whenever you want full manual control over where clones land.

                Example: esx-rack3-host07.example.com
              • hostSelectionCandidates : Array / List of String (optional)
                • hostSelectionCandidatesAsString : String (optional)
                  (Optional) Comma-separated list of host names that "Host Selection Mode" above is allowed to consider, e.g. esx01.example.com, esx02.example.com, esx03.example.com. Any other host in the cluster is ignored by automatic selection, even if it would otherwise be a better pick.

                  In a pipeline or Configuration-as-Code YAML, you can use this same comma-separated string form under the name hostSelectionCandidatesAsString, or instead give a native list of individual host names under hostSelectionCandidates, e.g. hostSelectionCandidates: ['esx01.example.com', 'esx02.example.com'] - whichever is more convenient. Both end up stored the same way; use only one of the two per template/step.

                  Not every host visible in a cluster is necessarily usable by the vCenter account running this connection - a vCenter admin may restrict provisioning permission to a subset of hosts. This field is the only mechanism this plugin offers to keep automatic selection within permitted hosts.

                  This is not verified live against actual vCenter permissions: an incorrect entry, or a host the account cannot actually write to, only surfaces as a vCenter-side error when a clone is attempted, not as a validation error here.

                  Leaving this blank inherits the cloud's own default candidate list (configured on the vSphere Cloud itself), if any; if the cloud has no default either, every (usable) host in the configured cluster is a candidate. To explicitly override the cloud's default to "no restriction" for this call site specifically - rather than inheriting whatever the cloud has configured - enter a single comma (,): this is not blank, so it is treated as a deliberate override, but it still parses to zero host names.

                • hostSelectionMode : String (optional)
                  (Optional) How to automatically pick a placement host when "Host" above is left blank. Without this, clones land wherever vCenter's own default logic decides - in practice, often the same host the source VM/template is registered on, which can unbalance load across a cluster over time.

                  Which mode fits best depends on your VMware license/edition and local preference, not just mechanics:

                  • (none) - inherits this cloud's own default hostSelectionMode (configured on the vSphere Cloud itself), if any; if the cloud has no default either, this is unchanged legacy behaviour. Safe default; existing jobs/pipelines are unaffected unless something opts in.
                  • Explicitly none - overrides the cloud's default (if any) to force unchanged legacy behaviour for this call site specifically, even when the cloud itself has a default mode configured.
                  • Least loaded host - this plugin reads current CPU/memory usage for each candidate host (see "Host Selection Candidates" below) and picks the least loaded one itself. No DRS feature or license is needed, so it works on Essentials/Standard editions, or on a cluster with DRS turned off. It does not know about VMware's own affinity/anti-affinity rules, HA reservations, or storage placement policies. Good default for quick/simple setups, or whenever DRS isn't available/licensed.
                  • DRS recommendation - asks vCenter's own DRS engine for a placement recommendation, restricted to the candidate hosts. This honours the cluster's real DRS/HA/affinity/storage policies, but requires DRS to be enabled and licensed on the cluster (vSphere Enterprise Plus, or an equivalent edition/license). On editions or clusters without DRS, the request fails and this plugin automatically falls back to "Least loaded host" behaviour (logged as a warning), rather than failing the build. Recommended for enterprise environments that already rely on DRS, so that Jenkins agent placement follows the same policy as everything else in the cluster.

                  Either automatic mode needs a cluster to search: if "Cluster" above is left blank, this plugin will use the only cluster in the vCenter's inventory if there is exactly one: otherwise (no clusters, or more than one) it logs a message and falls back to letting vCenter decide, exactly as if this field had been left blank.

              • $class: 'ExposeGuestInfo'
                • vm : String
                  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.
                • envVariablePrefix : String
                  Prefix for guest info environmental variables. E.g. for prefix VM1, variables would be VM1_IpAddress, VM1_HostName etc.
                • waitForIp4 : boolean
              • $class: 'PowerOff'
                • vm : String
                  The name of the VM to shut down.
                • evenIfSuspended : boolean
                  If the VM is currently suspended, it will still be shutdown.
                • shutdownGracefully : boolean
                  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.
                • ignoreIfNotExists : boolean
                • gracefulShutdownTimeout : int (optional)
                  The number of seconds after which the graceful shutdown attempt is abandoned, and hard power off is performed.
              • $class: 'PowerOn'
                • vm : String
                  The name of the VM to power on.
                • timeoutInSeconds : int
                  The maximum number of seconds to wait for the IP.
              • $class: 'Reconfigure'
                • vm : String
                  The name of the VM or template to reconfigure.
                • reconfigureSteps
                    Array / List of Nested Choice of Objects
                  • $class: 'ReconfigureAnnotation'
                    • annotation : String (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.
                    • append : boolean (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.
                  • $class: 'ReconfigureCpu'
                    • cpuCores : String
                      The number of CPU Cores.
                    • coresPerSocket : String
                      The number of CPU Cores per Socket.
                  • $class: 'ReconfigureDisk'
                    • diskSize : String
                    • datastore : String
                      The data store to be used by the disk.
                  • $class: 'ReconfigureMemory'
                    • memorySize : String
                      The amount of memory (RAM) in megabytes.
                  • $class: 'ReconfigureNetworkAdapters'
                    • deviceAction
                      • Values: ADD, EDIT, REMOVE
                    • deviceLabel : String
                      The name of the network device, such as "Network adapter 1". If blank, the first network adapter will be used.
                    • macAddress : String
                      The new MAC address for this network adapter. Leave blank to keep existing or default value.
                    • standardSwitch : boolean
                    • portGroup : String
                      The name of the network port group to use. Leave blank to keep existing or default value.
                    • distributedSwitch : boolean
                    • distributedPortGroup : String
                      Specifies the Distributed Switch Port Group.
                    • distributedPortId : String
                      Port Id to be used from the specified Distributed Switch Port Group.
              • $class: 'Rename'
                • oldName : String
                  The old name of the VM or template to be renamed.
                • newName : String
                  The new name of the VM or template.
              • $class: 'RenameSnapshot'
                • vm : String
                  The name of the VM or template.
                • oldName : String
                  The old name of the snapshot to be renamed.
                • newName : String
                  The new name of the snapshot.
                • newDescription : String
                  The new description of the snapshot.
              • $class: 'RevertToSnapshot'
                • vm : String
                  The name of the VM.
                • snapshotName : String
                  The name of the snapshot.
                • suppressPowerOn : boolean (optional)
              • $class: 'SuspendVm'
                • vm : String
                  The name of the VM to suspend.
              • $class: 'TakeSnapshot'
                • vm : String
                  The name of the VM you'd like to take a snapshot of.
                • snapshotName : String
                  The name of the snapshot.
                • description : String
                  The description to be saved with the snapshot.
                • includeMemory : boolean
                  Would you like to save the active memory in the snapshot?
            • serverName : String (optional)

            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.