Upgrading remote agents

5 minute read

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

Permissions for upgrading remote agents

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

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

Upgrading remote agents using the web interface

This section describes how to use the CloudBees CD web interface to upgrade remote agents. This process uses the underlying CloudBees CD 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.
  1. In the Cloud>Resources page of the Automation Platform, select the check boxes for resources that you want to upgrade on agent hosts. If the selected resources have different platforms or zones, an error prompt appears:

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

    Proxy resources are not supported for upgrade. Select the resources acting as proxy agents directly for upgrade.
  2. Click the Add menu and then Upgrade Resource(s). If the Upgrade Resource(s) menu option is not visible, you must log out and then log in as a user with the required permissions. For details about required permissions, see Remote Agent Permissions. The Upgrade Resources dialog box appears.

    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.

    On Solaris platforms, the installation directory path must have fewer than 70 characters.
  3. Choose the platform and published version, click the appropriate Re-Publish Installer link, then click Next. The Run Procedure/Publish Installer page opens.

  4. Enter the following information:

    • Parameters (required)

      • 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 installation or enter another name.

      • resource —Name of the resource used for publishing.

      • version —Build version for the CloudBees CD installation. For example, enter 5.0.0.56390. You can find the build version from the file name of the CloudBees CD installer.

    • Advanced (optional)

      • Set advanced options if needed.

  5. When the Publish Installer procedure runs, you can see the job status on the Job Details page. If you want to see the published installers, click the Artifacts tab and then click the com.electriccloud:installer artifact. The Artifact Details page lists the published installers. Click Run. The Upgrade Targets dialog box appears.

  6. 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. Driving Resource is the resource to perform all actions for installing or upgrading a host on behalf of the server. This is the agent that upgrades the agents on the remote hosts.

Click Next. The Authentication Settings dialog box for your platform is displayed. . Enter authentication information. * Linux- or UNIX-Based Platforms

+ From the Authentication Type menu, choose SSH User or SSH Key and enter authentication information required to connect to the remote machines:

+ SSH User : (Required) User Name —User name. This user must have 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 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, choose Local User, Domain User, or Built-in User Account and enter the authentication information required to connect to the remote machines:

    • (Required) User Name —User name. This user must have must have administrator privileges on the target machines.

    • (Required) Password —Password for the user name.

    • (Required) Domain —User’s Windows domain.

    Click Next. The Agent Configuration dialog box appears.

    1. In the dialog box, 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 the agents were originally installed using non-root installation mode.

      Click Next. The Post Upgrade Step dialog box appears.

    2. You can skip the Post Upgrade Step dialog by clicking Next at this point. 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 box appears, which summarizes your settings. For more than five hosts, the number of hosts appears instead of a space-separated list of host names.

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

When the installation or upgrade finishes, you can return to the Resources page to see the hosts that were just upgraded. To verify a resource version, click 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 API to upgrade remote agents. This process uses the underlying CloudBees CD 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.

You can automate remote upgrades for multiple resources by using scripts that call CloudBees CD 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

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 (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 (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 (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 (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', ] ] )"