fatmcgav / swarm-plugin

Jenkins swarm plugin

Swarm Plugin

• Introduction
• Getting started
• Documentation
• Available options
• Issues
• Contributing

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:

1. A self-contained client that can join an existing Jenkins controller.

2. 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

1. Install the Swarm plugin from the Update Center.

2. Ensure your agent is running version 8 or later of the Java Runtime Environment (JRE). The recommendation is to use the same JRE distribution and version as the controller.

3. Download the Swarm client from ${JENKINS_URL}/swarm/swarm-client.jar or Jenkins repository on your agent.

4. 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 -help option to see the available options.

Documentation

• Changelog

• Logging and Diagnostics

• Prometheus Monitoring

• Proxy Configuration

• Global Security Configuration

• YAML Configuration

Available options

$ java -jar swarm-client.jar -help

Name	Description
-config FILE	YAML configuration file containing the options.
-deleteExistingClients	Delete any existing agent with the same name. (default: false)
-description VAL	Description to be put on the agent.
-disableClientsUniqueId	Disable client’s unique ID. (default: false)
-disableSslVerification	Disable SSL verification in the HTTP client. (default: false)
-disableWorkDir	Disable Remoting working directory support and run the agent in legacy mode. (default: false)
-e (--env)	An environment variable to be defined on this agent. It is specified as `key=value'. Multiple variables are allowed.
-executors N	Number of executors (default: number of CPUs)
-failIfWorkDirIsMissing	Fail if the requested Remoting working directory or internal directory is missing. (default: false)
-fsroot FILE	Remote root directory. (default: .)
-help (--help, -h)	Show the help screen (default: false)
-internalDir FILE	The name of the directory within the Remoting working directory where files internal to Remoting will be stored.
-jar-cache FILE	Cache directory that stores JAR files sent from the controller.
-labels VAL	Whitespace-separated list of labels to be assigned for this agent. Multiple options are allowed.
-labelsFile VAL	File location with space delimited list of labels. If the file changes, the client is restarted.
-maxRetryInterval N	Max time to wait before retry in seconds. Default is 60 seconds. (default: 60)
-mode MODE	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 VAL	Name of the agent.
-noRetryAfterConnected	Do not retry if a successful connection gets closed. (default: false)
-password VAL	The Jenkins user API token or password.
-passwordEnvVariable VAL	Environment variable containing the Jenkins user API token or password.
-passwordFile VAL	File containing the Jenkins user API token or password.
-pidFile VAL	File to write PID to. The client will refuse to start if this file exists and the previous process is still running.
-prometheusPort N	If defined, then start an HTTP service on this port for Prometheus metrics. (default: -1)
-retry N	Number of retries before giving up. Unlimited if not specified. (default: -1)
-retryBackOffStrategy RETRY_BACK_OFF_STRATEGY	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)
-retryInterval N	Time to wait before retry in seconds. Default is 10 seconds. (default: 10)
-sslFingerprints VAL	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: )
-t (--toolLocation)	A tool location to be defined on this agent. It is specified as `toolName=location'.
-tunnel VAL	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
-url (-master) VAL	The complete target Jenkins URL like `http://server:8080/jenkins/'.
-username VAL	The Jenkins username for authentication.
-webSocket	Connect using the WebSocket protocol. (default: false)
-webSocketHeader NAME=VALUE	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.
-workDir FILE	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.