This plugin implements "Agent cloud" functionality for running agents within containers, such as Docker.
This allows an easy way to customize the build environment for every build, instead of maintaining a set of generalized build agent that should build anything, or having dozens of mostly idle specialized agents.
As a starting point to creating agent images, have a look at Jetbrain's teamcity-agent and teamcity-minimal-agent Docker containers.
This plugin has been developed and tested against TeamCity 10 only, so far.
The plugin is distributed as a single archive which TeamCity can load directly,
container-cloud.zip. Either drop the file within your server's plugin dir, or
upload it in the web interface. A server restart is required.
There are two steps to get started using the plugin:
- Create a Cloud profile
- Configure a build to run within a container
TeamCity has a concept of Cloud profiles, which can start agents on demand. In this plugin, a Cloud profile is created with a single Container provider, which is then responsible for starting the containers as requested by TeamCity. If required, you can create several Cloud profiles using the plugin with different configurations.
To create a cloud profile, go to Administration > Cloud agents, then click "Create new profile". Enter a name for the profile, then select "Container cloud" from the "Cloud type" drop down. Note that the "Terminate instance idle time" is ignored, and "Terminate instance" will always be set to "After first build finished", no matter is configured here.
Select the desired Container provider and fill in any options required.
A new build feature "Run in Container Cloud" is included with the plugin, which allows specifying a profile and image for the build directly from the build configuration. An image added here is automatically added to the profile's list of images if not already present.
Currently there are two providers supported, described below, Docket socket and Helios, but many more are planned.
This provider connects to a single Docker instance, either over a local unix socket or using http(s), and runs agents there. Simple to get started, but limited to as many agents as can be run on a single machine.
API endpoint: How to reach the Docker socket. Defaults to using the local
DOCKER_HOST environment variable.
This provider uses Spotify's Helios orchestration tool to run agents on any host joined to the Helios cluster. Specifying a subset of hosts is possible with either host name pattern matching or label selectors.
Currently, a random agent matching the given criteria will be chosen when starting a new build agent.
Master url: Url a single master, or the SRV record designating the a cluster.
Required.
Host name pattern: Substring pattern agent host names must match. For example
given agents foo.mydomain and foobar.mydomain, a pattern of foo would
match both agents, while the pattern bar would only match the second one.
Optional, if not given, all agents will be matched.
Host selectors: Comma-separated list of selectors used to filter agents. For
example, role=builder,az=us-east-1 would select only agents with both those
labels set.
Optional, if not given, all agents will be matched.
TeamCity will compute which agents can process a certain build and then choose
one of those. If you want to make sure a build is only run with a specific
container image, add an Agent requirement with
env.CONTAINER_CLOUD_AGENT_IMAGE_ID equalling the desired image.
In the same way, to restrict a build to a certain profile, add a requirement
for system.cloud.profile_id.
The plugin is built using Maven. There are a few dependencies that are not part
of the Teamcity open apis which you will need to aquire from a TeamCity
installation first. An up-to-date list is documented in pom.xml, but one
example is cloud-server.jar. This is located under
webapps/ROOT/WEB-INF/lib/cloud-server.jar in the server installation.
Copy this file to the Maven local repository, including the version number:
.m2/repository/org/jetbrains/teamcity/cloud-server/10.0/cloud-server-10.0.jar
Once you're setup, simply compile and package:
$ mvn clean compile packageIf all works, the finished plugin is located in target/container-cloud.zip.