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.

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.

The number of CPU Cores. Build variables such as ${CPU} are expanded when the step runs.

The number of CPU Cores per Socket. Build variables are expanded when the step runs.

Optional. The CPU reservation, in MHz, guaranteeing this amount of physical CPU capacity to the VM. Leave blank for no reservation (the previous, default behavior). Build variables are expanded when the step runs.

The data store to be used by the disk.

Selects which disk to act on, matched by any of:

• vSphere device label, e.g. "Hard disk 1";
• disk file base name, e.g. "kube15_1", taken from a backing file named "[datastore1] kube15/kube15_1.vmdk";
• controller moniker matching how vSphere itself displays the disk's address, e.g. "SCSI(0:2)" or "IDE(1:0)" (controller bus number : unit number).

Cannot be combined with Device Number.

• Add: optional; if given, the new disk's file is named after it instead of the default "<vm>_<N>" scheme (fails if a disk with that name already exists).
• Edit: selects the disk to resize; may be left blank if the VM has only one disk.
• Remove: always required (unless Device Number is used), since removing the wrong disk deletes its data.

Alternative to Device Label; cannot be combined with it. One-based (1 = first disk), to match the numbering vSphere itself uses in labels like "Hard disk 1".

• Add: names the new disk's file "<vm>_<N>" -- the same convention, and the same numbering, used when no name is given (fails if a disk with that name already exists).
• Edit/Remove: selects the Nth disk (counting only disks, in the same order vCenter itself returns them) rather than matching a name or address -- if you need a specific controller/unit instead, use Device Label with a moniker like "SCSI(0:2)" or "IDE(1:0)" (those bus/unit numbers are vSphere's own hardware addressing and remain zero-based).

The amount of memory (RAM) in megabytes. Build variables such as ${RAM} are expanded when the step runs.

The name of the network device, such as "Network adapter 1". If blank, the first network adapter will be used.

The new MAC address for this network adapter. Leave blank to keep existing or default value.

A given address is set as a manual (user-supplied) address. vCenter only accepts those from the right ranges: in the 00:50:56 block that is 00:50:56:00:00:00 - 00:50:56:3F:FF:FF (00:50:56:80:00:00 - 00:50:56:BF:FF:FF is what vCenter itself generates), and 00:0C:29 is what standalone ESXi hosts generate. The form warns about addresses that are likely to be refused.

If vCenter does refuse the reconfiguration, it is retried once with the address declared as one that vCenter "assigned", rather than a manual one; if that fails too, both reasons are reported.

The name of the network port group to use. Leave blank to keep existing or default value.

Specifies the Distributed Switch Port Group.

Port Id to be used from the specified Distributed Switch Port Group.

Alternative to Device Label for the Edit and Remove actions; cannot be combined with it, and is not supported for Add. One-based (1 = first adapter), to match the numbering vSphere itself uses in labels like "Network adapter 1": selects the Nth network adapter in the device list vCenter itself returns for the VM (counting only network adapters, in that same order) -- not a raw PCI slot number shared with other device types, and not the (freely renameable) device label text itself.

The name of the vSphere VM or template to clone.

The name of the cloned VM.

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.

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.

The vCenter cluster to be used by the VM.

The data store to be used by the VM.

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

Specifies whether or not the new VirtualMachine should be powered on after creation.

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.

The customization specification name, as defined under 'Policies and Profiles'

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.

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.

(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".

(Optional) The number of cores per socket (virtual sockets are then the number of CPU cores divided by this) to create the new VM with.

Applied in the very same operation that creates the VM, rather than cloning at the source's size and reconfiguring afterwards. Has the same meaning as the setting of the same name of the "Reconfigure CPU"/"Reconfigure Memory" steps. Leave blank to keep the source VM's (or template's) own value. Variables can be used.

The number of CPU cores, whether set here or kept from the source, has to be a multiple of this.

(Optional) The number of virtual CPUs to create the new VM with.

Applied in the very same operation that creates the VM, rather than cloning at the source's size and reconfiguring afterwards. Has the same meaning as the setting of the same name of the "Reconfigure CPU"/"Reconfigure Memory" steps. Leave blank to keep the source VM's (or template's) own value. Variables can be used.

When the "Require enough CPU cores"/"Require enough RAM"/"Require enough free RAM" options are in effect, automatic host selection compares candidate hosts against this value instead of the source's.

The cores per socket of the source are kept unless "Number Cores per Socket" is set too, and this number has to be a multiple of it, or vCenter will refuse the request.

(Optional) The CPU reservation, in MHz, guaranteeing this amount of physical CPU capacity to the new VM. (Named like the Reconfigure CPU step's setting, which also sets a reservation.)

Applied in the very same operation that creates the VM, rather than cloning at the source's size and reconfiguring afterwards. Has the same meaning as the setting of the same name of the "Reconfigure CPU"/"Reconfigure Memory" steps. Leave blank to keep the source VM's (or template's) own value. Variables can be used.

Mind that a reservation can make the cloned VM impossible to power on if the chosen host cannot guarantee it.

If the VM does not get an IP address within the time to wait for it, fail this build step. By default (unchecked) this only logs a warning and the build carries on, without the VSPHERE_IP variable being set. Check it if later steps need the address.

(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

(Optional, a whole number) Minimal free CPU in MHz a host must have right now to be a candidate for automatic host selection, as on the vSphere Cloud, where the limits are described in detail.

Leave all four host limit fields of this call blank to use the limits of the vSphere cloud. If you set any of them, the four values here replace the cloud's limits as a whole for this call, and the ones left blank count as 0 (no limit). Setting all four to 0 therefore removes the limits for this call, whatever the cloud has configured.

Variables can be used where this is a build step.

(Optional, a whole number) Minimal free CPU as a percentage of the host's capacity (0-100) a host must have right now to be a candidate for automatic host selection, as on the vSphere Cloud, where the limits are described in detail.

Leave all four host limit fields of this call blank to use the limits of the vSphere cloud. If you set any of them, the four values here replace the cloud's limits as a whole for this call, and the ones left blank count as 0 (no limit). Setting all four to 0 therefore removes the limits for this call, whatever the cloud has configured.

Variables can be used where this is a build step.

(Optional, a whole number) Minimal free RAM in MB a host must have right now to be a candidate for automatic host selection, as on the vSphere Cloud, where the limits are described in detail.

Leave all four host limit fields of this call blank to use the limits of the vSphere cloud. If you set any of them, the four values here replace the cloud's limits as a whole for this call, and the ones left blank count as 0 (no limit). Setting all four to 0 therefore removes the limits for this call, whatever the cloud has configured.

Variables can be used where this is a build step.

(Optional, a whole number) Minimal free RAM as a percentage of the host's memory (0-100) a host must have right now to be a candidate for automatic host selection, as on the vSphere Cloud, where the limits are described in detail.

Leave all four host limit fields of this call blank to use the limits of the vSphere cloud. If you set any of them, the four values here replace the cloud's limits as a whole for this call, and the ones left blank count as 0 (no limit). Setting all four to 0 therefore removes the limits for this call, whatever the cloud has configured.

Variables can be used where this is a build step.

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

(Optional, off by default) When no folder is given and the clone's host is set by the plugin (an explicit host, or automatic host selection), put the clone in a folder named after that host instead of in the folder of its source.

For inventories that group VMs in per-host folders: the folder of the source VM or template has the name of the host it is on as one element of its path. That element is replaced by the name of the host chosen for the clone, so a clone from a template on virt5x that is placed on virt4x goes to the same folder under virt4x. Short and fully qualified host names are matched alike, and the replacement uses the form the folder has.

If the source's folder path does not mention its host, or the folder for the chosen host does not exist, the source's own folder is used, as without this option, and a message about it is logged. A folder that is given explicitly always wins.

"Inherit" (the default) uses the setting of the vSphere cloud this belongs to; "Yes" or "No" overrides it for this one only.

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

(Optional, off by default) When automatic host selection is in use (a "Host Selection Mode" is set and no explicit host is given), only consider candidate hosts that have at least as much memory free right now as the VM being created is configured with, so the hypervisor does not have to start swapping to make room for it.

This differs from "Require enough RAM", which compares the memory installed in the host. This one uses the host's current memory usage as reported by vCenter, which changes by the minute and lags a little, so several VMs created at once can still land on the same host. A host whose memory usage is unknown does not qualify.

If no candidate host qualifies, a message is logged and placement is left to vCenter, as when no usable candidate host exists at all. It has no effect when an explicit host is given.

"Inherit" (the default) uses the setting of the vSphere cloud this belongs to; "Yes" or "No" overrides it for this one only.

(Optional, off by default) When automatic host selection is in use (a "Host Selection Mode" is set and no explicit host is given), only consider candidate hosts that are physically large enough in terms of CPU cores: the number of vCPUs the VM is configured with (taken from the source VM or template) must not exceed the host's number of physical CPU cores.

This compares the VM against each host's total capacity, not what is currently free, and applies in addition to the candidate list and to both "Least loaded" and "DRS" modes. Leave it off if your site deliberately oversubscribes (swap, hyperthreads, ...), so that a VM larger than a single host's physical resources is still allowed to be placed.

If no candidate host satisfies it, a message is logged and placement is left to vCenter, as when no usable candidate host exists at all. It has no effect when an explicit host is given.

"Inherit" (the default) uses the setting of the vSphere cloud this belongs to; "Yes" or "No" overrides it for this one only.

(Optional, off by default) When automatic host selection is in use (a "Host Selection Mode" is set and no explicit host is given), only consider candidate hosts that are physically large enough in terms of RAM: the VM's configured memory size (taken from the source VM or template) must not exceed the host's total physical RAM.

This compares the VM against each host's total capacity, not what is currently free, and applies in addition to the candidate list and to both "Least loaded" and "DRS" modes. Leave it off if your site deliberately oversubscribes (swap, hyperthreads, ...), so that a VM larger than a single host's physical resources is still allowed to be placed.

If no candidate host satisfies it, a message is logged and placement is left to vCenter, as when no usable candidate host exists at all. It has no effect when an explicit host is given.

"Inherit" (the default) uses the setting of the vSphere cloud this belongs to; "Yes" or "No" overrides it for this one only.

(Optional, a number) Pick at random among the hosts scoring within this fraction of the best one; negative: always the top host; above 1: any available host at random, load not considered. See the setting of the same name on the vSphere Cloud. Leave blank to use the cloud's setting. Variables can be used where this is a build step.

(Optional, a whole number of seconds) How long to wait, when automatic host selection finds no host that the VM can be created on at the moment (hosts too busy for the free resource limits, in maintenance, too small, not reporting usage, ...), before giving up. See the setting of the same name on the vSphere Cloud, which also says what giving up means.

• 0: do not wait; give up at once.
• a positive number: look at the hosts again every 15 seconds for up to that long.
• -1 or infinite: wait for as long as it takes (the build can still be aborted).

Leave blank to use the cloud's setting. Variables can be used where this is a build step.

(Optional, a whole number) How much a host's free CPU in MHz counts when automatic host selection looks for the "most available" host, as on the vSphere Cloud, where the scoring is described in detail.

Leave all four host weight fields of this call blank to use the weights of the vSphere cloud. If you set any of them, the four values here replace the cloud's weights as a whole for this call, and the ones left blank count as 0. Setting all four to 0 gives the original ranking (the host whose busier resource, CPU or memory, is the least used by percentage), whatever the cloud has configured.

Only the proportions between the weights matter, so 1 and 1 means the same as 50 and 50. Variables can be used.

(Optional, a whole number) How much a host's free CPU as percent of the host counts when automatic host selection looks for the "most available" host, as on the vSphere Cloud, where the scoring is described in detail.

Leave all four host weight fields of this call blank to use the weights of the vSphere cloud. If you set any of them, the four values here replace the cloud's weights as a whole for this call, and the ones left blank count as 0. Setting all four to 0 gives the original ranking (the host whose busier resource, CPU or memory, is the least used by percentage), whatever the cloud has configured.

Only the proportions between the weights matter, so 1 and 1 means the same as 50 and 50. Variables can be used.

(Optional, a whole number) How much a host's free RAM in MB counts when automatic host selection looks for the "most available" host, as on the vSphere Cloud, where the scoring is described in detail.

Leave all four host weight fields of this call blank to use the weights of the vSphere cloud. If you set any of them, the four values here replace the cloud's weights as a whole for this call, and the ones left blank count as 0. Setting all four to 0 gives the original ranking (the host whose busier resource, CPU or memory, is the least used by percentage), whatever the cloud has configured.

Only the proportions between the weights matter, so 1 and 1 means the same as 50 and 50. Variables can be used.

(Optional, a whole number) How much a host's free RAM as percent of the host counts when automatic host selection looks for the "most available" host, as on the vSphere Cloud, where the scoring is described in detail.

Leave all four host weight fields of this call blank to use the weights of the vSphere cloud. If you set any of them, the four values here replace the cloud's weights as a whole for this call, and the ones left blank count as 0. Setting all four to 0 gives the original ranking (the host whose busier resource, CPU or memory, is the least used by percentage), whatever the cloud has configured.

Only the proportions between the weights matter, so 1 and 1 means the same as 50 and 50. Variables can be used.

(Optional) The memory size, in MB, to create the new VM with.

Applied in the very same operation that creates the VM, rather than cloning at the source's size and reconfiguring afterwards. Has the same meaning as the setting of the same name of the "Reconfigure CPU"/"Reconfigure Memory" steps. Leave blank to keep the source VM's (or template's) own value. Variables can be used.

When the "Require enough CPU cores"/"Require enough RAM"/"Require enough free RAM" options are in effect, automatic host selection compares candidate hosts against this value instead of the source's.

The name of the VM to be converted to a template.

Check this if you want to force the conversion in the case where the VM is not already powered down.

The name of the template to be converted to a Virtual Machine.

The Resource Pool to be used by the VM.

The vCenter cluster to be used by the VM.

The name of the VM to be destroyed. This is a destructive operation that cannot be undone!

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.

The name of the VM.

The name of the snapshot.

Consolidate all redundant redo logs for this VM?

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.

The name of the vSphere template to clone.

The name of the cloned VM.

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.

The Resource Pool to be used by the VM. If no resource pool is being used, then leave blank.

The vCenter cluster to be used by the VM.

The data store to be used by the VM.

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

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.

Specifies whether or not the new VirtualMachine should be powered on after creation.

(Optional) The number of cores per socket (virtual sockets are then the number of CPU cores divided by this) to create the new VM with.

Applied in the very same operation that creates the VM, rather than cloning at the source's size and reconfiguring afterwards. Has the same meaning as the setting of the same name of the "Reconfigure CPU"/"Reconfigure Memory" steps. Leave blank to keep the source VM's (or template's) own value. Variables can be used.

The number of CPU cores, whether set here or kept from the source, has to be a multiple of this.

(Optional) The number of virtual CPUs to create the new VM with.

Applied in the very same operation that creates the VM, rather than cloning at the source's size and reconfiguring afterwards. Has the same meaning as the setting of the same name of the "Reconfigure CPU"/"Reconfigure Memory" steps. Leave blank to keep the source VM's (or template's) own value. Variables can be used.

When the "Require enough CPU cores"/"Require enough RAM"/"Require enough free RAM" options are in effect, automatic host selection compares candidate hosts against this value instead of the source's.

The cores per socket of the source are kept unless "Number Cores per Socket" is set too, and this number has to be a multiple of it, or vCenter will refuse the request.

(Optional) The CPU reservation, in MHz, guaranteeing this amount of physical CPU capacity to the new VM. (Named like the Reconfigure CPU step's setting, which also sets a reservation.)

Applied in the very same operation that creates the VM, rather than cloning at the source's size and reconfiguring afterwards. Has the same meaning as the setting of the same name of the "Reconfigure CPU"/"Reconfigure Memory" steps. Leave blank to keep the source VM's (or template's) own value. Variables can be used.

Mind that a reservation can make the cloned VM impossible to power on if the chosen host cannot guarantee it.

If the VM does not get an IP address within the time to wait for it, fail this build step. By default (unchecked) this only logs a warning and the build carries on, without the VSPHERE_IP variable being set. Check it if later steps need the address.

(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

(Optional, a whole number) Minimal free CPU in MHz a host must have right now to be a candidate for automatic host selection, as on the vSphere Cloud, where the limits are described in detail.

Leave all four host limit fields of this call blank to use the limits of the vSphere cloud. If you set any of them, the four values here replace the cloud's limits as a whole for this call, and the ones left blank count as 0 (no limit). Setting all four to 0 therefore removes the limits for this call, whatever the cloud has configured.

Variables can be used where this is a build step.

(Optional, a whole number) Minimal free CPU as a percentage of the host's capacity (0-100) a host must have right now to be a candidate for automatic host selection, as on the vSphere Cloud, where the limits are described in detail.

Leave all four host limit fields of this call blank to use the limits of the vSphere cloud. If you set any of them, the four values here replace the cloud's limits as a whole for this call, and the ones left blank count as 0 (no limit). Setting all four to 0 therefore removes the limits for this call, whatever the cloud has configured.

Variables can be used where this is a build step.

(Optional, a whole number) Minimal free RAM in MB a host must have right now to be a candidate for automatic host selection, as on the vSphere Cloud, where the limits are described in detail.

Leave all four host limit fields of this call blank to use the limits of the vSphere cloud. If you set any of them, the four values here replace the cloud's limits as a whole for this call, and the ones left blank count as 0 (no limit). Setting all four to 0 therefore removes the limits for this call, whatever the cloud has configured.

Variables can be used where this is a build step.

(Optional, a whole number) Minimal free RAM as a percentage of the host's memory (0-100) a host must have right now to be a candidate for automatic host selection, as on the vSphere Cloud, where the limits are described in detail.

Leave all four host limit fields of this call blank to use the limits of the vSphere cloud. If you set any of them, the four values here replace the cloud's limits as a whole for this call, and the ones left blank count as 0 (no limit). Setting all four to 0 therefore removes the limits for this call, whatever the cloud has configured.

Variables can be used where this is a build step.

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

(Optional, off by default) When no folder is given and the clone's host is set by the plugin (an explicit host, or automatic host selection), put the clone in a folder named after that host instead of in the folder of its source.

For inventories that group VMs in per-host folders: the folder of the source VM or template has the name of the host it is on as one element of its path. That element is replaced by the name of the host chosen for the clone, so a clone from a template on virt5x that is placed on virt4x goes to the same folder under virt4x. Short and fully qualified host names are matched alike, and the replacement uses the form the folder has.

If the source's folder path does not mention its host, or the folder for the chosen host does not exist, the source's own folder is used, as without this option, and a message about it is logged. A folder that is given explicitly always wins.

"Inherit" (the default) uses the setting of the vSphere cloud this belongs to; "Yes" or "No" overrides it for this one only.

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

(Optional, off by default) When automatic host selection is in use (a "Host Selection Mode" is set and no explicit host is given), only consider candidate hosts that have at least as much memory free right now as the VM being created is configured with, so the hypervisor does not have to start swapping to make room for it.

This differs from "Require enough RAM", which compares the memory installed in the host. This one uses the host's current memory usage as reported by vCenter, which changes by the minute and lags a little, so several VMs created at once can still land on the same host. A host whose memory usage is unknown does not qualify.

If no candidate host qualifies, a message is logged and placement is left to vCenter, as when no usable candidate host exists at all. It has no effect when an explicit host is given.

"Inherit" (the default) uses the setting of the vSphere cloud this belongs to; "Yes" or "No" overrides it for this one only.

(Optional, off by default) When automatic host selection is in use (a "Host Selection Mode" is set and no explicit host is given), only consider candidate hosts that are physically large enough in terms of CPU cores: the number of vCPUs the VM is configured with (taken from the source VM or template) must not exceed the host's number of physical CPU cores.

This compares the VM against each host's total capacity, not what is currently free, and applies in addition to the candidate list and to both "Least loaded" and "DRS" modes. Leave it off if your site deliberately oversubscribes (swap, hyperthreads, ...), so that a VM larger than a single host's physical resources is still allowed to be placed.

If no candidate host satisfies it, a message is logged and placement is left to vCenter, as when no usable candidate host exists at all. It has no effect when an explicit host is given.

"Inherit" (the default) uses the setting of the vSphere cloud this belongs to; "Yes" or "No" overrides it for this one only.

(Optional, off by default) When automatic host selection is in use (a "Host Selection Mode" is set and no explicit host is given), only consider candidate hosts that are physically large enough in terms of RAM: the VM's configured memory size (taken from the source VM or template) must not exceed the host's total physical RAM.

This compares the VM against each host's total capacity, not what is currently free, and applies in addition to the candidate list and to both "Least loaded" and "DRS" modes. Leave it off if your site deliberately oversubscribes (swap, hyperthreads, ...), so that a VM larger than a single host's physical resources is still allowed to be placed.

If no candidate host satisfies it, a message is logged and placement is left to vCenter, as when no usable candidate host exists at all. It has no effect when an explicit host is given.

"Inherit" (the default) uses the setting of the vSphere cloud this belongs to; "Yes" or "No" overrides it for this one only.

(Optional, a number) Pick at random among the hosts scoring within this fraction of the best one; negative: always the top host; above 1: any available host at random, load not considered. See the setting of the same name on the vSphere Cloud. Leave blank to use the cloud's setting. Variables can be used where this is a build step.

(Optional, a whole number of seconds) How long to wait, when automatic host selection finds no host that the VM can be created on at the moment (hosts too busy for the free resource limits, in maintenance, too small, not reporting usage, ...), before giving up. See the setting of the same name on the vSphere Cloud, which also says what giving up means.

• 0: do not wait; give up at once.
• a positive number: look at the hosts again every 15 seconds for up to that long.
• -1 or infinite: wait for as long as it takes (the build can still be aborted).

Leave blank to use the cloud's setting. Variables can be used where this is a build step.

(Optional, a whole number) How much a host's free CPU in MHz counts when automatic host selection looks for the "most available" host, as on the vSphere Cloud, where the scoring is described in detail.

Leave all four host weight fields of this call blank to use the weights of the vSphere cloud. If you set any of them, the four values here replace the cloud's weights as a whole for this call, and the ones left blank count as 0. Setting all four to 0 gives the original ranking (the host whose busier resource, CPU or memory, is the least used by percentage), whatever the cloud has configured.

Only the proportions between the weights matter, so 1 and 1 means the same as 50 and 50. Variables can be used.

(Optional, a whole number) How much a host's free CPU as percent of the host counts when automatic host selection looks for the "most available" host, as on the vSphere Cloud, where the scoring is described in detail.

Leave all four host weight fields of this call blank to use the weights of the vSphere cloud. If you set any of them, the four values here replace the cloud's weights as a whole for this call, and the ones left blank count as 0. Setting all four to 0 gives the original ranking (the host whose busier resource, CPU or memory, is the least used by percentage), whatever the cloud has configured.

Only the proportions between the weights matter, so 1 and 1 means the same as 50 and 50. Variables can be used.

(Optional, a whole number) How much a host's free RAM in MB counts when automatic host selection looks for the "most available" host, as on the vSphere Cloud, where the scoring is described in detail.

Leave all four host weight fields of this call blank to use the weights of the vSphere cloud. If you set any of them, the four values here replace the cloud's weights as a whole for this call, and the ones left blank count as 0. Setting all four to 0 gives the original ranking (the host whose busier resource, CPU or memory, is the least used by percentage), whatever the cloud has configured.

Only the proportions between the weights matter, so 1 and 1 means the same as 50 and 50. Variables can be used.

(Optional, a whole number) How much a host's free RAM as percent of the host counts when automatic host selection looks for the "most available" host, as on the vSphere Cloud, where the scoring is described in detail.

Leave all four host weight fields of this call blank to use the weights of the vSphere cloud. If you set any of them, the four values here replace the cloud's weights as a whole for this call, and the ones left blank count as 0. Setting all four to 0 gives the original ranking (the host whose busier resource, CPU or memory, is the least used by percentage), whatever the cloud has configured.

Only the proportions between the weights matter, so 1 and 1 means the same as 50 and 50. Variables can be used.

(Optional) The memory size, in MB, to create the new VM with.

Applied in the very same operation that creates the VM, rather than cloning at the source's size and reconfiguring afterwards. Has the same meaning as the setting of the same name of the "Reconfigure CPU"/"Reconfigure Memory" steps. Leave blank to keep the source VM's (or template's) own value. Variables can be used.

When the "Require enough CPU cores"/"Require enough RAM"/"Require enough free RAM" options are in effect, automatic host selection compares candidate hosts against this value instead of the source's.

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.

Prefix for guest info environmental variables. E.g. for prefix VM1, variables would be VM1_IpAddress, VM1_HostName etc.

The name of the VM to shut down.

If the VM is currently suspended, it will still be shutdown.

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.

The number of seconds after which the graceful shutdown attempt is abandoned, and hard power off is performed.

The name of the VM to power on.

The maximum number of seconds to wait for the IP.

If the VM does not get an IP address within the time to wait for it, fail this build step. By default (unchecked) this only logs a warning and the build carries on, without the VSPHERE_IP variable being set. Check it if later steps need the address.

The name of the VM or template to reconfigure.

The old name of the VM or template to be renamed.

The new name of the VM or template.

The name of the VM or template.

The old name of the snapshot to be renamed.

The new name of the snapshot.

The new description of the snapshot.

If the snapshot you are trying to rename does not exist, fail this build step (the default). Uncheck it when the job does not care and the snapshot may legitimately be absent, e.g. when rotating "current" to "old" before taking a new snapshot; the step then logs that there was nothing to rename and succeeds. A missing VM always fails the step.

The name of the VM.

The name of the snapshot.

The name of the VM to suspend.

The name of the VM you'd like to take a snapshot of.

The name of the snapshot.

The description to be saved with the snapshot.

Would you like to save the active memory in the snapshot?

The name of the vSphere VM or template to clone.

The name of the cloned VM.

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.

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.

The vCenter cluster to be used by the VM.

The data store to be used by the VM.

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

Specifies whether or not the new VirtualMachine should be powered on after creation.

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.

The customization specification name, as defined under 'Policies and Profiles'

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.

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.

(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".

(Optional) The number of cores per socket (virtual sockets are then the number of CPU cores divided by this) to create the new VM with.

Applied in the very same operation that creates the VM, rather than cloning at the source's size and reconfiguring afterwards. Has the same meaning as the setting of the same name of the "Reconfigure CPU"/"Reconfigure Memory" steps. Leave blank to keep the source VM's (or template's) own value. Variables can be used.

The number of CPU cores, whether set here or kept from the source, has to be a multiple of this.

(Optional) The number of virtual CPUs to create the new VM with.

Applied in the very same operation that creates the VM, rather than cloning at the source's size and reconfiguring afterwards. Has the same meaning as the setting of the same name of the "Reconfigure CPU"/"Reconfigure Memory" steps. Leave blank to keep the source VM's (or template's) own value. Variables can be used.

When the "Require enough CPU cores"/"Require enough RAM"/"Require enough free RAM" options are in effect, automatic host selection compares candidate hosts against this value instead of the source's.

The cores per socket of the source are kept unless "Number Cores per Socket" is set too, and this number has to be a multiple of it, or vCenter will refuse the request.

(Optional) The CPU reservation, in MHz, guaranteeing this amount of physical CPU capacity to the new VM. (Named like the Reconfigure CPU step's setting, which also sets a reservation.)

Applied in the very same operation that creates the VM, rather than cloning at the source's size and reconfiguring afterwards. Has the same meaning as the setting of the same name of the "Reconfigure CPU"/"Reconfigure Memory" steps. Leave blank to keep the source VM's (or template's) own value. Variables can be used.

Mind that a reservation can make the cloned VM impossible to power on if the chosen host cannot guarantee it.

If the VM does not get an IP address within the time to wait for it, fail this build step. By default (unchecked) this only logs a warning and the build carries on, without the VSPHERE_IP variable being set. Check it if later steps need the address.

(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

(Optional, a whole number) Minimal free CPU in MHz a host must have right now to be a candidate for automatic host selection, as on the vSphere Cloud, where the limits are described in detail.

Leave all four host limit fields of this call blank to use the limits of the vSphere cloud. If you set any of them, the four values here replace the cloud's limits as a whole for this call, and the ones left blank count as 0 (no limit). Setting all four to 0 therefore removes the limits for this call, whatever the cloud has configured.

Variables can be used where this is a build step.

(Optional, a whole number) Minimal free CPU as a percentage of the host's capacity (0-100) a host must have right now to be a candidate for automatic host selection, as on the vSphere Cloud, where the limits are described in detail.

Leave all four host limit fields of this call blank to use the limits of the vSphere cloud. If you set any of them, the four values here replace the cloud's limits as a whole for this call, and the ones left blank count as 0 (no limit). Setting all four to 0 therefore removes the limits for this call, whatever the cloud has configured.

Variables can be used where this is a build step.

(Optional, a whole number) Minimal free RAM in MB a host must have right now to be a candidate for automatic host selection, as on the vSphere Cloud, where the limits are described in detail.

Leave all four host limit fields of this call blank to use the limits of the vSphere cloud. If you set any of them, the four values here replace the cloud's limits as a whole for this call, and the ones left blank count as 0 (no limit). Setting all four to 0 therefore removes the limits for this call, whatever the cloud has configured.

Variables can be used where this is a build step.

(Optional, a whole number) Minimal free RAM as a percentage of the host's memory (0-100) a host must have right now to be a candidate for automatic host selection, as on the vSphere Cloud, where the limits are described in detail.

Leave all four host limit fields of this call blank to use the limits of the vSphere cloud. If you set any of them, the four values here replace the cloud's limits as a whole for this call, and the ones left blank count as 0 (no limit). Setting all four to 0 therefore removes the limits for this call, whatever the cloud has configured.

Variables can be used where this is a build step.

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

(Optional, off by default) When no folder is given and the clone's host is set by the plugin (an explicit host, or automatic host selection), put the clone in a folder named after that host instead of in the folder of its source.

For inventories that group VMs in per-host folders: the folder of the source VM or template has the name of the host it is on as one element of its path. That element is replaced by the name of the host chosen for the clone, so a clone from a template on virt5x that is placed on virt4x goes to the same folder under virt4x. Short and fully qualified host names are matched alike, and the replacement uses the form the folder has.

If the source's folder path does not mention its host, or the folder for the chosen host does not exist, the source's own folder is used, as without this option, and a message about it is logged. A folder that is given explicitly always wins.

"Inherit" (the default) uses the setting of the vSphere cloud this belongs to; "Yes" or "No" overrides it for this one only.

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

(Optional, off by default) When automatic host selection is in use (a "Host Selection Mode" is set and no explicit host is given), only consider candidate hosts that have at least as much memory free right now as the VM being created is configured with, so the hypervisor does not have to start swapping to make room for it.

This differs from "Require enough RAM", which compares the memory installed in the host. This one uses the host's current memory usage as reported by vCenter, which changes by the minute and lags a little, so several VMs created at once can still land on the same host. A host whose memory usage is unknown does not qualify.

If no candidate host qualifies, a message is logged and placement is left to vCenter, as when no usable candidate host exists at all. It has no effect when an explicit host is given.

"Inherit" (the default) uses the setting of the vSphere cloud this belongs to; "Yes" or "No" overrides it for this one only.

(Optional, off by default) When automatic host selection is in use (a "Host Selection Mode" is set and no explicit host is given), only consider candidate hosts that are physically large enough in terms of CPU cores: the number of vCPUs the VM is configured with (taken from the source VM or template) must not exceed the host's number of physical CPU cores.

This compares the VM against each host's total capacity, not what is currently free, and applies in addition to the candidate list and to both "Least loaded" and "DRS" modes. Leave it off if your site deliberately oversubscribes (swap, hyperthreads, ...), so that a VM larger than a single host's physical resources is still allowed to be placed.

If no candidate host satisfies it, a message is logged and placement is left to vCenter, as when no usable candidate host exists at all. It has no effect when an explicit host is given.

"Inherit" (the default) uses the setting of the vSphere cloud this belongs to; "Yes" or "No" overrides it for this one only.

(Optional, off by default) When automatic host selection is in use (a "Host Selection Mode" is set and no explicit host is given), only consider candidate hosts that are physically large enough in terms of RAM: the VM's configured memory size (taken from the source VM or template) must not exceed the host's total physical RAM.

This compares the VM against each host's total capacity, not what is currently free, and applies in addition to the candidate list and to both "Least loaded" and "DRS" modes. Leave it off if your site deliberately oversubscribes (swap, hyperthreads, ...), so that a VM larger than a single host's physical resources is still allowed to be placed.

If no candidate host satisfies it, a message is logged and placement is left to vCenter, as when no usable candidate host exists at all. It has no effect when an explicit host is given.

"Inherit" (the default) uses the setting of the vSphere cloud this belongs to; "Yes" or "No" overrides it for this one only.

(Optional, a number) Pick at random among the hosts scoring within this fraction of the best one; negative: always the top host; above 1: any available host at random, load not considered. See the setting of the same name on the vSphere Cloud. Leave blank to use the cloud's setting. Variables can be used where this is a build step.

(Optional, a whole number of seconds) How long to wait, when automatic host selection finds no host that the VM can be created on at the moment (hosts too busy for the free resource limits, in maintenance, too small, not reporting usage, ...), before giving up. See the setting of the same name on the vSphere Cloud, which also says what giving up means.

• 0: do not wait; give up at once.
• a positive number: look at the hosts again every 15 seconds for up to that long.
• -1 or infinite: wait for as long as it takes (the build can still be aborted).

Leave blank to use the cloud's setting. Variables can be used where this is a build step.

(Optional, a whole number) How much a host's free CPU in MHz counts when automatic host selection looks for the "most available" host, as on the vSphere Cloud, where the scoring is described in detail.

Leave all four host weight fields of this call blank to use the weights of the vSphere cloud. If you set any of them, the four values here replace the cloud's weights as a whole for this call, and the ones left blank count as 0. Setting all four to 0 gives the original ranking (the host whose busier resource, CPU or memory, is the least used by percentage), whatever the cloud has configured.

Only the proportions between the weights matter, so 1 and 1 means the same as 50 and 50. Variables can be used.

(Optional, a whole number) How much a host's free CPU as percent of the host counts when automatic host selection looks for the "most available" host, as on the vSphere Cloud, where the scoring is described in detail.

Leave all four host weight fields of this call blank to use the weights of the vSphere cloud. If you set any of them, the four values here replace the cloud's weights as a whole for this call, and the ones left blank count as 0. Setting all four to 0 gives the original ranking (the host whose busier resource, CPU or memory, is the least used by percentage), whatever the cloud has configured.

Only the proportions between the weights matter, so 1 and 1 means the same as 50 and 50. Variables can be used.

(Optional, a whole number) How much a host's free RAM in MB counts when automatic host selection looks for the "most available" host, as on the vSphere Cloud, where the scoring is described in detail.

Leave all four host weight fields of this call blank to use the weights of the vSphere cloud. If you set any of them, the four values here replace the cloud's weights as a whole for this call, and the ones left blank count as 0. Setting all four to 0 gives the original ranking (the host whose busier resource, CPU or memory, is the least used by percentage), whatever the cloud has configured.

Only the proportions between the weights matter, so 1 and 1 means the same as 50 and 50. Variables can be used.

(Optional, a whole number) How much a host's free RAM as percent of the host counts when automatic host selection looks for the "most available" host, as on the vSphere Cloud, where the scoring is described in detail.

Leave all four host weight fields of this call blank to use the weights of the vSphere cloud. If you set any of them, the four values here replace the cloud's weights as a whole for this call, and the ones left blank count as 0. Setting all four to 0 gives the original ranking (the host whose busier resource, CPU or memory, is the least used by percentage), whatever the cloud has configured.

Only the proportions between the weights matter, so 1 and 1 means the same as 50 and 50. Variables can be used.

(Optional) The memory size, in MB, to create the new VM with.

Applied in the very same operation that creates the VM, rather than cloning at the source's size and reconfiguring afterwards. Has the same meaning as the setting of the same name of the "Reconfigure CPU"/"Reconfigure Memory" steps. Leave blank to keep the source VM's (or template's) own value. Variables can be used.

When the "Require enough CPU cores"/"Require enough RAM"/"Require enough free RAM" options are in effect, automatic host selection compares candidate hosts against this value instead of the source's.

The name of the VM to be converted to a template.

Check this if you want to force the conversion in the case where the VM is not already powered down.

The name of the template to be converted to a Virtual Machine.

The Resource Pool to be used by the VM.

The vCenter cluster to be used by the VM.

The name of the VM to be destroyed. This is a destructive operation that cannot be undone!

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.

The name of the VM.

The name of the snapshot.

Consolidate all redundant redo logs for this VM?

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.

The name of the vSphere template to clone.

The name of the cloned VM.

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.

The Resource Pool to be used by the VM. If no resource pool is being used, then leave blank.

The vCenter cluster to be used by the VM.

The data store to be used by the VM.

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

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.

Specifies whether or not the new VirtualMachine should be powered on after creation.

(Optional) The number of cores per socket (virtual sockets are then the number of CPU cores divided by this) to create the new VM with.

Applied in the very same operation that creates the VM, rather than cloning at the source's size and reconfiguring afterwards. Has the same meaning as the setting of the same name of the "Reconfigure CPU"/"Reconfigure Memory" steps. Leave blank to keep the source VM's (or template's) own value. Variables can be used.

The number of CPU cores, whether set here or kept from the source, has to be a multiple of this.

(Optional) The number of virtual CPUs to create the new VM with.

Applied in the very same operation that creates the VM, rather than cloning at the source's size and reconfiguring afterwards. Has the same meaning as the setting of the same name of the "Reconfigure CPU"/"Reconfigure Memory" steps. Leave blank to keep the source VM's (or template's) own value. Variables can be used.

When the "Require enough CPU cores"/"Require enough RAM"/"Require enough free RAM" options are in effect, automatic host selection compares candidate hosts against this value instead of the source's.

The cores per socket of the source are kept unless "Number Cores per Socket" is set too, and this number has to be a multiple of it, or vCenter will refuse the request.

(Optional) The CPU reservation, in MHz, guaranteeing this amount of physical CPU capacity to the new VM. (Named like the Reconfigure CPU step's setting, which also sets a reservation.)

Applied in the very same operation that creates the VM, rather than cloning at the source's size and reconfiguring afterwards. Has the same meaning as the setting of the same name of the "Reconfigure CPU"/"Reconfigure Memory" steps. Leave blank to keep the source VM's (or template's) own value. Variables can be used.

Mind that a reservation can make the cloned VM impossible to power on if the chosen host cannot guarantee it.

If the VM does not get an IP address within the time to wait for it, fail this build step. By default (unchecked) this only logs a warning and the build carries on, without the VSPHERE_IP variable being set. Check it if later steps need the address.

(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

(Optional, a whole number) Minimal free CPU in MHz a host must have right now to be a candidate for automatic host selection, as on the vSphere Cloud, where the limits are described in detail.

Leave all four host limit fields of this call blank to use the limits of the vSphere cloud. If you set any of them, the four values here replace the cloud's limits as a whole for this call, and the ones left blank count as 0 (no limit). Setting all four to 0 therefore removes the limits for this call, whatever the cloud has configured.

Variables can be used where this is a build step.

(Optional, a whole number) Minimal free CPU as a percentage of the host's capacity (0-100) a host must have right now to be a candidate for automatic host selection, as on the vSphere Cloud, where the limits are described in detail.

Leave all four host limit fields of this call blank to use the limits of the vSphere cloud. If you set any of them, the four values here replace the cloud's limits as a whole for this call, and the ones left blank count as 0 (no limit). Setting all four to 0 therefore removes the limits for this call, whatever the cloud has configured.

Variables can be used where this is a build step.

(Optional, a whole number) Minimal free RAM in MB a host must have right now to be a candidate for automatic host selection, as on the vSphere Cloud, where the limits are described in detail.

Leave all four host limit fields of this call blank to use the limits of the vSphere cloud. If you set any of them, the four values here replace the cloud's limits as a whole for this call, and the ones left blank count as 0 (no limit). Setting all four to 0 therefore removes the limits for this call, whatever the cloud has configured.

Variables can be used where this is a build step.

(Optional, a whole number) Minimal free RAM as a percentage of the host's memory (0-100) a host must have right now to be a candidate for automatic host selection, as on the vSphere Cloud, where the limits are described in detail.

Leave all four host limit fields of this call blank to use the limits of the vSphere cloud. If you set any of them, the four values here replace the cloud's limits as a whole for this call, and the ones left blank count as 0 (no limit). Setting all four to 0 therefore removes the limits for this call, whatever the cloud has configured.

Variables can be used where this is a build step.

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

(Optional, off by default) When no folder is given and the clone's host is set by the plugin (an explicit host, or automatic host selection), put the clone in a folder named after that host instead of in the folder of its source.

For inventories that group VMs in per-host folders: the folder of the source VM or template has the name of the host it is on as one element of its path. That element is replaced by the name of the host chosen for the clone, so a clone from a template on virt5x that is placed on virt4x goes to the same folder under virt4x. Short and fully qualified host names are matched alike, and the replacement uses the form the folder has.

If the source's folder path does not mention its host, or the folder for the chosen host does not exist, the source's own folder is used, as without this option, and a message about it is logged. A folder that is given explicitly always wins.

"Inherit" (the default) uses the setting of the vSphere cloud this belongs to; "Yes" or "No" overrides it for this one only.

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

(Optional, off by default) When automatic host selection is in use (a "Host Selection Mode" is set and no explicit host is given), only consider candidate hosts that have at least as much memory free right now as the VM being created is configured with, so the hypervisor does not have to start swapping to make room for it.

This differs from "Require enough RAM", which compares the memory installed in the host. This one uses the host's current memory usage as reported by vCenter, which changes by the minute and lags a little, so several VMs created at once can still land on the same host. A host whose memory usage is unknown does not qualify.

If no candidate host qualifies, a message is logged and placement is left to vCenter, as when no usable candidate host exists at all. It has no effect when an explicit host is given.

"Inherit" (the default) uses the setting of the vSphere cloud this belongs to; "Yes" or "No" overrides it for this one only.

(Optional, off by default) When automatic host selection is in use (a "Host Selection Mode" is set and no explicit host is given), only consider candidate hosts that are physically large enough in terms of CPU cores: the number of vCPUs the VM is configured with (taken from the source VM or template) must not exceed the host's number of physical CPU cores.

This compares the VM against each host's total capacity, not what is currently free, and applies in addition to the candidate list and to both "Least loaded" and "DRS" modes. Leave it off if your site deliberately oversubscribes (swap, hyperthreads, ...), so that a VM larger than a single host's physical resources is still allowed to be placed.

If no candidate host satisfies it, a message is logged and placement is left to vCenter, as when no usable candidate host exists at all. It has no effect when an explicit host is given.

"Inherit" (the default) uses the setting of the vSphere cloud this belongs to; "Yes" or "No" overrides it for this one only.

(Optional, off by default) When automatic host selection is in use (a "Host Selection Mode" is set and no explicit host is given), only consider candidate hosts that are physically large enough in terms of RAM: the VM's configured memory size (taken from the source VM or template) must not exceed the host's total physical RAM.

This compares the VM against each host's total capacity, not what is currently free, and applies in addition to the candidate list and to both "Least loaded" and "DRS" modes. Leave it off if your site deliberately oversubscribes (swap, hyperthreads, ...), so that a VM larger than a single host's physical resources is still allowed to be placed.

If no candidate host satisfies it, a message is logged and placement is left to vCenter, as when no usable candidate host exists at all. It has no effect when an explicit host is given.

"Inherit" (the default) uses the setting of the vSphere cloud this belongs to; "Yes" or "No" overrides it for this one only.

(Optional, a number) Pick at random among the hosts scoring within this fraction of the best one; negative: always the top host; above 1: any available host at random, load not considered. See the setting of the same name on the vSphere Cloud. Leave blank to use the cloud's setting. Variables can be used where this is a build step.

(Optional, a whole number of seconds) How long to wait, when automatic host selection finds no host that the VM can be created on at the moment (hosts too busy for the free resource limits, in maintenance, too small, not reporting usage, ...), before giving up. See the setting of the same name on the vSphere Cloud, which also says what giving up means.

• 0: do not wait; give up at once.
• a positive number: look at the hosts again every 15 seconds for up to that long.
• -1 or infinite: wait for as long as it takes (the build can still be aborted).

Leave blank to use the cloud's setting. Variables can be used where this is a build step.

(Optional, a whole number) How much a host's free CPU in MHz counts when automatic host selection looks for the "most available" host, as on the vSphere Cloud, where the scoring is described in detail.

Leave all four host weight fields of this call blank to use the weights of the vSphere cloud. If you set any of them, the four values here replace the cloud's weights as a whole for this call, and the ones left blank count as 0. Setting all four to 0 gives the original ranking (the host whose busier resource, CPU or memory, is the least used by percentage), whatever the cloud has configured.

Only the proportions between the weights matter, so 1 and 1 means the same as 50 and 50. Variables can be used.

(Optional, a whole number) How much a host's free CPU as percent of the host counts when automatic host selection looks for the "most available" host, as on the vSphere Cloud, where the scoring is described in detail.

Leave all four host weight fields of this call blank to use the weights of the vSphere cloud. If you set any of them, the four values here replace the cloud's weights as a whole for this call, and the ones left blank count as 0. Setting all four to 0 gives the original ranking (the host whose busier resource, CPU or memory, is the least used by percentage), whatever the cloud has configured.

Only the proportions between the weights matter, so 1 and 1 means the same as 50 and 50. Variables can be used.

(Optional, a whole number) How much a host's free RAM in MB counts when automatic host selection looks for the "most available" host, as on the vSphere Cloud, where the scoring is described in detail.

Leave all four host weight fields of this call blank to use the weights of the vSphere cloud. If you set any of them, the four values here replace the cloud's weights as a whole for this call, and the ones left blank count as 0. Setting all four to 0 gives the original ranking (the host whose busier resource, CPU or memory, is the least used by percentage), whatever the cloud has configured.

Only the proportions between the weights matter, so 1 and 1 means the same as 50 and 50. Variables can be used.

(Optional, a whole number) How much a host's free RAM as percent of the host counts when automatic host selection looks for the "most available" host, as on the vSphere Cloud, where the scoring is described in detail.

Leave all four host weight fields of this call blank to use the weights of the vSphere cloud. If you set any of them, the four values here replace the cloud's weights as a whole for this call, and the ones left blank count as 0. Setting all four to 0 gives the original ranking (the host whose busier resource, CPU or memory, is the least used by percentage), whatever the cloud has configured.

Only the proportions between the weights matter, so 1 and 1 means the same as 50 and 50. Variables can be used.

(Optional) The memory size, in MB, to create the new VM with.

Applied in the very same operation that creates the VM, rather than cloning at the source's size and reconfiguring afterwards. Has the same meaning as the setting of the same name of the "Reconfigure CPU"/"Reconfigure Memory" steps. Leave blank to keep the source VM's (or template's) own value. Variables can be used.

When the "Require enough CPU cores"/"Require enough RAM"/"Require enough free RAM" options are in effect, automatic host selection compares candidate hosts against this value instead of the source's.

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.

Prefix for guest info environmental variables. E.g. for prefix VM1, variables would be VM1_IpAddress, VM1_HostName etc.

The name of the VM to shut down.

If the VM is currently suspended, it will still be shutdown.

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.

The number of seconds after which the graceful shutdown attempt is abandoned, and hard power off is performed.

The name of the VM to power on.

The maximum number of seconds to wait for the IP.

If the VM does not get an IP address within the time to wait for it, fail this build step. By default (unchecked) this only logs a warning and the build carries on, without the VSPHERE_IP variable being set. Check it if later steps need the address.

The name of the VM or template to reconfigure.

The old name of the VM or template to be renamed.

The new name of the VM or template.

The name of the VM or template.

The old name of the snapshot to be renamed.

The new name of the snapshot.

The new description of the snapshot.

If the snapshot you are trying to rename does not exist, fail this build step (the default). Uncheck it when the job does not care and the snapshot may legitimately be absent, e.g. when rotating "current" to "old" before taking a new snapshot; the step then logs that there was nothing to rename and succeeds. A missing VM always fails the step.

The name of the VM.

The name of the snapshot.

The name of the VM to suspend.

The name of the VM you'd like to take a snapshot of.

The name of the snapshot.

The description to be saved with the snapshot.

Would you like to save the active memory in the snapshot?