Configuring Agent Pools
Instead of having one common set of build agents, you can break them into separate groups called agent pools. A pool is a named set of agents to which you can assign projects.
An agent can belong to one pool only.
A project can use multiple pools for its builds.
The number of agents authorized by the TeamCity server is limited by the number of agent licenses. By default, all newly authorized agents are included into the Default pool.
With the help of agent pools you can bind specific agents to specific projects. Project builds can be run only on build agents from the pools assigned to the project. Besides, using agent pools makes it easier to monitor the required agents' capacity.
Using agent pools allows:
Binding specific agents to specific projects: project builds can be run only on build agents from the pools assigned to the project.
Filtering the build queue by pools.
Use grouping by pool on the Agent Matrix and Agent Statistics pages.
Monitoring the required agents' capacity.
Required Permissions
To be able to add/remove pools and set maximum number of agents in the pool, you need to have the " Manage agent pools " permission. By default, these permissions are granted to the System Administrator and Agent Manager roles.
Assigning and unassigning projects and agents to/from pools is restricted by the " Change agent pools associated with project " permission, which by default is a part of the Project Administrator role. Users can perform the operations on the pool only if they have the " Change agent pools associated with project " permission for all projects associated with all pools affected by the operation.
See also related agent management permissions.
Managing Agent Pools
You can manage build agents on the Agents page, a link to which is located in the UI header. If you are using the classic UI mode, note that it has a different navigation system than described in this article: pools are managed on the Agents | Pools tab.
The Agents sidebar allows navigating between the existing agent pools and shows the agent statuses in real time.
To create a new pool, click + in the sidebar and enter its name.
By default, a pool contains an unlimited number of agents. You can set a maximum number of agents in the pool (not applicable to the Default pool). If the maximum number of agents is reached, TeamСity will not allow adding any new agents to this pool. This includes moving agents from other pools and automatic authorization of cloud agents. New cloud agents will not start if the target pool is full.
To see the details of a certain pool or its nested agent, click its name in the sidebar.
Agents Tab
To populate a pool with agents, click the destination pool in the sidebar, then click Assign agents in the Agents tab, and select the required agents from the list. Since an agent can belong to only one pool, assigning it to a pool will remove it from its previous pool. If TeamCity detects that this action might cause compatibility problems, it will show a respective warning. Removing an agent from a custom pool will return it to the Default pool.
To assign a cloud agent to a pool, you need to configure it in the cloud image details of the agent cloud profile. Note that agents from all cloud profiles of the current project are automatically combined into a project pool.
Only cloud agent images configured in the <Root> project can be moved using Assign agents.
Projects Tab
The "Projects" tab lets you specify which agent pools your projects can utilize.
Browse the list of projects to check which projects can run their builds on agents that belong to the currently selected pool.
Click the Assign projects button to allow required projects to utilize this pool.
Click the Dissociate button to prevent the target project from using this pool.
Note that if you unbind a project from all existing agent pools, you can no longer run the build configurations of this project (unless they consist entirely of agentless build steps).
Favorite Pools
You can click a star icon next to the pool's name to bookmark it.
Favorite pools are pinned to the top of the side navigation pane. You can also view all agents and cloud images from all favorite pools in the "FAVORITES" section.
Favorite pools are user-specific, meaning that each TeamCity user can have their own set of favorite agent pools.