Skip to content

Commit

Permalink
Merge pull request #2101 from orrc/JENKINS-33364
Browse files Browse the repository at this point in the history
[JENKINS-33364] Core documentation: Agent configuration
  • Loading branch information
daniel-beck committed Apr 1, 2016
2 parents 2bd03ee + 4522226 commit 1258098
Show file tree
Hide file tree
Showing 45 changed files with 244 additions and 183 deletions.
4 changes: 2 additions & 2 deletions core/src/main/resources/hudson/model/Messages.properties
Expand Up @@ -336,8 +336,8 @@ Node.BecauseNodeIsReserved={0} is reserved for jobs with matching label expressi
Node.BecauseNodeIsNotAcceptingTasks={0} is not accepting tasks
Node.LabelMissing={0} doesn\u2019t have label {1}
Node.LackingBuildPermission={0} doesn\u2019t have a permission to run on {1}
Node.Mode.NORMAL=Utilize this node as much as possible
Node.Mode.EXCLUSIVE=Only build jobs with label restrictions matching this node
Node.Mode.NORMAL=Use this node as much as possible
Node.Mode.EXCLUSIVE=Only build jobs with label expressions matching this node

ListView.DisplayName=List View

Expand Down
32 changes: 22 additions & 10 deletions core/src/main/resources/hudson/model/Node/help-labelString.html
@@ -1,11 +1,23 @@
<div>
Labels (AKA tags) are used for grouping multiple agents into one logical group.
Use spaces between each label. For instance 'regression java6' will assign a
node the labels 'regression' and 'java6'.

<p>
For example, if you have multiple Windows agents and you have jobs that require
Windows, then you can configure all your Windows agents to have the label 'windows',
then tie the job to the 'windows' label. This allows your job to run on any
of your Windows agents but not on anywhere else.
</div>
Labels (or tags) are used to group multiple agents into one logical group.
<p>
For example, if you have multiple Windows agents and you have a job that
must run on Windows, then you could configure all your Windows agents to have
the label <tt>windows</tt>, and then tie that job to this label.
<br>
This would ensure that your job runs on one of your Windows agents, but not on
any agents without this label.
<p>
Labels do not necessarily have to represent the operating system on the agent;
you can also use labels to note the CPU architecture, or that a certain tool
is installed on the agent.
<p>
Multiple labels must be separated by a space. For example,
<tt>windows docker</tt> would assign two labels to the agent: <tt>windows</tt>
and <tt>docker</tt>.
<p>
Labels may contain any non-space characters, but you should avoid special
characters such as any of these: <tt>!&amp;|&lt;&gt;()</tt>, as other Jenkins
features allow for defining label expressions, where these characters may be
used.
</div>
11 changes: 7 additions & 4 deletions core/src/main/resources/hudson/model/Node/help-name.html
@@ -1,7 +1,10 @@
<div>
Name that uniquely identifies a agent within this Jenkins installation.

Name that uniquely identifies an agent within this Jenkins installation.
<p>
This value could be any string, and doesn't have to be the same as the agent host name,
but it's often convenient to make them the same.
This does not have to be the same as the agent hostname (where applicable),
but it is often convenient to make them the same.
<p>
The name may not contain any characters from this list:
<tt>?*/\%!@#$^&amp;|&lt;&gt;[]:;</tt>
<!-- See jenkins.model.Jenkins#checkGoodName -->
</div>
25 changes: 14 additions & 11 deletions core/src/main/resources/hudson/model/Node/help-numExecutors.html
@@ -1,15 +1,18 @@
<div>
This controls the number of concurrent builds that Jenkins can perform. So the value
affects the overall system load Jenkins may incur.
A good value to start with would be the number of processors on your system.

The maximum number of concurrent builds that Jenkins may perform on this
agent.
<p>
Increasing this value beyond that would cause each build to take longer, but it could increase
the overall throughput, because it allows CPU to build one project while another build is waiting
for I/O.

A good value to start with would be the number of CPU cores on the machine.
Setting a higher value would cause each build to take longer, but could
increase the overall throughput. For example, one build might be CPU-bound,
while a second build running at the same time might be I/O-bound &mdash; so
the second build could take advantage of the spare I/O capacity at that
moment.
<p>
When using Jenkins in the master/agent mode, setting this value to 0 would prevent the master
from doing any building on its own. Agents may not have zero executors, but may be
temporarily disabled using the button on the agent's status page.
Agents must have at least one executor. To temporarily prevent any builds from
being executed on an agent, use the <i>Mark this node temporarily offline</i>
button on the agent's page.
<p>
This does not apply to the Jenkins master &mdash; setting the number of
executors to zero will prevent any builds from being executed on the master.
</div>
38 changes: 18 additions & 20 deletions core/src/main/resources/hudson/model/Slave/help-remoteFS.html
@@ -1,36 +1,34 @@
<div>
<p>
An agent needs to have a directory dedicated to Jenkins. Specify
the path of this work directory on the agent. It is best to use
an absolute path, such as '/var/jenkins' or 'c:\jenkins'. This
should be a path local to the agent machine. There's no need for
this path to be visible from the master, under normal circumstances.

the path to this directory on the agent. It is best to use
an absolute path, such as <tt>/var/jenkins</tt> or <tt>c:\jenkins</tt>.
This should be a path local to the agent machine. There is no need for
this path to be visible from the master.
<p>
Agents do not maintain important data (other than active workspaces
of projects last built on it), so you can possibly set the agent
workspace to a temporary directory. The only downside of doing this
is that you may lose the up-to-date workspace if the agent is turned off.

Agents do not maintain important data; all job configurations, build logs and
artifacts are stored on the master, so it would be possible to use a temporary
directory as the agent root directory.
<br>
However, by giving an agent a directory that is not deleted after a machine
reboot, for example, the agent can cache data such as tool installations, or
build workspaces. This prevents unnecessary downloading of tools, or checking
out source code again when builds start to run on this agent again after a
reboot.
<p>
If you use a relative path, such as './jenkins-slave', the path will
be relative to the current working directory that the launcher provides.
If you use a relative path, such as <tt>./jenkins-agent</tt>, the path will be
relative to the working directory provided by the <i>Launch method</i>.
<ul>
<li>For launchers where Jenkins controls starting the agent process, such
as SSH, the current working directory will typically be consistent,
<i>e.g.</i> the user's home directory. This means that Jenkins will be able to
rely on the caching of tool installations and workspaces from previous
builds.
</li>
e.g. the user's home directory.</li>
<li>For launchers where Jenkins has no control over starting the agent
process, such as JNLP when launched from either the command line or via
a web browser link, the current working directory may change between
launches of the agent and use of a relative path may prove problematic.
<br>
The principal issue encountered when using relative paths with launchers
like JNLP is the proliferation of stale workspaces and tool installation
on the agent machine. This can cause disk space issues.
<i>Note: there are some cloud providers that specifically use relative
paths with the JNLP launcher to allow for dynamically provisioned pools
of semi-heterogeneous agents.</i></li>
on the agent machine. This can cause disk space issues.</li>
</ul>
</div>
Expand Up @@ -21,4 +21,4 @@
# THE SOFTWARE.

blurb=Starts an agent by having Jenkins execute a command from the master. \
Use this when the master is capable of remotely executing a process on an agent, such as through ssh/rsh.
Use this when the master is capable of remotely executing a process on another machine, e.g. via SSH or RSH.
Expand Up @@ -24,13 +24,13 @@ THE SOFTWARE.
<?jelly escape-by-default='true'?>
<j:jelly xmlns:j="jelly:core" xmlns:st="jelly:stapler" xmlns:d="jelly:define"
xmlns:l="/lib/layout" xmlns:t="/lib/hudson" xmlns:f="/lib/form">
<f:entry title="${%List of key-value pairs}" help="${descriptor.getHelpPage()}">
<f:entry title="${%List of variables}" help="${descriptor.getHelpPage()}">
<f:repeatable var="env" items="${instance.envVars.entrySet()}">
<table width="100%">
<f:entry title="${%name}">
<f:entry title="${%Name}">
<f:textbox name="env.key" value="${env.key}" />
</f:entry>
<f:entry title="${%value}">
<f:entry title="${%Value}">
<f:textbox name="env.value" value="${env.value}" />
</f:entry>
<f:entry title="">
Expand Down
@@ -1,4 +1,4 @@
# This file is under the MIT License by authors

name=nom
value=valor
Name=nom
Value=valor
Expand Up @@ -20,6 +20,6 @@
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
# THE SOFTWARE.

name=navn
value=v\u00e6rdi
List\ of\ key-value\ pairs=Liste af n\u00f8gle-v\u00e6rdi par
Name=navn
Value=v\u00e6rdi
List\ of\ variables=Liste af n\u00f8gle-v\u00e6rdi par
Expand Up @@ -20,6 +20,6 @@
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
# THE SOFTWARE.

List\ of\ key-value\ pairs=Liste der Schlüssel/Wert-Paare
name=Name
value=Wert
List\ of\ variables=Liste der Variablen
Name=Name
Value=Wert
Expand Up @@ -20,6 +20,6 @@
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
# THE SOFTWARE.

List\ of\ key-value\ pairs=Lista de nombre-valores
name=nombre
value=valor
List\ of\ variables=Lista de nombre-valores
Name=nombre
Value=valor
@@ -1,4 +1,4 @@
# This file is under the MIT License by authors

name=nombre
value=valor
Name=nombre
Value=valor
Expand Up @@ -20,6 +20,6 @@
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
# THE SOFTWARE.

List\ of\ key-value\ pairs=Lista avain-arvo pareja
name=nimi
value=arvo
List\ of\ variables=Lista avain-arvo pareja
Name=nimi
Value=arvo
Expand Up @@ -20,6 +20,6 @@
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
# THE SOFTWARE.

List\ of\ key-value\ pairs=Liste des paires clé-valeur
name=nom
value=valeur
List\ of\ variables=Liste des paires clé-valeur
Name=nom
Value=valeur
@@ -1,5 +1,5 @@
# This file is under the MIT License by authors

List\ of\ key-value\ pairs=\u05E8\u05E9\u05D9\u05DE\u05D4 \u05E9\u05DC \u05E9\u05D3\u05D4-\u05E2\u05E8\u05DA
name=\u05E9\u05DD
value=\u05E2\u05E8\u05DA
List\ of\ variables=\u05E8\u05E9\u05D9\u05DE\u05D4 \u05E9\u05DC \u05E9\u05D3\u05D4-\u05E2\u05E8\u05DA
Name=\u05E9\u05DD
Value=\u05E2\u05E8\u05DA
@@ -1,5 +1,5 @@
# This file is under the MIT License by authors

List\ of\ key-value\ pairs=Lista di coppie chiave-valore
name=nome
value=valore
List\ of\ variables=Lista di coppie chiave-valore
Name=nome
Value=valore
Expand Up @@ -20,6 +20,6 @@
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
# THE SOFTWARE.

List\ of\ key-value\ pairs=\u30AD\u30FC\u3068\u5024\u306E\u30EA\u30B9\u30C8
name=\u30AD\u30FC
value=\u5024
List\ of\ variables=\u30AD\u30FC\u3068\u5024\u306E\u30EA\u30B9\u30C8
Name=\u30AD\u30FC
Value=\u5024
@@ -1,5 +1,5 @@
# This file is under the MIT License by authors

List\ of\ key-value\ pairs=\uD0A4-\uAC12 \uBAA9\uB85D
name=\uC774\uB984
value=\uAC12
List\ of\ variables=\uD0A4-\uAC12 \uBAA9\uB85D
Name=\uC774\uB984
Value=\uAC12
@@ -1,4 +1,4 @@
# This file is under the MIT License by authors

name=pavadinimas
value=reik\u0161m\u0117
Name=pavadinimas
Value=reik\u0161m\u0117
Expand Up @@ -20,6 +20,6 @@
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
# THE SOFTWARE.

List\ of\ key-value\ pairs=Liste over n\u00F8kkel-verdi par
name=N\u00F8kkel
value=Verdi
List\ of\ variables=Liste over n\u00F8kkel-verdi par
Name=N\u00F8kkel
Value=Verdi
Expand Up @@ -20,6 +20,6 @@
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
# THE SOFTWARE.

List\ of\ key-value\ pairs=Lijst van sleutel-waarde-paren
name=naam
value=waarde
List\ of\ variables=Lijst van sleutel-waarde-paren
Name=naam
Value=waarde
@@ -1,5 +1,5 @@
# This file is under the MIT License by authors

List\ of\ key-value\ pairs=Lista par klucz-warto\u015B\u0107
name=nazwa
value=warto\u015B\u0107
List\ of\ variables=Lista par klucz-warto\u015B\u0107
Name=nazwa
Value=warto\u015B\u0107
Expand Up @@ -20,6 +20,6 @@
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
# THE SOFTWARE.

value=valor
name=nome
List\ of\ key-value\ pairs=Lista de pares de chave-valor
Value=valor
Name=nome
List\ of\ variables=Lista de pares de chave-valor
@@ -1,5 +1,5 @@
# This file is under the MIT License by authors

List\ of\ key-value\ pairs=Lista de pares chave-valor
name=nome
value=valor
List\ of\ variables=Lista de pares chave-valor
Name=nome
Value=valor
Expand Up @@ -20,6 +20,6 @@
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
# THE SOFTWARE.

List\ of\ key-value\ pairs=\u0421\u043F\u0438\u0441\u043E\u043A \u043F\u0430\u0440 "\u043A\u043B\u044E\u0447-\u0437\u043D\u0430\u0447\u0435\u043D\u0438\u0435"
name=\u0438\u043C\u044F
value=\u0437\u043D\u0430\u0447\u0435\u043D\u0438\u0435
List\ of\ variables=\u0421\u043F\u0438\u0441\u043E\u043A \u043F\u0430\u0440 "\u043A\u043B\u044E\u0447-\u0437\u043D\u0430\u0447\u0435\u043D\u0438\u0435"
Name=\u0438\u043C\u044F
Value=\u0437\u043D\u0430\u0447\u0435\u043D\u0438\u0435
@@ -1,5 +1,5 @@
# This file is under the MIT License by authors

List\ of\ key-value\ pairs=Zoznam p\u00E1rov k\u013E\u00FA\u010D - hodnota
name=k\u013E\u00FA\u010D
value=hodnota
List\ of\ variables=Zoznam p\u00E1rov k\u013E\u00FA\u010D - hodnota
Name=k\u013E\u00FA\u010D
Value=hodnota
Expand Up @@ -20,6 +20,6 @@
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
# THE SOFTWARE.

List\ of\ key-value\ pairs=Lista p\u00E5 nyckel-v\u00E4rde par
name=namn
value=v\u00E4rde
List\ of\ variables=Lista p\u00E5 nyckel-v\u00E4rde par
Name=namn
Value=v\u00E4rde
Expand Up @@ -20,6 +20,6 @@
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
# THE SOFTWARE.

List\ of\ key-value\ pairs=\u952E\u503C\u5BF9\u5217\u8868
name=\u952E
value=\u503c
List\ of\ variables=\u952E\u503C\u5BF9\u5217\u8868
Name=\u952E
Value=\u503c
Expand Up @@ -21,6 +21,6 @@
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
# THE SOFTWARE.

List\ of\ key-value\ pairs=Key-Value \u5c0d\u61c9\u6e05\u55ae
name=\u540d\u7a31
value=\u503c
List\ of\ variables=Key-Value \u5c0d\u61c9\u6e05\u55ae
Name=\u540d\u7a31
Value=\u503c
Expand Up @@ -20,7 +20,12 @@
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
# THE SOFTWARE.

blurb=Starts an agent by launching a program through <a href="http://en.wikipedia.org/wiki/Java_Web_Start">JNLP</a>. \
The launch in this case is initiated by the agent itself, \
thus agents need not be IP reachable from the master (e.g. behind the firewall.) \
It is still possible to start a launch without GUI, for example as a Windows service.
blurb=Allows an agent to be launched using <a href="https://en.wikipedia.org/wiki/Java_Web_Start" target="_blank">Java Web Start</a>.<br>\
In this case, a JNLP file must be opened on the agent machine, which will \
establish a TCP connection to the Jenkins master.<br>\
This means that the agent need not be reachable from the master; the agent \
just needs to be able to reach the master. If you have enabled security via \
the <i>Configure Global Security</i> page, you can customise the port on \
which the Jenkins master will listen for incoming JNLP agent connections.<br>\
By default, the JNLP agent will launch a GUI, but it's also possible to run \
a JNLP agent without a GUI, e.g. as a Window service.

0 comments on commit 1258098

Please sign in to comment.