Manage agents

Agents are small applications that PulseUno uses to run chains. This topic explains how to work with agents.

Note: Administrator permissions required.

For an overview of agents, see Agents architecture.

Agent guidelines and behaviors

  • Each agent is associated with a specific instance of PulseUno.
  • PulseUno doesn't provide an embedded agent. You need to install at least one agent for each PulseUno instance. See Install agents.
  • To distribute the processing load of chains, install multiple agents on different machines on a network.
  • Agents only include the code required to run chains and automatically download the required plugins from the PulseUno server. You do not need to manually install plugins on agents.
  • You can configure agents to run specific chains by adding capabilities and variables. See Add variables to agents and Add capabilities to agents.
  • By default, an agent can run one chain at a time.

    To change the default behavior, edit the agent.concurrent.jobs.max property in the agent's ${pulseAgentDataDir}/config.properties file.

    Note: To avoid issues, do not set the agent to run more than 4 chains at once. For optimal performance, we recommend that you use the default setting, one chain per one agent at a time.

  • To ensure that PulseUno servers and agents communicate without issues, the clocks on servers and agents must be synchronized.

For details on how to license agents, see Step 6: Approve agents.

Back to top

View agent information

You can view a list of registered agents on the Agents page.

The following agent information is displayed:

  • Agent name (same as the host machine, which you cannot change in PulseUno), for example, suse4130-buildagent.
  • Title (an optional description of the agent), for example, Windows compilers.
  • Status, for example, Embedded, Offline, or Unapproved.
  • Universal unique identifier (UUID).
  • Operating system of the host machine.
  • Connection status, for example, Started 2 weeks ago.
  • Heartbeat (when the agent last communicated with PulseUno).
  • Agent version.
  • Capabilities tags.
  • Memory usage of the host machine.
  • Work space remaining on the host machine. A work space is an area on disk that an agent can populate with code to run a chain.

To view agent details:

  1. In PulseUno, navigate to Administration > Agents.
  2. (Optional) To narrow down the list of agents, filter the list to display only online, offline, approved, or unapproved agents. By default, all agents are displayed.

    You can sort the list by hostname, creation date, last started date, last reported date, and in ascending or descending order.

  3. To enable or disable memory and workspace monitoring, click Agent Monitoring.
  4. To modify an agent's name or description, click the agent's name and then click Edit. In the Overview tab, change the title and note, and click Save.

Back to top

View agent chains

You can view the chains running on an agent, and the history of previous chain runs including the last run, last failure, last success, and the total number of runs.

To view agent chains:

  1. In PulseUno, navigate to Administration > Agents.
  2. On the Agents page, click the agent's name to open the agent.
  3. To view the chain that is currently running, select the Running tab.
  4. To view the history of previous chain runs, select the Chains tab. Each chain is displayed on a separate row.

Back to top

Take agents offline or online

You can take an agent offline, for example, when the host machine is being updated and you want to temporarily prevent the agent from running chains.

Note: Taking an approved agent offline does not release any licenses held by the agent.

To take agents offline:

  1. In PulseUno, navigate to Administration > Agents.
  2. On the Agents page, select one or more agents.
  3. From the Mark As list, select Offline.

To take agents back online, select Online from the Mark As list.

Back to top

Restart agents

If an agent is not responding, you can restart it. You need to restart the chains running on the agent.

To restart an agent:

  1. In PulseUno, navigate to Administration > Agents.
  2. On the Agents page, click the agent's name to open the agent.
  3. Click Restart.

Back to top

Delete agents

You can delete agents registered with PulseUno.

Guidelines:

  • Shut down the agent before you attempt to delete it.
  • If you restart a deleted agent, it will be displayed again in PulseUno.
  • Deleting an agent does not remove the agent from the host machine where it is installed.
  • Deleting an agent releases any licenses held by the agent.

To delete an agent:

  1. Stop the agent on the host machine.
  2. In PulseUno, navigate to Administration > Agents.
  3. Select the agent and click Delete .
  4. Confirm that you want to delete the agent.

Back to top

Add variables to agents

You can add variable definitions to agents. A variable provides information about agents that you can use in chain steps, for example, the configuration settings used by a plugin.

Variables enable you to add steps to chains without needing to know the installation details of applications and tools on your agents.

For details on how to reference variables in chains, see Use variables in chains.

To add a variable to an agent:

  1. In PulseUno, navigate to Administration > Agents.
  2. On the Agents page, click the agent's name to open the agent.
  3. Click Edit and select the Variables tab.
  4. Click Add variable .
  5. Enter a name and value pair, for example:

    Name: MAVEN_HOME

    Value: /home/autobuild/maven3

    You cannot add variables with duplicate or empty variable names.

  6. Click Save.

Back to top

Add capabilities to agents

You can add capabilities to agents. Capabilities describe a host machine's environment, for example:

  • A specific operating system
  • High memory
  • A specific network location

You can add multiple capabilities to agents, use them to match agents to chains, and restrict the agents that can run chains.

Example: Assume you have multiple agents running Windows. If a chain requires Windows Server 2016 and 64 GB of memory, you can:

  1. Add the WindowsServer2016 and 64gbMemory capabilities to the appropriate agent.
  2. Add WindowsServer2016 and 64gbMemory as required capabilities on the chain.

When the chain runs, it matches its required capabilities with the agent's capabilities. The chain runs only on the agent that is running Windows Server 2016 and has 64 GB of memory.

To add capabilities to an agent:

  1. In PulseUno, navigate to Administration > Agents.

  2. On the Agents page, select an agent.

  3. Click Edit and select the Capabilities tab.

  4. To add capabilities, enter one or more tags. Tags cannot contain spaces.

  5. Click Save.

Back to top

See also: