Skip to content
Permalink
Browse files

[JENKINS-31801] - Documentation Revamp + Pipeline support docs (#47)

* Add License

* Revamp Readme from Wiki, add Pipeline Support documentation towards JENKINS-31801

* Migrate changelog from Wiki, add JENKINS-31801 reference in "Coming Soon"

* Update Parent POM

* Update documentation to reflect the current state of Pipeline support
  • Loading branch information
oleg-nenashev committed May 19, 2017
1 parent 0bbd079 commit e5d829ba44d89e60ac9cf1e6e12691e8d14e81aa
@@ -0,0 +1,124 @@
Changelog
===

## 1.10.0

Release date: Coming soon

* [JENKINS-31801](https://issues.jenkins-ci.org/browse/JENKINS-31801) -
Add support of Jenkins Pipeline job throttling by category.
[Documentation](README.md)

## 1.9.0

Release date: (Apr 11, 2016)

* [JENKINS-25326](https://issues.jenkins-ci.org/browse/JENKINS-25326) -
Elevate user to SYSTEM during build throttling, fixes the issue with jobs in Folders.
* Bump the core dependency to 1.609.3 to skip versions with known Queue incompatibility (_`1.535` .. `1.609.2`_)
* FindBugs fixes and test suite improvements

## 1.8.5

Release date: (Apr 06, 2016)

* [PR #38](https://github.com/jenkinsci/throttle-concurrent-builds-plugin/pull/38) -
Support throttling based on parameter value examination.
* Bump the core dependency to `1.596.1`

## 1.8.4

Release date: (Oct 09, 2014)

* Count builds running on a node's `OneOffExecutor` list when making throttling decisions
* Fixes the throttling of build flows from Build Flow Plugin ( [JENKINS-24748](https://issues.jenkins-ci.org/browse/JENKINS-24748),
[JENKINS-21335](https://issues.jenkins-ci.org/browse/JENKINS-21335),
[JENKINS-17512](https://issues.jenkins-ci.org/browse/JENKINS-17512), etc.)
* Fixes the throttling of Matrix parent jobs

## 1.8.3

Release date: (Jul 2, 2014)

* [JENKINS-13619](https://issues.jenkins-ci.org/browse/JENKINS-13619) -
Add support of Matrix configurations throttling .

## 1.8.2

Release date: (Mar 7, 2014)

* [JENKINS-21044](https://issues.jenkins-ci.org/browse/JENKINS-21044) -
Fixes blocker issue with thread concurrency locks.

## 1.8.1

Release date: (Dec 08, 2013) - UNSTABLE

* [JENKINS-19623](https://issues.jenkins-ci.org/browse/JENKINS-19623) -
Minimize security checks to improve performance of build queue dispatcher.

:exclamation: The version has a "blocker" issue caused by threads concurrency. See [JENKINS-21044](https://issues.jenkins-ci.org/browse/JENKINS-21044) for more info.

## 1.8

Release date: (Sep 20, 2013)

* [JENKINS-19645](https://issues.jenkins-ci.org/browse/JENKINS-19645) -
Categories optionally configured with pairs of throttled node labels.
* Fix for working on Jenkins `1.480.3`.
* Optimize performance by changing from `getComputers()` to `getNodes()`.
* [JENKINS-12240](https://issues.jenkins-ci.org/browse/JENKINS-12240) -
Fixing handling of MatrixProjects and MatrixConfigurations.

## 1.7

Release date: (2011)

* You now choose either to throttle the builds for just this project, or to throttle as part of a category.

## 1.6

Release date: (Apr 25, 2011)

* Now checks all criteria until one rejects the build or all have been checked, rather than allowing the build to run as soon as one criteria passes.

## 1.5

Release date: (Feb 23, 2011)

* Matrix configurations are now throttled under the rules defined for their parent matrix project.

## 1.4

Release date: (Feb 22, 2011)

* Fixed problem with categories not checking for projects in pending state.

## 1.3

Release date: (Oct 15, 2010)

* Multiple categories per job now allowed.

## 1.2

Release date: (Sept 27, 2010)

* [JENKINS-7221](https://issues.jenkins-ci.org/browse/JENKINS-7221) -
Categories weren't saving due to not having a setter.

## 1.1.1

Release date: (Sept 24, 2010)

* Added ability to turn off throttling of a job, because it was not possible.
* [JENKINS-7559](https://issues.jenkins-ci.org/browse/JENKINS-7559) -
Fixed a problem when run in Hudson 1.377 or greater, due to changes in queue logic.

## 1.1

* Added support for "categories" - throttling multiple jobs as if they were one.

## 1.0

* Initial version.
@@ -0,0 +1,22 @@
The MIT License

Copyright (c) 2010-2017 Andrew Bayer, Oleg Nenashev, and other Jenkins contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.

3 README

This file was deleted.

131 README.md
@@ -0,0 +1,131 @@
Throttle Concurrent Builds Plugin
===

This plugin allows for throttling the number of concurrent builds of a project running per node or globally.

# Usage

The plugin supports two modes:

* Throttling of runs in Jenkins by one or multiple category
* Throttling of multiple runs of a same `AbstractProject` job (not recommended)
* Throttling of runs by parameter values

For each mode it is possible to setup global, label-specific, and node-specific limit of concurrent runs.
If multiple throttling categories defined, each requirement needs to be satisfied in order to pick the task from the queue.

Usage specifics:

* If throttling category cannot be satisfied, the task submission stays in queue until
the locked category becomes available.
The submission can be terminated manually or by timeout.
* The plugin throttles tasks only only on common executors.
Flyweight tasks will not be throttled.
* If the jobs are organized into a chain (e.g. via Parameterized Trigger build steps), each run in the chain is being counted independently.
E.g. if _ProjectA_ and _ProjectB_ use category `cat_A` on the same node, 2 executors will be required from the category pool.
Improper configuration of categories/jobs may cause deadlock of such build chains due to consumption of ll executors and waiting for downstream executions blocked in the queue.

## Global configuration

Global configuration allows defining global categories.
For each category you can setup global, label-specific, and node-specific restrictions for executor numbers.
After the configuration, it will be possible to select and use the categories in job configurations.

Configuration example:

![Global Category Configuration](doc/images/global_categoryConfig.png)

To set an unlimited value of concurrent builds for a restriction, use `0`.

## Throttling of classic job types

Classic job types (FreeStyle, Matrix, JobDSL) can be configured via job properties in the job configuration screen.
Below you can find the configuration example:

![Throttle Job Property](doc/images/abstractProject_jobProperty.png)

* There are two modes: _Throttle This Project Alone_ and _Throttle this project as part of one or more categories_.
Only one mode can be enabled.
* _Throttle This Project Alone_
* For this option you should configure _Maximum Total Concurrent Builds_ and/or _Maximum Concurrent Builds Per Node_
* To set an unlimited value of concurrent builds for a restriction, use `0`
* With this setting categories will be ignored
* _Throttle this project as part of one or more categories_
* For this option you should specify enabled categories using checkboxes
* _Maximum Total Concurrent Builds_ and _Maximum Concurrent Builds Per Node_ fields will be ignored
* _Prevent multiple jobs with identical parameters from running concurrently_
* Adds additional throttling by parameter values

For _Matrix projects_ the property offers two additional checkboxes,
which define throttling behavior for Matrix master run and configuration runs.

![Throttle Job Property for Matrix](doc/images/abstractProject_matrixFlags.png)

## Throttling in Jenkins Pipeline

<!--TODO: Remove warning once JENKINS-31801 is integrated-->

### throttle() step

Starting from `throttle-concurrents-2.0` the plugin allows throttling particular Pipeline blocks by categories.
For this purpose you can use the `throttle()` step.
Throttling within a single job **is not supported**, use features provided by the `parallel()` step or define a special global category for the job.

<!--TODO: Update example once JENKINS-31801 is integrated-->

```groovy
// The script below triggers 6 subtasks in parallel.
// Then tasks will be throttled according to the category settings.
def labels = ['1', '2', '3', '4', '5', '6']
def builders = [:]
for (x in labels) {
def label = x // Need to bind the label variable before the closure
// Create a map to pass in to the 'parallel' step so we can fire all the builds at once
builders[label] = {
node('linux') {
sh "sleep 5"
}
}
}
throttle(['myThrottleCategory1', 'myThrottleCategory2']) {
parallel builders
}
```

If the specified category is missing, `throttle()` execution will fail the run.

### Throttling Pipeline via Job properties

:exclamation: **Warning!** It is not recommended to use this option starting from `throttle-concurrents-2.0`.
Use the `throttle()` step instead.

Plugin supports definition of throttling settings via job properties starting from `throttle-concurrents-1.8.5`.
The behavior of such definition **may differ** from your expectation and **may change** in new plugin versions.

Current behavior:

* If the property is defined, Pipeline jobs will be throttled as any other project.
* Pipeline job will be throttled on the top level as a single instance, it will be considered as a single job even is there are declarations like `parallel()`.
* Node requirements will be considered for the Root Pipeline task only, so effectively only the master node will be checked

Use this option at your own risk.

# License

[MIT License](http://www.opensource.org/licenses/mit-license.php)


# Changelog

See [this page](CHANGELOG.md).

# Reporting issues

All issues should be reported to [Jenkins Issue Tracker](https://issues.jenkins-ci.org/secure/Dashboard.jspa).
Use the `throttle-concurrent-builds-plugin` component in the `JENKINS` project.
For more information about reporting issues to Jenkins see [this guide](https://wiki.jenkins-ci.org/display/JENKINS/How+to+report+an+issue).



Binary file not shown.
Binary file not shown.
Binary file not shown.
@@ -26,7 +26,7 @@ THE SOFTWARE.
<parent>
<groupId>org.jenkins-ci.plugins</groupId>
<artifactId>plugin</artifactId>
<version>2.22</version>
<version>2.26</version>
</parent>

<artifactId>throttle-concurrents</artifactId>
@@ -45,7 +45,7 @@ THE SOFTWARE.

<properties>
<jenkins.version>1.642.3</jenkins.version>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<java.level>6</java.level>
<!--TODO: do not fail on errors-->
<findbugs.failOnError>false</findbugs.failOnError>
<java.level>7</java.level>

0 comments on commit e5d829b

Please sign in to comment.
You can’t perform that action at this time.