Agent Management API reference

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

enabled

Description: Possible values are true or false.

Optional Arguments

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

agentId

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

agentName

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

filter

Description: 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.

text

Description: The comment text.

Optional Arguments

agentId

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

agentName

Description: 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

cloudCredentialName

Description: The user-defined name for this credential.

cloudProviderType

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

cloudCredentialData

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

EC2 credentials:

access_key_id

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

region

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

Kubernetes credentials:

token

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.

endpoint

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

Optional Arguments

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

resourceName

Description: 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’s Resource Request field (on the web interface), or or as the environment variable EMAKE_RESOURCE.

Optional Arguments

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

EC2:

ami_name

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

Kubernetes:

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.

cloudIdleTimeout

Description: (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

Description: (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

Description: (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

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

description

Description: A user-defined description for this resource.

hostMasks

Description: (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 Kubernetes cloud resource named myK8S (line breaks added for readability).

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

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

createResourceComment

Creates a new resource comment.

Required Arguments

resourceId

Description: A unique number that identifies each resource.

text

Description: 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.

commentId

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

Optional Arguments

agentId

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

agentName

Description: 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 getAgentComments 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

agentId

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

agentName

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

filter

Description: 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

cloudCredentialId

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

Optional Arguments

None

Syntax

cmtool deleteCloudCredential <cloudCredentialId>

Example

cmtool deleteCloudCredential 1

Deletes a cloud credentialwith `cloudCredentialId ` 3.

deleteCloudCredentials

Deletes a set of cloud credentials.

Required Arguments

None

Optional Arguments

filter

Description: 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

resourceId

Description: 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

filter

Description: 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

resourceId

Description: A unique number that identifies each resource.

commentId

Description: 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

agentId

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

agentName

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

Result Tags

commentId

Description: The unique key that identifies a comment.

createTime

Description: The time when the item was created.

lastModifiedBy

Description: The user who last modified the item.

modifyTime

Description: The time when the item was last modified.

text

Description: 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

agentId

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

agentName

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

agents

Description: A list of agents whose performance you want to see.

buildId

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

status

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

enabled

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

Result Tags

agentName

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

result

Description: 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

agentId

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

agentName

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

filter

Description: 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

Description: The maximum number of elements to return from a query.

firstResult

Description: 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

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

profile

Description: 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

a2aPort

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

agentId

Description: 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

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

agentVersion

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

availableResults

Description: 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

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

buildName

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

consolePort

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

efsVersion

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

enabled

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

errorCount

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

hostName

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

inPenaltyBox

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

ipAddress

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

lastErrorTime

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

lastPingTime

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

platform

Description: 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

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

restartCount

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

status

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

statusDetail

Description: 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

Description: 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

agentId

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

agentName

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

agents

Description: A list of agents whose status you want to see.

buildId

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

status

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

enabled

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

Result Tags

agentName

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

result

Description: 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

cloudCredentialId

Description: 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

cloudCredentialId

Description: 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

Description: The user-defined name for this credential.

cloudProviderType

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

cloudCredentialData

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

EC2 credentials:

access_key_id

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

region

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

Kubernetes credentials:

token

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.

endpoint

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

description

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

filter

Description: 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

Description: The maximum number of elements to return from a query.

firstResult

Description: 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

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

profile

Description: 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.

cloudCredentialId

Description: The credential Id assigned by the system at create time.

cloudCredentialName

Description: The user-defined name for this credential.

cloudProviderType

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

cloudCredentialData

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

EC2 credentials:

access_key_id

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

region

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

Kubernetes credentials:

token

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.

endpoint

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

description

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 or Kubernetes) that is in use.

Required Arguments

None

Optional Arguments

None

Result Tags

cloudHostManagerStatus

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

lastMessage

Description: Displays the latest message in the list of available messages.

Message

Description: 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

cloudJob

Description: Cloud provider instance ID.

id

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

hostName

Description: Cloud host where the agents reside.

lastUpdated

Description: Time when the status was retrieved.

platform

Description: Platform of the host where the agents reside.

resourceName

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

stalled

Description: Indicates if the job is stalled.

state

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

submittedAt

Description: 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.

cloudProvider

Description: The name of the provider; currently supported providers are ec2 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

resourceId

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

Optional Arguments

None

Result Tags

cloudConfigData

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

EC2:

ami_name

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

Kubernetes:

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.

cloudCredentialName

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

cloudIdleTimeout

Description: (For cloud resources) The period of time before idle agents are terminated. After their corresponding cluster resource is done being used, agents become idle and available for a subsequent build. If a new build starts using that resource during idle timeout, idle instances are used and new instances are provisioned if needed.

cloudInstanceAgents

Description: (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

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

hostMasks

Description: (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

Description: (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

Description: (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

Description: (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

Description: (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

Description: A unique number that identifies each resource.

resourceName

Description: 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

filter

Description: 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

Description: The maximum number of elements to return from a query.

firstResult

Description: 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

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

profile

Description: 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

Description: 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

Description: 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

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

resourceName

Description: 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

cloudConfigData

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

EC2:

ami_name

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

Kubernetes:

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.

cloudCredentialName

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

cloudIdleTimeout

Description: (For cloud resources) The period of time before idle agents are terminated. After their corresponding cluster resource is done being used, agents become idle and available for a subsequent build. If a new build starts using that resource during idle timeout, idle instances are used and new instances are provisioned if needed.

cloudInstanceAgents

Description: (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

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

hostMasks

Description: (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

Description: (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

Description: (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

Description: (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

Description: (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

Description: A unique number that identifies each resource.

resourceName

Description: 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

resourceId

Description: A unique that identifies each resource.

Optional Arguments

commentId

Description: 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.

commentId

Description: A unique key that identifies a comment.

text

Description: The comment text.

Optional Arguments

agentId

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

agentName

Description: 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

cloudCredentialID

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

Optional Arguments

description

Description: A user-defined description for this credential.

cloudCredentialName

Description: The name of the credential.

cloudProviderType

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

cloudCredentialData

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

EC2 credentials:

access_key_id

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

region

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

Kubernetes credentials:

token

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.

endpoint

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

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

resourceId

Description: A unique number that identifies each resource.

Optional Arguments

cloudConfigData

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

EC2:

ami_name

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

Kubernetes:

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.

cloudIdleTimeout

Description: (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

Description: (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

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

cloudCredential

Description: (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

Description: A user-defined description for this resource.

hostMasks

Description: (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

Description: 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

resourceId

Description: A unique number that identifies each resource.

commentId

Description: A unique key that identifies a comment.

text

Description: 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

level

Description: The debug level value. Can be:

all commands environment fileinfo log other profile

registry requests state test usage nothing

Optional Arguments

agentId

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

agentName

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

status

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

buildId

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

enabled

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

agents

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

Result Tags

agentName

Description: The name of the configured agent.

result

Description: The configuration result.

Syntax

cmtool setAgentDebug <level> [optionals...]

Example

cmtool setAgentDebug profile --agentName SOLAgent-4

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