Install remote agents using the API

Use the CloudBees CD/RO API to install remote agents. This process uses the underlying CloudBees CD/RO Centralized Agent Management (CAM) functionality.

You can automate remote installations by using scripts that call the following CloudBees CD/RO APIs. These APIs provide the same remote installation capability as the web interface.

Parameters for Running the Procedure to Publish an Installer to the Artifact Repository

The Publish Installer procedure is used to publish a CloudBees CD/RO installer to the artifact repository. The parameters for the Publish Installer procedure appear below. These parameters have equivalent options in the web interface.

Parameter	Description
fromDir	Directory where the installer is located. Only the installer itself will be published.
platform	Platform of the installer. The possible values are Linux_x86, Linux_x64, Windows_x86, Windows_x64.
repository	CloudBees CD/RO repository server where the installer will be published.
resource	Resource used by the publishing procedure.
version	Version of the installer. Use the format <major> . <minor> . <patch> . <build> . Because the build number changes with every build of the corresponding plugin, you should check this number often and update it if needed.

Parameter

Description

fromDir

Directory where the installer is located. Only the installer itself will be published.

platform

Platform of the installer. The possible values are Linux_x86, Linux_x64, Windows_x86, Windows_x64.

repository

CloudBees CD/RO repository server where the installer will be published.

resource

Resource used by the publishing procedure.

version

Version of the installer. Use the format <major> . <minor> . <patch> . <build> . Because the build number changes with every build of the corresponding plugin, you should check this number often and update it if needed.

Parameters for Running the Procedure to Perform the Installations

A top-level wrapper procedure named Centralized Agent Management is used for installer publishing. This procedure calls the Install Agent procedure to publish installers to the repository.

The parameters for the Centralized Agent Management procedure appear below. Most of these parameters have equivalent options in the web interface.

Parameter Windows Support Other Platform Support Description

Installation or Upgrade Parameters Based on Platform and Target Host

isUpgrade

Yes

Specifies whether you are installing agents or upgrading existing agents. Use 0 if installing agents and 1 if upgrading agents.

resources

Yes

(Upgrades only) Space-delimited list of resources to upgrade. The resources should belong to the same platform (such as Windows or Linux) and the same zone.

hostnames

Yes

(Installations only) List of hostnames or IP addresses on which to install the agent. You can delimit the host names or IP addresses by using any combination of spaces, commas, semicolons, or newlines. Host names cannot contain spaces.The hosts should belong to the same platform and the same network.

IPv6 addresses are only supported for Kubernetes platforms. If using an IPv6 address, enclose the address in square brackets. Example: [<IPv6-ADDRESS>].

zoneName

Yes

CloudBees CD/RO zone in which the agents will be installed or upgraded.

drivingResource

Yes

Existing resource within the selected zone that will be used to perform all proxy commands for installing or upgrading the target hosts. The driving resource must belong to the same platform and the same zone as the hosts.

resourceNameTemplate

Yes

(Installations only) String templates. Used for naming the resources in CloudBees CD/RO for the corresponding installation target hosts. The special tokens {name}, {counter}, and {shortname} can be used as place holders for the host name and for incrementing counters in the template value. For example, {name}-Win-{counter}.

version

Yes

Version of the agent previously published to the repository server to use. For example, 7.0.0.110954.

platform

Yes

Platform of the resources being upgraded or installed. The possible values are Linux_x86, Linux_x64, Windows_x86, or Windows_x64.

Connection Parameters for Communicating With the Target Hosts

connectionType

Yes

Type of authentication to use when connecting to the target machines. Use WINDOWS when installing or upgrading resources on Windows. Otherwise, use either SSH_PASSWORD or SSH_KEY depending on whether the SSH user name and password will be used or an SSH key will be used.

connectionCredential

Yes

Connection credentials based on the type of authentication used for connecting to the target hosts. Use the user account name and password if connectionType is WINDOWS or SSH_USER. Use the user name and SSH key passphrase if connectionType is SSH_KEY.

connectionDomain

Yes

–

(Windows platforms only) Name of the windows domain for the specified user account.

connectionPublicKey

–

Yes

Path to the SSH public key file on the driving resource.

connectionPrivateKey

–

Yes

Path to the SSH private key file on the driving resource.

Agent Configuration Parameters for Installing Agents on Target Hosts

(There are additional parameters for agent configuration that are not listed here. To specify additional agent configuration parameters, use the Additional Parameters field as described above.)

agentPort

Yes

(Installations only) Port that will be used by the agents installed on the target hosts. The default is 7800.

installDirectory

Yes

(Installations only) Path to the installation directory on the target hosts.

dataDirectory

Yes

(Installations only) Path to the data directory on the target hosts.

agentWorkspaceName

Yes

(Installations only) Name of the workspace that will be used by the agents installed on the target hosts.

agentCredential

Yes

(Installations only) Password for the user account that the installed agent service should run as. (This is not applicable if you are using LocalSystem as the agent user on Windows.)

agentDomain

Yes

–

(Installations only) Windows domain name for the agent user, if the user account belongs to a domain.

trustedAgent

Yes

(Installations only) Specifies whether the agent will be installed as a trusted agent. A trusted agent is "certificate verified," which means that the agent verifies the server or upstream agent’s certificate. If this is set to 1, the agent will be installed as a trusted agent. For more information, see the “Switching a Non-Trusted Agent to Trusted” section in Create and manage resources.

agentGroup

–

Yes

(Installations only) Group of the user account that the installed agent service should run as.

hostType

Yes

(Installations only) Host type when the service is licensed for both concurrent and registered agent hosts. Specify CONCURRENT to install concurrent host agents. Specify REGISTERED to install registered host agents.

additionalParameters

Yes

Specifies additional agent configuration parameters.

Do not use this parameter to specify agent configuration parameters (listed above) in conjunction with their equivalent arguments in the standard agent installer. Doing so might cause unpredictable behavior. For example, do not use ectool runProcedure EC-AgentManagement-1.2.0.111083 --procedureName "Centralized Agent Management" --actualParameter "additionalParameters=--agentPort 7800". Instead, use ectool runProcedure EC-AgentManagement-1.2.0.111083 --procedureName "Centralized Agent Management" --actualParameter "agentPort=7800". For a complete list of agent installer arguments, see Silent Install Arguments .

Post-Installation Parameters

postStepProjectName

Yes

Name of the project that contains the procedure to run as a post-installation step on each of the just-installed or upgraded resources.

postStepProcedureName

Yes

Name of the procedure to run as a post-installation step on each of the just-installed or upgraded resources.

postStepParameters

Yes

Parameters in JSON format. You must escape special characters that are not supported by JSON.

Examples for Publishing a CloudBees CD/RO Installer to the Artifact Repository

As mentioned above, Publish Installer is a procedure used to publish a CloudBees CD/RO installer to the artifact repository.

The cb-perl and DSL scripts below contain commands for using the promoted plugin version without hard-coding the version.

cb-perl Example

use strict;
use ElectricCommander;
my $ec = new ElectricCommander();
my $xpath      = $ec->getPlugin("EC-AgentManagement");
my $pluginProject = $xpath->findvalue('//projectName')->value;
my $jobId = $ec->runProcedure($pluginProject, {
    procedureName => "Publish Installer",
    actualParameter => [
        {
        actualParameterName => 'fromDir',
        value => '/home/build'
        },
        {
        actualParameterName => 'platform',
        value => 'Linux_x64'
        },
        {
        actualParameterName => 'repository',
        value => 'default'
        },
        {
        actualParameterName => 'resource',
        value => 'local'
        },
        {
        actualParameterName => 'version',
        value => '7.0.0.110576'
        }
    ]
})->findvalue('//jobId')->value();
print "jobId is: $jobId";▼

ectool Example

ectool runProcedure EC-AgentManagement-1.2.0.111083 --procedureName "Publish Installer"
--actualParameter "fromDir=/home/build"
--actualParameter "platform=Linux_x86"
--actualParameter "repository=default"
--actualParameter "resource=local"
--actualParameter "version=7.0.0.110576"▼

DSL Example

ectool evalDsl "
def pluginProject = getPlugin(pluginName: 'EC-AgentManagement').projectName;
runProcedure(pluginProject, procedureName: 'Publish Installer',
    actualParameter: [
        fromDir:    '/home/build',
        platform:   'Linux_x86',
        repository: 'default',
        resource:   'local',
        version:    '7.0.0.110576'
    ]
)"▼

Examples for Installing Remote Agents

As mentioned above, Centralized Agent Management is a top-level wrapper procedure that calls the Install Agent procedure for installing or upgrading individual agents on the agent hosts. Note that the DSL scripts below contain commands for using the promoted plugin version without hard-coding the version.

ectool Example (Linux)

IPv6 addresses are only supported for Kubernetes platforms. If using an IPv6 address, enclose the address in square brackets. Example: [<IPv6-ADDRESS>].

ectool runProcedure EC-AgentManagement-1.2.0.111083 --procedureName "Centralized Agent Management"
--actualParameter "isUpgrade=0"
--actualParameter "platform=Linux_x64"
--actualParameter "version=7.0.0.110954"
--actualParameter "zoneName=default"
--actualParameter "hostnames=192.168.4.208 192.168.4.210"
--actualParameter "drivingResource=local"
--actualParameter "resourceNameTemplate=prefix-{counter}"

--actualParameter "agentCredential=agentCredential"
--actualParameter "agentGroup=remote"
--actualParameter "agentPort=7800"

--actualParameter "trustedAgent=0"
--actualParameter "hostType=CONCURRENT"

--actualParameter "connectionType=SSH_PASSWORD"
--actualParameter "connectionCredential=connectionCredential"

--credential connectionCredential=remote
--credential agentCredential=remote▼

ectool Example (Linux with Post-Installation Procedure)

IPv6 addresses are only supported for Kubernetes platforms. If using an IPv6 address, enclose the address in square brackets. Example: [<IPv6-ADDRESS>].

ectool runProcedure EC-AgentManagement-1.3.0.0 --procedureName "Centralized Agent Management" \
--actualParameter "isUpgrade=0" \
--actualParameter "platform=Linux_x64" \
--actualParameter "version=7.0.0.111324" \
--actualParameter "zoneName=default" \
--actualParameter "hostnames=10.200.1.109" \
--actualParameter "drivingResource=local" \
--actualParameter "resourceNameTemplate=prefix-{counter}" \
--actualParameter "agentCredential=agentCredential" \
--actualParameter "agentGroup=vagrant" \
--actualParameter "agentPort=7800" \
--actualParameter "trustedAgent=0" \
--actualParameter "hostType=CONCURRENT" \
--actualParameter "connectionType=SSH_PASSWORD" \
--actualParameter "connectionCredential=connectionCredential" \
--actualParameter "postStepProcedureName=postinstall" \
--actualParameter "postStepProjectName=postinstall" \
--actualParameter "postStepParameters={\"another_resource\": \"local\",\"checkbox\":
\"true\",\"credential\": \"\",\"dropdown\": \"option3\",\"project\": \"Default\",
\"radio\": \"option3\",\"required1\": \"required1\",\"saved_filter\":
\"/projects/EC-Examples/ec_savedSearches/Test Outcome Filter\",\"textarea\":
\"Lorem ipsum amet\ntempor incididunt \nquis nostrud\nconsequat.\"}" \
--credential connectionCredential=vagrant \
--credential agentCredential=vagrant▼

ectool Example (Windows)

IPv6 addresses are only supported for Kubernetes platforms. If using an IPv6 address, enclose the address in square brackets. Example: [<IPv6-ADDRESS>].

ectool runProcedure EC-AgentManagement-1.2.0.111083 --procedureName "Centralized Agent Management"
--actualParameter "isUpgrade=0"
--actualParameter "platform=Windows_x64"
--actualParameter "version=7.0.0.110954"
--actualParameter "zoneName=default"
--actualParameter "hostnames=10.1.216.227"
--actualParameter "drivingResource=3EC-IT-3614"
--actualParameter "resourceNameTemplate={name}"

--actualParameter "connectionDomain=electric-cloud"
--actualParameter "agentCredential=agentCredential"
--actualParameter "agentPort=7800"

--actualParameter "trustedAgent=0"
--actualParameter "hostType=CONCURRENT"

--actualParameter "connectionType=WINDOWS"
--actualParameter "connectionCredential=connectionCredential"

--credential connectionCredential=remote
--credential agentCredential=remote▼

DSL Example (Linux)

In the following example, agentGroup is the group for the Linux user to connect to the remote machines.

IPv6 addresses are only supported for Kubernetes platforms. If using an IPv6 address, enclose the address in square brackets. Example: [<IPv6-ADDRESS>].

ectool evalDsl "
def pluginProject = getPlugin(pluginName: 'EC-AgentManagement').projectName;
runProcedure(pluginProject, procedureName: 'Publish Installer',
    actualParameter: [
        isUpgrade: '0',
        platform: 'Linux_x64',
        version: '7.0.0.110954',
        zoneName: 'default',hostnames: '192.168.4.210',
        drivingResource: 'local',
        resourceNameTemplate: 'prefix-{counter}',

        agentCredential: 'agentCredential',
        agentGroup: 'remote',
        agentPort: '7800',

        trustedAgent: '0',
        hostType: 'CONCURRENT',

        connectionType: 'SSH_PASSWORD',
        connectionCredential: 'connectionCredential'

    ],
    credential: [
        [
            credentialName: 'connectionCredential',
            userName: 'remote',
            password: ''Rem0te2''
        ],
        [
            credentialName: 'agentCredential',
            userName: 'remote',
            password: ''Rem0te3''
        ]
    ]
)"▼

DSL Example (Linux with Post-Installation Procedure)

IPv6 addresses are only supported for Kubernetes platforms. If using an IPv6 address, enclose the address in square brackets. Example: [<IPv6-ADDRESS>].

ectool evalDsl "
def pluginProject = getPlugin(pluginName: 'EC-AgentManagement').projectName;
runProcedure(pluginProject, procedureName: 'Centralized Agent Management',
    actualParameter: [
        isUpgrade: '0',
        platform: 'Linux_x64',
        version: '7.0.0.111324',
        zoneName: 'custom',
        hostnames: '10.200.1.109',
        drivingResource: 'local',
        resourceNameTemplate: '{shortname}-{name}-{counter} ',

        agentCredential: 'agentCredential',
        agentGroup: 'vagrant',
        agentPort: '7800',

        trustedAgent: '0',
        hostType: 'CONCURRENT',

        connectionType: 'SSH_PASSWORD',
        connectionCredential: 'connectionCredential',

        postStepProcedureName: 'postinstall',
        postStepProjectName: 'postinstall',
        postStepParameters: '{"another_resource": "local","checkbox":
"true","credential": "","dropdown": "option3","project": "Default",
"radio": "option3","required1": "required1","required2": "req2",
"saved_filter": "/projects/EC-Examples/ec_savedSearches/Test Outcome
Filter","textarea": "Lorem ipsum amet\ntempor incididunt \nquis
nostrud\ nconsequat."}'
    ],
    credential: [
        [
            credentialName: 'connectionCredential',
            userName: 'remote',
            password: 'remote4'
        ],
        [
            credentialName: 'agentCredential',
            userName: 'remote',
            password: 'remote5'
        ]
    ]
)"▼

DSL Example (Windows)

In the following example, connectionDomain is the Windows domain for the Windows user to connect to the remote machines.

IPv6 addresses are only supported for Kubernetes platforms. If using an IPv6 address, enclose the address in square brackets. Example: [<IPv6-ADDRESS>].

ectool evalDsl "
def pluginProject = getPlugin(pluginName: 'EC-AgentManagement').projectName;
runProcedure(pluginProject, procedureName: 'Publish Installer',
    actualParameter: [
        isUpgrade: '0',
        platform: 'Windows_x64',
        version: '7.0.0.110954',
        zoneName: 'default',
        hostnames: '10.1.216.235',
        drivingResource: '10.1.216.227',
        resourceNameTemplate: '{name}',

        connectionDomain: 'electric-cloud',
        agentCredential: 'agentCredential',
        agentPort: '7800',

        trustedAgent: '0',
        hostType: 'CONCURRENT',

        connectionType: 'WINDOWS',
        connectionCredential: 'connectionCredential'
    ],
    credential: [
        [
            credentialName: 'connectionCredential',
            userName: 'remote',
         password: ''Rem0te6''
        ],
        [
            credentialName: 'agentCredential',
            userName: 'remote',
            password: ''Rem0te7''
        ]
    ]
)"▼