Table of contents

CloudBees Jenkins Operations Center administration guide


Shared agents

Operations Center enables the sharing of agent executors across Client Masters in the Operations Center cluster. "Agents" were formerly called "slaves."

Note

For a Client Master to use shared agents, the Operations Center Cloud plugin must be installed on the Client Master. If the Client Master was installed with the "suggested plugins", then this plugin should be installed by default. However, before configuring shared agents in the Operations Center, it is prudent to verify that this plugin is installed on any Client Masters that will use these shared agents provisioned by the Operations Center.

Currently there are a number of restrictions on how agents are shared:

Restriction Description

Non-standard Launcher

If a non-standard launcher is used, the plugin defining the launcher must be installed on all the client masters within scope for using the shared agent, and the plugin versions on the client master and the Operations Center server must be compatible in terms of configuration data model. (An example of known non-compatibility would be that the ssh-slaves plugin before 0.23 uses a significantly different configuration data model from the model used post-1.0. This specific configuration data model difference is not of concern because the current versions of Jenkins all bundle versions of ssh-slaves newer than 1.0)

Shared Agent Usage

Shared agents can only be used by sibling client masters or by client masters in sub-folders of the container where the shared agent item is defined.

One Shot Build Mode

Shared agents operate in a "one-shot" build mode, unless the client master loses its connection with the Operations Center server. When the connection has been interrupted, client masters use any matching agents on-lease to perform builds. If there are no agents on-lease to the client master when the connection is interrupted, the client master may be unable to perform any builds (unless it has dedicated executors available).

Shared Agent with More than One Executor

If an agent is configured with more than one executor, the other executors are available to start builds while at least one executor is in use, and no more builds than the number of configured executors have been started on the agent. In other words, if an agent is configured with four executors, then accepts up to four builds on a client master, but after at least one build has completed, it is returned immediately after it becomes idle even if fewer than four builds have been run during the lease interval.

The sharing model used for shared agents is the same as the credentials propagation and role-based access control plugin’s group inheritance model. Consider the following configuration:

sharing model
Figure 1. Sample configuration
  • There are three folders: F1, F2, and F1/F3

  • There are three shared agents: F1/S1, F2/S2 and S3

  • There are four client masters: F1/F3/M1, F1/M2, F2/M3 and M4

The following logic is used to locate a shared agent:

  • If there is an available shared agent (or shared cloud) at the current level and that agent has the labels required by the job, then that agent is leased.

  • If there is no matching shared agent (or shared cloud with available capacity) at the current level, then proceed to the parent level and repeat.

Thus:

  • F1/F3/M1 and F1/M2 are able to perform builds on F1/S1 and S3 but not on F2/S2. F1/S1 is preferred as it is "nearer".

  • F2/M3 is able to perform builds on F2/S2 and S3 but not on F1/S1. F2/S2 is preferred.

  • M4 is only able to perform builds on S3

Under normal operation, when an agent is leased to a client master, it is leased for one and only one job build. After the build is completed, the agent is returned from its lease. This is known as "one-shot" build mode. If, while the agent is on lease, the connection between the client master and the Operations Center server is interrupted, the client master is unable to return the agent until the connection is re-established. While in this state, the agent is available for re-use by the client master.

Installing shared agents

You can install shared agents one of two ways.

  1. To create a shared agent, you must first decide how you want it created:

    • If you want to create the shared agent item at the root of the Operations Center server (example: the agent is available to all client masters), navigate to the root and select the New Job action on the left menu.

    • If you want to create the shared agent item within a folder in the Operations Center server (example: the agent is available only to client masters within the folder or within the folder’s sub-folders), then navigate to that folder and select the New Item action on the left menu.

      In either case, the standard new item screen appears:

      new item screen
      Figure 2. New item screen
  2. Provide a name and select Shared Agent as the type.

    Once the agent has been created, you are redirected to the configuration screen. A newly created shared agent is in the off-line state.

    configuration screen
    Figure 3. Configuration screen

    The configuration screen options are analogous to the standard Jenkins agent configuration options.

  3. When the agent configuration is complete, save or apply the configuration. If you do not want the agent to be available for immediate use, deselect the Take on-line after save/apply checkbox before saving the configuration.

Injecting node properties into shared agents

You can inject node properties into the shared agent when it is leased to the client masters through the Operations Center Cloud plugin. The initial implementation only provides support for two specific types of node properties:

  • Environment Variables

  • Tool Locations

Note

If you have written your own custom plugins that provide custom implementation(s) of NodeProperty, you can write a custom plugin for Operations Center (see Creating Custom Extensions) that provides implementation(s) of com.cloudbees.opscenter.server.properties.NodePropertyCustomizer with the appropriate injection logic for these custom node properties.

To inject node properties:

Select the Inject Node Properties option on the configuration screen and then add the required node property customizers:

  • Environment variables adds/updates the environment variables node property with the supplied values.

  • Tool Locations adds/updates the tool locations. The required tool installers must be defined with the same names both on Operations Center and on the client masters to which agents are leased.

Example 1. Injecting the tool location node properties of a shared agent
node property inject

Reviewing common shared agent tasks

Taking an agent offline

To take a shared agent offline, (for example, for maintenance of the server that hosts the shared agent process or to make configuration changes to the shared agent):

Navigate to the shared agent screen and select Take offline.

Example 2. An online shared agent
online state

Taking an agent online

To take a shared agent online, (for example, after maintenance of the server that hosts the shared agent process):

Navigate to the shared agent screen and select Take on-line.

Example 3. An offline shared agent
offline state

Configuring a shared agent

To configure a shared agent, you must first take the agent offline. If the shared agent is online, select Configure to take the agent offline first.

Example 4. Attempting to configure an online shared agent
configure online

Deleting a shared agent

To delete a shared agent, take the agent off-line first. If the shared agent is online, select Delete to take the agent off-line first.

Example 5. Attempting to delete an online shared agent
delete online

Moving a shared agent

A shared agent can be moved between folders by selecting Move on the shared agent screen.

Note

When moving shared agents, the JNLP agent launch commands include the path to the agent, so if you move a JNLP shared agent, you need to update the JNLP agents to connect to the new location. Any agents that are connected while the move is in progress are unaffected. If the Operations Center master is restarted or fails over in a HA cluster, however, the JNLP agents are unable to reconnect until they are reconfigured with the new path.

Recovering "lost" agents

Occasionally, due to lost connections between client masters and the Operations Center Server, a shared agent may become temporarily stuck in an on-lease state, whereby the Operations Center Server believes the agent to be leased to a specific client master, but the client master has no knowledge of the shared agent.

Built-in safety mechanisms identify and recover any such "lost" agents. By their nature, these processes perform cross-checks to ensure that an agent in use is not incorrectly recovered.

To start the recovery process, the client master that the agent is leased to must be connected to the Operations Center server. Once the connection is established, it can take up to 15 minutes for the recovery process to progress through its checks. Under normal circumstances, the checks are completed in less than two or three minutes.

If the automatic recovery processes fails, there is a Force release link that can be used to force the lease into a returned state.

Caution
Forcing a lease into a released (returned) state bypasses all the safety checks that ensure that the agent is no longer in use.

Reviewing CLI operations that support shared agents

The following CLI operations are designed to support management of shared agents:

  • create-job can be used to create a shared agent

  • disable-agent-trader can be used to take a shared agent off-line

  • enable-agent-trader can be used to take a shared agent on-line

  • list-leases queries the active leases of a shared agent

  • shared-agent-force-release can be used to force release of a "stuck" lease record

  • shared-agent-delete can be used to delete a shared agent

Note

The following CLI operations have been deprecated, and will be removed in a future release:

  • disable-slave-trader has been replaced with disable-agent-trader

  • enable-slave-trader has been replaced with enable-agent-trader

  • shared-slave-force-release has been replaced with shared-agent-force-release

  • shared-slave-delete has been replaced with shared-agent-delete