The described API may be changed in future TeamCity releases.
This page will guide you through the implementation of Cloud support in TeamCity. Open-source Google Cloud Agents plugin could be used as an example.
See javadoc for details.
We are looking to improve this documentation and API. Feel free to post comments with questions and suggestions.
We define the following notions:
Cloud profile could have multiple cloud images which could have multiple cloud instances.
Create a TeamCity plugin project which should include at least agent-side and server-side modules.
If you are not using using Gradle TeamCity plugin add the TeamCity maven repository in your project:
<repositories> <repository> <id>teamcity</id> <name>TeamCity</name> <url>https://download.jetbrains.com/teamcity-repository/</url> <layout>default</layout> <snapshots> <enabled>true</enabled> <updatePolicy>always</updatePolicy> </snapshots> </repository> </repositories>
Then add the following libraries in your project modules.
provided "org.jetbrains.teamcity:cloud-interface:2017.2" provided "org.jetbrains.teamcity:cloud-shared:2017.2" provided "org.jetbrains.teamcity.internal:agent:2017.2"
<dependency> <groupId>org.jetbrains.teamcity</groupId> <artifactId>cloud-interface</artifactId> <version>2017.2</version> <scope>provided</scope> </dependency> <dependency> <groupId>org.jetbrains.teamcity</groupId> <artifactId>cloud-shared</artifactId> <version>2017.2</version> <scope>provided</scope> </dependency> <dependency> <groupId>org.jetbrains.teamcity.internal</groupId> <artifactId>agent</artifactId> <version>2017.2</version> <scope>provided</scope> </dependency>
provided "org.jetbrains.teamcity:cloud-interface:2017.2" provided "org.jetbrains.teamcity:cloud-shared:2017.2" provided "org.jetbrains.teamcity.internal:server:2017.2"
<dependency> <groupId>org.jetbrains.teamcity</groupId> <artifactId>cloud-interface</artifactId> <version>2017.2</version> <scope>provided</scope> </dependency> <dependency> <groupId>org.jetbrains.teamcity</groupId> <artifactId>cloud-shared</artifactId> <version>2017.2</version> <scope>provided</scope> </dependency> <dependency> <groupId>org.jetbrains.teamcity.internal</groupId> <artifactId>server</artifactId> <version>2017.2</version> <scope>provided</scope> </dependency>
getCloudCodereturns the cloud plugin id with maximum length of 5 chars, i.e. "wmw"
getDisplayNamereturns a user-friendly name of the plugin
getInitialParameterValuesreturns default values for form fields if any
canBeAgentOfType:this method is called to check whether an agent is running on some instance of this could. If
trueis returned, TeamCity will create a
CloudClientand query it for details.
jetbrains.buildServer.clouds.CloudClientExinstance from cloud profile parameters. TeamCity creates one client per profile.
jetbrains.buildServer.clouds.CloudRegistrar. You can get an instance of the
CloudRegistrarinterface in the constructor of your plugin's spring bean.
This interface has a base interface called
jetbrains.buildServer.clouds.CloudClient with read-only operations. All action methods are declared in the
TeamCity assumes that all implemented methods work quite fast. It is normal for the implementation to have its own thread/thread pool to:
startNewInstace(CloudImage image, CloudInstanceUserData tag)
This method returns
CloudInstance object in the
RUNNING state. If staring takes a long time, it is recommended to implement this interface asynchronuously.
CloudInstanceUserData contains properties to be set into a build agent that is started in the virtual machine.
This method is used to stop a cloud instance.
This method is used to restart a virtual machine.
It may take some time for plugins to initialize. The clouds UI will show 'Loading' while this method returns false.
Returns a list of all images that are registered for the cloud client
Returns current communication error(s) if any
This method is called to check whether it is possible to start one mode instance of the provided image. If
false is returned, TeamCity will plan to call the
This method is called by TeamCity to find a running CloudInstance for the registered build agent. This method should work as fast as possible.
TeamCity maintains mapping between CloudInstances and registered build agents. This mapping is supported by calling:
jetbrains.buildServer.clouds.CloudInstance is the interface describing an instance that is detected in the cloud. A known cloud instance is a
An instance has one of the following states:
if the implementation fails to determine the status
Use this status for a newly created instance
The cloud system has reported a machine as starting
The cloud system has reported a machine as running, i.e. booted
A machine is restarting
Use this status for instances that have just been requested to stop
A stop command was sent to the cloud system
The cloud system has reported that the machine is stopped
jetbrains.buildServer.clouds.CloudImage is the cloud image interface describing a kind of image for virtual machines to start.
jetbrains.buildServer.clouds.CloudProfile is the cloud profile interface describing settings. Each profile contains the cloud type and holds user-configurable parameters. You do not have to implement this interface.
jetbrains.buildServer.clouds.CloudClientEx is the cloud client interface that has to be implemented in the plugin. This interface is required for
How to associate a build agent with a cloud instance?
You can set a special property in
the buildAgent.properties file on the build agent started inside the cloud. This parameter can be checked on the server to match build agents with
In TeamCity Amazon EC2 integration this is done from the build agent plugin. The plugin fetches Amazon Instance metadata (including Amazon EC2
instanceId) and publishes the metadata to build agent custom properties. Build agents are matched according to the machine instanceId provided as build agent custom properties.
One can change the buildAgent.properties file in a running virtual machine (guest OS) from a host machine to publish properties that will help to match a build agent to a cloud image.
It general, it is possible to write a custom service/daemon for a guest OS that will update build agent properties on the machine start.
To get security credentials and cloud image details could be used
jetbrains.buildServer.clouds.CloudClientParameters. To store these parameters in the UI could be used HTML for inputs with with "prop:" prefix or TeamCity JSP tags.
To store image details should be define HTML element with a following name:
jetbrains.buildServer.clouds.CloudImageParameters#SOURCE_IMAGES_JSON which should store the list of JSON objects with image parameters.
Each image should be declare following parameters:
Cloud support is prepared as usual plugin for TeamCity. Then it could be published in the TeamCity plugins gallery.