Swarm Plugin
Introduction
The Swarm plugin enables nodes to join a nearby Jenkins controller, thereby forming an ad-hoc cluster. This plugin makes it easier to scale a Jenkins cluster by spinning up and tearing down new agents, enabling team members to contribute compute resources to a build farm or to attach agents to which the Jenkins controller cannot initiate connections.
This plugin consists of two pieces:
-
A self-contained client that can join an existing Jenkins controller.
-
A plugin that needs to be installed on the Jenkins controller to accept Swarm clients.
With the Swarm client, a person who is willing to contribute some of his computing power to the cluster just needs to run a virtual machine with the Swarm client and the cluster gets an additional agent. Because the Swarm client is running on a separate VM, there is no need to worry about the builds/tests interfering with the host system or altering its settings unexpectedly.
Getting started
-
Install the Swarm plugin from the Update Center.
-
Ensure your agent is running version 11 or later of the Java Runtime Environment (JRE). The recommendation is to use the same JRE distribution and version as the controller.
-
Download the Swarm client from
${JENKINS_URL}/swarm/swarm-client.jaron your agent. -
Run the Swarm client with
java -jar path/to/swarm-client.jar -url ${JENKINS_URL} -username ${USERNAME}and one of the authentication options as described in the Global Security Configuration documentation. There are no other required command-line options; run with the-helpoption to see the available options.
Documentation
Available options
$ java -jar swarm-client.jar -help
| Name | Description |
|---|---|
|
YAML configuration file containing the options. |
|
Delete any existing agent with the same name. (default: false) |
|
Description to be put on the agent. |
|
Disable client’s unique ID. (default: false) |
|
Disable SSL verification in the HTTP client. (default: false) |
|
Disable Remoting working directory support and run the agent in legacy mode. (default: false) |
|
An environment variable to be defined on this agent. It is specified as `key=value'. Multiple variables are allowed. |
|
Number of executors (default: number of CPUs) |
|
Fail if the requested Remoting working directory or internal directory is missing. (default: false) |
|
Remote root directory. (default: .) |
|
Show the help screen (default: false) |
|
The name of the directory within the Remoting working directory where files internal to Remoting will be stored. |
|
Cache directory that stores JAR files sent from the controller. |
|
Do not remove clients from the controller when the agent becomes disconnected. (default: false) |
|
Whitespace-separated list of labels to be assigned for this agent. Multiple options are allowed. |
|
File location with space delimited list of labels. If the file changes, the client is restarted. |
|
Max time to wait before retry in seconds. Default is 60 seconds. (default: 60) |
|
The mode controlling how Jenkins allocates jobs to agents. Can be either `normal' (use this node as much as possible) or `exclusive' (only build jobs with label expressions matching this node). Default is `normal'. (default: normal) |
|
Name of the agent. |
|
Do not retry if a successful connection gets closed. (default: false) |
|
The Jenkins user API token or password. |
|
Environment variable containing the Jenkins user API token or password. |
|
File containing the Jenkins user API token or password. |
|
File to write PID to. The client will refuse to start if this file exists and the previous process is still running. |
|
If defined, then start an HTTP service on this port for Prometheus metrics. (default: -1) |
|
Number of retries before giving up. Unlimited if not specified. (default: -1) |
|
The mode controlling retry wait time. Can be either `none' (use same interval between retries) or `linear' (increase wait time before each retry up to maxRetryInterval) or `exponential' (double wait interval on each retry up to maxRetryInterval). Default is `none'. (default: NONE) |
|
Time to wait before retry in seconds. Default is 10 seconds. (default: 10) |
|
Whitespace-separated list of accepted certificate fingerprints (SHA-256/Hex), otherwise system truststore will be used. No revocation, expiration or not yet valid check will be performed for custom fingerprints! Multiple options are allowed. (default: ) |
|
A tool location to be defined on this agent. It is specified as `toolName=location'. |
|
Connect to the specified host and port, instead of connecting directly to Jenkins. Useful when connection to Jenkins needs to be tunneled. Can be also HOST: or :PORT, in which case the missing portion will be auto-configured like the default behavior |
|
The complete target Jenkins URL like `http://server:8080/jenkins/'. |
|
The Jenkins username for authentication. |
|
Connect using the WebSocket protocol. (default: false) |
|
Additional WebSocket header to set, e.g. for authenticating with reverse proxies. To specify multiple headers, call this flag multiple times, one with each header. |
|
The Remoting working directory where the JAR cache and logs will be stored. |
Issues
Report issues and enhancements in the Jenkins issue tracker. Use the swarm-plugin component in the JENKINS project.
Contributing
Refer to our contribution guidelines.