Upgrade the CloudBees Analytics server

Before you upgrade

Upgrading the CloudBees CD/RO server

Before you upgrade the CloudBees Analytics server, make sure that the CloudBees CD/RO server is upgraded to the corresponding version.

For details about the overall steps for installing CloudBees Analytics on a group of servers to create a CloudBees Analytics server cluster, refer to Installing the CloudBees Analytics Server in Cluster Mode.

Upgrading on a system with other CloudBees CD/RO components

For a production environment, CloudBees recommends that you run the CloudBees Analytics server on a system other than systems running other CloudBees CD/RO components (such as the CloudBees CD/RO server, web server, repository server, or agent). If you have installed it on the same system (such as for testing or other non-production or trial-basis situations), use the following upgrade process.

Uninstall the CloudBees Analytics server from the system.
Upgrade the other CloudBees CD/RO components on the system.
Install the new version of the CloudBees Analytics server on the system.

Preserving Non-CloudBees Analytics custom settings

The CloudBees Analytics installer overwrites the opensearch.yml configuration file with a new file. This file includes a Custom Settings section, which lets you add OpenSearch settings not managed by the CloudBees Analytics server without being lost during an upgrade.

Ensure cluster health before and after operations

To upgrade or reconfigure the CloudBees Analytics server in clustered environments, the CloudBees Analytics server settings must be written to the Analytics cluster data. However, the server settings cannot be written to the cluster data if the Analytics cluster is unhealthy ("status": "red").

If you attempt to upgrade or reconfigure the CloudBees Analytics server with an unhealthy Analytics cluster, the operation will pause and wait for a healthy cluster.

When upgrading or reconfiguring the CloudBees Analytics server on nodes, you must perform the operation on each node individually, first master nodes and then data nodes. After performing any operation on a master node, CloudBees suggests checking the status of your Analytics cluster to ensure the operation did not degrade the cluster health.

Renaming or upgrading the CloudBees Analytics cluster

An exception to this procedure occurs when renaming or upgrading the CloudBees Analytics cluster version. During these operations, the initial master nodes you update automatically pause at the Starting services stage. This is because the cluster cannot be formed, since not all nodes have the same cluster name during renaming or version during upgrades.

To ensure the cluster health when renaming or upgrading the CloudBees Analytics cluster:

Perform the update on each master node without waiting for the update to complete. Updated nodes will pause at the Starting services stage.
Once the number of updated master nodes meets the minimum number of required nodes, the cluster is formed, and all paused updates continue.
Once all master nodes are updated, check the cluster health.
Continue updating the remaining data nodes.
Once all nodes are updated, check the health of your cluster.

Check CloudBees Analytics cluster health

CloudBees strongly suggests before and after performing any operation on the CloudBees Analytics cluster to ensure your cluster has either a green or yellow status by running the following curl command:

curl -k 'https://reportuser:<YOUR PASSWORD>@localhost:9201/_cluster/health?pretty'▼

The output should look similar to the following with "status" : "green" or "status" : "yellow":

{
  "cluster_name" : "analytics",
  "status" : "green",
  "timed_out" : false,
  "number_of_nodes" : 1,
  "number_of_data_nodes" : 1,
  "discovered_master" : true,
  "discovered_cluster_manager" : true,
  "active_primary_shards" : 1,
  "active_shards" : 1,
  "relocating_shards" : 0,
  "initializing_shards" : 0,
  "unassigned_shards" : 0,
  "delayed_unassigned_shards" : 0,
  "number_of_pending_tasks" : 0,
  "number_of_in_flight_fetch" : 0,
  "task_max_waiting_in_queue_millis" : 0,
  "active_shards_percent_as_number" : 100.0
}▼

If the cluster is unhealthy, the command returns results similar to:

OpenSearch Security not initialized.▼

For help troubleshooting your CloudBees Analytics cluster health, refer to the Cluster health.

User interface upgrade method

The graphical user interface installation method is supported by Windows platforms and Linux platforms running the X Window System.

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.

Use this procedure to upgrade the CloudBees Analytics server.

Double-click the following file to run the installer.
- Linux: CloudBeesSDAAnalyticsServer-x64-<version>
- Windows: CloudBeesSDAAnalyticsServer-x64-<version>.exe
  
  The Welcome to the CloudBees Analytics CloudBees CD/RO Installer screen appears.
Choose one of the following options:
- Select Use existing configuration settings to upgrade your current installation without changing the settings.
- Select Update configuration settings to specify new parameters for the upgraded software.
Click Next to continue.

If you selected Update configuration settings, then several additional screens appear during the upgrade that let you specify new parameters for the software being upgraded. Click Next to continue.

The Move the server data directory checkbox lets you change the location of the CloudBees Analytics index data. This option is useful if the system ran low on disk space because the data files outgrew the space available on the volume where the data directory is configured. If you check the checkbox, the Server data directory field appears.

Complete the information on the Advanced Settings screen, and click Next to continue. The Remote CloudBees CD/RO Server screen displays.

If you are currently using the default password for the reportuser user for regular access to the CloudBees Analytics server services, CloudBees recommends that you enter y so that you can change that password.

Complete the following, as appropriate.
- Skip CloudBees CD/RO server configuration — Determines whether to skip the automatic configuration of the remote CloudBees CD/RO server with the services being installed. If you choose this option, fill in the fields in the screen as follows:
- Server host name — Name of the CloudBees CD/RO server that will communicate with this CloudBees Analytics server. If the remote server is using a non-default HTTPS port, you must enter <host>:<port>.
- CloudBees CD/RO User Name — Name of a CloudBees CD/RO user on the CloudBees CD/RO server who has sufficient privileges to edit server settings. This field defaults to the CloudBees CD/RO-supplied admin user.
- Password — Password for the CloudBees CD/RO user. The default password for the admin user is changeme.
Click Next. The Ready to Upgrade screen appears.
Review your upgrade settings. Use the Back button to change your selections if necessary.
Click Begin Upgrade to continue.

The installer displays a status bar to show the progress of the upgrade process. You can also view the installer-CBSDAAnalyticsServer.log file to see the upgrade progress. Once this process is complete, the new CloudBees Analytics server version is installed:
Click Finish to complete the upgrade.

Interactive Command-Line Upgrade Method

The command-line user interface upgrade method is supported only by Linux platforms. In this mode, additional command line parameters that are listed in CloudBees Analytics Server Silent Unattended Installation Example can be used.

Use the following procedure to complete an interactive command-line upgrade of a Linux platform.

Choose one of the following commands:
- On Linux without the X Window System, enter sudo ./CloudBeesSDAAnalyticsServer-x64-<version>
- On Linux with the X Window System, enter sudo ./CloudBeesSDAAnalyticsServer-x64-<version> --mode console
  
  This command prevents the installer from automatically invoking the installation graphical user interface.
  
  The following prompt appears:
  Logging to "/tmp/ijtmp_604C8462-46F8-7E8E-90EE-0B51FD317C01/installer-CBSDAAnalyticsServer.log"
  ▼
  Installing temporary... Copyright (c) 2006-2024, CloudBees, Inc. All rights reserved.
  ▼
  Version <version> of CloudBees Analytics Server is already installed on this machine.
  ▼
  Repair or reconfigure the server? [n/Y]
  ▼

Enter y.

The following prompt appears:

Do you want to update configuration settings? [y/N]▼

Choose one of the following options:
- To upgrade your current installation without changing the settings, enter n.
- To specify new parameters for the upgraded software, enter y.
  
  The following prompt appears:
  Choose the port which will be used by CloudBees Analytics server [9201]
  ▼
  The CloudBees Analytics server uses the OpenSearch search engine to gather and store data from the CloudBees CD/RO server for use in the CloudBees Analytics dashboards.
If you want to specify a non-default port number, enter that number, or accept the default port number by pressing Enter.

The following prompt appears:
```
Choose the port which will be used by the CloudBees SDA Analytics server for communication between nodes within the cluster [9301]▼
```
This port is used for internal communication between nodes within the CloudBees Analytics cluster.
If you want to specify a non-default port number, enter that number, or accept the default port number by pressing Enter.

The following prompt appears:
```
Do you want to specify additional cluster mode settings? [y/N]▼
```
(Optional) Enter y if you want to add this system to a CloudBees Analytics server cluster. Otherwise, enter n.

If you enter y, the following prompt appears:
```
Please ensure that all nodes in the cluster are configured with the same cluster name.▼
```
```
Specify the name of the CloudBees Analytics cluster [analytics]▼
```
The following prompts related to the cluster are skipped if you declined to configure it automatically.
Enter the name of the cluster.

The following prompt appears:
```
Specify the name of this node [<hostname>]▼
```
Enter the name of the node to be installed or press Enter to accept the default value.

This serves as a unique identifier and therefore must be a unique name in the cluster.

The following prompt appears:
```
Specify comma-delimited list of other nodes in the cluster that are likely to be live and reachable [127.0.0.1,[::1]]▼
```
Enter any additional nodes that are running CloudBees Analytics and can become part of the cluster.

These can be any nodes (whether they are master-eligible or not). You can enter any combination of IP addresses or host names.

The following prompt appears:
```
Is this node eligible to be elected as the master node, which controls the cluster? [n/Y]▼
```
Enter Y if this node is master-eligible. (If this is the only node, it must be master-eligible.) Otherwise, enter n.

The following prompt appears:
```
Does this node holds data and performs data related operations such as CRUD, search, and aggregations? [n/Y]▼
```
Enter Y if this node holds data and performs data-related operations such as CRUD, search, and aggregations. Otherwise, enter n.

The following prompt appears:
```
Is this node able to apply an ingest pipeline to a document in order to transform and enrich the document before indexing? [n/Y]▼
```

Enter Y if this node is able to process an ingest pipeline. Otherwise, enter n.

The following prompt appears:

Installer will automatically create a user with user name "reportuser" to connect to CloudBees Analytics.▼

Specify a password for this user []▼

Enter the password that will be used to access the server. The installer will automatically create a user named reportuser with the password that you provide. If you do not specify a password, the installer generates a default password changeme.

The following prompt appears:
```
Confirm password []▼
```

Enter the same password as before.

The following prompt appears:

Do you want to regenerate the certificates used for secured access to CloudBees Analytics Server? [y/N]▼

Enter y if you want you regenerate the certificates that are used by the CloudBees Analytics services. Otherwise, enter N.

The following prompt appears:

Do you want to provide the certificate file containing a CA-signed certificate for the CloudBees Analytics Server, any intermediate CA certificates and a private key [y/N]▼

Enter y if you want to provide the path to a new PKCS#12 certificate file of the signing certification authority used for TLS/SSL certificates. Otherwise, enter N.

Any certificate regeneration will occur with the new certificate if you specify one.

The following prompt appears:
```
Do you want to move the server data directory? [y/N]▼
```
Enter N to continue, or enter y to specify different directory locations.

The following information appears:
```
Installing CloudBees Analytics Server...
Installing server...
Installing jre-64...
Copied log file to "/opt/cloudbees/sda/logs/analytics"
Installation complete.▼
```
The CloudBees Analytics server uses the OpenSearch engine to gather and store data from the CloudBees CD/RO server for use in the various CloudBees Analytics dashboards.

CloudBees CD/RO is installed on the machine.

Silent (Unattended) Upgrade Method

You can run the CloudBees Analytics server installer in unattended (silent) mode with no user interface on either Windows or Linux. Enter one of the following commands from a command line.

Linux: sudo ./CloudBeesSDAAnalyticsServer-x64-<version> --mode silent <arguments>
Windows: CloudBeesSDAAnalyticsServer-x64-<version>.exe --mode silent <arguments>

where:

<version> is your CloudBees Analytics server version number.
<arguments> represents any additional silent install arguments for upgrading the server.

For a list of the available arguments, see Silent Install Arguments .

Configuring

If you chose to skip the option to configure the remote CloudBees CD/RO server during the installation or upgrade of the CloudBees Analytics server, you must do so afterward to ensure connectivity and authentication between the CloudBees Analytics server and the CloudBees CD/RO server. To do this, navigate to Administration Configurations Analytics server. For details, refer to Configuring the CloudBees Analytics server.

Checking the configuration

You can confirm the correct CloudBees Analytics server settings by entering the following ectool command on the CloudBees CD/RO server command line:

ectool getAnalyticsServerConfiguration▼

Following is sample output:

<response requestId="1" nodeId="10.30.176.76">
    <analyticsServerConfiguration>
      <analyticsServerConfigurationId>fd48b25e-e74a-11ee-9cbf-02425ed14558</analyticsServerConfigurationId>
      <analyticsServerUrl>https://prodhost.internal:9201</analyticsServerUrl>
      <createTime>2024-03-21T06:19:35.801Z</createTime>
      <enabled>1</enabled>
      <lastModifiedBy>admin</lastModifiedBy>
      <modifyTime>2024-03-21T06:20:21.521Z</modifyTime>
      <owner>admin</owner>
      <userName>reportuser</userName>
    </analyticsServerConfiguration>
</response>▼

For details about the getAnalyticsServerConfiguration options, enter

ectool getAnalyticsServerConfiguration --help▼

Testing connectivity and authentication

After you enable connectivity and authentication between the CloudBees Analytics server and the CloudBees CD/RO server, you can perform a test by using one of the following methods:

Check the Test Connection option on the Administration Configurations Analytics server, then select Save.

Enter the following ectool command on the CloudBees CD/RO server command line:

ectool setAnalyticsServerConfiguration --testConnection 1▼

For details about the setAnalyticsServerConfiguration options, enter

ectool setAnalyticsServerConfiguration --help▼

For example, the following response appears if the user name or password is incorrect:

ectool error [InvalidCredentials]: HTTP/1.1 401 Unauthorized: Access to 'https://prodserver.internal:9201' is denied due to invalid credentials.▼

Also, for example, the following response appears if you specify an invalid analyticsServerUrl:

ectool error [ConnectException]: HTTP/1.1 404 Not Found: Failed to connect to server on 'https://localhost:9201'.▼

The following example shows the response when a valid analyticsServerUrl is used:

ectool setAnalyticsServerConfiguration --analyticsServerUrl https://prodserver.internal:9201 --testConnection 1
<response requestId="1" nodeId="10.30.176.76">
    <analyticsServerConfiguration>
      <analyticsServerConfigurationId>fd48b25e-e74a-11ee-9cbf-02425ed14558</analyticsServerConfigurationId>
      <analyticsServerUrl>https://prodserver.internal:9201</analyticsServerUrl>
      <createTime>2024-03-21T06:19:35.801Z</createTime>
      <enabled>1</enabled>
      <lastModifiedBy>admin</lastModifiedBy>
      <modifyTime>2024-03-21T06:20:21.521Z</modifyTime>
      <owner>admin</owner>
      <userName>reportuser</userName>
    </analyticsServerConfiguration>
  </response>▼

To do so, you use the Administration > CloudBees Analytics Server tab in the Automation Platform. For details, refer to Configuring the CloudBees Analytics server.