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
- Implement the
jetbrains.buildServer.clouds.CloudClientFactory
interface wheregetCloudCode
returns the cloud plugin id with maximum length of 5 chars, i.e. "wmw"getDisplayName
returns 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.
getInitialParameterValues
returns 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. Iftrue
is returned, TeamCity will create aCloudClient
and query it for details.- createNewClient: this factory method creates a new cloud client
jetbrains.buildServer.clouds.CloudClientEx
instance from cloud profile parameters. TeamCity creates one client per profile.
- Register the implemented
CloudClientFactory
injetbrains.buildServer.clouds.CloudRegistrar
. You can get an instance of theCloudRegistrar
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
methodCloudClient#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:
status | description |
---|---|
| 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 |
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.
1 Comment
Vidhi
While using
jetbrains.buildServer.clouds.CloudType
, maven throws error: packagejetbrains.buildServer.clouds
does not exists.Any idea which package to use to make plugin cloud supportive??