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.
We define the following notions:
- Cloud profile - allows to define general cloud integration settings, e.g. security credentials.
- Cloud image - allows to define configuration parameters for image source, e.g. machine image, amount of RAM.
- Cloud instance - an instance of the running cloud image in the cloud.
Cloud profile could have multiple cloud images which could have multiple cloud instances.
Create Plugin Project
Create a TeamCity plugin project which should include at least agent-side and server-side modules.
Add Library References
If you are not using using Gradle TeamCity plugin add the TeamCity maven repository in your project:
Then add the following libraries in your project modules.
Agent Side Module
Server Side Module
How to implement a plugin for cloud support
- Implement the
getCloudCodereturns the cloud plugin id with maximum length of 5 chars, i.e. "wmw"
getDisplayNamereturns a user-friendly name of the plugin
- getEditProfileUrl returns a context-path to the controller that will provide the cloud profile settings fields for the form.
getInitialParameterValuesreturns default values for form fields if any
- getPropertiesProcessor returns form values validator
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.
- createNewClient: this factory method creates a new cloud client
jetbrains.buildServer.clouds.CloudClientExinstance from cloud profile parameters. TeamCity creates one client per profile.
- Register the implemented
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
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.
Build Agent mappings
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.