Create and manage agent pools
TFS 2018
Note
Microsoft Visual Studio Team Foundation Server 2018 and earlier versions have the following differences in naming:
- Pipelines for build and release are called definitions
- Runs are called builds
- Service connections are called service endpoints
- Stages are called environments
- Jobs are called phases
An agent pool is a collection of agents. Instead of managing each agent individually, you organize agents into agent pools. In TFS, pools are scoped to the entire server; so you can share an agent pool across project collections and projects.
An agent queue provides access to an agent pool within a project. When you create a build or release pipeline, you specify which queue it uses. Queues are scoped to your project in TFS 2017 and newer, so you can only use them across build and release pipelines within a project.
To share an agent pool with multiple projects, in each of those projects, you create an agent queue pointing to the same agent pool. While multiple queues across projects can use the same agent pool, multiple queues within a project cannot use the same agent pool. Also, each agent queue can use only one agent pool.
Note
Agent pool jobs run a job on a single agent. If you need to run a job on all agents, such as a deployment group for classic release pipelines, see Provision deployment groups.
You create and manage agent pools from the agent pools tab in admin settings.
Navigate to your project and choose Settings (gear icon) > Agent Queues.
Choose Manage pools.
You create and manage agent queues from the agent queues tab in project settings.
Navigate to your project and choose Settings (gear icon) > Agent Queues.
Default agent pools
The following agent pools are provided by default:
- Default pool: Use it to register self-hosted agents that you've set up.
Designate a pool in your pipeline
Manage pools and queues
You create and manage agent pools from the agent pools tab in admin settings.
Navigate to your project and choose Settings (gear icon) > Agent Queues.
Choose Manage pools.
You create and manage agent queues from the agent queues tab in project settings.
Navigate to your project and choose Settings (gear icon) > Agent Queues.
Pools are used to run jobs. Learn about specifying pools for jobs.
If you've got a lot of self-hosted agents intended for different teams or purposes, you might want to create additional pools as explained below.
Create agent pools
Here are some typical situations when you might want to create self-hosted agent pools:
You're a member of a project and you want to use a set of machines owned by your team for running build and deployment jobs. First, make sure you're a member of a group in All Pools with the Administrator role. Next create a New project agent pool in your project settings and select the option to Create a new organization agent pool. As a result, both an organization and project-level agent pool will be created. Finally install and configure agents to be part of that agent pool.
You're a member of the infrastructure team and would like to set up a pool of agents for use in all projects. First make sure you're a member of a group in All Pools with the Administrator role. Next create a New organization agent pool in your admin settings and select the option to Auto-provision corresponding project agent pools in all projects while creating the pool. This setting ensures all projects have a pool pointing to the organization agent pool. The system creates a pool for existing projects, and in the future it will do so whenever a new project is created. Finally install and configure agents to be part of that agent pool.
You want to share a set of agent machines with multiple projects, but not all of them. First create a project agent pool in one of the projects and select the option to Create a new organization agent pool while creating that pool. Next, go to each of the other projects, and create a pool in each of them while selecting the option to Use an existing organization agent pool. Finally, install and configure agents to be part of the shared agent pool.
Security of agent pools
Understanding how security works for agent pools helps you control sharing and use of agents.
Roles are defined on each agent pool, and membership in these roles governs what operations you can perform on an agent pool.
Organization-level security settings
| Role on an agent pool in organization settings | Purpose |
|---|---|
| Reader | Members of this role can view the agent pool as well as agents. You typically use this to add operators that are responsible for monitoring the agents and their health. |
| Service Account | Members of this role can use the organization agent pool to create a project agent pool in a project. If you follow the guidelines above for creating new project agent pools, you typically do not have to add any members here. |
| Administrator | In addition to all the above permissions, members of this role can register or unregister agents from the organization agent pool. They can also refer to the organization agent pool when creating a project agent pool in a project. Finally, they can also manage membership for all roles of the organization agent pool. The user that created the organization agent pool is automatically added to the Administrator role for that pool. |
The All agent pools node in the Agent Pools tab is used to control the security of all organization agent pools. Role memberships for individual organization agent pools are automatically inherited from those of the 'All agent pools' node. By default, TFS and Azure DevOps Server administrators are also administrators of the 'All agent pools' node when using TFS or Azure DevOps Server.
Project-level security settings
Roles are also defined on each project agent pool, and memberships in these roles govern what operations you can perform on an agent pool at the project level.
| Role on an agent pool in project settings | Purpose |
|---|---|
| Reader | Members of this role can view the project agent pool. You typically use this to add operators that are responsible for monitoring the build and deployment jobs in that project agent pool. |
| User | Members of this role can use the project agent pool when authoring pipelines. |
| Administrator | In addition to all the above operations, members of this role can manage membership for all roles of the project agent pool. The user that created the pool is automatically added to the Administrator role for that pool. |
The All agent pools node in the Agent pools tab is used to control the security of all project agent pools in a project. Role memberships for individual project agent pools are automatically inherited from those of the 'All agent pools' node. By default, the following groups are added to the Administrator role of 'All agent pools': Build Administrators, Release Administrators, Project Administrators.
FAQ
If I don't schedule a maintenance window, when will the agents run maintenance?
If no window is scheduled, then the agents in that pool will not run the maintenance job.
What is a maintenance job?
You can configure agent pools to periodically clean stale working directories and repositories. This should reduce the potential for the agents to run out of disk space. Maintenance jobs are configured at the organization level in agent pool settings.
To configure maintenance job settings:
Navigate to your project and choose Settings (gear icon) > Agent Queues.
Choose Manage pools.
Choose the desired pool and choose Settings to configure maintenance job settings for that agent pool.
Important
You must have the Manage build queues permission to configure maintenance job settings. If you don't see the Settings tab or the Maintenance History tab, you don't have that permission, which is granted by default to the Administrator role. For more information, see Security of agent pools.
Configure your desired settings and choose Save.
Select Maintenance History to see the maintenance job history for the current agent pool. You can download and review logs to see the cleaning steps and actions taken.
The maintenance is done per agent pool, not per machine; so if you have multiple agent pools on a single machine, you may still run into disk space issues.
The maintenance job of my self-hosted agent pool looks stuck. Why?
Typically, a maintenance job gets "stuck" when it's waiting to run on an agent that is no longer in the agent pool. This happens when, for example, the agent has been purposefully taken offline or when there are issues communicating with it.
Maintenance jobs that have been queued to run will wait seven days to run. Afterward, they'll be automatically set to failed state if not run. This time limit cannot be changed.
The seven-day limit is different from the maintenance job timeout setting. The latter controls the maximum number of minutes an agent can spend doing maintenance. The timer starts when the job starts, not when the job is queued on an agent.
I'm trying to create a project agent pool that uses an existing organization agent pool, but the controls are grayed out. Why?
On the 'Create a project agent pool' dialog box, you can't use an existing organization agent pool if it is already referenced by another project agent pool. Each organization agent pool can be referenced by only one project agent pool within a given project collection.