Upgrading a non-clustered environment

4 minute readDeveloper productivity

This section describes how to upgrade the software. The procedure is the same as when you upgrade CloudBees CD/RO and upgrade cluster configurations at the same time, except that you do not need to perform additional tasks to upgrade the cluster.

After upgrading from CloudBees CD/RO 10.8 or older version, you should delete all .old files, such as .properties.old in the conf subdirectory to finish encryption process.

To upgrade, use the CloudBeesFlow-<version> installer, which performs the following:

  • Collects the CloudBees CD/RO service account credentials.

  • Uninstalls the current release.

  • Installs the latest CloudBees CD/RO release.

  • Configures the system with all property values mined.

  • Restores custom files and data.

After preparing for the upgrade, make sure to shut down the CloudBees CD/RO server service before installing the newer version of CloudBees CD/RO.

These instructions presume you are upgrading from CloudBees CD/RO v5.x or later. To upgrade from v4.2.x or earlier, contact CloudBees Support directly for extra instructions.

Upgrading from version 9.1 or earlier

If you are upgrading CloudBees CD/RO from version 9.1 or earlier, to version 9.2 or later, a new passkey with AES 256-bit encryption is automatically generated, replacing the older 128-bit passkey. During the database upgrade phase of the process, the CloudBees CD/RO server re-encrypts the following using the newly generated passkey.

  • All the credentials in the system including the COMMANDER_DB_PASSWORD in database.properties

  • User credentials

  • Passwords in email configurations

  • CloudBees Analytics configuration passwords

If you encounter any issues with your passkey after completing this upgrade, do not apply your passkey from your previous system as this will likely cause your database credential data to become corrupted. Please contact CloudBees Support if you encounter issues to help analyze whether the upgrade can be salvaged or if a repeat of the effort may be required.

Upgrade testing

In most implementations, CloudBees CD/RO is being used in an environment that affects many users. We recommend that you test your upgrade on a separate test server to understand all aspects of the upgrade process. This minimizes the potential impacts to downstream users.

Backing up your existing CloudBees CD/RO data

Before upgrading a CloudBees CD/RO server, you must back up your existing CloudBees CD/RO data. See CloudBees CD/RO Server Backups for more information about backups.

Backing up custom files

The CloudBees CD/RO files that might have been modified are too numerous to list, so you should back up the entire CloudBees CD/RO data directory and other miscellaneous files that might have changed. However, you must back up the following files:

  • The plugins directory. The default location is the plugins subdirectory within <data_dir>.

  • Files that contain custom configuration data. To ensure that important settings are saved, back up the following subdirectories in <data_dir>:

    These properties are stored in the server-level property sheet, which can be viewed in the web UI by accessing the Administration tab/Server subtab.
    • The entire conf subdirectory, which contains the CloudBees CD/RO server and agent configuration files.

    • Apache web server configuration files in the apache/conf subdirectory.

    • (If applicable) The local MySQL database configuration file, my.ini, in the mysql subdirectory.

    • (If you use an artifact repository) The CloudBees CD/RO repository configuration files in the conf/repository subdirectory.

  • Any other files where you created custom configurations, specified other custom information, or created any type of modification.

    The upgrade process overwrites default custom editor and preflight driver scripts nested property sheets. Therefore, we recommend backing up the ec_customEditors and ec_preflight property sheets.
  • Backup the ec_customEditors and ec_preflight property sheets by renaming them. For example, change ec_preflight/clientDrivers/perforce to ec_preflight/clientDrivers/perforce_modified.

Saving the upgrade installer

After you back up your CloudBees CD/RO server, create a folder where you can download the CloudBeesFlow-<version> installation file.

Starting the installation process

Install the upgrade by choosing the correct upgrade method for your environment.

Copying repository contents

After you have updated CloudBees CD/RO, perform the following steps to copy the contents of an existing repository server into a newly installed repository server:

  1. Install the new repository server software.

  2. Stop the existing and new repository servers.

  3. Copy the entire contents of the repository backingstore directory from the existing repository server to the corresponding location on the newly installed repository server.

    The default location for the backingstore directory (<datadir>/repository-data) is:

    • UNIX: /opt/cloudbees/sda/repository-data

    • Windows: C:\ProgramData\CloudBees\Software Delivery Automation\repository-data

Configuring CloudBees CD/RO server, agent and Repository server logging

If you defined custom log settings for CloudBees CD/RO, you must migrate this data from the current log configuration file to the new one.

Use these steps to configure each new file referenced in the table below.

  1. Copy data from current file into new file.

  2. Modify this configuration entry from ` logger("org.hibernate.SQL", TRACE)` to 'org.hibernate.SQL=TRACE'

    Log Type Current file New file

    CloudBees CD/RO server

    /opt/electriccloud/electriccommander/conf/logback-local.groovy

    /opt/cloudbees/sda/conf/logback-local.groovy

    /opt/cloudbees/sda/conf/logging-local.properties

    Agents

    /opt/electriccloud/electriccommander/conf/agent/logback-local.groovy

    /opt/cloudbees/sda/conf/agent/logback-local.groovy

    /opt/cloudbees/sda/conf/agent/logging-local.properties

    Repository Server

    /opt/electriccloud/electriccommander/conf/logback-local.groovy

    /opt/cloudbees/sda/conf/logback-local.groovy

    /opt/cloudbees/sda/conf/logging-local.properties

MySQL upgrades

CloudBees CD/RO upgrades involving a MySQL database can take several hours to complete if you have a significant data set. Do not interrupt the upgrade process. You can corrupt your database if the upgrade process is interrupted. A restore from a previous database backup will be required.

Use the ectool to view the upgrade progress. On a command line, enter:

ectool getServerStatus

An install/upgrade log file named installer.log is created in the logs subdirectory in the data directory.