Agent Management API reference

34 minute readReference

This section describes agent management-related requests.

All database examples provided in this guide are specific to MySQL. If you use a different database, use syntax that is appropriate for your respective database.

changeAgentsEnabled

Changes the agent enabled status of one or more agents.

Required arguments

Field Description

enabled

Possible values are true or false.

Optional arguments

If no agent name, agent ID, or filter is specified, all agents are changed.
Field Description

agentId

Unique, internal number that can change; assigned by the Cluster Manager.

agentName

Name defined by the host where the agent resides (numbers and/or letters).

filter

A SQL query used to limit the result set. For a list of possible SQL values, see the getAgents command.
There is a syntax difference between MySQL and Oracle/MS SQL for enclosing criteria when using this argument for specific strings—for MySQL, use double quotes; for Oracle/MS SQL, use single quotes.

Syntax

cmtool changeAgentsEnabled <enabled> [optionals...]
▼

Examples

cmtool changeAgentsEnabled false
▼

Disables all agents in the cluster.

cmtool changeAgentsEnabled true --agentName linagent1
▼

Enables the agent named “linagent1”.

cmtool changeAgentsEnabled true --filter "agent_name LIKE ’winbuild1-%’"
▼

Enables all agents with a name that begins with “winbuild1-”.

createAgentComment

Creates a new agent comment.

Required arguments

Either agentId or agentName must also be specified.
Field Description

text

The comment text.

Optional arguments

Field Description

agentId

Unique, internal number that can change; assigned by the Cluster Manager.

agentName

Name defined by the host where the agent resides (numbers and/or letters).

Syntax

cmtool createAgentComment <text> [optionals...]
▼

Example

cmtool createAgentComment --agentName linagent "Agent has been running great"
▼

Creates a comment for an agent named “linagent”.

createCloudCredential

Creates a new cloud credential definition.

Required arguments

Field Description

cloudCredentialName

The user-defined name for this credential.

cloudProviderType

The cloud provider type. Use the getCloudProviders command for a list of currently supported providers.

cloudCredentialData

A formatted JSON list of fields that describes this credential. The set of fields varies with the type of cloud resource.
Field Description

Kubernetes credentials:

token

Image that is used by the resource that you specified via the --emake-resource option when invoking eMake to launch the instance.

endpoint

Name of the Kubernetes namespace within which the deployed services should be discovered. Defaults to the default namespace.

Microsoft Azure credentials:

tenantId

The tenant ID (GUID) from the Azure active directory.

subscriptionID

The subscription ID (GUID), which is a unique alphanumeric string identifying your Azure subscription.

clientID

The Application ID (GUID) from the Azure application.

clientSecret

The secret key (GUID) created from the client ID for the Azure application.

Amazon EC2 credentials:

access_key_id

Unique identifier that is associated with a secret_access_key. The access key ID and the secret access key are used together to sign programmatic AWS requests cryptographically.

secret_access_key

Used in conjunction with the access_key_id to cryptographically sign programmatic AWS requests. Signing a request identifies the sender and prevents request alteration. You can generate secret access keys for your AWS account, individual IAM users, and temporary sessions.

server_iam_role

Used if you are using the Cluster Manager server IAM role instead of the access_key_id and secret_access_key to cryptographically sign programmatic AWS requests.

You must set up the appropriate permissions for the IAM role. For the list of required permissions, see see Configuring Amazon EC2 for Agent Cloud Bursting - Setting Up a Server IAM Role.

region

Named set of AWS resources in the same geographical area. A region comprises at least two Availability Zones.

Google Cloud Platform (GCP) credentials:

<GCP Credential>

  • If specifying a credential using a service account, use the contents of the service account file as the value specified with cloudCredentialData.

    The service account file is a JSON file generated by creating a key for a service account in the Google Cloud Platform Console.

  • If specifying the credential as the service account that was used to start the instance where the Cluster Manager is running, specify the literal string: {"credential_provider" : "Server_IAM_Role"}.

Optional arguments

Field Description

description

A user-defined description for this credential.

Syntax

cmtool createCloudCredential <cloudCredentialName> [optionals...]
▼

Example

Create an EC2 cloud credential named my_cred (line break added for readability).

cmtool createCloudCredential 'my_cred' --cloudProviderType 'ec2' --cloudCredentialData "{"region":"us-west-1",
    "access_key_id":"ABCDEFGHKLMNOPQRST", "secret_access_key":"ABCDEFGHKLMNOPQRST12345678"}"
▼

createResource

Creates a new resource definition.

Required arguments

Field Description

resourceName

Unique name for the resource definition. The name can contain numbers and letters.

This is also the name that you specify in the --emake-resource=resourcename command, in the build class’ Resource Request field (on the web interface), or as the environment variable EMAKE_RESOURCE.

Optional arguments

Field Description

cloudConfigData

(For cloud resources) A formatted list of fields that describe the resource. The set of fields varies with the type of cloud resource.

Kubernetes resources:

imageName

This is the image that is used by the resource that you specified via the --emake-resource option when invoking eMake to launch the instance.

namespace

The name of the Kubernetes namespace within which the deployed services should be discovered. Defaults to the default namespace.

labels

(Optional) Define and use labels that identify semantic attributes of your application or deployment.

imagePullPolicy

(Optional) The image pull policy and the tag of the image affect when the kubelet attempts to pull the specified image.

Always —the image is pulled every time the pod is started.

If Not Present —the image is pulled only if it is not already present locally.

Never —the image is assumed to exist locally. No attempt is made to pull the image.

Default is Always if :latest label is specified; otherwise, If Not Present. Cannot be updated.

By default, the kubelet tries to pull each image from the specified registry. However, if the Image Pull Policy of the container is set to If Not Present or Never, then a local image is used preferentially or exclusively, respectively.

If you want to rely on pre-pulled images as a substitute for registry authentication, you must ensure all nodes in the cluster have the same pre-pulled images. This can be used to pre-load certain images for speed or as an alternative to authenticating to a private registry.

Microsoft Azure resources:

location

Azure region in which cloud burst agent instances will be launched.

resourceGroupName

Name of the Azure resource group where metadata for the cloud burst agent instances will be stored.

azureImageName

The Azure image name with preinstalled on-demand agent that is used to launch cloud burst instances.

vmSize

Specifies the Azure virtual machine size that defines the memory, CPU, storage capacity, and usage cost for a managed virtual machine.

storageAccountType

The type of storage account for the cloud burst agent virtual machine disk.

virtualNetworkName

The name of the Azure Virtual Network (VNet) where cloud burst agent instances are launched.

Amazon EC2 resources:

ami_name

Amazon EC2 image name that is used to launch cloud burst agent instances.

availability_zone

Distinct location within a region that is insulated from failures in other Availability Zones.

instance_type

Information provided from AWS EC2 specification that defines the memory, CPU, storage capacity, and usage cost for an instance.

keypair_name

Set of security credentials that you use to prove your identity electronically. A key pair consists of a private key and a public key. You use the private key to create a digital signature, and then AWS uses the corresponding public key to validate the signature.

security_group

Named set of allowed inbound network connections for an instance. Security groups in Amazon Virtual Private Cloud (VPC) also include support for outbound connections.

subnet_id

Segment of the IP address range of a VPC that Amazon EC2 instances can be attached to. You can create subnets to group instances according to security and operational needs.

use_spot

If set to true, cloud bursting will launch Amazon EC2 spot instances. If the launch fails for some reason, like MaximumSpotInstanceCountExceeded, the code tries again to launch a regular instance. Possible values are true or false.

Google Cloud Platform (GCP) resources:

image_name

Unique name for the GCP image to be used to create the instance.

machine_type

Type for a particular collection of virtualized hardware resources available to a VM instance, including the system memory size, virtual CPU (vCPU) count, and maximum persistent disk capability.

zone

Deployment area for GCP resources. This is the GCP zone where the cloud burst agents will be started.

disk_type

Type of the node VM boot disk to use to create the instance. Select the most appropriate disk type from the provided list .

network_name

This is the name of the GCP VPC network used to start the cloud burst agents. The cluster manager must have been configured with the selected network. For custom mode GCP VPC networks, the subnetwork must also be specified.

subnet_name

If the GCP VPC network selected was created in custom mode, this is the name of the subnetwork used to start cloud burst agents. The subnetwork must be in the GCP region of the specified zone. For auto mode GCP VPC networks, the value is default.

additional_metadata

Extra (custom) tags to add to the GCP agent instance at launch time. These tags are visible in the instance properties as custom metadata. These are in addition to CB-Name, which is the tag that CloudBees Build Acceleration uses to indicate that it started the instance.

To add extra tags, you set the variable to a comma-separated list of key:value pairs. For example: Name:MyAgent, ProvisionedBy:CB

preemptible

If set to true, cloud bursting will launch GCP preemptible instances which can help save Compute Engine costs. Possible values are true or false.
Field Description

cloudIdleTimeout

(For cloud resources) The period of time before idle agents are terminated. When the build finishes, any agents it used are available for use with other builds using the same resource. If no other build uses an agent, that agent becomes idle. If a cloud burst agent is idle for 15 minutes (by default), the instance hosting that agent will be terminated automatically by the Cluster Manager.

cloudInstanceAgents

(For cloud resources) The number of agents installed on the image used to create the instance. This value is used to determine how many instances are launched.

cloudCredential

(For cloud resources) The name of an existing credential set that is used for connection to cloud provider. Use the getCloudCredentials command for a list of credentials.

cloudProviderType

(For cloud resources) The cloud provider type. Use the getCloudProviders command for a list of currently supported providers.

description

A user-defined description for this resource.

hostMasks

(For static resources) This is a semi-colon delimited list of host name masks, used to identify the list of hosts that support a resource. This field is empty if no static hosts have been configured.

Host name masks follow the same standard globbing rules as Make. (Globbing lets you use a pattern to match one or more files.)

Pattern arguments may contain any of the following special characters:

*—Matches any sequence of zero or more characters

?—Matches any single character

[…​]—Matches a set or range of characters. For example, myhost [1-9] matches the hosts myhost1 through myhost9.

\—Escapes the following characters

Syntax

cmtool createResource <resourceName> <hostMasks> [optionals...]
▼

Example

Create a new resource named R29 that only uses hosts whose names start with ’rs’ or ’rt’.

cmtool createResource R29 "rs*; rt*" --description "rs or rt hosts"
▼

Create a new EC2 cloud resource named myEC2 (line breaks added for readability).

cmtool createResource myEC2 --cloudProviderType ec2 --cloudCredential my_ec2_cred
      --cloudConfigData "{"instance_type":"t2.micro","security_group":"sg-abcdefgh","keypair_name":"my_keypair",
                         "availability_zone":"us-west-1a","subnet_id":"subnet-1234567","ami_name":"Agent_Image_EC2",
                         "extra_tags":"resource_name:my_resource"}"
      --cloudIdleTimeout 10
▼

Create a new GCP cloud resource named myGCP (line breaks added for readability).

cmtool createResource myGCP --cloudProviderType gcp --cloudCredential my_gcp_cred
      --cloudConfigData "{"image_name": "myagent", "machine_type": "n1-standard-1",
                         "zone": "us-west1-b", "disk_type": "pd-standard",
                         "network_name": "default", "subnet_name": "default",
                         "additional_metadata": "Company:CB,Group:A"}"
      --cloudIdleTimeout 5
      --cloudInstanceAgents 15
▼

Create a new Kubernetes cloud resource named myK8S (line breaks added for readability).

cmtool createResource myK8S --cloudProviderType kubernetes --cloudCredential my_kube_cred
      --cloudConfigData "{"imageName":"mygithub/agent_image","namespace":"default",
                          "labels":"os:ubuntu,version:test","imagePullPolicy":"Never"}"
      --cloudIdleTimeout 2
▼

createResourceComment

Creates a new resource comment.

Required arguments

Field Description

resourceId

A unique number that identifies each resource.

text

The comment text.

Optional arguments

None.

Syntax

cmtool createResourceComment <resourceId> <text>
▼

Example

cmtool createResourceComment 2 "This resource identifies production servers"
▼

Creates a comment for resource 2.

deleteAgentComment

Deletes an agent comment.

Required arguments

Either agentId or agentName must also be specified.
Field Description

commentId

The unique key that identifies a comment. Use the getAgentComments command to get a list of comment ID numbers.

Optional arguments

Field Description

agentId

Unique, internal number that can change; assigned by the Cluster Manager.

agentName

Name defined by the host where the agent resides (numbers and/or letters).

Syntax

cmtool deleteAgentComment <commentId> [optionals...]
▼

Example

cmtool deleteAgentComment 1008 --agentId 14
▼

Deletes comment 1008 from agent 14 (14 is the Cluster Manager internal ID for the agent). To find out what the appropriate comment ID is, use the the getAgentComments command command, which will list the comments attached to a particular agent.

deleteAgents

Deletes one or more agents, including all dependent records.

Required arguments

None.

Optional arguments

Field Description

agentId

Unique, internal number that can change; assigned by the Cluster Manager.

agentName

Name defined by the host where the agent resides (numbers and/or letters).

filter

A SQL query used to limit the result set. For a list of possible SQL values, see the getAgents command.

Syntax

cmtool deleteAgents [optionals...]
▼

Example

cmtool deleteAgents --agentName winbuild1
▼

Deletes agent “winbuild1” and all associated comments.

deleteCloudCredential

Deletes a cloud credential definition.

Required arguments

Field Description

cloudCredentialId

A unique number that identifies each cloud credential. Use the the getCloudCredentials command command to get a list of cloud credential IDs.

Optional arguments

None.

Syntax

cmtool deleteCloudCredential <cloudCredentialId>
▼

Example

cmtool deleteCloudCredential 1
▼

Deletes a cloud credential with cloudCredentialId 3.

deleteCloudCredentials

Deletes a set of cloud credentials.

Required arguments

None.

Optional arguments

Field Description

filter

A SQL query used to limit the result set. For a list of possible SQL values, see the getCloudCredentials command.

Syntax

cmtool deleteCloudCredentials [optionals...]
▼

Example

cmtool deleteCloudCredentials
▼

Deletes all cloud credentials.

deleteResource

Deletes a resource definition.

You cannot delete the default resource.

Required arguments

Field Description

resourceId

A unique number that identifies each resource. Use the getResources command to get a list of resource IDs.

Optional arguments

None.

Syntax

cmtool deleteResource <resourceId>
▼

Example

cmtool deleteResource 3
▼

Deletes the resource definition for resource 3.

deleteResources

Deletes multiple resource definitions.

You cannot delete the default resource.

Required arguments

None.

Optional arguments

Field Description

filter

A SQL query used to limit the result set. For a list of possible SQL values, see the getResources command.

Syntax

cmtool deleteResources [optionals...]
▼

Example

cmtool deleteResources
▼

Deletes all resource definitions.

deleteResourceComment

Deletes a resource comment.

Required arguments

Field Description

resourceId

A unique number that identifies each resource.

commentId

The unique key that identifies a comment. Use the getResourceComments command to get a list of comment IDs.

Optional arguments

None.

Syntax

cmtool deleteResourceComment <resourceId> <commentId>
▼

Example

cmtool deleteResourceComment 3 49
▼

Deletes comment 49 from resource 3.

getAgentComments

Retrieves a list of related agent comments, or a specific comment (by using the --commentId option).

Required arguments

None.

Optional arguments

Field Description

agentId

Unique, internal number that can change; assigned by the Cluster Manager.

agentName

Name defined by the host where the agent resides (numbers and/or letters).

Result tags

Field Description

commentId

The unique key that identifies a comment.

createTime

The time when the item was created.

lastModifiedBy

The user who last modified the item.

modifyTime

The time when the item was last modified.

text

The text of the item.

Syntax

cmtool getAgentComments [optionals...]
▼

Example

cmtool getAgentComments --agentName ahost-3
▼

Retrieves all comments for agent “ahost-3”.

getAgentPerformance

Retrieves the performance log of one or more agents.

Required arguments

None.

Optional arguments

Field Description

agentId

Unique, internal number that can change; assigned by the Cluster Manager.

agentName

Name defined by the host where the agent resides (numbers and/or letters).

agents

A list of agents whose performance you want to see.

buildId

Further restricts the returned agents to those running a specific build ID.

status

Can be 1 or 0. Choose active or inactive agents only.

enabled

Can be 1 or 0. Choose enabled or disabled agents only.

Result tags

Field Description

agentName

This is the name of the agent as it appears on the web page (product UI).

result

This is the performance information of the agent.

Syntax

cmtool getAgentPerformance [optionals...]
▼

Example

cmtool getAgentPerformance --agentName SOL1-1
▼

Returns the performance log of the agent named “SOL1-1”.

getAgents

Retrieves a list of agents.

Required arguments

None.

Optional arguments

Field Description

agentId

Unique, internal number that can change; assigned by the Cluster Manager.

agentName

Name defined by the host where the agent resides (numbers and/or letters).

filter

A SQL query used to limit the result set. See the possible values below.

There is a syntax difference between MySQL and Oracle/MS SQL for enclosing criteria when using this argument for specific strings—for MySQL, use double quotes; for Oracle/MS SQL, use single quotes.

maxResults

The maximum number of elements to return from a query.

firstResult

The starting index for the query result set.

This argument takes values beginning with 0. A negative value indicates a record starting from the end of the set, counting backwards, so -1 is the last record, -2 is the next to last, and so on.

order

A SQL order by clause. Used to specify ordering for the query result set.

profile

Set to one of the following: details —returns all information. info —returns a reduced information set.

You must set this argument to details in order to print fields that are part of the details category.

Result tags and SQL query names

Field Description

a2aPort

The agent to agent protocol communication port. SQL query name for --filter and --order: a2a_port

agentId

A unique, internal number assigned to each agent by the Cluster Manager; this number can change. SQL query name for --filter and --order: id

agentName

A name defined by the host where the agent resides (numbers and/or letters). SQL query name for --filter and --order: agent_name

agentVersion

The agent version string. SQL query name for --filter and --order: agent_version

availableResults

This is a count of ’max’ or ’first’ results if --maxResults or --firstResult is specified. SQL query name for --filter and --order: N/A

buildId

A unique number assigned by the Cluster Manager for each build. SQL query name for --filter and --order: current_build_id

buildName

The build name that is the expanded build class tag. SQL query name for --filter and --order: N/A

consolePort

The agent console port. SQL query name for --filter and --order: console_port

efsVersion

The EFS version string. SQL query name for --filter and --order: efs_version

enabled

The flag indicating if an agent is enabled or not. SQL query name for --filter and --order: enabled

errorCount

The number of internal agent errors. SQL query name for --filter and --order: error_count

hostName

The name of the machine where eMake was invoked. SQL query name for --filter and --order: host_name

inPenaltyBox

A flag indicating eMake had a recent problem with this agent. SQL query name for --filter and --order: N/A

ipAddress

The agent IP address. SQL query name for --filter and --order: ip_address

lastErrorTime

The last time the agent experienced an error. SQL query name for --filter and --order: last_error_time

lastPingTime

The last time the agent was pinged to determine its status. SQL query name for --filter and --order: last_ping_time

platform

The operating system being used or supported. If an OS is specified for a build class, builds from other operating systems cannot affiliate themselves with this class. SQL query name for --filter and --order: platform

port

The agent protocol communication port. SQL query name for --filter and --order: port

restartCount

The number of agent restarts. SQL query name for --filter and --order: restart_count

status

The agent status. 1= OK, but anything else is an error code. SQL query name for --filter and --order: status

statusDetail

If the last status update resulted in an error, it contains the error string (or the “OK” string if no error occurred). SQL query name for --filter and --order: status_detail

webPort

The agent web server port. SQL query name for --filter and --order: web_port

Syntax

cmtool getAgents [optionals...]
▼

Example

cmtool getAgents --filter "agent_name like ’%SOL%’"
▼

Retrieves a list of all agents whose names start with “SOL”.

getAgentStatus

Retrieves the state of one or more agents. By default, only active agents are returned. Use --status 0 to list inactive agents.

Required arguments

None.

Optional arguments

Field Description

agentId

Unique, internal number that can change; assigned by the Cluster Manager.

agentName

Name defined by the host where the agent resides (numbers and/or letters).

agents

A list of agents whose status you want to see.

buildId

Further restricts the returned agents to those running a specific build ID.

status

Can be 1 or 0. Choose active or inactive agents only.

enabled

Can be 1 or 0. Choose enabled or disabled agents only.

Result tags

Field Description

agentName

This is the name of the agent as it appears on the web page (product UI).

result

This is the text string that describes the current state of the agent.

Syntax

cmtool getAgentStatus [optionals...]
▼

Example

cmtool getAgentStatus --agentName SOL1-1
▼

Returns the status of the agent named “SOL1-1”.

getCloudCredential

Get full details for the specified cloud credential.

Required arguments

Field Description

cloudCredentialId

The credential Id assigned by the system at create time. Use the getCloudCredentials command to retrieve the list of available credentials with their IDs.

Optional arguments

None.

Result tags

Field Description

cloudCredentialId

The credential Id assigned by the system at create time. Use the getCloudCredentials command to retrieve the list of available credentials with their IDs.

cloudCredentialName

The user-defined name for this credential.

cloudProviderType

The cloud provider type. Use the getCloudProviders command for a list of currently supported providers.

cloudCredentialData

A formatted JSON list of fields that describes this credential. The set of fields varies with the type of cloud resource:

|Field |Description

2+|Kubernetes credentials:

|token |Image that is used by the resource that you specified via the --emake-resource option when invoking eMake to launch the instance.

|endpoint |Name of the Kubernetes namespace within which the deployed services should be discovered. Defaults to the default namespace.

2+|Microsoft Azure credentials:

|tenantId |The tenant ID (GUID) from the Azure active directory.

|subscriptionID |The subscription ID (GUID), which is a unique alphanumeric string identifying your Azure subscription.

|clientID |The Application ID (GUID) from the Azure application.

|clientSecret |The secret key (GUID) created from the client ID for the Azure application.

2+|Amazon EC2 credentials:

|access_key_id |Unique identifier that is associated with a secret_access_key. The access key ID and the secret access key are used together to sign programmatic AWS requests cryptographically.

|secret_access_key |Used in conjunction with the access_key_id to cryptographically sign programmatic AWS requests. Signing a request identifies the sender and prevents request alteration. You can generate secret access keys for your AWS account, individual IAM users, and temporary sessions.

|server_iam_role |Used if you are using the Cluster Manager server IAM role instead of the access_key_id and secret_access_key to cryptographically sign programmatic AWS requests.

You must set up the appropriate permissions for the IAM role. For the list of required permissions, see see Configuring Amazon EC2 for Agent Cloud Bursting - Setting Up a Server IAM Role.

|region |Named set of AWS resources in the same geographical area. A region comprises at least two Availability Zones.

2+|Google Cloud Platform (GCP) credentials:

|<GCP Credential>

| * If specifying a credential using a service account, use the contents of the service account file as the value specified with cloudCredentialData.

+ The service account file is a JSON file generated by creating a key for a service account in the Google Cloud Platform Console.

  • If specifying the credential as the service account that was used to start the instance where the Cluster Manager is running, specify the literal string: {"credential_provider" : "Server_IAM_Role"}.

description

A user-defined description for this credential.

Syntax

cmtool getCloudCredential <cloudCredentialId>
▼

Example

cmtool getCloudCredential 1
▼

Retrieves cloud credential with cloudCredentialId 1.

getCloudCredentials

Retrieve a list of all cloud credentials.

Required arguments

None.

Optional arguments

Field Description

filter

A SQL query used to limit the result set. See the possible values below.

There is a syntax difference between MySQL and Oracle/MS SQL for enclosing criteria when using this argument for specific strings—for MySQL, use double quotes; for Oracle/MS SQL, use single quotes.

maxResults

The maximum number of elements to return from a query.

firstResult

The starting index for the query result set.

This argument takes values beginning with 0. A negative value indicates a record starting from the end of the set, counting backwards, so -1 is the last record, -2 is the next to last, and so on.

order

A SQL order by clause. Used to specify ordering for the query result set.

profile

Set to one of the following: details —returns all information. info —returns a reduced information set.

You must set this argument to details in order to print fields that are part of the details category.

Result tags

A list of cloudCredential objects, each with the following fields.

Field Description

cloudCredentialId

The credential Id assigned by the system at create time.

cloudCredentialName

The user-defined name for this credential.

cloudProviderType

The cloud provider type. Use the getCloudProviders command for a list of currently supported providers.

cloudCredentialData

A formatted JSON list of fields that describes this credential. The set of fields varies with the type of cloud resource:

|Field |Description

2+|Kubernetes credentials:

|token |Image that is used by the resource that you specified via the --emake-resource option when invoking eMake to launch the instance.

|endpoint |Name of the Kubernetes namespace within which the deployed services should be discovered. Defaults to the default namespace.

2+|Microsoft Azure credentials:

|tenantId |The tenant ID (GUID) from the Azure active directory.

|subscriptionID |The subscription ID (GUID), which is a unique alphanumeric string identifying your Azure subscription.

|clientID |The Application ID (GUID) from the Azure application.

|clientSecret |The secret key (GUID) created from the client ID for the Azure application.

2+|Amazon EC2 credentials:

|access_key_id |Unique identifier that is associated with a secret_access_key. The access key ID and the secret access key are used together to sign programmatic AWS requests cryptographically.

|secret_access_key |Used in conjunction with the access_key_id to cryptographically sign programmatic AWS requests. Signing a request identifies the sender and prevents request alteration. You can generate secret access keys for your AWS account, individual IAM users, and temporary sessions.

|server_iam_role |Used if you are using the Cluster Manager server IAM role instead of the access_key_id and secret_access_key to cryptographically sign programmatic AWS requests.

You must set up the appropriate permissions for the IAM role. For the list of required permissions, see see Configuring Amazon EC2 for Agent Cloud Bursting - Setting Up a Server IAM Role.

|region |Named set of AWS resources in the same geographical area. A region comprises at least two Availability Zones.

2+|Google Cloud Platform (GCP) credentials:

|<GCP Credential>

| * If specifying a credential using a service account, use the contents of the service account file as the value specified with cloudCredentialData.

+ The service account file is a JSON file generated by creating a key for a service account in the Google Cloud Platform Console.

  • If specifying the credential as the service account that was used to start the instance where the Cluster Manager is running, specify the literal string: {"credential_provider" : "Server_IAM_Role"}.

description

A user-defined description for this credential.

Syntax

cmtool getCloudCredentials [optionals...]
▼

Example

cmtool getCloudCredentials --order cloudCredentialName
▼

Retrieves cloud credentials sorted by their name.

getCloudInformation

Retrieves current information about the cloud provider (Amazon EC2, Azure, GCP, or Kubernetes) that is in use.

Required arguments

None.

Optional arguments

None.

Result ags

Field Description

cloudHostManagerStatus

Displays the following status messages for Amazon EC2, Azure, GCP, or Kubernetes (depending on the type of cloud provider that is in use).

lastMessage

Displays the latest message in the list of available messages.

Message

Displays an individual message.

Syntax

cmtool getCloudInformation
▼

Example

cmtool getCloudInformation
▼
<?xml version="1.0" encoding="UTF-8"?>

<responses xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="accelerator-output.xsd" version="2.0">
  <response requestId="1">
    <cloudHostManagerStatus>
      <lastMessage>DEBUG Setting up check stalled resource timer thread:60000</lastMessage>
      <messages>
        <message>2017-11-16T19:36:25.408 DEBUG Setting up idle host timer thread:30000</message>
        <message>2017-11-16T19:36:25.409 DEBUG Setting up clean CloudResource timer thread:60000</message>
        <message>2017-11-16T19:36:25.410 DEBUG Setting up check stalled resource timer thread:60000</message>
      </messages>
    </cloudHostManagerStatus>
  </response>
</responses>
▼

getCloudJobs

Retrieves information about all jobs submitted to the cloud provider that is in use.

Required arguments

None.

Optional arguments

None.

Result tags

Field Description

cloudJob

Cloud provider instance ID.

id

Cloud instance ID (also called a cloud job ID) assigned for the job.

hostName

Cloud host where the agents reside.

lastUpdated

Time when the status was retrieved.

platform

Platform of the host where the agents reside.

resourceName

The user-defined resource name assigned at resource-create time.

stalled

Indicates if the job is stalled.

state

Status of the agent host (such as pending, running, or shutting down).

submittedAt

Date and time when the job was requested.

Syntax

cmtool getCloudJobs
▼

Example

cmtool getCloudJobs
▼
<?xml version="1.0" encoding="UTF-8"?>
▼
<responses xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="accelerator-output.xsd" version="2.0">
  <response requestId="1">
    <cloudJob>
      <id>i-0aca17d5cd971f99c</id>
      <hostName>ip-172-31-47-204</hostName>
      <lastUpdatedAt>2017-11-16T19:48:53.039Z</lastUpdatedAt>
      <platform>linux</platform>
      <resourceName>eaAgent</resourceName>
      <stalled>0</stalled>
      <state>running</state>
      <submittedAt>2017-11-16T19:48:25.443Z</submittedAt>
    </cloudJob>
    <cloudJob>
      <id>i-0b1285de24559f33c</id>
      <hostName>ip-172-31-40-113</hostName>
      <lastUpdatedAt>2017-11-16T19:49:42.336Z</lastUpdatedAt>
      <platform>linux</platform>
      <resourceName>eaAgent</resourceName>
      <stalled>0</stalled>
      <state>running</state>
      <submittedAt>2017-11-16T19:49:18.679Z</submittedAt>
    </cloudJob>
    <cloudJob>
      <id>i-0f0ece89aa7130b8b</id>
      <hostName>ip-172-31-39-146</hostName>
      <lastUpdatedAt>2017-11-16T19:49:42.336Z</lastUpdatedAt>
      <platform>linux</platform>
      <resourceName>eaAgent</resourceName>
      <stalled>0</stalled>
      <state>pending</state>
      <submittedAt>2017-11-16T19:49:42.335Z</submittedAt>
    </cloudJob>
  </response>
</responses>
▼

getCloudProviders

Retrieves a list of all available cloud providers.

Required arguments

None.

Optional arguments

None.

Result tags

A cloudProvider element is returned for each supported provider.

Field Description

cloudProvider

The name of the provider; currently supported providers are ec2, azure, gcp, and kubernetes.

Syntax

cmtool getCloudProviders
▼

Example

cmtool getCloudProviders
▼

Retrieves a list of all available cloud providers.

getResource

Returns full details for the specified resource.

Required arguments

Field Description

resourceId

A unique number that identifies each resource. Use the getResources command to retrieve a list of resource IDs.

Optional arguments

None.

Result tags

Field Description

cloudConfigData

(For cloud resources) A formatted list of fields that describe the resource. The set of fields varies with the type of cloud resource.

Kubernetes resources:

imageName

This is the image that is used by the resource that you specified via the --emake-resource option when invoking eMake to launch the instance.

namespace

The name of the Kubernetes namespace within which the deployed services should be discovered. Defaults to the default namespace.

labels

(Optional) Define and use labels that identify semantic attributes of your application or deployment.

imagePullPolicy

(Optional) The image pull policy and the tag of the image affect when the kubelet attempts to pull the specified image.

Always —the image is pulled every time the pod is started.

If Not Present —the image is pulled only if it is not already present locally.

Never —the image is assumed to exist locally. No attempt is made to pull the image.

Default is Always if :latest label is specified; otherwise, If Not Present. Cannot be updated.

By default, the kubelet tries to pull each image from the specified registry. However, if the Image Pull Policy of the container is set to If Not Present or Never, then a local image is used preferentially or exclusively, respectively.

If you want to rely on pre-pulled images as a substitute for registry authentication, you must ensure all nodes in the cluster have the same pre-pulled images. This can be used to pre-load certain images for speed or as an alternative to authenticating to a private registry.

Microsoft Azure resources:

location

Azure region in which cloud burst agent instances will be launched.

resourceGroupName

Name of the Azure resource group where metadata for the cloud burst agent instances will be stored.

azureImageName

The Azure image name with preinstalled on-demand agent that is used to launch cloud burst instances.

vmSize

Specifies the Azure virtual machine size that defines the memory, CPU, storage capacity, and usage cost for a managed virtual machine.

storageAccountType

The type of storage account for the cloud burst agent virtual machine disk.

virtualNetworkName

The name of the Azure Virtual Network (VNet) where cloud burst agent instances are launched.

Amazon EC2 resources:

ami_name

Amazon EC2 image name that is used to launch cloud burst agent instances.

availability_zone

Distinct location within a region that is insulated from failures in other Availability Zones.

instance_type

Information provided from AWS EC2 specification that defines the memory, CPU, storage capacity, and usage cost for an instance.

keypair_name

Set of security credentials that you use to prove your identity electronically. A key pair consists of a private key and a public key. You use the private key to create a digital signature, and then AWS uses the corresponding public key to validate the signature.

security_group

Named set of allowed inbound network connections for an instance. Security groups in Amazon Virtual Private Cloud (VPC) also include support for outbound connections.

subnet_id

Segment of the IP address range of a VPC that Amazon EC2 instances can be attached to. You can create subnets to group instances according to security and operational needs.

use_spot

If set to true, cloud bursting will launch Amazon EC2 spot instances. If the launch fails for some reason, like MaximumSpotInstanceCountExceeded, the code tries again to launch a regular instance. Possible values are true or false.

Google Cloud Platform (GCP) resources:

image_name

Unique name for the GCP image to be used to create the instance.

machine_type

Type for a particular collection of virtualized hardware resources available to a VM instance, including the system memory size, virtual CPU (vCPU) count, and maximum persistent disk capability.

zone

Deployment area for GCP resources. This is the GCP zone where the cloud burst agents will be started.

disk_type

Type of the node VM boot disk to use to create the instance. Select the most appropriate disk type from the provided list .

network_name

This is the name of the GCP VPC network used to start the cloud burst agents. The cluster manager must have been configured with the selected network. For custom mode GCP VPC networks, the subnetwork must also be specified.

subnet_name

If the GCP VPC network selected was created in custom mode, this is the name of the subnetwork used to start cloud burst agents. The subnetwork must be in the GCP region of the specified zone. For auto mode GCP VPC networks, the value is default.

additional_metadata

Extra (custom) tags to add to the GCP agent instance at launch time. These tags are visible in the instance properties as custom metadata. These are in addition to CB-Name, which is the tag that CloudBees Build Acceleration uses to indicate that it started the instance.

To add extra tags, you set the variable to a comma-separated list of key:value pairs. For example: Name:MyAgent, ProvisionedBy:CB

preemptible

If set to true, cloud bursting will launch GCP preemptible instances which can help save Compute Engine costs. Possible values are true or false.
Field Description

cloudCredentialName

(For cloud resources) Existing credential set that is used for connection to cloud provider. See the getCloudCredentials command for a list of credentials.

cloudIdleTimeout

(For cloud resources) The period of time before idle agents are terminated. When the build finishes, any agents it used are available for use with other builds using the same resource. If no other build uses an agent, that agent becomes idle. If a cloud burst agent is idle for 15 minutes (by default), the instance hosting that agent will be terminated automatically by the Cluster Manager.

cloudInstanceAgents

(For cloud resources) The number of agents installed on the image used to create the instance. This value is used to determine how many instances are launched.

cloudProviderType

(For cloud resources) The cloud provider type. Use the getCloudProviders command for a list of currently supported providers.

hostMasks

(For static hosts) This is a semi-colon delimited list of host name masks, used to identify the list of hosts that support a resource. This field is empty if no static hosts have been configured.

Host name masks follow the same standard globbing rules as Make. (Globbing lets you use a pattern to match one or more files.)

Pattern arguments may contain any of the following special characters:

*—Matches any sequence of zero or more characters

?—Matches any single character

[…​]—Matches a set or range of characters. For example, myhost [1-9] matches the hosts myhost1 ` through `myhost9.

\—Escapes the following characters

matchingAgents

(For static hosts) The number of active agents running on the matching hosts. This comes into play only if the resource configures static hosts.

matchingCloudAgents

(For cloud resources) The number of active agents running on cloud bust hosts. This field is set to zero unless there are agents available from cloud bursting.

matchingCloudHosts

(For cloud resources) The number of cloud burst hosts from the cluster instantiated for this resource. Applicable if the resource configures a cloud provider and it is in use.

matchingHosts

(For static hosts) The number of static hosts from the list of static hosts associated with this resource. Applicable if the resources configures static hosts.

resourceId

A unique number that identifies each resource.

resourceName

This name is used on the eMake parameter: --emake-resource, and can be specified in a build class.

Syntax

cmtool getResource <resourceId>
▼

Example

cmtool getResource 7
▼

Retrieves resource 7.

getResources

Retrieves a list of all resources.

Required arguments

None.

Optional arguments

Field Description

filter

A SQL query used to limit the result set. See the possible values below.

There is a syntax difference between MySQL and Oracle/MS SQL for enclosing criteria when using this argument for specific strings—for MySQL, use double quotes; for Oracle/MS SQL, use single quotes.

maxResults

The maximum number of elements to return from a query.

firstResult

The starting index for the query result set.

This argument takes values beginning with 0. A negative value indicates a record starting from the end of the set, counting backwards, so -1 is the last record, -2 is the next to last, and so on.

order

A SQL order by clause. Used to specify ordering for the query result set.

profile

Set to one of the following: details —returns all information. info —returns a reduced information set.

You must set this argument to details in order to print fields that are part of the details category.

availableResults

This is a count of ’max’ or ’first’ results if --maxResults or --firstResult is specified. SQL query name for --filter and --order: N/A

hostMasks

This is a semi-colon delimited list of host name masks, used to identify the list of hosts that support a resource. “*” is the wildcard character. SQL query name for --filter and --order: host_masks

resourceId

A unique number that identifies each resource. SQL query name for --filter and --order: id

resourceName

This name is used on the eMake parameter: --emake-resource, and can be specified in a build class. SQL query name for --filter and --order: resource_name

Result tags

Field Description

cloudConfigData

(For cloud resources) A formatted list of fields that describe the resource. The set of fields varies with the type of cloud resource.

Kubernetes resources:

imageName

This is the image that is used by the resource that you specified via the --emake-resource option when invoking eMake to launch the instance.

namespace

The name of the Kubernetes namespace within which the deployed services should be discovered. Defaults to the default namespace.

labels

(Optional) Define and use labels that identify semantic attributes of your application or deployment.

imagePullPolicy

(Optional) The image pull policy and the tag of the image affect when the kubelet attempts to pull the specified image.

Always —the image is pulled every time the pod is started.

If Not Present —the image is pulled only if it is not already present locally.

Never —the image is assumed to exist locally. No attempt is made to pull the image.

Default is Always if :latest label is specified; otherwise, If Not Present. Cannot be updated.

By default, the kubelet tries to pull each image from the specified registry. However, if the Image Pull Policy of the container is set to If Not Present or Never, then a local image is used preferentially or exclusively, respectively.

If you want to rely on pre-pulled images as a substitute for registry authentication, you must ensure all nodes in the cluster have the same pre-pulled images. This can be used to pre-load certain images for speed or as an alternative to authenticating to a private registry.

Microsoft Azure resources:

location

Azure region in which cloud burst agent instances will be launched.

resourceGroupName

Name of the Azure resource group where metadata for the cloud burst agent instances will be stored.

azureImageName

The Azure image name with preinstalled on-demand agent that is used to launch cloud burst instances.

vmSize

Specifies the Azure virtual machine size that defines the memory, CPU, storage capacity, and usage cost for a managed virtual machine.

storageAccountType

The type of storage account for the cloud burst agent virtual machine disk.

virtualNetworkName

The name of the Azure Virtual Network (VNet) where cloud burst agent instances are launched.

Amazon EC2 resources:

ami_name

Amazon EC2 image name that is used to launch cloud burst agent instances.

availability_zone

Distinct location within a region that is insulated from failures in other Availability Zones.

instance_type

Information provided from AWS EC2 specification that defines the memory, CPU, storage capacity, and usage cost for an instance.

keypair_name

Set of security credentials that you use to prove your identity electronically. A key pair consists of a private key and a public key. You use the private key to create a digital signature, and then AWS uses the corresponding public key to validate the signature.

security_group

Named set of allowed inbound network connections for an instance. Security groups in Amazon Virtual Private Cloud (VPC) also include support for outbound connections.

subnet_id

Segment of the IP address range of a VPC that Amazon EC2 instances can be attached to. You can create subnets to group instances according to security and operational needs.

use_spot

If set to true, cloud bursting will launch Amazon EC2 spot instances. If the launch fails for some reason, like MaximumSpotInstanceCountExceeded, the code tries again to launch a regular instance. Possible values are true or false.

Google Cloud Platform (GCP) resources:

image_name

Unique name for the GCP image to be used to create the instance.

machine_type

Type for a particular collection of virtualized hardware resources available to a VM instance, including the system memory size, virtual CPU (vCPU) count, and maximum persistent disk capability.

zone

Deployment area for GCP resources. This is the GCP zone where the cloud burst agents will be started.

disk_type

Type of the node VM boot disk to use to create the instance. Select the most appropriate disk type from the provided list .

network_name

This is the name of the GCP VPC network used to start the cloud burst agents. The cluster manager must have been configured with the selected network. For custom mode GCP VPC networks, the subnetwork must also be specified.

subnet_name

If the GCP VPC network selected was created in custom mode, this is the name of the subnetwork used to start cloud burst agents. The subnetwork must be in the GCP region of the specified zone. For auto mode GCP VPC networks, the value is default.

additional_metadata

Extra (custom) tags to add to the GCP agent instance at launch time. These tags are visible in the instance properties as custom metadata. These are in addition to CB-Name, which is the tag that CloudBees Build Acceleration uses to indicate that it started the instance.

To add extra tags, you set the variable to a comma-separated list of key:value pairs. For example: Name:MyAgent, ProvisionedBy:CB

preemptible

If set to true, cloud bursting will launch GCP preemptible instances which can help save Compute Engine costs. Possible values are true or false.
Field Description

cloudCredentialName

(For cloud resources) Existing credential set that is used for connection to cloud provider. See the getCloudCredentials command for a list of credentials.

cloudIdleTimeout

(For cloud resources) The period of time before idle agents are terminated. When the build finishes, any agents it used are available for use with other builds using the same resource. If no other build uses an agent, that agent becomes idle. If a cloud burst agent is idle for 15 minutes (by default), the instance hosting that agent will be terminated automatically by the Cluster Manager.

cloudInstanceAgents

(For cloud resources) The number of agents installed on the image used to create the instance. This value is used to determine how many instances are launched.

cloudProviderType

(For cloud resources) The cloud provider type. Use the getCloudProviders command for a list of currently supported providers.

hostMasks

(For static hosts) This is a semi-colon delimited list of host name masks, used to identify the list of hosts that support a resource. This field is empty if no static hosts have been configured.

Host name masks follow the same standard globbing rules as Make. (Globbing lets you use a pattern to match one or more files.)

Pattern arguments may contain any of the following special characters:

*—Matches any sequence of zero or more characters

?—Matches any single character

[…​]—Matches a set or range of characters. For example, myhost [1-9] matches the hosts myhost1 ` through `myhost9.

\—Escapes the following characters

matchingAgents

(For static hosts) The number of active agents running on the matching hosts. This comes into play only if the resource configures static hosts.

matchingCloudAgents

(For cloud resources) The number of active agents running on cloud bust hosts. This field is set to zero unless there are agents available from cloud bursting.

matchingCloudHosts

(For cloud resources) The number of cloud burst hosts from the cluster instantiated for this resource. Applicable if the resource configures a cloud provider and it is in use.

matchingHosts

(For static hosts) The number of static hosts from the list of static hosts associated with this resource. Applicable if the resources configures static hosts.

resourceId

A unique number that identifies each resource.

resourceName

This name is used on the eMake parameter: --emake-resource, and can be specified in a build class.

Syntax

cmtool getResources [optionals...]
▼

Example

cmtool getResources --order resource_name
▼

Retrieves a list of resources ordered by the resource name.

getResourceComments

Retrieves resource comments.

Required arguments

Field Description

resourceId

A unique that identifies each resource.

Optional arguments

Field Description

commentId

A unique key that identifies a comment.

Syntax

cmtool getResourceComments <resourceId> [optionals...]
▼

Example

cmtool getResourceComments 29
▼

Retrieves comments for resource 29.

modifyAgentComment

Modifies an agent comment.

Required arguments

Either agentId or agentName must also be specified.
Field Description

commentId

A unique key that identifies a comment.

text

The comment text.

Optional arguments

Field Description

agentId

Unique, internal number that can change; assigned by the Cluster Manager.

agentName

Name defined by the host where the agent resides (numbers and/or letters).

Syntax

cmtool modifyAgentComment <commentId> <text> [optionals...]
▼

Example

cmtool modifyAgentComment 1037 "changed comment" --agentName SOL1-1
▼

Changes comment number 1037 on agent SOL1-1 to “changed comment”.

modifyCloudCredential

Modifies an existing cloud credential definition.

Required arguments

Field Description

cloudCredentialID

The system-assigned Id for this credential. Use the getCloudCredentials command for a list of credential Ids.

Optional arguments

Field Description

description

A user-defined description for this credential.

cloudCredentialName

The name of the credential.

cloudProviderType

The cloud provider type. Use the getCloudProviders command for a list of currently supported providers.

cloudCredentialData

A formatted JSON list of fields that describes this credential. The set of fields varies with the type of cloud resource:

|Field |Description

2+|Kubernetes credentials:

|token |Image that is used by the resource that you specified via the --emake-resource option when invoking eMake to launch the instance.

|endpoint |Name of the Kubernetes namespace within which the deployed services should be discovered. Defaults to the default namespace.

2+|Microsoft Azure credentials:

|tenantId |The tenant ID (GUID) from the Azure active directory.

|subscriptionID |The subscription ID (GUID), which is a unique alphanumeric string identifying your Azure subscription.

|clientID |The Application ID (GUID) from the Azure application.

|clientSecret |The secret key (GUID) created from the client ID for the Azure application.

2+|Amazon EC2 credentials:

|access_key_id |Unique identifier that is associated with a secret_access_key. The access key ID and the secret access key are used together to sign programmatic AWS requests cryptographically.

|secret_access_key |Used in conjunction with the access_key_id to cryptographically sign programmatic AWS requests. Signing a request identifies the sender and prevents request alteration. You can generate secret access keys for your AWS account, individual IAM users, and temporary sessions.

|server_iam_role |Used if you are using the Cluster Manager server IAM role instead of the access_key_id and secret_access_key to cryptographically sign programmatic AWS requests.

You must set up the appropriate permissions for the IAM role. For the list of required permissions, see see Configuring Amazon EC2 for Agent Cloud Bursting - Setting Up a Server IAM Role.

|region |Named set of AWS resources in the same geographical area. A region comprises at least two Availability Zones.

2+|Google Cloud Platform (GCP) credentials:

|<GCP Credential>

| * If specifying a credential using a service account, use the contents of the service account file as the value specified with cloudCredentialData.

+ The service account file is a JSON file generated by creating a key for a service account in the Google Cloud Platform Console.

  • If specifying the credential as the service account that was used to start the instance where the Cluster Manager is running, specify the literal string: {"credential_provider" : "Server_IAM_Role"}.

Syntax

cmtool modifyCloudCredential <cloudCredentialId> [optionals...]
▼

Example

cmtool modifyCloudCredential 1 --description "New description"
▼

Modifies a cloud credential with an ID of 1.

modifyResource

Modifies a resource definition.

Required arguments

Field Description

resourceId

A unique number that identifies each resource.

Optional arguments

Field Description

cloudConfigData

(For cloud resources) A formatted list of fields that describe the resource. The set of fields varies with the type of cloud resource.

Kubernetes resources:

imageName

This is the image that is used by the resource that you specified via the --emake-resource option when invoking eMake to launch the instance.

namespace

The name of the Kubernetes namespace within which the deployed services should be discovered. Defaults to the default namespace.

labels

(Optional) Define and use labels that identify semantic attributes of your application or deployment.

imagePullPolicy

(Optional) The image pull policy and the tag of the image affect when the kubelet attempts to pull the specified image.

Always —the image is pulled every time the pod is started.

If Not Present —the image is pulled only if it is not already present locally.

Never —the image is assumed to exist locally. No attempt is made to pull the image.

Default is Always if :latest label is specified; otherwise, If Not Present. Cannot be updated.

By default, the kubelet tries to pull each image from the specified registry. However, if the Image Pull Policy of the container is set to If Not Present or Never, then a local image is used preferentially or exclusively, respectively.

If you want to rely on pre-pulled images as a substitute for registry authentication, you must ensure all nodes in the cluster have the same pre-pulled images. This can be used to pre-load certain images for speed or as an alternative to authenticating to a private registry.

Microsoft Azure resources:

location

Azure region in which cloud burst agent instances will be launched.

resourceGroupName

Name of the Azure resource group where metadata for the cloud burst agent instances will be stored.

azureImageName

The Azure image name with preinstalled on-demand agent that is used to launch cloud burst instances.

vmSize

Specifies the Azure virtual machine size that defines the memory, CPU, storage capacity, and usage cost for a managed virtual machine.

storageAccountType

The type of storage account for the cloud burst agent virtual machine disk.

virtualNetworkName

The name of the Azure Virtual Network (VNet) where cloud burst agent instances are launched.

Amazon EC2 resources:

ami_name

Amazon EC2 image name that is used to launch cloud burst agent instances.

availability_zone

Distinct location within a region that is insulated from failures in other Availability Zones.

instance_type

Information provided from AWS EC2 specification that defines the memory, CPU, storage capacity, and usage cost for an instance.

keypair_name

Set of security credentials that you use to prove your identity electronically. A key pair consists of a private key and a public key. You use the private key to create a digital signature, and then AWS uses the corresponding public key to validate the signature.

security_group

Named set of allowed inbound network connections for an instance. Security groups in Amazon Virtual Private Cloud (VPC) also include support for outbound connections.

subnet_id

Segment of the IP address range of a VPC that Amazon EC2 instances can be attached to. You can create subnets to group instances according to security and operational needs.

use_spot

If set to true, cloud bursting will launch Amazon EC2 spot instances. If the launch fails for some reason, like MaximumSpotInstanceCountExceeded, the code tries again to launch a regular instance. Possible values are true or false.

Google Cloud Platform (GCP) resources:

image_name

Unique name for the GCP image to be used to create the instance.

machine_type

Type for a particular collection of virtualized hardware resources available to a VM instance, including the system memory size, virtual CPU (vCPU) count, and maximum persistent disk capability.

zone

Deployment area for GCP resources. This is the GCP zone where the cloud burst agents will be started.

disk_type

Type of the node VM boot disk to use to create the instance. Select the most appropriate disk type from the provided list .

network_name

This is the name of the GCP VPC network used to start the cloud burst agents. The cluster manager must have been configured with the selected network. For custom mode GCP VPC networks, the subnetwork must also be specified.

subnet_name

If the GCP VPC network selected was created in custom mode, this is the name of the subnetwork used to start cloud burst agents. The subnetwork must be in the GCP region of the specified zone. For auto mode GCP VPC networks, the value is default.

additional_metadata

Extra (custom) tags to add to the GCP agent instance at launch time. These tags are visible in the instance properties as custom metadata. These are in addition to CB-Name, which is the tag that CloudBees Build Acceleration uses to indicate that it started the instance.

To add extra tags, you set the variable to a comma-separated list of key:value pairs. For example: Name:MyAgent, ProvisionedBy:CB

preemptible

If set to true, cloud bursting will launch GCP preemptible instances which can help save Compute Engine costs. Possible values are true or false.
Field Description

cloudIdleTimeout

(For cloud resources) The period of time before idle agents are terminated. When the build finishes, any agents it used are available for use with other builds using the same resource. If no other build uses an agent, that agent becomes idle. If a cloud burst agent is idle for 15 minutes (by default), the instance hosting that agent will be terminated automatically by the Cluster Manager.

cloudInstanceAgents

(For cloud resources) The number of agents installed on the image used to create the instance. This value is used to determine how many instances are launched.

cloudProviderType

(For cloud resources) The cloud provider type. Use the getCloudProviders command for a list of currently supported providers.

cloudCredential

(For cloud resources) The name of an existing credential set that is used for connection to cloud provider. Use the getCloudCredentials command for a list of credentials.

description

A user-defined description for this resource.

hostMasks

(For static resources) This is a semi-colon delimited list of host name masks, used to identify the list of hosts that support a resource. This field is empty if no static hosts have been configured.

Host name masks follow the same standard globbing rules as Make. (Globbing lets you use a pattern to match one or more files.)

Pattern arguments may contain any of the following special characters:

*—Matches any sequence of zero or more characters

?—Matches any single character

[…​]—Matches a set or range of characters. For example, myhost [1-9] matches the hosts myhost1 through myhost9.

\—Escapes the following characters

resourceName

Unique name for the resource definition. The name can contain numbers and letters.

This is also the name that you specify in the --emake-resource=resourcename command, in the build class’ Resource Request field (on the web interface), or or as the environment variable EMAKE_RESOURCE.

You cannot edit the name of the default resource.

Syntax

cmtool modifyResource <resourceId> [optionals...]
▼

Example

cmtool modifyResource 27 --hostMasks "SOL*; SRL*"
▼

Sets the host masks for resource 27 to “SOL*; SRL*”.

modifyResourceComment

Modifies a resource comment. Use the getResources command to retrieve a list of resource IDs.

Required arguments

Field Description

resourceId

A unique number that identifies each resource.

commentId

A unique key that identifies a comment.

text

The comment text.

Optional arguments

None.

Syntax

cmtool modifyResourceComment <resourceId> <commentId> <text>
▼

Example

cmtool modifyResourceComment 1 1015 "new test resource"
▼

Changes comment 1015 for resource 1.

setAgentDebug

Sets the agent debug level (see the getAgentStatus command). This command sends a message to the agent(s) in real time; therefore, the agents must be up and connected to the Cluster Manager to have any effect.

Required arguments

Field Description

level

The debug level value. Can be: all commands environment fileinfo log other profile registry requests state test usage nothing.

Optional arguments

Field Description

agentId

Unique, internal number that can change; assigned by the Cluster Manager.

agentName

Name defined by the host where the agent resides (numbers and/or letters).

status

Can be 1 or 0. Choose active or inactive agents only.

buildId

Further restricts the returned agents to those running a specific build ID.

enabled

Can be 1 or 0. Choose enabled or disabled agents only.

agents

Specifies individual agents based on their host name and listening port using this format: <host>[:<port>[:<agentKey>]]

Result tags

Field Description

agentName

The name of the configured agent.

result

The configuration result.

Syntax

cmtool setAgentDebug <level> [optionals...]
▼

Example

cmtool setAgentDebug profile --agentName SOLAgent-4
▼

Sets SOLAgent-4’s debug level to “profile”.

Build Management API