CloudBees Label Throttling plugin

2 minute read

The CloudBees Label Throttling 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.

You can 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. This prevents the overloading of 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 CloudBees Label Throttling plugin was introduced in Nectar 11.04.

Setting up the CloudBees Label Throttling plugin

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

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.

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.

Figure 3. Go to the labels page

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

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, which is enforced as you can see in the executor state in CloudBees Label Throttling plugin in action. Two builds are already running, so the third job sits in the queue.

Figure 5. CloudBees Label Throttling 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 VMWare Autoscaling plugin.
In August 2020, the Jenkins project voted to replace the term master with controller. We have taken a pragmatic approach to cleaning these up, ensuring the least amount of downstream impact as possible. CloudBees is committed to ensuring a culture and environment of inclusiveness and acceptance - this includes ensuring the changes are not just cosmetic ones, but pervasive. As this change happens, please note that the term master has been replaced through the latest versions of the CloudBees documentation with controller (as in managed controller, client controller, team controller) except when still used in the UI or in code.