Using Agents

You can have Jenkins installed on one machine, known as a master, and use it to run projects that control your day-to-day development processes on other machines, known as agents. This can be very helpful if you need to ensure that your applications run correctly on a variety of different test configurations.

Note: An agent can either be a physical or a virtual machine.

The process of setting up agents in Jenkins is as follows:

  1. In Jenkins on the master, create a node that defines a connection to the machine you want to use as an agent. See the example below for instructions.
  2. On the agent, open the Jenkins UI. Open the page for the node and follow the link to launch a Jenkins agent which will establish a connection between Jenkins on the master machine and the agent machine.
  3. In Jenkins on the master, create a project and configure it to execute on the agent.

Example of Creating Agent Machines

The following example shows how to create a connection to an agent machine which is stored in a vSphere cloud. This requires that you install the vSphere plugin in Jenkins.

Ensure that Jenkins is connected to the vSphere cloud:

  1. From the Jenkins Home page, click Manage Jenkins.
  2. Click General.
  3. Under the Cloud section, click Add new cloud > vSphere cloud.
  4. Specify the configuration and login details for connecting to the vSphere host that contains your virtual machines.

To create a connection to an agent machine, first create a node in Jenkins as follows:

  1. Click Manage Jenkins.
  2. Click Manage Nodes.

    This opens the Nodes page showing the machine that has Jenkins installed as the master.

  3. Click New Node.
  4. Specify a name for the node and click Permanent Agent, then click OK.
  5. Fill in the details as required - for example, specify a Remote root directory if this is needed for checking out sources on the agent.
  6. Click Save.

To configure the agent to connect to the master:

  1. On the agent machine, load the Jenkins Home page (http://mastermachine:8080).
  2. From the Jenkins Home page, click the node for the machine that appears under the Build Execution Status box.
  3. From the Jenkins page for the node, click Launch to start the agent that connects the machine to Jenkins.

Configure an existing project to execute on the agent as follows:

  1. On the master machine, go to the project configuration page.
  2. Check Restrict where this project can be run in the General section.
  3. In the Label Expression, specify the name of the node that you just created and connected to.
  4. Save the project.

    Next time you build the project, it will execute on the agent.

Parent topic: Advanced Configuration