Skip to main content

Distributing a Jenkins Build

Hands-On Lab


Photo of Michael McClaren

Michael McClaren

Linux Training Architect I in Content





In this hands-on lab we will be creating a build agent on a second server, and then creating a build that runs only on that server. This will demonstrate the use of labels for the build.

What are Hands-On Labs?

Hands-On Labs are scenario-based learning environments where learners can practice without consequences. Don't compromise a system or waste money on expensive downloads. Practice real-world skills without the real-world risk, no assembly required.

Distributing a Jenkins Build


In this hands-on lab we will be creating a build agent on a second server, and then creating a build that runs only on that server. This will demonstrate the use of labels for the build.

The Scenario

Your company has decided that they need to scale out their Jenkins installation, and that running projects on the master is no longer desirable. You have been tasked with configuring a build agent on a second server. Log into the Jenkins master web interface at port :8080 using these credentials: username: student password: OmgPassword!.

It should have the following configuration:

  • The node name should be worker1.
  • It should connect via SSH with keys.
  • The root directory should be /var/lib/jenkins.
  • The remote user should be jenkins.
  • The remote should have 2 executors.
  • All builds should be configured to run on the agent by default.
  • Ensure that the build is running on the agent by issuing a hostname command.
  • Verify that the agent builds are able to be archived and fingerprinted.

Configure SSH on the Remote Agent

Log into the master via SSH, using the credentials provided on the hands-on lab overview page. Then from the master node, use SSH to log into the worker node.

On the worker node, create the directory for the user's home:

[cloud_user@worker ]$ sudo mkdir /var/lib/jenkins

Add the user, assigning the home directory:

[cloud_user@worker ]$ sudo useradd -d /var/lib/jenkins jenkins

Make the user the owner of their home directory:

[cloud_user@worker ]$ sudo chown -R jenkins:jenkins /var/lib/jenkins

Create an .ssh directory for the jenkins user:

[cloud_user@worker ]$ sudo mkdir /var/lib/jenkins/.ssh

Run ssh-keygen. Hit Enter to accept defaults until it completes.

Copy the contents of ~/.ssh/ to the file /var/lib/jenkins/.ssh/authorized_keys

[cloud_user@worker ]$ cat ~/.ssh/ # Copy the output

[cloud_user@worker ]$ sudo vim /var/lib/jenkins/.ssh/authorized_keys # Paste the output of cat and save

We need the contents of id_rsa, as this is the private key that we will paste into Jenkins:

[cloud_user@worker ]$ cat ~/.ssh/id_rsa

Copy that command's output and exit the worker node.

Create an .ssh directory on the master in the jenkins directory:

[cloud_user@master ]$ sudo mkdir /var/lib/jenkins/.ssh

Copy the known_hosts entry over from the .ssh directory in /home/cloud_user to the jenkins user's .ssh directory:

[cloud_user@master ]$ sudo cp ~/.ssh/known_hosts /var/lib/jenkins/.ssh

Set up the Node on the Jenkins Master

Log into the Jenkins master using these credentials: username: student password: OmgPassword!

In the Jenkins master, go to Manage Jenkins and select Manage Nodes and Clouds. On this page, click New Node, and fill out the following web form with these values:

  • Name: worker1
  • #of executors: 2
  • Remote root directory: /var/lib/jenkins
  • Labels: linux
  • Host: Use the public IP of the worker node here.
  • Credentials: Click the Add dropdown and select Jenkins. This will pop up another form we need to fill out:
    • Kind: SSH Username with private key
    • Username: jenkins
    • Private Key: Click Enter directly and paste in the key that we copied right before we exited from the worker node SSH session.
    • Description: jssh
    • Click Add.
  • We'll land back on the first form we were filling out. Finish up the Credentials section by clicking the dropdown (it currently says -none-) and choosing jenkins (jssh).

Leave any fields alone that weren't mentioned here, and click Save.

On the Nodes page we are redirected to, click on worker1, then See log for more details. We're looking to see if there was a successful SSH authentication. If there's one shown in the log, and we see an entry saying Agent successfully connected and online, we're good to go.

Test a Remote Build

We need to configure the master to use labels, to ensure default builds run on the remote.

On the master node, get back into the main Jenkins screen, then in the left-hand menu click Manage Jenkins. Now click on select Configure System, and then we can fill out a couple of form values:

  • On the Labels line, enter master.
  • Set Usage to Only build jobs with label expressions matching this node.
  • Click Save.

Back out on the main Jenkins screen, click New Item. Enter an item name of test, click on Freestyle project, then click OK.

On the next screen, scroll down to the Build section, and choose Execute shell from the *Add build step** dropdown.

In the Command box, type this:

hostname > location.txt

Now, in Post-build Actions, click the Add post-build action dropdown and select Archive the artifacts. Paste location.txt in the Files to archive box. Click on Advanced and check the box next to Fingerprint all archived artifacts.

Click Save.

Run the build by clicking Build Now in the left-hand menu, then click on the build number to get into the build itself. If we watch the Console Output, we'll see the build process happening.

Go back to the test environment (using the breadcrumb navigation at the top of the screen), and we will see location.txt listed in the Last Successful Artifacts section. Open the view link that's next to it, in a new tab or window.


If we see jslave in that window, we know the build executed on the worker node, not the master. We're done! Congratulations!