Upgrading the CloudBees Analytics server

12 minute readDeveloper productivity

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.

  1. Uninstall the CloudBees Analytics server from the system.

  2. Upgrade the other CloudBees CD/RO components on the system.

  3. Install the new version of the CloudBees Analytics server on the system.

Preserving Non-CloudBees Analytics custom settings

The CloudBees Analytics installer overwrites the elasticsearch.yml configuration file with a new file. As of CloudBees Analytics version 8.3, the file includes a Custom Settings section, which lets you add Elasticsearch settings not managed by the CloudBees Analytics server without being lost during an upgrade. If you added settings to this file in version 8.2 or earlier that you want to preserve, you must back up the file to a separate location before upgrading to version 8.3 or newer versions and then add the settings to the Custom Settings section after the upgrade. During future upgrades, the installer will preserve the settings in the Custom Settings section.

User interface upgrade method

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

Use this procedure to upgrade the CloudBees Analytics server.

  1. Double-click the following file to run the installer.

    • Linux: CloudBeesFlowDevOpsInsightServer-x64-<version>

    • Windows: CloudBeesFlowDevOpsInsightServer-x64-<version>.exe

      The Welcome to the CloudBees Analytics CloudBees CD/RO Installer screen appears.

If you are upgrading a CloudBees Analytics cluster with more than one master node from CloudBees CD/RO v10.1 or below, you are presented with the following:

You will upgrade the cluster from version <VERSION>. In this case, the first master node to be updated must be configured with specific parameters. Please specify whether the current node is the first node to be updated in your cluster?

The answer must be yes only for the first node to be updated and no for the second and subsequent updatable nodes.

  1. 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.

  2. 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 Elasticsearch data directory checkbox lets you change the location of the Elasticsearch 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 Elasticsearch data directory field appears.

  3. 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 Elasticsearch 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.
  4. 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.

  5. Click Next. The Ready to Upgrade screen appears.

  6. Review your upgrade settings. Use the Back button to change your selections if necessary.

  7. 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-EFlowReportServ.log file to see the upgrade progress. Once this process is complete, the new CloudBees Analytics server version is installed:

  8. 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.

  1. Choose one of the following commands:

    • On Linux without the X Window System, enter sudo ./CloudBeesFlowDevOpsInsightServer-x64-<version>

    • On Linux with the X Window System, enter sudo ./CloudBeesFlowDevOpsInsightServer-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_C75F6886-BE25-D84C-BB8F-56EC5C16DBC1/installer-EFlowReportServ.log"
      Installing temporary... Copyright (c) 2006-2019, CloudBees, Inc. All rights reserved.
      Version <version> of {SDA-ANALYTICS} Server is already installed on this machine.
      Upgrade the server to <version> ? [n/Y]
  2. Enter y.

    The following prompt appears:

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

    If you are upgrading a CloudBees Analytics cluster with more than one master node from CloudBees CD/RO v10.1 or below, you are presented with the following:

    You will upgrade the cluster from version <VERSION>. In this case, the first master node to be updated must be configured with specific parameters. Please specify whether the current node is the first node to be updated in your cluster? [Y/n]

    The answer must be Y only for the first node to be updated and n for the second and subsequent updatable nodes.

  3. 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 Elasticsearch [9200]

      The CloudBees Analytics server uses the Elasticsearch search engine and the Logstash data-collection engine to gather data from the CloudBees CD/RO server for use in the CloudBees Analytics dashboards.

  4. 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 Elasticsearch service for communication between nodes within the Elasticsearch cluster [9300]

    This port is used for internal communication between nodes within the Elasticsearch cluster.

  5. 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 Logstash [9500]
  6. 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 Logstash service for the Logstash monitoring APIs [9600]

    This port is used by the Logstash monitoring APIs that provide runtime metrics about Logstash.

  7. 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 Elasticsearch cluster mode settings? [y/N] y
  8. (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 and the minimum number of master eligible nodes.
    Specify the name of the Elasticsearch cluster [elasticsearch]
    The following prompts related to the cluster are skipped if you declined to configure it automatically.
  9. Enter the name of the cluster.

    The following prompt appears:

    Specify comma-delimited list of other nodes in the Elasticsearch cluster that are likely to be live and reachable [127.0.0.1,[::1]]
  10. 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:

    Specify minimum number of master-eligible nodes that must be visible in order to form an Elasticsearch cluster [1]
  11. Enter the minimum number of master-eligible nodes that must be visible in order to form a cluster.

    For details about how to determine how many master-eligible nodes you need for your cluster, see Installing the CloudBees Analytics Server in Cluster Mode . The master node will be elected from the list of master-eligible nodes.

    For details about master-eligible nodes and master elections, see the Elasticsearch Reference at https://www.elastic.co.

    IMPORTANT:

    If you specify 1, you are asked to confirm this number in the following warning:

    The minimum number of master eligible nodes is set to 1. This can result in data loss in case of network failure in a cluster with two or more master eligible nodes.
    Please refer to the {PRODUCT} Installation Guide for more details.
    Please confirm if you would like to proceed. [N/y] n

    To prevent data loss in case of network failure, the minimum number of master-eligible nodes that must be visible in the cluster must be set to a quorum of master-eligible nodes:

    (Number of master-eligible nodes in the cluster / 2) + 1

    For example, in a cluster with three master-eligible nodes, the minimum number of master-eligible nodes should be set to 2.

    The minimum number of master-eligible nodes should be set to 1 only if you intend to run a single-node cluster. For a multi-node cluster, the minimum number of master-eligible nodes must be set to a quorum as described above.

    The following prompt appears:

    Specify the name of this node in the Elasticsearch cluster [loc-10-lin-ub1604-64]
  12. Enter the name of this node in the cluster.

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

    The following prompt appears:

    Is this node eligible to be elected as the master node, which controls the Elasticsearch cluster? [n/Y]
  13. 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]
  14. 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:

    Installer will automatically create a user with user name "reportuser" to connect to Elasticsearch.
    Specify a password for this user []
    If you are currently using the default Elasticsearch 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.
  15. 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 []
  16. Enter the same password as before.

    The following prompt appears:

    Do you want to regenerate the certificates used for secured access to {SDA-ANALYTICS} Server? [y/N]
  17. 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 {SDA-ANALYTICS} Server, any intermediate CA certificates and a private key [y/N]
  18. 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 Elasticsearch data directory? [y/N]
  19. Enter N to continue, or enter y to specify different directory locations.

    The following prompt appears:

    Do you want to specify the remote {PRODUCT} server which will be configured to interact with the services being installed?
  20. Enter y if you want to automatically configure the remote CloudBees CD/RO server to interact with the services being installed.

    The following prompts related to the configuration of the remote CloudBees CD/RO server are skipped if you declined to configure it automatically.

    The following prompt appears:

    Specify the host[:port] of the remote {PRODUCT} server []
  21. Enter the 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 specify the host name as <host>:<port>. If you do not specify a port, HTTPS port 8443 is assumed (the same as the CloudBees CD/RO server default port).

    The following prompt appears:

    Specify the user name with which to login to "<remote host>" [admin]
  22. Enter the 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.

    The following prompt appears:

    Specify the password for "<remote user>" on "<remote host>" []
  23. Enter the password for the CloudBees CD/RO user. The default password for the admin user is changeme.

    The following prompt appears:

    The {SDA-ANALYTICS} Server will be configured on {PRODUCT} server version <version> on <remote host>

    The following information appears:

    ============================================================ For {SDA-ANALYTICS} to work, please update the following settings on the {PRODUCT} server Go to the "Administration->{SDA-ANALYTICS} Server" tab and update the following: * Enable {SDA-ANALYTICS} * URL for Logstash service on the {SDA-ANALYTICS} Server: \https://ip-10-0-0-84.us-west-1.compute.internal:9500 * URL for Elasticsearch service on the {SDA-ANALYTICS} Server: \https://ip-10-0-0-84.us-west-1.compute.internal:9200 * Username: reportuser * Password: Password for authenticating with the {SDA-ANALYTICS} Server ============================================================ Installing {SDA-ANALYTICS} Server... Installing elasticsearch... Installing logstash... Installing jre-64... Copied log file to "/opt/cloudbees/sda/logs/reporting" Installation complete.

    The CloudBees Analytics server uses the Elasticsearch search engine and the Logstash data-collection and log-parsing engine to gather data from the CloudBees CD/RO server for use in the various CloudBees Analytics dashboards.

    CloudBees CD/RO is installed on the machine.

  24. 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.

      If you choose this option, prompts appear that let you specify new parameters for the software being upgraded:

      • The Is this node eligible to be elected as the master node, which controls the Elasticsearch cluster? [n/Y] prompt asks you whether you have made this node eligible to be elected as a CloudBees Analytics master node. Master-eligible nodes participate in updating the cluster state as well as elections of the master node.

      • The Does this node hold data and perform data related operations such as CRUD, search, and aggregations? [n/Y] prompt asks you whether you have made this node a CloudBees Analytics data node. A data node stores data that is indexed into Elasticsearch and performs data-related operations such as CRUD, search, and aggregations.

      • The Do you want to regenerate the certificates used for secured access to CloudBees Analytics Server? prompt lets you regenerate the certificates that are used by the CloudBees Analytics services. You can specify a new certificate file for the regeneration.

      • The 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] prompt lets you enter the path to a new certificate file. Any certificate regeneration will occur with the new certificate if you specify one.

      • The Do you want to move the Elasticsearch data directory? prompt lets you change the location of the Elasticsearch 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.

      • The xxx prompt lets you change xxx.

      • Detailed descriptions of the remaining prompts are in Running a CloudBees Analytics Server Interactive Command-Line Installation .

        If you are currently using the default Elasticsearch 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.

The following prompt appears:

Installing {SDA-ANALYTICS} Server...Installing elasticsearch...Installing logstash...Installing jre-64...Copied log file to "/opt/cloudbees/sda/logs/reporting"Installation complete.

The CloudBees Analytics server uses the Elasticsearch search engine and the Logstash data-collection and log-parsing engine to gather data from the CloudBees CD/RO server for use in the various CloudBees Analytics dashboards.

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 ./CloudBeesFlowDevOpsInsightServer-x64-<version> --mode silent <arguments>

  • Windows: CloudBeesFlowDevOpsInsightServer-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 .

If you are upgrading a CloudBees Analytics cluster with more than one master node from CloudBees CD/RO v10.1 or below you must use the following command line parameter during the upgrade for the first master node, where <NodeName> is the name of the first master node that is under upgrade:

--elasticsearchClusterInitialMasterNodes "<NodeName>"

Reconfiguring after the upgrade

The installers (GUI, interactive console, and silent mode) for the CloudBees Analytics server do not preserve the configuration setting for the CloudBees Analytics server host name ( --hostName ) or the setting for the Elasticsearch number of shards ( --elasticsearchNumberOfShards ) during the upgrade from 7.3 to 9.2. If you specified nondefault values during the 7.3 Reporting server installation, you must re-specify these settings during the upgrade. (All other settings are preserved.)

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 getDevOpsInsightServerConfiguration

Following is sample output:

<response requestId="1" nodeId="192.168.5.138"> <devOpsInsightServerConfiguration> <devOpsInsightServerConfigurationId>12642169-71c4-11e7-8a08-0050568f29b0</devOpsInsightServerConfigurationId> <createTime>2017-07-26T05:34:19.404Z</createTime> <elasticSearchUrl>https://192.168.5.54:9200</elasticSearchUrl> <enabled>1</enabled> <lastModifiedBy>admin</lastModifiedBy> <logStashUrl>https://192.168.5.54:9500</logStashUrl> <modifyTime>2017-07-26T05:40:13.458Z</modifyTime> <owner>admin</owner> <userName>reportuser</userName> </devOpsInsightServerConfiguration> </response>

For details about the getDevOpsInsightServerConfiguration options, enter

ectool getDevOpsInsightServerConfiguration --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 checkbox on the Administration  Configurations  Analytics server select OK.

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

    ectool setDevOpsInsightServerConfiguration --testConnection 1

    For details about the setDevOpsInsightServerConfiguration options, enter

    ectool setDevOpsInsightServerConfiguration --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://192.168.5.54:9500' is denied due to invalid credentials.

    Also, for example, the following response appears if you specify an invalid elasticSearchUrl or logstashUrl :

    ectool error [InvalidUrl]: The url 'https://192.168.5.54:9500' is invalid

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

    ectool setDevOpsInsightServerConfiguration --elasticSearchUrl https://192.168.5.54:9200 --testConnection 1

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