Jenkins job to update machine labels and description

- This is part of what NodeMaintaince job will be doing
- This job only updates labels and desription
- Updated readme for UpdateMachineIdentifiers
- Replaced initial_run with overWriteLabels
- Added functionality to allow user to overwrite pre-configured labels

issue adoptium#10

Signed-off-by: Shubham Verma <shubhamv.sv@gmail.com>

Jenkins_jobs/UpdateMachineIdentifiers.groovy

@@ -0,0 +1,79 @@
+@Library('NodeHelper') _
+
+node {
+    String[] machineNames = params.machineNames.trim().split(",")
+    def nodeHelper = new NodeHelper();
+
+    /* if the flag updateDescription is not set we only update the labels
+     * The user can chose to either overwrite, add preconfigured labels or append labels
+     *
+     * To overwrite labels, the overwrite flag must be set
+     * To add preconfigured labels, only the manchine names need to passed in
+     * To append labels, a set of label(s) must be passed in
+     */
+    stage('Update_Labels') {
+        String[] labels;
+        if (!params.labels.isEmpty()) {
+            labels = params.labels.trim().split(",")
+        }
+
+        for (int index = 0; index < machineNames.length; index++) {
+            println "Machine ${machineNames[index]} old labels: ${nodeHelper.getLabels(machineNames[index])}"
+
+            if (!params.overWriteLabels && params.projectLabel.isEmpty()) {
+                // We shoulidn't be touching any machine if a project label isn't is passed
+                error("Neither project label was provied nor overWriteLabels flag was set")
+            }
+
+
+            if (params.overWriteLabels) {
+
+                if (labels == null) { // No labels have been supplied so we'll overwrite just with preconfigured labels 
+                    String constructedLabels = "${nodeHelper.constructLabels(machineNames[index])}"
+                    println "Machine ${machineNames[index]} updated labels: ${nodeHelper.addLabel(machineNames[index],constructedLabels)}"
+                } else { // else overwrite with the supplied labels
+                    println "Machine ${machineNames[index]} updated labels: ${nodeHelper.addLabel(machineNames[index], labels[index%labels.length])}"    
+                }
+
+            } else if (params.projectLabel.equals("all")
+                        || nodeHelper.getLabels(machineNames[index]).contains(params.projectLabel)) {
+
+                if (labels == null) { // Add preconfigured labels
+
+                    String constructedLabels = "${params.projectLabel} ${nodeHelper.constructLabels(machineNames[index])}"
+                    println "Machine ${machineNames[index]} updated labels: ${nodeHelper.addLabel(machineNames[index],constructedLabels)}"
+
+                } else { // Append labels
+                    println "Machine ${machineNames[index]} updated labels: ${nodeHelper.appendLabel(machineNames[index], labels[index%labels.length])}"
+                }
+
+            }
+        }
+    }
+    if (params.updateDescription) {
+        /* Update the description if the updateDescription flag is set
+         * This stage assumes that the description doesn't already have RAM, CPU and disk info
+         */
+        stage('Update_Description') {
+            // def nodeHelper = new NodeHelper();
+
+            for (int index = 0; index < machineNames.length; index++) {
+                println "Pre-update description of ${machineNames[index]}: ${nodeHelper.getDescription(machineNames[index])}"
+                if (params.projectLabel.equals("all")
+                        || nodeHelper.getLabels(machineNames[index]).contains(params.projectLabel)) {
+
+                    String description = nodeHelper.getDescription(machineNames[index]);
+                    description += " - ${nodeHelper.getCpuCount(machineNames[index])}CPU";
+                    description += " ${nodeHelper.getMemory(machineNames[index]).get(0)} RAM";
+                    description += " ${nodeHelper.getTotalSpace(machineNames[index])} Disk";
+
+                    String updatedDescription = nodeHelper.setDescription(machineNames[index], description);
+                    println "Description of ${machineNames[index]} has been updated to ${updatedDescription}";
+
+                } else {
+                    println "Machine specified ${machineNames[index]} does not belong to the project ${params.projectLabel}";
+                }
+            }
+        }
+    }
+}

README.md

@@ -3,6 +3,7 @@
 ## Files
 ### API Functions (NodeHelper.groovy)
 The NodeHelper API contains helper functions to query basic machine stats in real time, add new machines, update/overwrite labels.
+
 * Get CPU count ```String getCpuCount(String computerName)```
 * Get Installed memory ```Tuple  getMemory(String computerName)```
 * Get OS information ```Tuple  getOsInfo(String computerName)```
@@ -20,6 +21,7 @@ The NodeHelper API contains helper functions to query basic machine stats in rea
 
 ### Space Monitoring (WorkspaceInfo.groovy)
 Iterates over online nodes on Jenkins and prints the contents of the workspace directory along with the space they occupy
+
 * The computers it iterates over can be limited by input parameter, ```projectLabel```
 * As of now, it only works for linux, aix, and mac
 
@@ -36,6 +38,42 @@ Used to create new nodes with any basic labels
         * Each label must be separated by spaces and labels for different machines must be separated by `,`
         * If identical labels need to be applied to all the machines, only one set of labels need to be supplied
 
+### Update Machine Identifiers (UpdateMachineIdentifiers.groovy)
+Used to update machine labels and description
+
+* The computers it iterates over can be limited by input parameter, ```projectLabel```
+* The job expects 5 input parameters
+    * ```boolean overWriteLabels```
+        * Does excatly as the name suggests, completely wipes previous labels
+        * If set true, you do not need to pass a ```projectLabel```
+    * ```String labels```
+        * Labels you would like to be added to the machine.
+         * Each label must be separated by spaces and labels for different machines must be separated by `,` 
+         * If identical labels need to be applied to all the machines, only one set of labels need to be supplied
+         * Use Cases:
+              * Multiple machines, unique labels: `machine1Label1 machine1Label2, machine2Label1 machine2Label2`
+              * Single or multiple machines, identical labels: `Label1 Label2`
+    * ```String machineNames```
+        * Can either enter a list of names or a single name. For list seperate them with ","
+    * ```boolean updateDescription```
+        * If this is set true, the job will update description
+        * This has higher precedence than overWriteLabels
+    * ```String projectlabel```
+        * This limits which machines will be touched
+* Use Cases:
+    * Update labels:
+        * Objective: add default labels(os, arch, and kernel)
+        * Procedure: overWriteLabels is not set and only the machine name(s) is supplied
+    * Overwrite Labels:
+        * Objective: overwrite previous labels with new ones
+        * Procedure: overWriteLabels is set and machine name(s) + labels are supplied
+    * Append labels:
+        * Objective: want to add a custom label.
+        * Procedure: supply labels and machine names
+    * Update description:
+        * It adds CPU count, Disk space and installed RAM to the description
+        * Procedure: have ```updateDescription``` parameter checked
+
 ## How-to
 
 ### Setup

src/NodeHelper.groovy

@@ -856,6 +856,26 @@ class  NodeHelper {
         return ret;
     }
 
+    /**
+     * Sets the machine description from jenkins
+     *
+     * @param compterName computer whose location is needed
+     * @param description the new updated description
+     *
+     * @return machine description as string
+     */
+    public String setDescription(String computerName, String description) {
+        String ret = "setDescription:COMPUTER_NOT_FOUND";
+
+        Computer computer = getComputer(computerName);
+        if (computer != null) {
+            computer.getNode().setNodeDescription(description);
+            ret = getDescription(computerName);
+        }
+
+        return ret;
+    }
+
     /**
      * Gets cpu count via exec on the computer passed
      * in.