Manage agents

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

Note: Administrator permissions required.

Agent guidelines

When working with agents, take into account:

  • 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.

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

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

For an overview of agents, see Agent architecture.

Back to top

View agent information

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

On the Agents page, each agent is displayed graphically as a set of the following details:

  • 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, Disconnected, 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.
  • Agent capabilities.
  • 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 an agent's details:

  1. Navigate to Administration > Agents.

  2. (Optional) Filter the list to display only online, offline, approved, or unapproved agents. By default, all agents are displayed.

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

  3. Click the agent's name to open the agent.

  4. On the agent details page, navigate between the tabs to view agent information:

    Tab Description
    Overview Displays general agent information, including title, host name, status, UUID, agent version, and memory and work space usage.
    History Displays the history of changes made to the agent. You can sort the event list by date or user and in ascending or descending order.
    Running Displays the chains currently running on the agent.
    Chains Displays the history of previous chain runs, including the last run, last failure, last success, and the total number of runs.
    Variables Displays the variables defined for the agent. For details, see Add variables to agents.
    Capabilities Displays the capabilities defined for the agent. For details, see Add capabilities to agents.
    Limits Displays the agent's memory and work space thresholds. For details on how to set global and individual thresholds, see Set memory and disk space thresholds.
  5. To modify an agent's name or description, click Edit. In the Overview tab, change the title and note, and click Save.

Back to top

Set memory and disk space thresholds

To ensure the stability of your agents, set the monitoring thresholds for memory, temporary disk space, and work area space allocated for running chains.

You can specify thresholds that issue a warning or take the agent offline. By default, when any threshold is reached, PulseUno sends a notification to selected users about the event. You can customize email notifications as needed.

Example: Suppose your low watermark for work area space is set to 150 MB. Whenever the usable work space on an agent falls below 150 MB, PulseUno takes the agent offline and sends an email to designated users.

You can set global thresholds for all agents and override these limits for individual agents.

To set monitoring thresholds for all agents:

  1. Navigate to Administration > Agents.

  2. On the Agents page, click Agent Monitoring.

  3. In the Thresholds tab, set the thresholds for work area disk space, temporary disk space, and memory.

  4. To configure agent notifications, select the Notifications tab and specify the users to be notified, the events that trigger notifications, the email subject, and the frequency for monitoring agents.
  5. Click Save.

To set monitoring thresholds for a single agent:

  1. Navigate to Administration > Agents.

  2. On the Agents page, click the agent's name to open the agent.

  3. Click Edit and select the Limits tab.

  4. In the Limits tab, select Override global limits.

  5. Set the work area disk space, temporary disk space, and memory thresholds for the agent.

  6. To change the users who receive notifications about this agent, select the Overview tab. In the Contacts field, specify user emails separated by commas, semicolons, spaces, or new lines. Then select Only notify the agent's contact list.

    The agent's contact list overrides the list of users specified for all agents.

  7. Click Save.

Back to top

Take agents offline

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. 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 one or more agents are not responding, you can restart them. You also need to restart the chains running on the agents.

To restart agents:

  1. Navigate to Administration > Agents.
  2. On the Agents page, select one or more started agents.

  3. Click Restart.

  4. Provide a reason for restarting the agents, and click Restart.

Back to top

Add variables to agents

You can add variable definitions to agents. A variable provides agent information 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. Navigate to Administration > Agents.
  2. On the Agents page, click an 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. (Optional) To make the variable private, select the Private option. The values of private variables are not displayed in the user interface and the logs.

  7. Click Save.

Back to top

Add capabilities to agents

Capabilities describe the agent host machine's environment, for example, a specific operating system, high memory, or network location. Use capabilities to match agents to chains and restrict which agents can run chains.

Guidelines:

  • An agent provides capabilities to chains. After you add capabilities to each agent, you can use them in a chain to match one or more agents. For details, see Add capabilities to chains.

  • When you add capabilities to a chain, you restrict the chain to run only on those agents that provide all the same capabilities. If no agents match, the chain doesn't run.

    Example: You may have multiple agents running Windows, but some chains may require Windows Server 2019 and 64 GB of memory. In this case, you can:

    1. Add the WindowsServer2019 and 64gbMemory capabilities to appropriate agents.

    2. Add the matching WindowsServer2019 and 64gbMemory capabilities to relevant chains.

    As a result, these chains run only on the agents that provide the necessary capabilities.

  • You can add mandatory capabilities to agents. A mandatory capability makes an agent exclusive. A chain can run on such an agent only if the chain requires the agent's mandatory capability.

    Using mandatory capabilities, you can form a pool of agents available for specific jobs. For example, if you have agents with continuous integration (CI) capabilities, you can restrict these agents to run only CI jobs.

    Mandatory agent capabilities are prefixed with a plus sign (+), for example, +CI.

    Example: You may have multiple agents with WindowsServer2019 and 64gbMemory capabilities, and they may run multiple chains that require such capabilities. Suppose you need to restrict one of these agents to run only CI jobs. In this case, you can:

    1. Designate a CI agent by adding the +CI mandatory capability to it.

    2. Add the matching CI capability (without a plus sign) to the relevant chain.

    As a result, only the chain with the CI capability can run on the CI agent. Other chains with WindowsServer2019 and 64gbMemory capabilities can no longer run on the CI agent because they don't explicitly require the CI capability.

To add capabilities to an agent:

  1. Navigate to Administration > Agents.

  2. On the Agents page, click the agent's name to open the agent.

  3. Click Edit and select the Capabilities tab.

  4. To add one or more capabilities, enter their labels. Separate each label with a comma or space. Labels cannot contain spaces.

    To add a mandatory capability, prefix the label with a plus sign (+), for example, +WindowsServer2019.

  5. Click Save.

Back to top

Delete agents

You can delete one or more agents registered with PulseUno. Shut down the agent before deleting it.

Guidelines:

  • 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.
  • If you restart a deleted agent, it is displayed in PulseUno again.

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

See also: