Skip to content

Jenkins Workers Configuration

Overview

Purpose

Jenkins workers (agents) are used to offload build and test execution from the Jenkins controller, ensuring scalability and performance.

Scope

Configuration and management of Jenkins SSH workers.

Audience

INFRA, CORE

Prerequisites

VM Hardware Requirements (per Worker)

Component Requirement
CPU XX cores
RAM XX GB
Disk Space XX GB+ (depending on workspace)

Software Requirements

Component Version
Operating System Debian 12
Java 8, 11, 17, 21, 25
Git Latest

Access Requirements

  • User: qcuser for agent execution.
  • SSH access from Jenkins Controller to Workers.

Architecture Diagram

We use a distributed architecture where the Jenkins Controller manages multiple permanent SSH agents. Each agent is configured with specific tool locations (JDKs) and labels to handle different types of workloads.

Configuration Details

Worker Nodes

Name Host Labels Remote FS
qcjenwrk01-qcint qcjenwrk01-qcint worker w1 /home/qcuser/jenkins
qcjenwrk02-qcint qcjenwrk02-qcint worker w2 /home/qcuser/jenkins
qcjenwrk03-qcint qcjenwrk03-qcint worker w3 /home/qcuser/jenkins

Tool Locations (Example for qcjenwrk01-qcint)

  • Java 8: /opt/jdk/java8
  • Java 11: /opt/jdk/java11
  • Java 17: /opt/jdk/java17
  • Java 21: /opt/jdk/java21
  • Java 25: /opt/jdk/java25
  • Maven 3.9.9: /opt/maven/apache-maven-3.9.9
  • Maven 3.5.4: /opt/maven/apache-maven-3.5.4
  • Sonar Scanner: /opt/maven/sonar/sonar-scanner
  • Git: /opt/git
  • Groovy 2.4.7: /opt/groovy/groovy-2.4.7
  • Groovy 3.0.24: /opt/groovy/groovy-3.0.24
  • Groovy 3.0.25: /opt/groovy/groovy-3.0.25
  • Groovy 4.0.25: /opt/groovy/groovy-4.0.25
  • Grails 2.5.6: /opt/grails/grails-2.5.6
  • FDBuild Eclipse 3.7.1: /opt/fdbuild/eclipse3.7.1
  • FDBuild Eclipse 3.8.1: /opt/fdbuild/eclipse3.8.1
  • FDBuild Eclipse 3.8: /opt/fdbuild/eclipse3.8
  • FDBuild Eclipse 3.6.2: /opt/fdbuild/eclipse3.6.2
  • Gradle 8.8: /opt/gradle/gradle-8.8

Step-by-Step Setup

Prepare the Worker VM

  1. Ensure qcuser exists on the target VM.
  2. Install required Java versions in /opt/jdk/ or standard system paths.
  3. Authorize the Jenkins Controller's SSH public key for qcuser.

Configure via Jenkins GUI

To manually add or update a worker via the Jenkins interface:

  1. Navigate to Nodes:
  2. Go to Manage Jenkins > Nodes.
  3. Create New Node:
  4. Click New Node.
  5. Enter Node name (e.g., qcjenwrk01-qcint).
  6. Select Permanent Agent and click Create.
  7. Configure Node Settings:
  8. Number of executors: 5.
  9. Remote root directory: /home/qcuser/jenkins.
  10. Labels: worker (and specific labels if needed).
  11. Usage: Only build jobs with label expressions matching this node (EXCLUSIVE mode).
  12. Launch method: Launch agents via SSH.
    • Host: The FQDN or IP of the worker.
    • Credentials: Select the credential.
    • Host Key Verification Strategy: Manually trusted key Verification Strategy (with Require manual trust unchecked if appropriate).
  13. Configure Tool Locations:
  14. Under Node Properties, check Tool Locations.
  15. Add entries for each JDK version (e.g., Java 17 -> /opt/jdk/java17).
  16. Save and Connect:
  17. Click Save.
  18. Jenkins will attempt to launch the agent via SSH. Check the log to verify connection.

Configure via JCasC (Alternative)

If using Configuration as Code, ensure the jenkins.nodes section in your config.yml includes the worker definitions as seen in the repository.

Validation & Testing

  • Check the Nodes status page in Jenkins GUI.
  • Ensure the agent status is "In sync" and "Online".
  • Run a test job restricted to the specific worker label.

Troubleshooting

  • SSH Connection Failed: Verify network connectivity and SSH keys.
  • Java Not Found: Ensure the path in Tool Locations matches the actual path on the worker VM.
  • Permission Denied: Check remoteFS permissions for qcuser.

Maintenance

Responsibility

Managed by the Infra Team.

Compatibility Considerations

Ensure new workers have all required build tools (Maven, Docker, etc.) installed and configured.

  • https://www.jenkins.io/doc/book/using/using-agents/
  • Repository: https://gitlab.quintessence.net/net.quintessence/ci-cd

Changelog

Date Author Message
2026-02-25 aresnikowa Merge remote-tracking branch 'origin/master'