Resource management

21 minute readAutomation

Viewing the resource list

If you have not already logged in, refer to Sign in to CloudBees CD/RO.

You can view the resources list in either of two ways:

  • From the Deploy UI: browse to https://<cloudbees-flow-server>/flow/, and then from the main menu, select DevOps Essentials > Resources.

  • From the Automation Platform UI: browse to https://<cloudbees-flow-server>/commander/, and then from the main menu, select Cloud > Resources.

The Resources list displays all resources on this CloudBees CD/RO server and provides easy access to resource configuration and all other resource management functionality.

  • Each resource has a logical name—a unique name to distinguish this resource from other resources.

  • Each resource refers to an agent machine by its host name.

  • Each resource can be assigned to one or more pools.

    A pool is a group of interchangeable resources. For example, a pool of Windows servers.

    If you name a pool in a procedure step, CloudBees CD/RO can assign any resource in the pool to that step, which allows CloudBees CD/RO to choose a lightly loaded resource. You can change the resources in a pool without modifying procedures that use the pool.

  • Each resource can be assigned to a zone. A default zone is created during installation, and all resources are members of that zone until they are assigned to a different zone.

    A zone is a collection of agents. Every agent, and all resources defined on that agent, belong to only one zone. When CloudBees CD/RO is installed, a default zone is created. If a zone is deleted, all agents in that zone are moved to the default zone. The CloudBees CD/RO server resides in the default zone.

    The default zone cannot be deleted.
  • Several resources can correspond to the same physical host or agent machine.

  • When you specify a resource name in a procedure step, the step executes on that resource.

Supported Resource Categories

  • Standard —This category specifies a machine running the CloudBees CD/RO agent on one of the supported agent platforms, as specified in Supported platforms for CloudBees CD/RO.

  • Proxy —This category requires SSH keys for authentication. You can create proxy resources (agents and targets) for CloudBees CD/RO to use on other remote platforms or hosts that exist in your environment.

    • Proxy agent —This is an agent on a supported Linux or Windows platform, used to proxy commands to an otherwise unsupported platform. A proxy agent is a CloudBees CD/RO agent, channeling to a proxy target.

    • Proxy target —This is a machine on an unsupported platform that can run commands through an SSH server. Proxy targets have limitations, such as the inability to work with plugins or communicate with ectool commands.

Help topic "Best Practice": You should review this entire Help to become familiar with resource management features and functionality. Later, when using the Resources page, use the following quick links to go to the Help section that you need to review.

Resource Page Information and Functions

Immediately after the Resources title above the table, you can see how many licensed resources are in use.

Hover your mouse over an icon or button to see the available actions. You can select one of these actions on a single resource or on multiple resources (selected using the checkbox in the first column) to perform the action on one or more resources at the same time.

  • Select one or more resources from the table, and then select the button to perform the task or action.

  • Exception: When you select the Action icon and select Create Resource or Create Proxy Resource, a panel opens where you can create one of these new objects. You can create only one object at a time.

Icon or Link Name Description

Resource actions

Select one of these actions:

  • Create Resource —The New Resource panel opens. For information about the fields, refer to #NewResourcepanel.

  • Create Proxy Resource —The New Proxy Resource panel opens. For information about the fields, refer to #NewProxyResource.

  • Install Resource(s) —A dialog box opens where you enter information about the agents to install. For more information, refer to Remote host traditional installation with Centralized Agent Management. This section describes how to use the CloudBees CD/RO Centralized Agent Management (CAM) feature.

    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.

    If you are upgrading one or more agents or resources, the label on this option is 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, refer to Permissions to install or upgrade remote agents.
If the EC-AgentManagement plugin is not installed, you will not see this option.

Copy resources

Copy Resource —Makes a duplicate copy of one or more resources that you selected.

Delete resources

Delete Resource —Deletes one or more resources that you selected.

If a resource is on a “gateway agent,” the gateway will be deleted.

Ping resources

Ping Resource —CloudBees CD/RO pings one or more resources to check if they are available.

When CloudBees CD/RO pings a resource, it sends a message to the agent (for the resource) to make sure the agent is alive and running a version of software compatible with the CloudBees CD/RO server. After the ping completes (or fails), the page refreshes to reflect the current resource state.

A gateway must exist before you ping a resource in a remote zone.

Enable resources

Enable Resource —Enables one or more resources that you selected in the checkboxes in the first column.

Disable resources

Disable Resource —Disables one or more resources that you selected in the checkboxes in the first column.

Edit resources

Select one of these actions:

  • When you click the button with no resources selected, the Select some resources to edit message appears.

  • When you select resources and select this button, these options appear:

    • Add to Pool —Adds the selected resources to a pool.

    • Remove from Pool —This is available only if all the selected resources have at least one pool in common. If not, this link becomes Remove from Pool <name>.

    • Move to Zone —Moves the selected resources to a zone.

    • Set Trusted —This is not available if the selected resources are already trusted. If not, all the selected resource will be changed to trusted.

    • Unset Trusted —This is available only if all the selected resources are trusted. If not, the selected resources will be changed to untrusted.

Add resources to your Home page or Resource is already available from your Home page

Select this button to add this Resources page to your Home page for one-click access to return to this page. If the icon is yellow, the page is already accessible from your Home page.

New Search link

Use this link to go to the Searching and Filtering page if you need to search for a particular object or set of objects. For example, job, resource, artifact, workflow, and so on. Use the "back" button to return to the Resources page.

Table View—Column Descriptions

Not all resource configuration information appears within the table, but you can see all other information about the resource when you edit the resource or access other slide-out panels. For example, the action to see or add access control privileges to a resource is available on the Edit Resource panel or from the Access Control link on that panel.

Most column headings can be sorted. Select a column heading to re-sort the information in that column.
Column name / icon Description

Enable resources

Select this check box to enable the corresponding resource in that row for a single or batch action. For example, deleting or enabling multiple resources at the same time is a batch action.

If you select this icon in the table header row, it will select or deselect all resources in the table.

Agent status

Status of the agent. If an agent machine is not available, any resources associated with that host will not be available. If an agent is down, the CloudBees CD/RO server is not able to provide additional information about the cause.

Name

Name of the resource. The icon to the left of the resource name indicates whether this resource is enabled or disabled. These icons are: Enabled resource enabled icon or Disabled resource disabled icon.

If a resource is disabled, no job steps are assigned to it. If a step requests a particular resource and that resource is disabled, the step waits until the resource becomes enabled again. If the resource is in a pool, CloudBees CD/RO uses any enabled resource in the pool to satisfy the request for the resource. Other actions:

  • To change the enabled or disabled icon, select the checkbox (in first column) in the row for one or more resources, and then select the enabled or disabled icon above the table. Select multiple resources if this is a batch change.

    You can change the resource enable/disable specification from the Edit Resource panel too, but this is an individual operation for one particular resource.
  • Select the resource name to see the Resource Details panel — this panel displays how your resources is configured currently. To make changes, select Edit to go to the Edit Resource panel.

Pools

A list of pool names where this resource is a member.

Type

A resource can be static or dynamic.

  • A static resource is part of your system or network (not in the cloud), such as a server, database, or agent machine.

  • A dynamic resource is a cloud resource that can be provisioned and later spun up on-demand when an application or microservice is deployed.

Resource Template Name

The name of the resource template to which the resource is applied. Only dynamic resources can be applied to a resource template.

Time running

If the resource is a dynamic resource, how long it has been running.

Job Status

Indicates the current job status with the following icons:

Running job Running job —A job is still running, which means the resource is currently being used for one or more jobs. The names of all jobs using the resource are displayed next to the icon.

Success Success— The job running on this resource completed successfully.

Warning Error— The job running on this resource encountered an error and may or may not have completed. One or more error messages will be listed in this column.

Warning Warning— The job running on this resource encountered a warning and may or may not have completed. One or more warning messages will be listed in this column.

Busy Busy —CloudBees CD/RO is attempting to refresh the job status, but the resource is not responding or the UI cannot parse the response. Changing the value of 'Agent Host Name' to the IP address can sometimes resolve this issue.

Description

(Optional) Plain text or HTML description for this object. If using HTML, you must surround your text with <html> …​ </html> tags. Allowable HTML tags are <a>, <b>, <br>, <div>, <dl>, <font>, <i>, <li>, <ol>, <p>, <pre>, <span>, <style>, <table>, <tc>, <td>, <th>, <tr>, and <ul>.

  • For example, the following HTML:

    <p> <span style="font-family: Arial;"> <i>Note:</i> For more information about the <b>abc</b> object, see <a href="https://www.google.com/">https://www.google.com</a>. </span> </p>

    renders as follows:

    <i>Note</i>: For more information about the <b>abc</b> object, see https://www.google.com.

Zone

The name of the zone where this resource is a member.

HTTPS & Host

The "Connection Type" you specified when this resource was created.

Step Load

Resource load is indicated by one of the following:

  • One step is using the resource —Indicates 1 step is using this resource and an unlimited number of steps can use this resource at the same time.

    If 5 steps are using this resource, you would see "5 of unlimited".

  • No resources are running —Indicates that no steps are running on this resource and the step limit is set to 4.

    The bar indicates graphically how close you are to the step limit.

Use the Create/Edit Resource panels to define the number of steps that can run on a resource. Setting the Step Limit to "0" or leaving the field blank defaults to NO step limit.

Actions

Actions you can perform on the resource, including:

  • Copy —Create a new resource by copying this resource

  • Delete —Delete this resource

  • Tear Down —Remove (decommission) the dynamic resource from a dynamic environment

  • Track Changes —Open the Change History for the resource

Grid View

Two icons above the Filters pane: Resource table Resource grid

  • The first icon (on the left) is the default Table view icon.

  • The second icon (on the right) displays the resource Grid view. Use the drop-down menus to filter the Grid view:

  • Grouping — Select the resource "grouping" you want to see—choose Pool, Job, Operating System, Platform, Proxy Agent, Version, or Zone.

    For example, if you have multiple resource pools defined and chose Pool, you will see groups labeled with your various pool names and a group (No Pool) for resources not included in a pool.

  • Coloring — Select what you want to view in each group—choose Platform, Step Count/Limit, Status, Held Exclusive, Version, or Operating System to sort your group.

    Colors are dynamically assigned per the view you select. Within a single view, the same color "square" implies similar information.

  • Hovering your mouse over a grid "square" provides more detailed information about that resource.

Filters pane

Use the Filters pane to filter resources shown in either the Table or Grid view. The fields in the Filter pane correspond to columns in the Table view.

Enter the Filter criteria as follows:

Actions / Field Description

Save Filters

Select this link to save your filter criteria. A dialog appears so you can name your filter. For easy, repeat access, filters are saved in a "saved filters" box above the link. When you select a saved filter name, the Filter pane fields populate automatically.

Reset

Use this link to clear all entries in the Filter pane.

Quick Search

Enter any text for your search. For example, enter a host name. You do not need to enter a full name or text string—this field filters on a partial text entry, sometimes 2-3 characters are all you might need.

Status

The status for the agent machine.

Both Enabled/Disabled

Default is both enabled and disabled resources. Use the drop-down arrow to choose enabled or disabled only.

Pools

Name of a pool. The pool name must be entered exactly—a shortened version of the pool name will fail.

Hosts

List one or more full host names as shown in the Table view "HTTPS & Host" column (each name separated by a space). Entering a partial name will not yield a successful result.

Step Limit

Choose the step limit corresponding to your desired search.

Proxy Agent

Select No if not searching for a proxy agent or Yes if you are trying to locate a proxy agent.

Filter

Select this button after you complete the fields/selections to define your filter criteria.

New Resource Panel

To define a new standard resource, enter information in the following fields:

Field Description

Name

Enter a unique name for this resource. Do not use "spaces" in a resource name. This is the name used to select the resource for a job step—It need not be the same as the host name for the machine.

Description

(Optional) Plain text or HTML description for this object. If using HTML, you must surround your text with <html> …​ </html> tags. Allowable HTML tags are <a>, <b>, <br>, <div>, <dl>, <font>, <i>, <li>, <ol>, <p>, <pre>, <span>, <style>, <table>, <tc>, <td>, <th>, <tr>, and <ul>.

  • For example, the following HTML:

    <p> <span style="font-family: Arial;"> <i>Note:</i> For more information about the <b>abc</b> object, see <a href="https://www.google.com/">https://www.google.com</a>. </span> </p>

    renders as follows:

    <i>Note</i>: For more information about the <b>abc</b> object, see https://www.google.com.

Agent Host Name

Enter the domain name or IP address of the agent machine for this resource. This is the name all other machines in this agent/resource’s zone will use to communicate with this agent host.

Agent Port Number

Enter the port number to use when connecting to the agent for the resource, Default port is 7800.

Default Workspace

Enter the workspace name or leave blank to use the local, default workspace. The workspace specification can be overridden at the project, procedure, or step level.

If you specify a workspace name here, it will be used as the default for all job steps that run on this resource. See the Workspaces Help topic in the Automation Platform for more information.

Pool(s)

A comma-separated list of arbitrary names indicating the pools associated with this resource.

Host Type

Use the drop-down menu to select the host type:

  • Concurrent

  • Registered

Depending on the license installed on the CloudBees CD/RO server, this field may appear.

  • If the license on the server is a concurrent resource license, the host type defaults to Concurrent and this field does not appear.

  • If the license on the server is a registered host license, the host type defaults to Registered and this field does not appear.

  • If the license on the server is a mixed-mode license (concurrent resources and registered hosts), you must specify the host type when adding a resource.

Default Shell

The name of the shell program used to execute the step’s commands on a resource. For example, using sh or cmd /c, the agent saves the command block to a temporary file with a .cmd extension and runs it: sh foo.cmd or cmd /c foo.cmd. If you do not specify a shell on a step, at step run-time the server looks at the resource shell. If a resource shell is not set, the shell line used by the agent is platform dependent: Windows: cmd /q /c "{0}.cmd" UNIX: sh -e "{0}.cmd" When you specify a shell (in the step or resource), and omit the cmd-file marker, the agent notices the omission and takes the correct action. For example: a user specifies sh -x. The agent converts this to sh -x "{0}.cmd". Two alternate forms of shell syntax where CloudBees CD/RO uses a "marker," {0}, as a placeholder for the command file argument:

  • < myShell > {0} < potential extra shell args > In this example, the command file is not meant to be the last argument in the final command line. For example, mysql -e "source {0}" This shell example runs the mysql command against this step’s command containing sql.

  • < myShell > {0} < .file extension > < potential extra shell args > In this example, the shell requires the command file to end in an extension other than .cmd. For example, powershell "& '{0}.ps1'" This shell example runs Microsoft PowerShell against this step’s command containing PowerShell commands.

  • When the agent parses the shell, it will parse the extension as everything after {0}. until it sees a space or non-alphanumeric character.

  • If your script uses International characters (non-ASCII), add the following block to the top of your cb-perl command block: use utf8; ElectricCommander::initEncodings

Step Limit

The maximum number of steps that can execute simultaneously on this resource—a step limit applies to a particular resource only, not to its underlying host.

For example, if you define two resources, resource1 with a step limit of 5 and resource2 with a step limit of 1, both specifying the same host machine, it is possible for a total of 6 steps to execute simultaneously on the underlying host.

The Resource Details panel displays this information.

Setting the Step Limit to "0" or leaving the field blank defaults to no step limit.

Artifact Cache Directory

The directory on this resource’s agent host from which artifact versions are retrieved and made available to job steps. Enter an absolute path to the resource containing this cache directory.

Zone

The name of the zone where this resource is or will be a member—a zone is a top-level network containing one or more mutually accessible resources.

Repository Names

A "new-line" delimited list of repository names for this resource, if needed. When a step attempts to retrieve artifact versions from a CloudBees CD/RO repository, it queries repositories specified here. If no repositories are specified, it will "fallback" to the default repository.

Connection Type

Use the drop-down menu to select your Connection Type:

  • HTTP —Choose this option if you are not using SSL and the agent does not need to be "trusted".

  • HTTPS —Choose this option if you are using SSL, but this agent does not need to be "trusted".

  • Trusted HTTPS —Choose this option if you are using SSL and this agent must be “trusted.” A trusted agent is “certificate verified”—The agent verifies the server or “upstream” agent’s certificate.

    For information about the certificate used for trusted agents, refer to eccert.

Agents can be either trusted or untrusted :

  • trusted— The CloudBees CD/RO agent verifies the server or “upstream” agent’s certificate.

  • untrusted— The CloudBees CD/RO agent does not verify the server or “upstream” agent’s certificate. This agent will accept communications from any CloudBees CD/RO server. An untrusted agent is a potential security risk.

Enabled

Select this box to enable this resource. When this box is checked, the resource is enabled, which means job steps can be assigned to it. If a job step requests a pool containing this resource, the step executes on a resource in that pool. If disabled, and this is the only resource that satisfies a particular job step, the step’s execution is delayed until the resource is re-enabled. If a resource is disabled while job steps are running on it, the running steps continue to completion but no new steps are assigned to that resource.

Select OK to save your settings and see your new resource listed in the table.

New Proxy Resource Panel

These are the definitions of a proxy agent and proxy target:

  • Proxy agent —This is an agent on a supported Linux or Windows platform, used to proxy commands to an otherwise unsupported platform.

  • Proxy target —This is a machine on an unsupported platform that can run commands via an SSH server.

To define a new proxy resource,enter information in the following fields:

Field Description

General

Name

Enter a unique name for this resource. Do not use spaces in a resource name. This is the name used to select the resource for a job step; it does not need to be the same as the host name for the machine.

Description

(Optional) Plain text or HTML description for this object. If using HTML, you must surround your text with <html> …​ </html> tags. Allowable HTML tags are <a>, <b>, <br>, <div>, <dl>, <font>, <i>, <li>, <ol>, <p>, <pre>, <span>, <style>, <table>, <tc>, <td>, <th>, <tr>, and <ul>.

  • For example, the following HTML:

    <p> <span style="font-family: Arial;"> <i>Note:</i> For more information about the <b>abc</b> object, see <a href="https://www.google.com/">https://www.google.com</a>. </span> </p>

    renders as follows:

    <i>Note</i>: For more information about the <b>abc</b> object, see https://www.google.com.

Proxy Agent Host Name

Enter the domain name or IP address of the proxy agent machine corresponding to this resource.

Proxy Agent Port Number

Enter the port number to use when connecting to the agent for the resource.

Default Workspace

Enter the workspace name for leave blank to use the local, default workspace.

If you specify a workspace here, it will be used as the default for all job steps that run on this resource. See the Workspace overview topic in the Automation Platform online Help for more information.

Pool(s)

Enter a comma-separated list of arbitrary names, indicating the pools associated with this resource.

Host Type

Use the drop-down menu to select the host type:

  • Concurrent

  • Registered

Depending on the license installed on the CloudBees CD/RO server, this field may appear.

  • If the license on the server is a concurrent resource license, the host type defaults to Concurrent and this field does not appear.

  • If the license on the server is a registered host license, the host type defaults to Registered and this field does not appear.

  • If the license on the server is a mixed-mode license (concurrent resources and registered hosts), you must specify the host type when adding a resource.

Step Limit

Specify the maximum number of steps that can execute simultaneously on this resource—a step limit applies to a particular resource only, not to its underlying host. For example, if you define two resources, resource1 with a step limit of 5 and resource2 with a step limit of 1, both specifying the same host machine, it is possible for a total of 6 steps to execute simultaneously on the underlying host.

Zone

The name of the zone where this resource will be a member.

Connection Type

Use the drop-down menu to select your Connection Type:

  • HTTP —choose this option if you are not using SSL and the agent does not need to be "trusted".

  • HTTPS —choose this option if you are using SSL, but this agent does not need to be "trusted".

  • Trusted HTTPS —choose this option if you are using SSL and this agent must be "trusted". A trusted agent is "certificate verified"—the agent verifies the server or "upstream" agent’s certificate.

For information about the certificate used for trusted agents, see eccert.

Agents can be either trusted or untrusted :

  • trusted —The CloudBees CD/RO server verifies the agent’s identity using SSL certificate verification.

  • untrusted —The CloudBees CD/RO server does not verify agent identity. Potentially, an untrusted agent is a security risk.

Enabled

Select this box to enable this resource. When this box is checked, the resource is enabled, which means job steps will be assigned to it. If a job step requests a pool containing this resource, the step executes on a resource in that pool. If disabled, and this is the only resource that satisfies a particular job step, the step’s execution is delayed until the resource is re-enabled. If a resource is disabled while job steps are running on it, the running steps continue to completion but no new steps are assigned to that resource.

Proxy Target

Proxy Target Host Name

Enter the domain name or IP address of the proxy target machine corresponding to this resource.

Proxy Target Port Number

Enter the port number to use when connecting to the proxy target host or leave blank to use the default. The default port is 22, the SSH server port.

Proxy Target Default Shell

The name of the shell program used to execute commands on this [the proxy target] resource—may be overridden at the step level. This shell will be used to execute the step’s commands on a resource. For example, using sh or cmd /c, the agent saves the command block to a temporary file with a .cmd extension and runs it: sh foo.cmd or cmd /c foo.cmd. If you do not specify a shell on a step, at step run-time the server looks at the resource shell. If a resource shell is not set, the shell line used by the agent is platform dependent: Windows: cmd /q /c "{0}.cmd" UNIX: sh -e "{0}.cmd" When you specify a shell (in the step or resource), and omit the cmd-file marker, the agent notices the omission and takes the correct action. For example: a user specifies sh -x. The agent converts this to sh -x "{0}.cmd". Two alternate forms of shell syntax where CloudBees CD/RO uses a "marker," {0}, as a placeholder for the command file argument:

  • < myShell > {0} < potential extra shell args > In this example, the command file is not meant to be the last argument in the final command line. For example, mysql -e "source {0}" This shell example runs the mysql command against this step’s command containing sql.

  • < myShell > {0} < .file extension > < potential extra shell args > In this example, the shell requires the command file to end in an extension other than .cmd. For example, powershell "& '{0}.ps1'" This shell example runs Microsoft PowerShell against this step’s command containing PowerShell commands.

NOTE:

  • When the agent parses the shell, it will parse the extension as everything after {0}. until it sees a space or non-alphanumeric character.

  • If your script uses International characters (non-ASCII), add the following block to the top of your cb-perl command block: use utf8; ElectricCommander::initEncodings

Proxy Customizations

This is proxy-specific customization data. Default is "none".

For more information, see ecproxy.

Select OK to save your settings.

Edit Resource Panel

All the fields on this panel are the same as those on the New Resource panel:

  • All information you previously provided to create this resource is filled-in for you.

  • You can change any information already supplied.

  • You can add information in any blank fields.

The Gateway(s): field that appears in the Resource Details panel is not editable (not even for a gateway resource) and therefore does not appear in the Edit Resource panel. This field is automatically filled and is only for gateway agents. For example, in the Resource Details panel for agentp1-gw-01 and agentp2-gw-01 resources as they form a gateway Default_to_zone1_gateway using the steps in the KBEC-00393 - Setting up an environment with two zones and a gateway KB article.

Select OK to save your modifications.

If you want to change the Connection Type, using the UI by itself is insufficient. You must also use the ecconfigure utility to change the protocol. Run: ecconfigure --agentProtocol [http|https]

Edit Proxy Resource Panel

All fields on this panel are the same as those on the New Proxy Resource panel:

  • All information you previously provided to create this resource is filled-in for you.

  • You can change any information already supplied.

  • You can add information in any blank fields.

Select OK to save your modifications.

Resource Details Panel

This panel displays how this resource is configured with the CloudBees CD/RO server. Some information supplied is linked to its source. For example, the zone name for this resource is a link to its Zone Details panel.

  • The name of the resource is shown below the panel title.

  • The resource description is shown under the resource name.

  • Links at the top of the panel:

  • Use the View Usage link to go to the Job Step Search Results page.

  • Use the Edit link to modify the resource specifications.

  • Use the Access Control link [at the top of the panel] to specify or view access privileges for this resource.

  • The tabs:

  • General—By default, the panel opens to display the "general" resource configuration.

  • Properties—Select this tab to add properties to this resource or see existing resource properties if already configured.

    Custom Resource Properties You can define custom properties for any CloudBees CD/RO object. For example, if configuration information varies from resource to resource, use custom properties to store this information and then reference it from procedure steps where it is needed. For example, if you have a pool of test machines with test hardware in a different location on each machine, you could define a property named "testLocation" on each resource, then pass this property to procedure steps using a reference such as $[/myResource/testLocation].

The Gateway(s): field that appears in the Resource Details panel is not editable (not even for a gateway resource) and therefore does not appear in the Edit Resource panel. This field is automatically filled and is only for gateway agents. For example, in the Resource Details panel for agentp1-gw-01 and agentp2-gw-01 resources as they form a gateway Default_to_zone1_gateway using the steps in the KBEC-00393 - Setting up an environment with two zones and a gateway KB article.

Switching a Non-Trusted Agent to Trusted

By default, the local agent is not trusted during a new or upgrade installation. After an upgrade, if you want to use a trusted configuration, any existing agent or host machines must be manually switched to "trusted."

Perform the following steps on the agent machine to change the agent status to trusted in your environment and in the customer’s site.

  1. Enter ectool --server your_server_name login admin to log into the server and save the session ID.

  2. Enter eccert --server your_server_name initAgent --remote --force to install the agent with a self-signed certificate that needs to be overwritten.

    To run this command, the user must have “modify” privilege on systemObject 'resources'. The user or the group to which they belong can be given this permission in the Resources category in the Administration> Server > System Access Control page in the Automation Platform.

  3. Restart the agent.

    If you do not restart the agent, it tries to use a previously-cached certificate if one exists. The old certificate is invalid because a new one was just created.

  4. In the CloudBees CD/RO UI, ping the agent.

For information about the CloudBees CD/RO Certificate Authority (CA) and the certificates configured in CloudBees CD/RO Server and CloudBees CD/RO Agent installations, CloudBees CD/RO Installed Tools.

Creating the First Trusted Agent in a New Zone

This section describes how to create a new trusted agent in a new zone that is protected by a firewall. Perform the following steps to create the first trusted agent in the new zone. These steps assume that port 7800 is open between the new agent and the gateway agent in the default zone:

  1. Set the following property to specify the gateway agent:

    COMMANDER_HTTP_PROXY=https://gateway_agent_IP:7800
  2. Create a trusted connection between the agent and the CloudBees CD/RO server:

    ectool --server your_server_name login admin your_admin_password
    eccert --server your_server_name initAgent --force --remote
  1. Restart the agent.

    A certificate is generated (required for the trusted connection for the two gateway agents).

  2. Change the Connection Type of the agent as described above.

Upgrading Agents for Compatibility with Transport Layer Security (TLS)

If there are outdated agents, a warning appears on the Resources page that says:

You have Windows or Linux agents older than 6.0.4 or 6.3, or UNIX agents older than 8.5. You would need to upgrade those agents to the latest version to avoid security risk.

Also, those resources that require an upgrade are flagged with a Resources that require an upgrade icon in the Upgrade Required column.

The Upgrade Required column appears only if there are outdated agents.

The default security configurations are as follows:

  • First-time CloudBees CD/RO installations: TLSv1, TLSv1.1, and TLSv1.2 are enabled

  • Existing CloudBees CD/RO installations: TLSv1, TLSv1.1, TLSv1.2, and SSLv2Hello are enabled

CloudBees recommends removing the SSL 2.0 Client Hello or SSLv2Hello protocol from your security configurations for all components. When you do this, you would also need to upgrade older agents to the latest version to avoid security risks. You would need to upgrade agents if you are using the following agent versions:

  • Windows: 6.0.3 or older

  • Linux: 6.2 or older

  • Mac OS: 8.4 or older

For details about upgrading agents and enabling the TLS protocol for agents, refer to Upgrade remote agents.