Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/jenkinsci/swarm-plugin

Jenkins swarm plugin
https://github.com/jenkinsci/swarm-plugin

jenkins jenkins- jenkins-agent jenkins-plugin

Last synced: 6 days ago
JSON representation

Jenkins swarm plugin

Awesome Lists containing this project

README 

        
= Swarm Plugin

:toc:

:toc-placement!:

:toc-title:

ifdef::env-github[]

:tip-caption: :bulb:

:note-caption: :information_source:

:important-caption: :heavy_exclamation_mark:

:caution-caption: :fire:

:warning-caption: :warning:

endif::[]



https://ci.jenkins.io/job/Plugins/job/swarm-plugin/job/master/[image:https://ci.jenkins.io/job/Plugins/job/swarm-plugin/job/master/badge/icon[Build Status]]

https://github.com/jenkinsci/swarm-plugin/graphs/contributors[image:https://img.shields.io/github/contributors/jenkinsci/swarm-plugin.svg[Contributors]]

https://plugins.jenkins.io/swarm[image:https://img.shields.io/jenkins/plugin/v/swarm.svg[Jenkins Plugin]]

https://github.com/jenkinsci/swarm-plugin/releases/latest[image:https://img.shields.io/github/release/jenkinsci/swarm-plugin.svg?label=changelog[GitHub release]]

https://plugins.jenkins.io/swarm[image:https://img.shields.io/jenkins/plugin/i/swarm.svg?color=blue[Jenkins Plugin Installs]]



toc::[]



== 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.jar` on 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 xref:docs/security.adoc#authentication[the Global Security Configuration documentation]. There are no other required command-line options; run with the `-help` option to see the available options.



== Documentation



* xref:CHANGELOG.adoc[Changelog]

* xref:docs/logging.adoc[Logging and Diagnostics]

* xref:docs/prometheus.adoc[Prometheus Monitoring]

* xref:docs/proxy.adoc[Proxy Configuration]

* xref:docs/security.adoc[Global Security Configuration]

* xref:docs/configfile.adoc[YAML Configuration]



== Available options



`$ java -jar swarm-client.jar -help`



[cols="1,1",options="header"]

|===

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

|`-keepDisconnectedClients` |Do not remove clients from the controller when the agent becomes disconnected. (default: false)

|`-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 https://issues.jenkins.io/[Jenkins issue tracker]. Use the `swarm-plugin` component in the `JENKINS` project.



== Contributing



Refer to our https://github.com/jenkinsci/.github/blob/master/CONTRIBUTING.md[contribution guidelines].