Jenkins : Lockable Resources Plugin

Plugin Information

View Lockable Resources on the plugin site for more information.

Older versions of this plugin may not be safe to use. Please review the following warnings before using an older version:

This plugin allows defining lockable resources (such as printers, phones, computers, etc.) that can be used by builds. If a build requires a resource which is already locked, it will wait for the resource to be free. One can define a lock-priority globally and on a per-job basis.

Quick usage guide

  • Install the plugin
  • In Manage Jenkins > Configure System go to Lockable Resources Manager   
    • Select Add Lockable Resource    

      Brief description of the named fields:

      • Name - A name (not containing spaces!) for this particular resource, i.e. DK_Printers.
      • Description - A verbose description of this particular resource, i.e.Printers in the Danish Office
      • Labels - Space-delimited list of Labels (Not containing spaces) used to identify a pool of resources. i.e. DK_Printers_Office   DK_Printer_Production   DK_Printer_Engineering
      • Reserved by - If anything is written here, the resource will be taken and therefore unavailable for other jobs. i.e. All printers are currently not available due to maintenance.
  • In Jenkins > <job name> >  Configure > General

    Brief description of the named fields:

    • Resources - The name or names of resources needed. In this example, DK_Printers will select all of the three printers in the pool.
    • Label - One or more Labels to select resources. In this example, DK_Printer_Production   DK_Printer_Engineering will select two labeled printers in the larger pool.

  • Start a build.
    • Under build #<number> select  Locked Resources 
    • You should see something like: This build has locked the following resources: <resource_name> - <resource description>
  • Start a different build which uses the same resource. * You will see *Build Queue in Jenkins status/menu showing job name
    • Hover text shows Started <by>, Waiting for resources <resources list>, Waiting for <time>

Pipeline usage

  • When the lock step is used in a Pipeline, if the resource to be locked isn't already defined in the Jenkins global configuration, it'll be set up automatically.
  • The arguments to the lock step are:
    • resource - The resource name to lock as defined in Global settings. If inversePrecedence isn't also specified, the step can be called as lock('some-resource') without the named argument.
    • label - can be used to require locks on multiple resources concurrently. The build will wait until all resources tagged with the given label are available. Only this or resource can be used simultaneously.
    • quantity - (optional) specifies the number of resources required within the selected label. If not set, all resources from the label will be required.
    • inversePrecedence - (optional) By default waiting builds are given the lock in the same order they requested to acquire it. If inversePrecedence is set to true, this will be done in reverse order instead, so that the newest build to request the lock will be granted it first.
    • variable - (optional) When locking a resource via a label you can use variable to set an environment variable with the name of the locked resource.
  • Examples:

    echo 'Starting'
    lock('my-resource-name') {
      echo 'Do something here that requires unique access to the resource'
      // any other build will wait until the one locking the resource leaves this block
    }
    echo 'Finish'
    
    lock(resource: 'staging-server', inversePrecedence: true) {
        node {
            servers.deploy 'staging'
        }
        input message: "Does ${jettyUrl}staging/ look good?"
    }
    
    lock(label: 'test-farm') {
        parallel test1: {
            node('farm-server-linux') {
                sh './run-tests.sh'
            }
        },
        test2: {
            node('farm-server-windows') {
                sh './run-tests.bat'
            }
        }
    }
    
    lock(label: 'some_resource', variable: 'LOCKED_RESOURCE') {
      echo env.LOCKED_RESOURCE
    }

Changelog

Release 2.5 (2019-3-25)

Release 2.4 (2019-1-18)

Release 2.3 (2018-6-26)

  • JENKINS-34433 - Signal queued Pipeline tasks on unreserve

  • Allow locking multiple resources in Pipeline

Release 2.2 (2018-3-6)

  • JENKINS-40997 - New configuration option to get the name of the locked resource inside the lock block (Pipeline).

  • JENKINS-49734 - Add a PauseAction to the build when waiting for locking, so Pipeline representations in the UI are correctly shown.
  • JENKINS-43574 - Fixed the "empty" resources lock (message: "acquired lock on []")

Release 2.1 (2017-11-13)

Release 1.11.2 (2017-3-15)

  • JENKINS-40368 - Locked resources are not always freed up on Pipeline hard kill when there are other pipelines waiting on the Resource

Release 1.11.1 (2017-2-20)

  • JENKINS-40879 - Locked areas are executed multiple times in parallel

Release 1.11 (2016-12-19)

Release 1.10 (2016-07-12)

  • JENKINS-36479 - properly clean up resources locked by hard-killed or deleted while in progress Pipeline builds.

Release 1.9 (2016-06-01)

  • Reserved resources parameter visibility in environment (related to SECURITY-170)

Release 1.8 (2016-04-14)

  • Pipeline compatibility: lock step

Release 1.2 (2014-02-05)

  • Manual reservation/un-reservation of resources now require specific permissions

Release 1.1 (2014-02-03)

  • Allow jobs to require a subset of specified resources (the number of required resources is configurable)
  • Allow manual reservation/un-reservation of resources

Release 1.0 (2013-12-12)

  • Initial release

Attachments: