Install remote agents using the web interface

This section describes how to use the CloudBees CD/RO web UI to install remote agents. This process uses the underlying CloudBees CD/RO Centralized Agent Management (CAM) functionality.

In the Cloud > Resources page of the Automation Platform, click the Add menu and then click Install Resource(s) to install resources on host machines to use as agent hosts for your CloudBees CD/RO resources. The Install Resource(s) dialog box appears.

If the Install 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 Permissions for installing or upgrading remote agents.

If a CloudBees CD/RO agent installer is already published and available for your desired platform, then you can select it to continue with the installation. Otherwise, click the appropriate Publish Installer or Re-Publish Installer link for the appropriate platform, then click Next. The Run Procedure/Publish Installer page opens.

Enter the following information:
- 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.
Set advanced options if needed.
Click Run.
- View the publish installer procedure progress from the Job Details page.
- View the published installers by selecting the Artifacts tab and then choose the com.electriccloud:installer artifact. The Artifact Details page lists the published installers.
  
  You can republish a new agent installer version. To do so, return to the Cloud Resources page, select > Install Resource(s), and then select the radio button for the installer.
  
  If the Install 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, refer to Permissions to install or upgrade remote agents. The Install Targets dialog appears.
Enter the information for the target host machines as follows:

IPv6 addresses are only supported for Kubernetes platforms. If using an IPv6 address, enclose the address in square brackets. Example: [<IPv6-ADDRESS>].
- (Required) Installation target hostnames or IP addresses —One or more host names or IP addresses separated by any combination of spaces, commas, semicolons, or newlines. Host names cannot contain spaces.
- (Required) Zone —Zone where you are installing agents. If only one zone exists, this option is grayed out. For multiple zones, only the zones for which you have permissions are displayed.
  
  You can install agents to only one zone at a time. A functioning gateway must exist before an agent can be installed into the non-default zone, so installing the first agent into a zone must be done manually.
- (Required) Driving Resource —Resource to perform all actions for installing a host on behalf of the server. This is the agent that installs the agents on the remote hosts.
  
  The driving resource must belong to the same platform and zone as the hosts being installed or upgraded. Also, on Windows systems containing the driving resource, Windows PowerShell 3.0 or newer must be installed on older Windows versions.
- Resource Name Format —Naming scheme for newly-created resources to correspond to the hosts on which to perform the installation.
  - Hostname/IP —Use fully-qualified domain names (FQDNs), which will be derived from the host names or IP addresses of the hosts.
  - Short name —Use host names that do not include domain names. For example, the host11 part of host11.bigco.com.
    
    If you provided IP addresses for the target hosts for installation, resources are named using the short names of the FQDNs, which are derived from those IP addresses. If you provided short host names for installation, resources are named using the short names.
    
    If you provided IP addresses for the target hosts for installation and the FDQNs cannot be determined, the installation will fail for those resources (but will continue with the rest of the installation). Also, because there might be duplicate resource names across domains and subdomains if you use short names, if a resource by that name already exists, the installation will fail for the resource (but will continue with the rest of the installation).
  - Custom —Custom template for resource naming. The value in this field undergoes property expansion in a global context and is scanned for the name, counter, and shortname special tokens.
Click Next. One of two Authentication Settings dialog boxes appears depending on the platform.

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

Before using a domain user to install agents on remote hosts, you must enable multi-hop support for WinRM on the driving resource system and on each remote host. For more information, see the How to get server status information from multiple machines within your environment KB article.

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.
Local 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.
Domain User : This user must have must have administrator privileges on the target machines.
(Required) User Name —User name.
(Required) Password —Password for the user name.
(Required) Domain —User’s Windows domain.
Built-in User Account —This user must have must have administrator privileges on the target machines.
(Required) Service Account —

Click Next.

One of two Agent Configuration dialog boxes appears depending on the platform.

Linux- or UNIX-Based Platforms

Provide the agent settings to be passed to the CloudBees CD/RO agent installer. The agent settings appear in two sections: Information for the user account to be used to run the agent and the agent or resource configurations such as agent port:

(Required) Agent Service User —User that the CloudBees CD/RO agent runs as.
(Required) Agent Service Group —Group that the CloudBees CD/RO agent runs as.

Windows Platforms

Local User :
(Required) User Name —User name.
(Required) Password —Password for the user name.
Domain User :
(Required) User Name —User name.
(Required) Password —Password for the user name.
(Required) Domain —User’s Windows domain.
Built-in User Account :
(Required) Service Account — LocalSystem is the only option available in this release.

All Platforms

Agent type —Agent type. (This menu appears only if a mixed-mode license is installed on the server for both registered and concurrent hosts.)
- If the license on the server is a concurrent resource license, the host type defaults to Concurrent, and this menu does not appear.
- If the license on the server is a registered host license, the host type defaults to Registered, and this menu does not appear.
- If the license on the server is a mixed-mode license (concurrent resources and registered hosts), you must choose the host type when adding a resource.
(Optional) Click Advanced to view additional options. Complete the advanced options as follows:
- Agent Port —Port for communication between the local agent and the server. The default is 7800.
- Install Directory —Path to the install directory. Spaces are allowed. Do not use quotation marks.
- Data Directory —Path to the directory where your modified CloudBees CD/RO files are stored (configuration and log files). Spaces are allowed. Do not use quotation marks.
- Trusted Agent —Check this check box if all agent machines being installed or upgraded are trusted. For more information, see the “Switching a Non-Trusted Agent to Trusted” section on Create and manage resources.
- Workspace —Name of the workspace to set as the default workspace for the new resource(s).
- Additional Parameters —Parameters that are not available in the UI. For example, --agentMaxMemoryMB 256. All arguments for a parameter must be on the same line.
Click Next. The Post Installation Step dialog box appears. You can skip the dialog box by clicking Next at this point.
(Optional) Choose Project or Plugin. The following examples use Project.
- Enter a project name into the Name dialog box. For example:
- Enter a procedure name. If the procedure has parameters, the Parameters menu appears, which includes the parameter fields for the selected procedure. For example:
- Enter the parameters for the selected procedure. For example:
  
  Credential parameters are not supported in post-installation steps.
Click Next.

The Ready to Install dialog box appears, which summarizes your settings. For example, for more than five hosts, the number of hosts appears (instead of a space-separated list of host names).
Review your settings in the Ready to Install dialog box, then 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 installed. To verify a resource version, click a resource name (in table view) to open the Resource Details panel for that resource.