buildStep Clone: expose all options of cloneOrDeployVm() method, allow to use namedSnapshot and extraConfigParameters

src/main/java/org/jenkinsci/plugins/vsphere/builders/Clone.java

@@ -28,6 +28,8 @@
 import java.io.PrintStream;
 import java.io.PrintWriter;
 import java.io.StringWriter;
+import java.util.HashMap;
+import java.util.Map;
 
 import edu.umd.cs.findbugs.annotations.NonNull;
 
@@ -60,211 +62,286 @@
     private final Integer timeoutInSeconds;
     private String IP;
 
+    /** Optionally used by {@code #linkedClone} setting or on its own,
+     *  conflicts with {@code #namedSnapshot}. Is {@code null} by default. */
+    private final Boolean useCurrentSnapshot;
+    /** Optionally used by {@code #linkedClone} setting or on its own,
+     *  conflicts with {@code #useCurrentSnapshot}. Is {@code null} by default. */
+    private final String namedSnapshot;
+    private final Map<String, String> extraConfigParameters;
+
     @DataBoundConstructor
     public Clone(String sourceName, String clone, boolean linkedClone,
                  String resourcePool, String cluster, String datastore, String folder,
-                 boolean powerOn, Integer timeoutInSeconds, String customizationSpec) throws VSphereException {
+                 boolean powerOn, Integer timeoutInSeconds, String customizationSpec,
+                 Boolean useCurrentSnapshot, String namedSnapshot,
+                 Map<String, String> extraConfigParameters) throws VSphereException {
         this.sourceName = sourceName;
         this.clone = clone;
         this.linkedClone = linkedClone;
-        this.resourcePool=resourcePool;
-        this.cluster=cluster;
-        this.datastore=datastore;
-        this.folder=folder;
-        this.customizationSpec=customizationSpec;
-        this.powerOn=powerOn;
+        this.resourcePool = resourcePool;
+        this.cluster = cluster;
+        this.datastore = datastore;
+        this.folder = folder;
+        this.customizationSpec = customizationSpec;
+        this.powerOn = powerOn;
         this.timeoutInSeconds = timeoutInSeconds;
+        this.useCurrentSnapshot = useCurrentSnapshot;
+
+        // Config form data may involve empty strings - treat them as null
+        if (namedSnapshot == null || namedSnapshot.isEmpty()) {
+            this.namedSnapshot = null;
+        } else {
+            this.namedSnapshot = namedSnapshot;
+        }
+
+        if (extraConfigParameters == null || extraConfigParameters.isEmpty()) {
+            this.extraConfigParameters = null;
+        } else {
+            this.extraConfigParameters = extraConfigParameters;
+        }
     }
 
     public String getSourceName() {
         return sourceName;
     }
 
     public String getClone() {
         return clone;
     }
 
     public boolean isLinkedClone() {
         return linkedClone;
     }
 
+    public String getNamedSnapshot() {
+        return namedSnapshot;
+    }
+
+    public boolean isUseCurrentSnapshot() {
+        if (useCurrentSnapshot == null) {
+            if (namedSnapshot == null) {
+                // Hard-coded default in VSphere.cloneVm()
+                // TOTHINK: Should this rely on linkedClone value?
+                return true;
+            }
+
+            // Will use specified named snapshot
+            return false;
+        }
+
+        // Caller had an explicit request
+        // Note that if linkedClone==true, at least some snapshot must be used
+        return useCurrentSnapshot;
+    }
+
     public String getCluster() {
         return cluster;
     }
 
     public String getResourcePool() {
         return resourcePool;
     }
 
     public String getDatastore() {
         return datastore;
     }
 
     public String getFolder() {
         return folder;
     }
 
     public String getCustomizationSpec() {
         return customizationSpec;
     }
 
     public boolean isPowerOn() {
         return powerOn;
     }
 
     public int getTimeoutInSeconds() {
         if (timeoutInSeconds==null) {
             return TIMEOUT_DEFAULT;
         }
         return timeoutInSeconds.intValue();
     }
 
+    public Map<String, String> getExtraConfigParameters() {
+        return extraConfigParameters;
+    }
+
     @Override
     public void perform(@NonNull Run<?, ?> run, @NonNull FilePath filePath, @NonNull Launcher launcher, @NonNull TaskListener listener) throws InterruptedException, IOException {
         try {
             cloneFromSource(run, launcher, listener);
         } catch (Exception e) {
             throw new AbortException(e.getMessage());
         }
     }
 
     @Override
     public String getIP() {
         return IP;
     }
 
     @Override
     public boolean perform(final AbstractBuild<?, ?> build, final Launcher launcher, final BuildListener listener) throws AbortException {
         boolean retVal = false;
         try {
             retVal = cloneFromSource(build, launcher, listener);
         } catch (Exception e) {
             StringWriter sw = new StringWriter();
             PrintWriter pw = new PrintWriter(sw);
             e.printStackTrace(pw);
             VSphereLogger.vsLogger(listener.getLogger(), "Error cloning VM or template\n" + sw.toString());
 
             try {
                 sw.close();
             } catch (Exception ex) {
                 // ignore
             }
             throw new AbortException(e.getMessage());
         }
         return retVal;
     }
 
     private boolean cloneFromSource(final Run<?, ?> run, final Launcher launcher, final TaskListener listener) throws VSphereException {
         PrintStream jLogger = listener.getLogger();
         String expandedClone = clone;
         String expandedSource = sourceName;
         String expandedCluster = cluster;
         String expandedDatastore = datastore;
         String expandedFolder = folder;
         String expandedResourcePool = resourcePool;
         String expandedCustomizationSpec = customizationSpec;
+        String expandedNamedSnapshot = namedSnapshot;
+        Map<String, String> expandedExtraConfigParameters;
         EnvVars env;
         try {
             env = run.getEnvironment(listener);
         } catch (Exception e) {
             throw new VSphereException(e);
         }
 
         if (run instanceof AbstractBuild) {
             env.overrideAll(((AbstractBuild) run).getBuildVariables()); // Add in matrix axes..
             expandedClone = env.expand(clone);
             expandedSource = env.expand(sourceName);
             expandedCluster = env.expand(cluster);
             expandedDatastore = env.expand(datastore);
             expandedFolder = env.expand(folder);
             expandedResourcePool = env.expand(resourcePool);
             expandedCustomizationSpec = env.expand(customizationSpec);
+            if (namedSnapshot != null) {
+                expandedNamedSnapshot = env.expand(namedSnapshot);
+            }
         }
-        vsphere.cloneVm(expandedClone, expandedSource, linkedClone, expandedResourcePool, expandedCluster,
-                expandedDatastore, expandedFolder, powerOn, expandedCustomizationSpec, jLogger);
+
+        if (extraConfigParameters != null && !(extraConfigParameters.isEmpty())) {
+            // Always pass a copy of the non-trivial original parameter map
+            // (expanded or not), just in case, to protect caller's data.
+            expandedExtraConfigParameters = new HashMap<String, String>();
+            if (run instanceof AbstractBuild) {
+                extraConfigParameters.forEach((k, v) -> expandedExtraConfigParameters.put(k, env.expand(v)));
+            } else {
+                expandedExtraConfigParameters.putAll(extraConfigParameters);
+            }
+        } else {
+            // Only init to null here, due to lambda used in forEach() above
+            expandedExtraConfigParameters = null;
+        }
+
+        vsphere.cloneOrDeployVm(expandedClone, expandedSource, linkedClone, expandedResourcePool, expandedCluster,
+                expandedDatastore, expandedFolder, this.isUseCurrentSnapshot(), expandedNamedSnapshot,
+                powerOn, expandedExtraConfigParameters, expandedCustomizationSpec, jLogger);
+
         final int timeoutInSecondsForGetIp = getTimeoutInSeconds();
         if (powerOn && timeoutInSecondsForGetIp>0) {
             VSphereLogger.vsLogger(jLogger, "Powering on VM \""+expandedClone+"\".  Waiting for its IP for the next "+timeoutInSecondsForGetIp+" seconds.");
             IP = vsphere.getIp(vsphere.getVmByName(expandedClone), timeoutInSecondsForGetIp);
         }
         VSphereLogger.vsLogger(jLogger, "\""+expandedClone+"\" successfully cloned " + (powerOn ? "and powered on" : "") + "!");
 
         return true;
     }
 
     @Extension
     public static final class CloneDescriptor extends VSphereBuildStepDescriptor {
 
         public CloneDescriptor() {
             load();
         }
 
         @Override
         public String getDisplayName() {
             return Messages.vm_title_Clone();
         }
 
         public static int getDefaultTimeoutInSeconds() {
             return TIMEOUT_DEFAULT;
         }
 
         public FormValidation doCheckSource(@QueryParameter String value) {
             if (value.length() == 0)
                 return FormValidation.error("Please enter the sourceName name");
             return FormValidation.ok();
         }
 
         public FormValidation doCheckClone(@QueryParameter String value) {
             if (value.length() == 0)
                 return FormValidation.error(Messages.validation_required("the clone name"));
             return FormValidation.ok();
         }
 
         @RequirePOST
         public FormValidation doCheckResourcePool(@AncestorInPath Item context,
                                                   @QueryParameter String value,
                                                   @QueryParameter String serverName,
                                                   @QueryParameter String sourceName) {
             throwUnlessUserHasPermissionToConfigureJob(context);
             try {
                 if (serverName == null){
                     return FormValidation.error(Messages.validation_required("serverName"));
                 }
                 VSphere vsphere = getVSphereCloudByName(serverName, null).vSphereInstance();
 
                 VirtualMachine virtualMachine = vsphere.getVmByName(sourceName);
                 if (virtualMachine == null) {
                     return FormValidation.error("The source VM \""+sourceName+"\"was not found cannot check the configuration.");
                 }
                 if ((virtualMachine.getConfig().template) && (value.length() == 0)) {
                     return FormValidation.error(Messages.validation_required("the resource pool"));
                 }
             } catch (VSphereException ve) {
                 return FormValidation.error("Cannot connect to vsphere. "+ve.getMessage());
             }
             return FormValidation.ok();
         }
 
         public FormValidation doCheckCluster(@QueryParameter String value) {
             if (value.length() == 0)
                 return FormValidation.error(Messages.validation_required("the cluster"));
             return FormValidation.ok();
         }
 
         public FormValidation doCheckCustomizationSpec(@QueryParameter String value) {
             return FormValidation.ok();
         }
 
         public FormValidation doCheckTimeoutInSeconds(@QueryParameter String value) {
             return FormValidation.validateNonNegativeInteger(value);
         }
 
         @RequirePOST
         public FormValidation doTestData(@AncestorInPath Item context,
                                          @QueryParameter String serverName,
                                          @QueryParameter String sourceName, @QueryParameter String clone,
                                          @QueryParameter String resourcePool, @QueryParameter String cluster,
-                                         @QueryParameter String customizationSpec) {
+                                         @QueryParameter String customizationSpec,
+                                         @QueryParameter Boolean linkedClone,
+                                         @QueryParameter Boolean useCurrentSnapshot,
+                                         @QueryParameter String namedSnapshot) {
+            // TODO? @QueryParameter Map<String, String> extraConfigParameters
             throwUnlessUserHasPermissionToConfigureJob(context);
             try {
                 if (sourceName.length() == 0 || clone.length()==0 || serverName.length()==0
@@ -285,9 +362,21 @@
                 if (vm == null)
                     return FormValidation.error(Messages.validation_notFound("sourceName"));
 
-                VirtualMachineSnapshot snap = vm.getCurrentSnapShot();
-                if (snap == null)
-                    return FormValidation.error(Messages.validation_noSnapshots());
+                if (linkedClone || useCurrentSnapshot || (namedSnapshot != null && !(namedSnapshot.isEmpty()))) {
+                    // Use-case (according to parameters) requires a snapshot
+                    VirtualMachineSnapshot snap;
+                    if (namedSnapshot == null || namedSnapshot.isEmpty()) {
+                        // either useCurrentSnapshot or linkedClone is true
+                        snap = vm.getCurrentSnapShot();
+                    } else {
+                        // namedSnapshot is non-trivial
+                        if (useCurrentSnapshot)
+                            return FormValidation.error(Messages.validation_useCurrentAndNamedSnapshots());
+                        snap = vsphere.getSnapshotInTree(vm, namedSnapshot);
+                    }
+                    if (snap == null)
+                        return FormValidation.error(Messages.validation_noSnapshots());
+                }
 
                 if(customizationSpec != null && customizationSpec.length() > 0 &&
                         vsphere.getCustomizationSpecByName(customizationSpec) == null) {

src/main/java/org/jenkinsci/plugins/vsphere/tools/VSphere.java

@@ -147,7 +147,6 @@
         final boolean useCurrentSnapshotIsFALSE = false;
         final String namedSnapshotIsNULL = null;
         final Map<String, String> extraConfigParameters = null;
-        logMessage(jLogger, "Deploying new vm \""+ cloneName + "\" from template \""+sourceName+"\"");
         cloneOrDeployVm(cloneName, sourceName, linkedClone, resourcePoolName, cluster, datastoreName, folderName, useCurrentSnapshotIsFALSE, namedSnapshotIsNULL, powerOn, extraConfigParameters, customizationSpec, jLogger);
     }
 
@@ -170,7 +169,6 @@
         final boolean useCurrentSnapshotIsTRUE = true;
         final String namedSnapshotIsNULL = null;
         final Map<String, String> extraConfigParameters = null;
-        logMessage(jLogger, "Creating a " + (linkedClone?"shallow":"deep") + " clone of \"" + sourceName + "\" to \"" + cloneName + "\"");
         cloneOrDeployVm(cloneName, sourceName, linkedClone, resourcePoolName, cluster, datastoreName, folderName, useCurrentSnapshotIsTRUE, namedSnapshotIsNULL, powerOn, extraConfigParameters, customizationSpec, jLogger);
     }
 
@@ -220,6 +218,21 @@
      *             if anything goes wrong.
      */
     public void cloneOrDeployVm(String cloneName, String sourceName, boolean linkedClone, String resourcePoolName, String cluster, String datastoreName, String folderName, boolean useCurrentSnapshot, final String namedSnapshot, boolean powerOn, Map<String, String> extraConfigParameters, String customizationSpec, PrintStream jLogger) throws VSphereException {
+        if (namedSnapshot == null && extraConfigParameters == null) {
+            // NOTE: This "if" clause may be superfluous - just that previously
+            // this message was only logged by cloneVm() or deployVm()... so for
+            // least surprise and unexpected noise in the logs, effectively kept
+            // so for upgraded plugins where we can also directly call this method
+            // as a "buildStep" under a "vSphere" pipeline step.
+            if (useCurrentSnapshot) {
+                // Called from cloneVm() above.
+                logMessage(jLogger, "Creating a " + (linkedClone ? "shallow" : "deep") + " clone of \"" + sourceName + "\" to \"" + cloneName + "\"");
+            } else {
+                // Called from deployVm() above.
+                logMessage(jLogger, "Deploying new vm \""+ cloneName + "\" from template \""+sourceName+"\"");
+            }
+        }
+
         try {
             final VirtualMachine sourceVm = getVmByName(sourceName);
             if (sourceVm==null) {
@@ -239,19 +252,19 @@
 
             if (namedSnapshot != null && !namedSnapshot.isEmpty()) {
                 if (useCurrentSnapshot) {
-                    throw new IllegalArgumentException("It is not valid to request a clone of " + sourceType + "  \"" + sourceName + "\" based on its snapshot \"" + namedSnapshot + "\" AND also specify that the latest snapshot should be used.  Either choose to use the latest snapshot, or name a snapshot, or neither, but not both.");
+                    throw new IllegalArgumentException("It is not valid to request a clone of " + sourceType + " \"" + sourceName + "\" based on its snapshot \"" + namedSnapshot + "\" AND also specify that the latest snapshot should be used.  Either choose to use the latest snapshot, or name a snapshot, or neither, but not both.");
                 }
                 final VirtualMachineSnapshot namedVMSnapshot = getSnapshotInTree(sourceVm, namedSnapshot);
                 if (namedVMSnapshot == null) {
-                    throw new VSphereNotFoundException("Snapshot", namedSnapshot, "Source " + sourceType + "  \"" + sourceName + "\" has no snapshot called \"" + namedSnapshot + "\".");
+                    throw new VSphereNotFoundException("Snapshot", namedSnapshot, "Source " + sourceType + " \"" + sourceName + "\" has no snapshot called \"" + namedSnapshot + "\".");
                 }
                 logMessage(jLogger, "Clone of " + sourceType + " \"" + sourceName + "\" will be based on named snapshot \"" + namedSnapshot + "\".");
                 cloneSpec.setSnapshot(namedVMSnapshot.getMOR());
             }
             if (useCurrentSnapshot) {
                 final VirtualMachineSnapshot currentSnapShot = sourceVm.getCurrentSnapShot();
                 if (currentSnapShot==null) {
-                    throw new VSphereNotFoundException("Snapshot", null, "Source " + sourceType + "  \"" + sourceName + "\" requires at least one snapshot.");
+                    throw new VSphereNotFoundException("Snapshot", null, "Source " + sourceType + " \"" + sourceName + "\" requires at least one snapshot.");
                 }
                 logMessage(jLogger, "Clone of " + sourceType + " \"" + sourceName + "\" will be based on current snapshot \"" + currentSnapShot.toString() + "\".");
                 cloneSpec.setSnapshot(currentSnapShot.getMOR());

src/main/resources/org/jenkinsci/plugins/vsphere/builders/Clone/config.jelly

@@ -28,6 +28,14 @@ limitations under the License.
     <f:checkbox  />
   </f:entry>
 
+  <f:entry title="${%Use Current Snapshot?}" field="useCurrentSnapshot">
+    <f:checkbox  />
+  </f:entry>
+
+  <f:entry title="${%Use Named Snapshot?}" field="namedSnapshot">
+    <f:textbox  />
+  </f:entry>
+
   <f:entry title="${%Cluster}" field="cluster">
     <f:textbox  />
   </f:entry>
@@ -54,5 +62,7 @@ limitations under the License.
     </f:entry>
   </f:optionalBlock>
 
+  <!-- TODO: How can we specify an optional Map<String,String> to set extraConfigParameters? -->
+
   <f:validateButton title="${%Check Data}" progress="${%Testing...}" method="testData" with="serverName,sourceName,clone,resourcePool,cluster"/>
 </j:jelly>

src/main/resources/org/jenkinsci/plugins/vsphere/builders/Clone/help-extraConfigParameters.html

@@ -0,0 +1,9 @@
+<div>
+  (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
+  <tt>vmtoolsd --cmd "info-get guestinfo.Foo"</tt>.
+</div>

src/main/resources/org/jenkinsci/plugins/vsphere/builders/Clone/help-namedSnapshot.html

@@ -0,0 +1,6 @@
+<div>
+  If set then the clone will be created from the source VM's
+  snapshot of this name.
+  If this is set then <tt>useCurrentSnapshot</tt> must not be set.
+  May impact the <tt>linkedClone</tt> behavior.
+</div>

src/main/resources/org/jenkinsci/plugins/vsphere/builders/Clone/help-useCurrentSnapshot.html

@@ -0,0 +1,7 @@
+<div>
+  If true then the clone will be created from the source VM's
+  "current" snapshot. This means that the VM <em>must</em> have
+  at least one snapshot.
+  If this is set then <tt>namedSnapshot</tt> must not be set.
+  May impact the <tt>linkedClone</tt> behavior.
+</div>

src/main/resources/org/jenkinsci/plugins/vsphere/builders/Messages.properties

@@ -33,6 +33,7 @@ validation.alreadySet=Specified {0} is already a {1}!
 validation.exists=Specified {0} already exists!
 validation.notActually=Specified {0} is not actually a {0}!
 validation.noSnapshots=No snapshots found for specified template!
+validation.useCurrentAndNamedSnapshots=Can not specify use of both a named and a current snapshot!
 validation.positiveInteger={0} must be a positive integer!
 validation.maxValue=Please enter a value less than {0}!
 validation.success=Success