Implementing Cloud support

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.

Cloud structure

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

1. Implement the jetbrains.buildServer.clouds.CloudClientFactory interface where
   1. getCloudCode returns the cloud plugin id with maximum length of 5 chars, i.e. "wmw"
   2. getDisplayName returns a user-friendly name of the plugin
   3. getEditProfileUrl returns a context-path to the controller that will provide the cloud profile settings fields for the form.
   4. getInitialParameterValues returns default values for form fields if any
   5. getPropertiesProcessor returns form values validator
   6. canBeAgentOfType: this method is called to check whether an agent is running on some instance of this could. If true is returned, TeamCity will create a CloudClient and query it for details.
   7. createNewClient: this factory method creates a new cloud client jetbrains.buildServer.clouds.CloudClientEx instance from cloud profile parameters. TeamCity creates one client per profile.
2. Register the implemented CloudClientFactory in jetbrains.buildServer.clouds.CloudRegistrar. You can get an instance of the CloudRegistrar interface in the constructor of your plugin's spring bean.

Implementing CloudClientEx

This interface has a base interface called jetbrains.buildServer.clouds.CloudClient with read-only operations. All action methods are declared in the jetbrains.buildServer.clouds.CloudClientEx interface.

Action methods

startNewInstace(CloudImage image, CloudInstanceUserData tag)

This method returns CloudInstance object in the SCHEDULED_TO_START, or STARTING, or 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.

terminateInstance(CloudInstance instance)

This method is used to stop a cloud instance.

restartInstance(CloudInstance instance)

This method is used to restart a virtual machine.

Readonly methods

isInitialized()

It may take some time for plugins to initialize. The clouds UI will show 'Loading' while this method returns false.

getImages()

Returns a list of all images that are registered for the cloud client

getErrorInfo()

Returns current communication error(s) if any

canStartNewInstance(CloudImage image)

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 startNewInstance method.

Find methods

findImageById

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:

• CloudType#canBeAgentOfType method
• CloudClient#findInstanceByAgent method

Cloud Instance

jetbrains.buildServer.clouds.CloudInstance is the interface describing an instance that is detected in the cloud. A known cloud instance is a cloud image.
An instance has one of the following states:

Cloud Image

jetbrains.buildServer.clouds.CloudImage is the cloud image interface describing a kind of image for virtual machines to start.

Cloud Profile

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.

Cloud Client

jetbrains.buildServer.clouds.CloudClientEx is the cloud client interface that has to be implemented in the plugin. This interface is required for CloudImages and CloudInstances.

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 CloudInstances.

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.

Configuration Parameters

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.

Image Parameters

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.

Plugin Building & Distribution

Cloud support is prepared as usual plugin for TeamCity. Then it could be published in the TeamCity plugins gallery.