Label Throttle Build plugin

The Label Throttle Build plugin brings hypervisor-aware scheduling to Jenkins. The plugin allows users to limit the number of builds on over-subscribed VM guests on a particular host.

When agents are set up as virtual machines and share the same underlying physical resources, Jenkins may think that there is more capacity available for builds than there really is.

For example, in such an environment, Jenkins might think that there are 10 agents with 2 executors each, but in reality the physical machine cannot execute 20 concurrent builds without thrashing. The number is usually much lower; say, 4.[1] This is particularly the case when you have a single-system hypervisor, such as VMWare ESXi, VirtualBox, etc.

Every time a new build is to start, Jenkins schedules it to one of the available virtual agents. However, in this particular case the underlying physical infrastructure cannot support all the virtual agents running their respective builds concurrently.

CloudBees Jenkins Enterprise allows you to define an actual limit to the number of concurrent builds that can be run on the system. One can group agents together, then assign a limit that specifies how many concurrent builds can happen on all the agents that belong to that group. In this way, CloudBees Jenkins Enterprise avoids overloading your hypervisor host machine.[2]

The benefit of using this plugin is that builds run much faster as the underlying physical machines are not overloaded anymore.

The Label Throttle plugin was introduced in Nectar 11.04.

Setting up the Label Throttle Build plugin

Enable the CloudBees Label Throttle Build plugin in the plugin manager as shown in Install from the plugin manager. Restart CloudBees Jenkins Enterprise to enable the plugin.

throttle label
Figure 1. Install from the plugin manager

Configuring a label throttle

First, decide on a label and assign it to all the agents that you’d like to group together. For example, you can use the hypervisor host name as a label, and put that label on all the agents that are the virtual machines on that host. This can be done from the agent configuration page as shown in Set appropriate label on the agent configuration page.

throttle enter label
Figure 2. Set appropriate label on the agent configuration page

Then click the newly entered label to jump to the label page as show in Go to the labels page.

throttle click label
Figure 3. Go to the labels page

Then configure this label and enter the limit as shown in Set limit on the hypervisor.

throttle set limit
Figure 4. Set limit on the hypervisor

With this setting, as you can see, the total number of concurrent builds on hypervisor1 is limited to 2, and CloudBees Jenkins Enterprise will enforce this as you can see in the executor state in Label Throttle Build plugin in action. Two builds are already running, so the third job sits in the queue.

throttle usage
Figure 5. Label Throttle Build plugin in action

1. This number of course depends on the machine’s specifications and configuration.
2. This is very handy in combination with the CloudBees Jenkins Enterprise VMWare Autoscaling plugin.