Agent policies

3 minute read

Use this page to set up and manage an CloudBees Build Acceleration cluster by choosing an agent allocation policy, the cluster’s preemption policy, the agent lock interval, and wide/deep allocation policy.

See Understanding a Cluster Sharing Policy for information about cluster sharing policies.

Agent allocation policy

Before selecting the agent allocation policy, consider these choices:

  • Exclusive —All agents on a specific machine are assigned to the same build.

  • Shared —(Default) Agents on the same machine can be assigned to different builds. This policy requires that eMake client and agent machines have synchronized clocks.

Maximum clock skew (milliseconds)

The maximum clock skew, in seconds, allowed between the eMake client and the agents in the cluster.

Preemption policy

The preemption policy determines how the allocation algorithm responds to requests to preempt agents. To avoid wasted work, a currently running build may lock agents that have been working on the same command for a specified amount of time. The allocation algorithm does not reassign locked agents. In some circumstances the allocation algorithm can reassign “unlocked” agents to balance the load.

Reassigning agents can end in two results, and these two results determine if agents can be reassigned.

Preemption policy field descriptions

Setting Description

always

If reassigning an agent would drop a build below its minimum number of agents, agents cannot be taken. If reassigning an agent would leave a build with at least its minimum number of agents, unlocked agents can always be taken.

priority

If reassigning an agent drops a build below its minimum number of agents, agents can be taken from a lower priority build in order to bring a higher priority build up to its minimum number of agents. If reassigning an agent leaves a build with at least its minimum number of agents, unlocked agents can be taken from a lower priority build or an equivalent priority build.

never

Agents can never be taken.

The build class priority and minimum and maximum agent settings are set on the New Build Class page or the Edit Build Class page.

The following scenarios illustrate how the preemption policy setting affects agent reassignment:

Preemption policy scenario 1

  • Build A currently has 1 agent and its minimum number of agents is 2.

  • Build A needs 1 agent from Build B to meet Build A’s minimum number of agents.

  • Build B currently has 2 agents and its minimum number of agents is 2.

  • If 1 agent is reassigned to Build A, then Build B falls below its minimum number of agents.

Use the following matrix to determine if the agent is reassigned to Build A from Build B.

Preemption Policy Setting Reassign the agent to A from B?

always

No

priority

Yes, if Build A is higher priority

No, if Build B is higher priority

No, if priority is equal

never

No

Whether agents are locked or unlocked is disregarded in this scenario because reassigning an agent from Build B results in that build falling below its minimum number of agents.

Preemption policy scenario 2

  • Build A has at least its minimum number of agents; or Build A needs 1 agent from Build B to meet Build A’s minimum number of agents.

  • Build B has 3 agents and its minimum number of agents is 2.

  • If 1 agent is reassigned to Build A, then Build B still has its minimum number of agents.

For this scenario, determining whether to reassign agents depends on Preemption Policy settings and whether agents are locked or unlocked.

The default Agent Lock Interval is 60 (seconds). This means agents are locked after 60 seconds; until 60 seconds elapse, the agents are unlocked. Setting the Agent Lock Interval to 0 means the agents remain unlocked indefinitely.

Preemption Policy Setting Reassign the agent to A from B?

Unlocked or Lock Interval = 0

Lock Interval > 0 and time elapsed exceeds interval

always

Yes

No

priority

Yes, if Build A is higher priority

No, if Build B is higher priority

Yes, if priority is equal

No

never

No

No

Agent lock interval (seconds)

The value indicates how long, in seconds, an agent is locked from being taken by another build. This interval provides a buffer so the current build can perform any housekeeping tasks before being taken over by a subsequent build.

Wide/Deep agent allocation policy

Indicates whether the agent allocation policy is set to deep or wide. Deep means the agent allocation algorithm favors assigning more agents on the same host to a build. Wide means the algorithm favors assigning more agents from different hosts.

By default, this setting is deep. If you change this setting to wide, be sure the agent allocation policy is set to shared.

Click OK to save all selections.