Host Build Agents in Cloud

TeamCity supports two types of integrations:

• Regular cloud agents. This integration type uses cloud hosting providers (AWS, Microsoft Azure, Google Cloud, and so on) as an environment where build agents are hosted. These agents are entirely controlled by TeamCity: build queue distribution, compatibility check-ups, start-up and wind down activity, and more.

• Agentless integrations. In this scenario, a cloud provider serves as a "contractor" that handles TeamCity builds. TeamCity server sends queued builds to the "executor" and does not interfere in how it handles this queue.

Both options are available from the Project Settings | Cloud Profiles page.

This documentation section focuses primarily on regular cloud agents. For more information about the agentless executor mode, refer to this article: Executor Mode: Agentless Kubernetes Integration.

For each queued build, TeamCity first tries to start it on one of the self-hosted agents. If there is none available, TeamCity finds a matching cloud image with a compatible agent and starts a new instance for this image. TeamCity ensures that the number of running cloud instances limit is not exceeded.

The regular cloud agent integration requires:

• A configured virtual machine with an installed TeamCity agent in your cloud. It should be preconfigured to start the TeamCity agent on boot.

• A configured cloud profile in TeamCity.

Once a cloud profile is configured in TeamCity with one or several images, TeamCity does a test start of one instance for all the newly added images to learn about the agents configured on them. When the agents are connected, TeamCity stores their parameters to be able to correctly process build configurations-to-agents compatibility. An agent connected from a cloud instance started by TeamCity is automatically authorized, provided there are available agent licenses: the number of cloud agents is limited by the total number of agent licenses you have in TeamCity. After that, the agent is processed as a regular agent.

Depending on the profile settings, when TeamCity realizes it needs more agents, it can either:

• Start an existing virtual machine and stop it (after the build is finished or an idle timeout elapses). The machines that are stopped will be deallocated so the virtual machine fee does not apply when the agent is not active. The storage cost for this type of TeamCity agent will still apply.

• Create a new virtual machine from an image. Such machines will be destroyed (after the build is finished or an idle timeout elapses). This ensures that the machines will incur no further running costs.

The disconnected agent will be removed from the authorized agents list and deleted from the system to free up TeamCity build agent licenses.

A cloud profile is a collection of settings for TeamCity to start virtual machines with installed TeamCity agents on-demand while distributing a build queue. A cloud profile stores such general settings as:

• Credentials required to connect to a cloud provider.

• The maximum number of simultaneously active cloud agents.

• Conditions that specify when active agents should be terminated or stopped.

• TeamCity server URL that should be passed to new cloud agents when they start.

Each profile has one or multiple cloud images that store the following settings:

• An ID of a cloud instance to start or instance image to use.

• The container image to pull when an instance/node starts.

• Post-launch scripts.

• An agent pool that should own cloud agents spawned from this image.

  note

  You can only select the pool that contains the current project and/or its subprojects. Pools containing projects other than the current one and its subprojects will not be available for assignment. If the selected agent pool is changed in the future so that the criteria are not met or if the agent pool is not specified (or if this field is blank), TeamCity will automatically assign the cloud agents to the project pool.

  TeamCity automatically composes the project pool containing agents from all cloud profiles of the current project and all its subprojects. Thus, the added image will be available to all the subprojects as well. On the Agents | Pools page, this pool is marked as " \<Project name\> project pool ". Project pools cannot be deleted or modified.

This section describes general steps required for cloud integration.

The requirements for a virtual machine/image to be used for TeamCity cloud integration:

• The TeamCity agent must be correctly installed and configured to start automatically on the machine startup.

• To skip the update attempts on each agent connection to the server, make sure that the agent is up to date: start and wait for the update to complete. The agent state changes each time a plugin or tool is installed/updated/removed on the server.

• The buildAgent.properties file can be left "as is". The serverUrl, name, and authorizationToken properties can be left empty or set to any value, they are ignored when TeamCity starts the instance.

Provided these requirements are met, the usual TeamCity agent installation and cloud-provider image bundling procedures are applicable.

If you need the connection between the server and the agent machine to be secure, you will need to set up the agent machine to establish a secure tunnel (for example, VPN) to the server on boot so that the TeamCity agent receives data via the secure channel. Keep in mind that communication between the TeamCity agent and server requires opening ports on both the agent and the server.

The cloud provider pricing applies. Note that the charges can depend on the specific configuration implemented to deploy TeamCity. We advise you to check your configuration and the cloud account data regularly in order to discover and prevent unexpected charges as early as possible.

Note that traffic volumes and necessary server and agent machines characteristics greatly depend on the TeamCity setup and nature of the builds run.