Nodes, Agents, Labels, Executors, Workspaces, Offline Causes, and Agent Capacity Design: Configuration, Design Choices, and Tradeoffs

1. One executor versus many

One executor provides the simplest isolation model: only one Jenkins task consumes the node at a time. Multiple executors can improve utilization when jobs are lightweight or spend time waiting on external systems, but concurrency multiplies demand for CPU, RAM, disk bandwidth, temporary space, process limits, licenses and network connections.

2. Static versus ephemeral workers

Static agents are easy to inspect and cache aggressively, but persistent workspaces and manually installed tools drift. Ephemeral agents can start from reviewed images and disappear after work, reducing residue and easing horizontal scaling. They shift durability requirements outward: artifacts, reports and important logs must not depend on the worker surviving.

Chapter 20 will cover Kubernetes-based dynamic agents. Here, the design rule is provider-neutral: worker lifecycle is separate from the build record. If a worker disappears, Jenkins should still retain enough source/build/artifact evidence to diagnose what happened.

3. Label taxonomy: capability, platform and trust

Prefer labels that are stable properties administrators can verify: linux, windows, arm64, jdk21, high-memory, gpu, release-trusted. Avoid making every job depend on physical host names such as server42 unless affinity to that exact machine is the real requirement.

// Good: expresses capabilities and trust
node('linux && jdk21 && !release-trusted') {
  sh './gradlew test'
}

// Deliberate privileged pool
node('linux && release-trusted') {
  echo 'Simulated release evidence only in this lab'
}

Labels are administrator-controlled scheduling claims. Periodically verify that nodes carrying high-trust labels still satisfy the intended hardening and access requirements.

4. Dedicated versus shared agents

A shared CI pool improves utilization and developer throughput. A dedicated signing/release/hardware pool improves isolation and makes privileged access easier to audit. The key is to separate conflicting trust levels, not to create a dedicated machine for every project by habit.

5. Workspace reuse versus clean isolation

Workspace reuse is fast and cache-friendly, but it can preserve untracked files, old dependencies and generated state. Clean isolation improves reproducibility at the cost of checkout/download time. Separate dependency caches from the source workspace when possible and make cache keys/version ownership explicit.

For high-trust or cross-tenant pools, stronger isolation is usually worth the cost. For a single trusted project, controlled reuse may be reasonable when the build explicitly recreates outputs and validates cache identity.

6. Node usage mode

A node configured “Use this node as much as possible” can accept suitable unlabelled work. “Only build jobs with label expressions matching this node” requires explicit scheduling intent. For scarce, privileged or specialized workers, explicit label targeting reduces accidental use.

Usage mode is controller configuration; it does not alter host resources. Changing it can immediately change queue eligibility, so record the previous setting and affected queued jobs before mutation.

7. Worked scenario: growing service with release signing

8. Capacity changes need rollback criteria

Before raising executors from 1 to 2, state what success means—for example p95 queue wait decreases while median build duration changes less than 10%, memory remains above a safety threshold, disk latency stays healthy and failure rate does not increase. If those conditions fail, revert the executor count and investigate the real bottleneck.

Likewise, changing label taxonomy should have a compatibility plan: temporarily support old and new labels, update jobs, verify routing, then remove the deprecated label. Do not perform a fleet-wide rename without proving who still depends on it.

Knowledge check

Answer before revealing the explanation.

Official references and version notes

• Jenkins LTS changelog and Java support policy — lab baseline Jenkins 2.568.3 LTS, Java 21; this LTS line supports Java 21 and 25.
• Managing Nodes — controller, node, agent, executor and node-monitor concepts.
• Using Jenkins agents — labels, executor counts, usage modes and distributed builds.
• Controller Isolation — do not run builds on the built-in node; set its executor count to 0 once agents exist.
• Securing Builds — isolate builds and separate trust domains instead of treating every shared agent as equivalent.
• Pipeline: Nodes and Processes step reference — node, ws, workspace context and supported label-expression operators.
• Pipeline: Nodes and Processes plugin — baseline 1479.v56e587f413a_7, requires Jenkins 2.479.3 or newer.
• SSH Build Agents plugin — optional launcher baseline 3.1097.v868116049892; use verified host keys and least-privilege agent accounts.
• Built-In Node Name and Label Migration — terminology and NODE_NAME/NODE_LABELS behavior.