Connecting build agents

3 minute read

A build agent is a computer that handles the tasks of running builds, at the direction of a controller. It can be a virtual machine (VM), a Docker container, or it can run on bare metal. Within the context of a CloudBees CI cluster, a build agent can be a shared resource for client controllers. A build agent can also be dedicated to a specific controller.

What is a build agent?

Before installing a build agent, learn what a Jenkins agent is.

What is a Jenkins agent?

Setting up an agent

It is a best practice to build on a build agent instead of the built-in node that comes pre-configured on the controller. A build agent can take many forms - a VM, a Docker container, or a Kubernetes pod, for example.

How to set up Docker containers as build agents for Jenkins
How to use Kubernetes pods as Jenkins agents

Creating an agent node

How to create an agent node

To add an external build agent to your controller:

  1. Go to Manage Jenkins  Manage Nodes.

    Manage nodes
    Figure 1. Manage nodes
  2. Select New node.

    New node
    Figure 2. New node
  3. Type a unique node name.

    Unique node name
    Figure 3. Unique node name
  4. On the Node configuration page, enter all the required values, depending on the type of build agent.

    Node configuration
    Figure 4. Node configuration
    You can launch a Jenkins agent machine in many ways. Select one of the methods to launch a new node. CloudBees recommends that Windows users use JNLP and that Linux users use SSH.
  5. After selecting Save, Jenkins should either try to launch the agent machine, or prompt you for next steps for creating the machine.

Connecting inbound agents using WebSocket for Agent Remoting Connections

CloudBees CI supports using WebSocket transport to connect inbound agents to controllers. This works for shared agents and clouds, as well.

This feature is available in CloudBees CI version 2.222.2.1 and later.

This functionality lets you make a connection via HTTP(S), then holds the connection open to create a bidirectional channel to send data back and forth between controllers and inbound agents.

No special network configuration is needed since the regular HTTP(S) port for your controller is used for all communications.

For additional details about WebSocket support in Jenkins, refer to JEP-222: WebSocket Support for Jenkins Remoting and CLI.

To connect inbound agents:

  1. On the Agent Configuration screen, in Launch method, select Launch agent by connecting it to the controller.

  2. Select Use WebSocket. Enabling the Use WebSocket option allows the agent to make a connection to the WebSocket.

  3. Follow the instructions on the Agent page to connect the agent. For more details, refer to Launching inbound agents.

Connecting a shared agent

With CloudBees CI, you can connect one or more shared agent to the operations center, making it available to all the controllers connected to the operations center. By sharing agents among controllers, you can balance workloads and make efficient use of resources.

Using shared agents with CloudBees CI

Connecting a Mac agent

You can configure Mac build agents like any other JNLP-based agent. The best practices are to:

  • Create a new permanent agent.

  • Change the Launch method to Launch Agent via Java Web Start

  • Launch the agent from a browser on the Mac machine.

  • When prompted, install the agent service on the Mac.

Please note that this means that the Mac agent must be able to make inbound connections to your CloudBees CI instance via the JNLP port.