Upgrade remote agents

You can install or upgrade remote hosts that are running Linux (x86 or x64), Windows (x86 or x64), or macOS. The installation or upgrade processes take advantage of the underlying CloudBees CD/RO Centralized Agent Management (CAM) feature, which significantly simplifies distribution of new agents and reduces the administrative cost of upgrading CloudBees CD/RO to newer versions.

After upgrading from CloudBees CD/RO 10.8 or an earlier version, delete all .old files, such as .properties.old in the conf subdirectory to finish the encryption process.

Permissions for upgrading remote agents

The following table describes the user permissions required to install or upgrade remote agents. For information about modifying permissions, refer to Access control.

Allowed action Object Required privilege ("allow")

Allowed action	Object	Required privilege ("allow")
Install a resource in a zone	The “Resources” system object	Read
Modify
Execute
Zone (such as `US1`)	Read
Modify
Upgrade a resource	Resource (such as `ResourceA`)	Read
Modify
Execute

Install a resource in a zone

The “Resources” system object

Read

Modify

Execute

Zone (such as US1)

Read

Modify

Upgrade a resource

Resource (such as ResourceA)

Read

Modify

Execute

Upgrading remote agents using the web interface

This section describes how to use the CloudBees CD/RO web interface to upgrade remote agents. This process uses the underlying CloudBees CD/RO centralized agent management (CAM) functionality.

Agents installed by root or using sudo can be upgraded only by root or using sudo. Similarly, you cannot use non-root installation mode (--nonRoot) to upgrade agents unless they were originally installed using non-root installation mode.

In the Cloud>Resources page of the Automation Platform, select the resources that you want to upgrade on agent hosts.

To upgrade resources via CAM, the resource must be up and enabled because the CAM upgrade job acquires an exclusive lock on this resource (with the help of running a special job step) to prevent it from being used by other jobs.

If the selected resources have different platforms or zones, an error prompt displays:

Resources belonging to different platforms and zones cannot be upgraded at the same time. Please select resources belonging to the same platform and the same zone.▼

If any selected resource is a proxy resource, an error prompt displays:

Proxy resources are not supported for upgrade. Select the resources acting as proxy agents directly for upgrade.▼

If any selected resource is not a proxy resource but shows up in the filter results with Proxy Agent as Yes, check if the output of ectool getResource for the resource has a proxyHostName value.

If it has a non-empty proxyHostName element, you can delete and recreate the resource to avoid the following error message during upgrade.

Resource [ResourceName] is not available for upgrade.▼

Select the Add Upgrade Resource(s). The Upgrade Resources dialog displays.

If the Upgrade Resource(s) menu option is not visible, you must sign out and then sign in as a user with the required permissions. For details about required permissions, refer to Permissions to install or upgrade remote agents.

Either one or two platforms for the selected resource are listed. Two platforms are listed if the platform, such as Linux x86 or Linux x64, could not be determined.

Choose the platform and published version, select the appropriate Re-Publish Installer link, and then select Next. The Run Procedure/Publish Installer page opens.
Enter the following information:
- Required parameters
  - fromDir: Directory on the resource used for publishing. For example, enter /var/tmp for Linux or C:/<temp> for Windows.
  - platform: Host platform type.
  - repository: Repository name. Use default to use the repository installed during the CloudBees CD/RO installation or enter another name.
  - resource: Name of the resource used for publishing.
  - version: Build version for the CloudBees CD/RO installation. For example, enter 5.0.0.56390. You can find the build version from the file name of the CloudBees CD/RO installer.
- Optional advanced parameters
  - Set advanced options if needed.
When the Publish Installer procedure runs, you can view the job status on the Job Details page. To view the published installers, select the Artifacts tab, and then select the com.electriccloud:installer artifact. The Artifact Details page lists the published installers. Select Run. The Upgrade Targets dialog displays.
Enter a list of resource names to upgrade into the Upgrade target resource names field. Names must be separated by any combination of spaces, commas, semicolons, or newlines. The resources must already exist, must be in the same zone, and must be of the same platform.

The Zone field displays the zone of the selected resources for upgrade. The Driving Resource is the resource that performs all file transfer actions towards installing or upgrading a host on behalf of the server. This agent works with the repository server to deliver the installation files to the destination agent(s) and then triggers the upgrade to start on the remote agent via SSH.

Select Next. The Authentication Settings dialog for your platform displays.
Enter authentication information.
- Linux- or UNIX-based platforms:
  
  From the Authentication Type menu, choose SSH User or SSH Key and enter the authentication information required to connect to the remote machines:
  - SSH User:
    
    (Required) User Name: User name. This user must have administrator privileges on the target machines.
    
    (Required) Password: Password for the user name.
  - SSH Key:
    
    (Required) User Name: User name. This user must have administrator privileges on the target machines.
    
    (Required) Public Key Path: Path to the SSH public key file.
    
    (Required) Private Key Path: Path to the SSH private key file.
    
    (Optional) Passphrase: Passphrase for unlocking the private key file.
- Windows platforms:
  
  From the Authentication Type menu, select Local User, Domain User, or Built-in User Account, and then enter the authentication information required to connect to the remote machines:
  - (Required) User Name: User name. This user must have administrator privileges on the target machines.
  - (Required) Password: Password for the user name.
  - (Required) Domain: User’s Windows domain.
Select Next. The Agent Configuration dialog displays.
In the dialog, enter any additional parameters into the Additional Parameters field. This field is for parameters that are not available in the UI. For example, --agentMaxMemoryMB 256. All arguments for a parameter must be on the same line. Note that you cannot use --nonRoot for agent upgrades if the agents were originally installed using non-root installation mode.

Select Next. The Post Upgrade Step dialog displays.
You can skip the Post Upgrade Step dialog by selecting Next. Otherwise, choose Project or Plugin. For Project, enter a project name, procedure name, and if the selected procedure has parameters, enter its parameters.

The Ready to Upgrade dialog displays, which summarizes your settings. For more than five hosts, the number of hosts displays instead of a space-separated list of host names.

Credential parameters are not supported in post-installation steps.
Review your settings in the Ready to Upgrade dialog, and select Finish to start the installation or upgrade. The Job Details page displays.

When the installation or upgrade finishes, you can return to the Resources page to view the hosts that were just upgraded. To verify a resource version, select a resource name (in table view) to open the Resource Details panel for that resource.

Upgrading remote agents using the API

This section describes how to use the CloudBees CD/RO API to upgrade remote agents. This process uses the underlying CloudBees CD/RO CAM functionality.

Agents installed by root or using sudo can be upgraded only by root or using sudo. Similarly, you cannot use non-root installation mode ( --nonRoot ) to upgrade agents unless they were originally installed using non-root installation mode.

You can automate remote upgrades for multiple resources by using scripts that call CloudBees CD/RO APIs to run those upgrades. These APIs provide the same remote upgrade capability as the web interface.

Parameters for running the procedure to perform the installations

Refer to Install remote agents using the API.

Examples for upgrading 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 for Linux

ectool runProcedure EC-AgentManagement-1.2.0.111083 --procedureName "Centralized Agent Management"
--actualParameter "isUpgrade=1"
--actualParameter "platform=Linux_x64"
--actualParameter "version=7.0.0.110954"
--actualParameter "zoneName=default"
--actualParameter "resources=4.208 4.210"
--actualParameter "drivingResource=local"

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

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

ectool example for Windows

ectool runProcedure EC-AgentManagement-1.2.0.111083 --procedureName "Centralized Agent Management"
--actualParameter "isUpgrade=1"
--actualParameter "platform=Windows_x64"
--actualParameter "version=7.0.0.110954"
--actualParameter "zoneName=default"
--actualParameter "resources=10.1.216.227"
--actualParameter "drivingResource=3EC-IT-3614"

--actualParameter "connectionDomain=electric-cloud"

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


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

DSL example for Linux

ectool evalDsl
"def pluginProject = getPlugin(pluginName: 'EC-AgentManagement').projectName;
runProcedure(pluginProject, procedureName: 'Publish Installer',
    actualParameter: [
        isUpgrade: '1',
        platform: 'Linux_x64',
        version: '7.0.0.110954',
        zoneName: 'default',
        resources: '4.208',
        drivingResource: 'local',

        connectionType: 'SSH_PASSWORD',
        connectionCredential: 'connectionCredential',
        agentCredential: 'agentCredential'
    ],
    credential: [
        [
            credentialName: 'connectionCredential' ,
            userName: 'remote',
            password: ''Rem0te4''
        ],
        [
            credentialName: 'agentCredential' ,
        ]
    ]
)"▼

DSL example for Windows

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

        connectionDomain: 'electric-cloud',

        connectionType: 'WINDOWS',
        connectionCredential: 'connectionCredential',
        agentCredential: 'agentCredential'

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