Getting started with Azure Devops -create a build agent

This is part 4 of a multipart series on getting started with Azure DevOps. Please refer to the below links to access other notes in this series.
Part 1: Getting started with Azure DevOps
Part 2: Getting started with Azure DevOps -work items
Part 3: Getting started with Azure DevOps -add a repo
Part 4: Getting started with Azure DevOps -create a build agent (this note)
Part 5: Getting started with Azure DevOps -create a build pipeline -Part 1 (YAML pipeline)
Part 6: Getting started with Azure DevOps -create a build pipeline -Part 2 (Classic Editor)
Part 7: Getting started with Azure DevOps -create a deployment group
Part 8: Getting started with Azure DevOps -create a release definition

Project teams will come to use Azure DevOps Server 2019 in one of two ways (i) either an upgrade from a previous version of TFS or (ii) a fresh setup of Azure DevOps Server 2019.

In case of a fresh setup of Azure DevOps Server 2019, it is a good idea to get a new (build) agent pool created and ready before a build definition requires to use the agent pool. In case a project team is upgrading from the previous version of TFS (version 2015 and later), the build agents tied to build pools in the earlier TFS installation should be able to pick up requests from build definitions (I have tested this for TFS2018.Update2 but not for an earlier version of TFS). Although, irrespective of which version of TFS you are upgrading from, my preference would be to create a new (build) agent pool in case of a TFS upgrade as well.

So let’s roll back a bit and identify a few key components that I’m talking about.

As you can see, a build definition consumes source code and build steps. A build downloads the source code to the build agent machine and uses the software installed on that machine to run the build steps on the source code. In the end, a build produces a build status and build artifacts.

What is a build agent pool?
As the name suggests, its a collection (pool) of build agents. A single machine (VM) can host multiple build agents and multiple machines can belong to a single build agent pool. Also, the same machine can host build agents belonging to different agent pools. However, a build agent can belong to only one build agent pool. Agent pools are a level of abstraction provided by Azure DevOps so that you do not have to manually manage the agents from a build definition. When you queue a build, it executes on an agent from the agent pool specified in the build definition.

Why do I need to know about build agents?
The build machine is where the actual builds will be executed. Ideally, you’d want it to be a separate machine from the App and DB server hosting Azure DevOps 2019. You may have multiple machines belonging to as many agent pools.

How to create a build agent pool and build agent?
The steps required are:
Step 1: Create an agent pool.
Navigate to Project Settings (gear at the bottom left corner) ->Pipelines -> Agent Pools
I named the pool: Sandbox Pool

Step 2: Once you have an agent pool created, click on the Download agent button.

(I already had a couple of agents created and they are being listed here -Sandbox-agent1 and Sandbox-agent2)

Step 3:
When you click on the Download agent button a new window pops out with agent commands to install on Windows, Mac, and Linux OSes. In my case, Windows is selected and (please read carefully) by default the version of agent architecture is x86. I categorically selected x64 since I was installing an agent on a Windows Server 2016 Standard.
Note: Do not install x86 version of agent on x64. You will be able to install and the agent will also come up, but your builds will fail without any clear error log.

Step 4: Download the agent and copy the zip file to the appropriate build agent. The first command block is to unzip and if the zip file is not located at the correct path the script will error out.
I unzipped the file: vsts-agent-win-x64-2.144.2 at E:\TFS-Sandbox-BuildAgent

Step 5: From here, open a Powershell command prompt as Admin and run config.cmd

I was prompted to enter the server URL and went ahead with the Integrated authentication type.
After connecting to the server, we start with registering the agent.

Step 6: Although we could create an agent pool on the fly at this step, I would not recommend that. This is where we enter the name of the agent pool we created.
Agent pool: Sandbox Pool
The next prompt was for agent name. I entered: Sandbox-agent3 to be consistent with the naming convention.

At this point, if I go back and check Azure DevOps portal -> Project Settings -> Agent pools, I see the following:

As you can see, the agent is listed but still offline. We have a few more steps left.

Step 7: Coming back to the Powershell command the next set of prompts are for the work area, the service and the user under which to run the service as.

If you open windows services, you will see this new service there:

Step 8: After this, if we go back to the portal we will see that the agent is green now.

And this is how we create an agent in Azure DevOps 2019 server.

There are a few notes that I’d want people to be careful of:

Can I have multiple build agents installed on the same machine?
Yes, we can have multiple (4/5) build agents, depending upon machine resources (memory/RAM). Although they can belong to separate build agent pools make sure they all have a unique agent name.

I am going to create multiple agents on a particular machine. Can I create copies of an existing agent folder and trigger the config.cmd file later?
There is a tendency to create a copy because it’s easy, right. But please do not create a copy of an existing installed agent, instead, unzip again from the zip file that was downloaded. Every time an agent gets configured, there are a few hidden files added to that folder. See below:

On opening .agent file you will see configuration specific to the installed agent.

Similarly, the other three files too have agent specific values …and that is why you should not copy an existing agent folder and instead take the unzip route.
If at all you have to, my suggestion would be to create copies of the unzipped folder before configuring the first agent.

What will happen if I create a copy of an existing agent folder and trigger the config.cmd file?
I tried that.

If I run “config.cmd remove” my existing installed agent will be removed. I do not want that. There is a use case for this command though. Say for example you configured the agent and something wasn’t correct… maybe you want to change the agent name, maybe you want to connect the agent to a different Azure DevOps URL. Under those circumstances, it is recommended that you do a clean removal of the agent and start configuring again.

Which machine can act as a build agent?
The machine that has all the necessary software installed so that the builds that run on that complete successfully. If the product needs .net and/or java to compile, have those installed before you install the agent on the machine. If you realized that you installed a software after installing the agent, restart the windows service under which the agent was running or better still (if possible) restart the build agent machine.

Note: I also noticed a slight difference in URL to agent pool
In TFS the url was $(TFSUrl)/DefaultCollection/_admin/_AgentPool
In AzureDevops it is: $(TFSUrl)/DefaultCollection/_settings/agentpools

Next, Part 5: Getting started with Azure DevOps -create a build pipeline -Part 1 (YAML pipeline)