TeamCity REST API Reference 2023.11 Help

Manage Cloud Profiles

This article lists REST API requests concerning cloud profiles.

Get Cloud Profiles

To get a list of all available cloud profiles, use:

/app/rest/cloud/profiles

To get a specific profile, use:

/app/rest/cloud/profiles/<cloudProfileLocator>

where cloudProfileLocator is typed as CloudProfileLocator.

For example, to get profiles belonging to the MyProject project, use:

/app/rest/cloud/profiles/project:MyProject

Get Cloud Images

To get cloud images, use:

/app/rest/cloud/images

This call, similarly to the above, supports the locator parameter:

/app/rest/cloud/images/<cloudImageLocator>

Here, cloudImageLocator is typed as CloudImageLocator.

For example, to get cloud image with ID my-ec2-image under amazon-1 cloud profile, use:

/app/rest/cloud/images/id:(id:my-ec2-image,profileId:amazon-1)

Get Cloud Instances

To get cloud instances, use:

/app/rest/cloud/instances

This call, similarly to the above, supports the locator parameter:

/app/rest/cloud/instances/<cloudInstanceLocator>

where cloudInstanceLocator is typed as CloudInstanceLocator.

To extend previous example, use the following request to get cloud instance i-0a7c2f04a1e58ca53 started from my-ec2-image under amazon-1 cloud profile:

/app/rest/cloud/images/id:(id:i-0a7c2f04a1e58ca53,imageId:my-ec2-image,profileId:amazon-1)

Start and Stop Cloud Instances

To start a new cloud instance, use:

/app/rest/cloud/instances

The request accepts the following payload:

<cloudInstance id="profileId:<profileId>,imageId:<imageId>,id:<instanceId>" name="<instanceName>"> <image id="profileId:<profileId>,id:<imageId>" name="<imageName>"/> </cloudInstance>
{ "id" : "profileId:<profileId>,imageId:<imageId>,id:<instanceId>", "name" : "<instanceName>", "image": { "id": "profileId:<profileId>,id:<imageId>", "name": "<imageName>" } }

To stop a running cloud instance, send a POST request to either /app/rest/cloud/instances/<cloudInstanceLocator>/actions/stop or /app/rest/cloud/instances/<cloudInstanceLocator>/actions/forceStop endpoint.

The .../actions/stop endpoint requests ensure that agents are not terminated during a build. Use this endpoint to tell an agent it should stop after finishing its current tasks.

Stop cloud agent after build

To immediately wind down a cloud agent even if it's currently busy, send a POST request to the .../actions/forceStop endpoint (recommended), or a DELETE request to the /app/rest/cloud/instances/<cloudInstanceLocator> endpoint.

POST http://localhost:8111/app/rest/cloud/instances/id:(id:i-0ce24a92a92285423,imageId:Win-Server-2022-xLarge,profileId:amazon-1)/actions/forceStop # or DELETE http://localhost:8111/app/rest/cloud/instances/id:(id:i-0ce24a92a92285423,imageId:Win-Server-2022-xLarge,profileId:amazon-1)
Last modified: 04 October 2023