Skip to end of metadata
Go to start of metadata

Plugin Information

View Node and Label parameter on the plugin site for more information.

This plugin adds two new parameter types to job configuration - node and label, this allows to dynamically select the node where a job/project should be executed.

Description

The plugin allows to configure additional parameters for a job. These new parameter types are 'Node' and 'Label'. This is specially useful if you want to execute the job on different nodes without changing the configuration over and over again. It also allows you to use Jenkins in a scenario where you would like to setup different nodes with the same script/jobs configured - e.g. SW provisioning.
Another usage scenario would be to configure a node maintenance job which you could trigger on request on each node.

Restrict where this project can be run

If your using a node or label parameter to run your job on a particular node, you should not use the option "Restrict where this project can be run" in the job configuration - it will not have any effect to the selection of your node anymore!

  • Node

    Define a list of nodes on which the job should be allowed to be executed on. A default node used for scheduled jobs can be defined.
    You are able to configure the job to run one after the other or even concurrent.


In case multi node selection was disabled, you get a dropdown to select one node to execute the job on.

If multi node selection was enabled, you get the chance to select multiple nodes to run the job on. The job will then be executed on each of the nodes, one after the other or concurrent - depending on the configuration.

  • Label

    Define a label of 'Restrict where this project can be run' on the fly.

Trigger via script

One can also trigger a job via remote call (e.g. script)

Trigger job on multiple nodes:

curl --silent -u USER:PASSWORD --show-error --data 'json={"parameter":[{"name":"PARAMNAME","value":["node1","node2"]}]}&Submit=Build' http://localhost:8080/job/remote/build?token=SECTOKEN

Although the first format also supports passing just one node name as parameter in the list, the plugin also supports to pas a simple key/value parameter to trigger the job on  single node only:

curl --silent -u USER:PASSWORD --show-error --data 'json={"parameter":[{"name":"PARAMNAME","value":"master"}]}&Submit=Build' http://localhost:8080/job/remote/build?token=SECTOKEN

If you have a 'label' parameter (instead of a 'node' parameter), then the request should look like this:

curl --silent -u USER:PASSWORD --show-error --data 'json={"parameter":[{"name":"PARAMNAME","label":"mylabel"}]}&Submit=Build' http://localhost:8080/job/remote/build?token=SECTOKEN

It is also possible to pass the parameter via GET (example: NODENAME is a 'Node' parameter defined on the job):

 http://localhost:8080/jenkins/job/MyJob/buildWithParameters?NODENAME=node1

Parameterized Trigger plugin

Post Build Action

If the Parameterized Trigger Plugin is installed, an additional parameter is available to pass to the target job. The parameterized trigger plugin handles Node and Label parameters as every other parameter if you use the option 'Current build parameters'.
But it is not possible to use the 'Predefined parameters' to overwrite such a parameter, therefore the NodeLabel Parameter plugin adds a new parameter to the trigger plugin.

This parameter type defines where the target job should be executed, the value must match either a label or a node name - otherwise the job will just stay in the queue. The NodeLabel parameter passed to the target job, does not have to exist on the target job (but if the target has one defined, it should match the name). This way it is possible to trigger jobs on different nodes then they are actually configured.

BuildParameterFactory

The nodelabel parameter plugin also adds a BuildParameterFactory to the parameterized trigger plugin, this factory enables you to trigger a build of a specific project on all nodes having the same label.

  1. Add the a "Trigger/call builds on other projects" build step
  2. define the project you want to run on each node
  3. select the "All Nodes for Label Factory" from the "Add ParameterFactory" dropdown
  4. define the label identifying all the nodes you want to run the project on

Similarly, you can also add "Build on every online node" as a parameter factory. This will cause the specified projects to run on all nodes (master and all slaves) that are online and have non-zero executor configured to it.

Version History

1.7 (7. Dec. 2015)

  • fix JENKINS-22185 Trigger a build in all nodes matching a label (thanks to Antonio)

1.6 (23. Nov. 2015)

  • add MIT license PR #8 (thanks vaneyckt)
  • fix JENKINS-28374 enable triggering via rebuild plugin (thanks lrobertson39)
  • fix JENKINS-27880 expose value in API (thanks Charles Stephens)
  • fix typo PR #4 (thanks guysoft)

1.5.1 (2. March 2014)

  • fix JENKINS-21828 encoding issues with german "umlaute"
  • integrate PR #3  LabelParameterDefinition extends SimpleParameterDefinition to support better integration with other plugins

1.5.0 (10. Feb 2014)

  • implement JENKINS-17660 for convenience, allow usage of 'value' for calls of label parameters via script
  • implement JENKINS-21194 add notion of NodeEligibility to differentiate between different offline modes of nodes
  • new feature: "build on all nodes matching label" for Label parameter
  • fix JENKINS-20885 default node not selected in dropdown
  • fix JENKINS-20823 Stack Trace when Configuring a task with "Label Factory"
  • lift dependency to core 1.509.4

1.4 (28. March 2013)

  • implement JENKINS-17305 don't wait for offline nodes (new option added for node parameter and parameter factory)
  • implement JENKINS-14407 allow multi-value default for scheduled builds

1.3 (9. Dec 2012)

  • Add new build parameter factory for Parameterized Trigger Plugin : List of nodes - factory takes a list of nodes to trigger the job on
  • fix JENKINS-15339 breaks Windows batch file build steps if Name field not filled in
  • fix JENKINS-15370 Value of Node param variable does not contain all values when selecting multiple nodes

1.2.1 (2. July 2012)

  • fixed JENKINS-14230 Node parameter value can't be passed by HTTP GET

1.2 (25. June 2012)

1.1.4 (21. May 2012)

  • supported a build parameter factory that lets you run a specified job on all the slaves.

1.1.3 (11. May 2012)

  • fix JENKINS-13704 Unable to start a concurrent build when there are nodeParameterValues

1.1.2 (25. Feb. 2011)

  • fix JENKINS-12226 Triggering a build with "Current build parameters" fails when the current build parameters includes a node name
  • fix issue if a a job has many parameters

1.1.1 (27. Nov. 2011)

  • Fix issue if a label was using expressions

1.1.0 (15. Nov. 2011)

  • Added a BuildParameterFactory to get all Nodes for a Label when triggered via buildstep from "parameterized-trigger-plugin" (pull #1, thanks to wolfs)

1.0.0 (18. Sep. 2011)

  • fix JENKINS-10982 trim labels / nodes
  • fix JENKINS-11006 fix remote triggering (e.g. via script)
  • enhance node parameter to support concurrent job execution
  • ...in case you have an issue after updating to this version, try to just open the job configuration and save it again.

0.2.0

  • add badge icon to show on which node/label the build was done
  • add support to execute the job on multiple nodes automatically  (one after the other)

0.1.2

  • add additional parameter to parameterized-trigger plugin (JENKINS-10088)

0.1.0

  • Inital

Help and Support

type key summary

Data cannot be retrieved due to an unexpected error.

View these issues in Jira

For Help and support please use the Jenkins Users mailing list.
The comment list below is not monitored.

18 Comments

  1. I'm trying to use this plugin both from wgets and through the Groovy Postbuild Plugin. When I use the wget, Jenkins recieves the job with a blank node and when I use the Groovy Postbuild Plugin, the job acts normal and runs on a random node. How can I access the NodeParameterValue object so that I can specify it within groovy?

    1. Hi,

      I have succeeded in doing what you want by using

      new org.jvnet.jenkins.plugins.nodelabelparameter.LabelParameterValue('node', 'node name')

      inspite of usual

      new hudson.model.StringParameterValue('node', 'value')

  2. Hi there, this plugin has huge potential for me to run tests in parallel. I'm a little stuck in the sense that I cannot seem to retrieve the list of nodes I selected when I build from a system groovy script. Ok well I can retrieve it but the value isn't what I expected.

    I have a parameterized build that contains a Node parameter named HOSTS. I've selected "Allow multi node selection for concurrent builds" and I've checked the box further down to allow executing concurrent builds. I have a system groovy script further down the page that contains this snippet of code:

    import hudson.model.*
    import hudson.util.*
    def build = Thread.currentThread().executable
    def resolver = build.buildVariableResolver
    def chosenHosts = resolver.resolve("HOSTS")
    println "HOSTS from System Groovy Script= " + chosenHosts
    

    When I build I select node1 and node2 from the list. It builds and executes on both nodes.
    However the value of chosenHosts in the job that ran on node 1 prints a value of node1
    The job that executed on node2 prints a value of null.
    What I expected was that the value of chosenHosts would be "node1, node2".

    I'm wondering what I'm doing wrong to try and retrieve the list of hosts that was selected.

    This is in a system groovy script, so it is executing on the master. Where I'm going with this is, once I can retrieve the list of nodes that the job is executing on, I plan to inject this variable with envinject to pass it down to the slaves for further processing. This will allow me to instruct my test runner to execute a subset of test packages, thereby distributing my testing across multiple nodes. (Side note, the DistTest plugin cannot do this by package, already been down that road).

    Thanks so much for your help! I've never posted here before so if there's a more appropriate place to ask this question I'm happy to move my post there instead.

  3. When I select NODE parameter, it shows "All ... , master, in the list with other nodes that i just want to show".. so confusing to a user.

    When I select LABEL paramter, i dont see a choice funcationality.

    Isn't there a way to use "Restrict where this project can be run" checkbox and the value will be "%variable%", where 'variable' will hold / is one of the choice parameter's variable's / value. In simple words, why can't value for "Restrict..." allows variable substitution.

  4. I have a job B which has a label parameter named "MAIN_RUN_NODE" in parameterized build section (no default value)

    I'm calling B from job A as a Multujob phase, while passing (through Multijob params) MAIN_RUN_NODE=$NODE_NAME (I want B to run on the same node A started on).

    However it seems to completely ignore the parameter when passed in such fashion.

    I also tried in addition setting "Restrict where this project can be run" to $MAIN_RUN_NODE only to have the jobs hang indefinitely waiting for nodes under label "$MAIN_RUN_NODE" to become available - it doesn't expend the variable. I have 1 jenkins master where the latter works, but on all other masters despite all efforts it seems to be unable to resolve the variable properly.

    Any ideas?

  5. Hi,

    I am trying to run a job on multiple slaves, concurrently, and on the same custom workspace.

    For example:

    I have a project that needs to be checked out from the svn server to slaves A, B, and C and to the following workspace destination:

    c:\path\to\workspace 

    Finally, run a maven command on c:\path\to\workspace\checked-out-project folder.

    I could do everything described in this example except for running a job on multiple slaves on my custom workspace.

    Any help will be appreciated. Thanks.

  6. Hello,

    It seems that if I have a MultiJob task that launches the same project twice, once with NodeLabel parameter set to "master" and once set "slave1" the second job is launched runs on whatever parameter was set for the first job. So, if the first job is launched with "master" both jobs launch on master and if set to slave both jobs launch on slave.

    What's your recommendation for running the same job from a MultiJob project on two different nodes?

  7. Hello,

    It seems that if I have a MultiJob task that launches the same project twice, once with NodeLabel parameter set to "master" and once set "slave1" the second job is launched runs on whatever parameter was set for the first job. So, if the first job is launched with "master" both jobs launch on master and if set to slave both jobs launch on slave.

    What's your recommendation for running the same job from a MultiJob project on two different nodes?

    1. Never mind, this seems to be a bug with the Multijob plugin. The two jobs are launched, but clicking on the concole output for both jobs opens the same console output for both build, the console output from the last build.

      But looking in the console output from the Multijob shows that two different builds are launched on two workspaces

  8. To the author of this plugin. It would be appreciated if the plugin was placed under some kind of license.

    MIT License is the most common for Jenkins plugins.

  9. I have jobs which get called in a sequence like this,
    DummyMultiJob > DummyJob1(nodename:rhel6x) > DummyJob2(nodename:db2)

    While triggering each job, I add current build parameters and node label parameter.

    So I start with DummyMultiJob and while calling DummyJob1, I pass on both current build parameters and node label parameter with its value set to rhel6x
    When it comes to DummyJob1, if I check the build parameters, it has got [LabelParameterValue: rhel6x], which is fine.

    Now DummyJob1 triggers DummyJob2 and passes current build parameters and node label value set to db2
    If I check the build parameters of DummyJob2 now, I see that it has got [LabelParameterValue: rhel6x][LabelParameterValue: db2] !
    As you can see, label parameter has been set to db2, but there was this labelparametervalue which I guess came from current build parameters which is set to rhel6x. Now DummyJob2 picks up rhel6x and happily proceeds further though it was asked to execute on db2 node.

    I dont know whether this is the expected behaviour.
    If I have added nodelabel parameter after current build parameters, I would expect it to override the values which might be there in current build parameters.
    In many cases, we invariably end up using both current build parameters and node label parameter. So if the current behaviour is as per design, IMHO we atleast need an option to explicitly state whether it should override it or append to it.

    Could you please let me know whether this issue can be considered as a bug/feature request ?

  10. It seems it is not directly possible to have a label expression selection list, which is what I currently need.

    I have been able to get this to work with the  https://wiki.jenkins-ci.org/display/JENKINS/Groovy+Label+Assignment+plugin plugin and a simple choice parameter.

    The node slection list of this plugin here seems pretty well thought out, but the label selection just allows a simple string to be entered by the user. Also, I have not been able to get this string to reference the value of another parameter.

  11. I am trying to use "Active Choices Reactive and Reactive Reference Parameters" with Node selection, I set Active Choices relying on UI element change (Node drop down list), however the value from node selection $NODE_NAME is empty. looks like $NODE_NAME isn't auto responding the selected value until built. is there way I can get the Node value when select the node? 

    I set "Disallow multi node selection when triggering build manually" to get single drop down list.

  12. Hi,

    Great Article, Although I don’t think we need to use shell commands as i used batch commands to copy and run a script that gets parameters, replaces them and the Jenkins can read the parameters from the files into its downstream projects.

    AS you can see it here:
    https://jenkinsmanagment.wordpress.com/

    Regards, Adi

  13. Can anyone tell me what is the class i should I use? I am trying to pass parameters from groovy script 

     

     [$class:<whatvalue>>', name: 'testsuite', value: 'slave1']
  14. I tried configuring a "Label" parameter and start the build from groovy script as follows

     

    node {
        build job: "Util_filter_sanity_check", parameters: [[$class: 'StringParameterValue', name: 'testsuite', value: 'suite1'],[$class: 'StringParameterValue', name: 'testcase', value: "tcMG1.pl"],[$class: 'LabelParameterValue', name: 'node_label', value: "M8"]]
    }

     

    However the "node" parameter value is empty and is not being passed on correctly to the job. Am I missing anything?

  15. How to restrict unwanted nodes in node parameter plugin.

     

    For me i need to display only 4 nodes out of 8 is there any solution for it

  16. Any chance to have  JENKINS-43720 - Getting issue details... STATUS  solved ?

    Or, is there another way to get selected nodes using a pipeline or groovy code ?