How to Setup Jenkins Build Agent on Windows (Tutorial)
How to Setup Jenkins Build Agent on Windows (Tutorial). The following guide examines How to Setup Jenkins Build Agent on Windows. Jenkins facilitates parallelism through build agents. They allow you to simultaneously deploy to multiple environments which is a necessity for synchronous software deployments.
Sometimes, you may find that you need more executors. Your queued jobs are taking too long. In these instances, it is best to have more Jenkins build agents. They help you to improve your Jenkins CI/CD pipeline speeds. The following guide shows you how to configure and add more build agents.
How to Setup a Jenkins Build Agent
The following instructions and screenshots were captured using Jenkins 2.422. It is recommended that you update Jenkins to the latest version.
Your installation of Jenkins should periodically check for updates and, if available, allow you to install them from the Manage Jenkins menu.
To access the Jenkins Management screen and setup a new Jenkins Build Agent on Windows, do the following:
- Make sure, that the Jenkins service is running
- Open the Windows Run dialog
- Enter services.msc into the text field
- Scroll down until you find the Jenkins service
- Check the status field to see if it is Running
- If the status field is empty, right-click Jenkins then select Start
- Open a web browser of your choice then navigate to your Jenkins Dashboard
- Select Manage Jenkins(⚙) from the left panel
- Scroll down to the System Configuration section and then select the Nodes option.
- Click on the New Node button.
- Your new node acts as your new build agent. Give it an appropriate name such as WindowsBuildAgent.
- Next, click on the Permanent Agent radio button.
- Finally, click on the Create button.
After a few moments, the Jenkins controller takes you to the Node configuration screen.
Configuring Your Build Agent
The node configuration screen for your build agent contains the following configurations:
Description
This configuration indicates The purpose of your node. You can enter “A Windows Build Agent” as your description.
Number of Executors
The number of simultaneous builds that Jenkins executes on your agent. A good rule of thumb is to use the number of CPU cores on the machine you’ll run the builds on.
Find the number of CPU cores on Windows by using the Performance tab in the Windows Task Manager:
Alternatively, run the following PowerShell command:
Get-CimInstance -ClassName Win32_Processor | Select-Object -Property Number*
Add more or fewer executors, you get the best performance by tying the value to the number of CPU cores. Build agents should have at least a single executor.
Remote root directory
Your agent requires a dedicated working directory. Your agent uses it to store cached data such as logs, and build workspaces and tool installations. It’s best to use a permanent directory that is not deleted when your machine is rebooted.
This allows your agent to work more efficiently as it doesn’t have to redownload or build new files. The value of this configuration should be absolute. Use:
C:\Jenkins
Labels
Labels act as tags that allow you to group multiple agents. Thus, if you’d like to create a build that consists of multiple agents, use the labels field to organize and find them.
This setting is optional and as such, can be left completely blank.
Usage
Usage allows you to define whether the agent should be used freely or in the context of a group (label). This allows you to synchronize how your agents are run. Since you’re defining a singular agent, use the default value for this field (Use this node as much as possible).
Launch method
Allows you to define how the Jenkins controller should launch your agent. There are three options:
- Launch agent by connecting it to the controller: Your agent automatically launches by the Jenkins controller when it’s available.
- Launch agent via execution of command on controller: Your agent is launched by commands sent from the Jenkins controller. Allows you to set triggers and remotely launch your agent. Your Jenkins controller must be capable of accepting remote commands for execution.
- Launch agents via SSH: Allows your agents to be launched via commands over a Secure Shell (SSH) Protocol. While this method does not require any root privileges, your agent must be accessible from the Jenkins controller. Additionally, you need to supply Jenkins with a user account that logs in on the build target machine.
For your agent, select Launch agent by connecting it to the controller. This configuration features optional sub-configurations. For instance, disable the Remote working directory (WorkDir) for your agent which ultimately disables logging. Alternatively, also set a custom working directory (Custom WorkDir path).
The Internal data directory allows you to create an additional folder in your working directory. It contains all your agent’s internal data.
If the Fail if workspace is missing option is checked, remoting fails if the target work directory is missing. This option allows you to verify and ensure that there are structural issues that may be caused by a failed mount or bad remote connection.
The Use WebSocket option allows you to connect to the Jenkins Master as opposed to using the TCP Port. Read the JEP-222 spec for more information.
You can skip all sub-configurations and leave them as is.
Availability
This setting dictates when Jenkins starts and stops your agent. There are 3 options:
- Keep this agent online as much as possible
- Bring this agent online according to a schedule
- Bring this agent online when there is a demand
Select Keep this agent online as much as possible for now.
Node Properties
This section allows you to set additional Jenkins node properties for your agent. Disable deferred wipeout on this node allows you to control when workspace cleanup is performed on your node.
Also set a list of Environment variables and additional Tool Locations for your build agent. For now skip over this option.
Finalizing and Deploying Your Jenkins Build Agent
There are only four options that you need to be concerned with Name, Number of executors, Remote root directory, and Launch Method. Your configuration should resemble the following:
Next click on the Save button. Jenkins redirects to the Nodes list. You notice that your Build Agent has now been added to the list.
Clicking on the node reveals its management screen with the Status tab selected. This section displays all the agent installation links:
Simply copy and run the commands from the specified command lines (UNIX and Windows). It’s best to copy and run the commands line by line, starting with the `curl.exe` command and then the `java` command:
curl.exe -sO http://localhost:8080/jnlpJars/agent.jar
java -jar agent.jar -jnlpUrl http://localhost:8080/computer/WindowsBuildAgent/jenkins-agent.jnlp -workDir "C:\Jenkins"
Upon running the curl command, you are required to set a password. Give a suitable password and note it down. The curl fetches the build agent.jar:
Next, run the java command which builds and runs the agent:
Now, return to the Build Agent Status screen. Refresh (F5) before you see any changes. Once that’s done, the installation commands are gone. Moreover, the cross/x that was previously affixed to the Status icon is now gone. See a status message that reads: “Agent is connected”.
In addition to the Agent’s Status details, you can also delete, configure, and view the build history and the log for your agent. Also monitor the status of your agent’s build executors. Returning the Nodes screen reveals more information about the machine it’s running on:
This includes how much space there is on the local hard drive, the clock difference, and available virtual RAM (Swap Space).
How to Setup Jenkins Build Agent on Windows (Tutorial) Conclusion
In the above guide, we explored the intricacies of how to setup Jenkins Build Agent on Windows (Tutorial). In addition to load balancing, you can also run custom PowerShell scripts from your build agents. Paired with Jenkins’ rich library of plugins, Build agents can go a long way to help you optimize and streamline your builds and deployments. Nevertheless, we hope this guide was helpful.
