Upgrading CloudBees Build Acceleration on Windows

6 minute read
Installing a component overwrites the entire installation on that machine. Only one CloudBees Build Acceleration installation can exist on a machine, which is the combination of components that are in the most recent installation. For example, installing the Cluster Manager on a machine with the Electric Agent results in a machine with the Cluster Manager only, not a machine with the Electric Agent and the Cluster Manager.

You can install the Cluster Manager and agents at the same time on the same machine.

Upgrading the Cluster Manager

  • The Cluster Manager server and agent hosts must run the same version of CloudBees Build Acceleration.

  • If you want to upgrade the Cluster Manager and migrate the database to a different machine, you must first upgrade the Cluster Manager (to update the existing database’s schema), then migrate the database to the new machine.

  • The remote database configuration upgrade might trigger a warning. The Cluster Manager can connect to a remote database, and the user can shut down the local database (if applicable).

    During the upgrade, the installer cannot reach the local database (because it is shut down already), so it gives this prompt:

    Unable to contact the database. Please enter a correct username/password: Root User (empty=no database migration):

    Leaving the value empty lets the installer finish. Upon completion, a warning message appears. This is the expected behavior and does not indicate a problem.

  • The duration of the database schema upgrade might trigger an extraneous failure message. During a CloudBees Build Acceleration upgrade, the installer attempts to connect to the Cluster Manager. Because the Cluster Manager handles the database schema upgrade, a large database might cause the Cluster Manager to take a long time to finish the upgrade.

    A failure message stating that the Cluster Manager failed to start might appear. This message does not indicate an actual failure and means only that the Cluster Manager is still processing the schema upgrade. The Cluster Manager will load after the schema upgrade completes.

  • To back up and restore your database, use the exportData and importData cmtool commands as described in the cmtool Reference Guide.

  • CloudBees no longer bundles MySQL as the default local database for CloudBees Build Acceleration. Starting with CloudBees Build Acceleration version 7.1, CloudBees bundles MariaDB and installs it as the default local database on the Cluster Manager. When you perform a Cluster Manager upgrade, MariaDB replaces the local MySQL database (if applicable) and migrates all information from it.

    MariaDB is an open-source database that is fully compatible with MySQL. As open-source software, there is no enterprise license support model available with MariaDB. If using an open-source database is of concern to your organization, you continue to have the option to use any of the following databases as a replacement: MySQL, Oracle, or SQL Server. See the online help topic “Database Configuration” for information about configuring CloudBees Build Acceleration to use an external database.

To upgrade the Cluster Manager:

  1. Sign in as Administrator.

  2. Ensure that no builds are running.

  3. Copy the installer executable to the Cluster Manager machine to a location such as c:\temp.

    Do not run the installer from a directory path that contains spaces (such as the Windows desktop).

  4. Double-click the CloudBeesAccelerator-<version> file.

    The Welcome screen appears after the installation packages are extracted.

  5. Proceed with the upgrade in the same way that you initially installed the Cluster Manager.

    Ensure that you type in the correct value for your Cluster Manager admin password. The encrypted default password is changeme.

    The upgrade fails if the correct password is not used. You can change the Cluster Manager admin password during the upgrade only if the current password is the default password.

  6. Accept the existing Cluster Manager configuration or update your configuration settings.

  7. When the Start Copying Files screen appears, click Next.

    The Installing screen appears. When installation is finished, the Complete screen appears.

  8. Click Finish.

  9. If you changed Cluster Manager ports during the upgrade, close your browser windows to avoid potential conflicts and to ensure that your settings take effect.

Installation is complete. The installation log file is in the installation directory’s root by default.

If Apache fails to start properly after the Cluster Manager installs, reboot the system.

Upgrading the Electric Agent/EFS

The Cluster Manager server and agent hosts must run the same version of CloudBees Build Acceleration.

Upgrading the Electric Agent/EFS on multiple hosts simultaneously

If you run ecclusterupgrade on a Windows Cluster Manager under a user account other than the administrator account, you might encounter a permission denied error. This is because of a Windows issue. The workaround is to run cmd using “Run as administrator” and then run ecclusterupgrade.

To upgrade the Electric Agent/EFS on multiple hosts simultaneously:

  1. Sign in as Administrator.

  2. Ensure that no builds are running.

  3. Copy the installer executable to the Cluster Manager machine to a location such as c:\temp.

    Do not run the installer from a directory path that contains spaces (such as the Windows desktop).

  4. On the Cluster Manager machine, cd to the CloudBees Build Acceleration bin directory and run:

    ecclusterupgrade.exe

    Depending on your setup, you might need the following options as well:

    • --agentinstalldir=<path> indicates the agents’ installation location. All agents that you want to upgrade must have the same installation location. If this is not true, you must run the script multiple times using the relevant --agentinstalldir path names. You must also specify the --hosts option to limit the upgrade to machines that use the nonstandard agent installation directory.

    • --targetos=<os> limits which operating system to upgrade. indicates which operating system to update. Available values for <os> are windows and linux. This lets you update any operating system type from any operating system.

    • --hosts="host1 host2 …​" specifies a list of hosts to upgrade. You can also use a pattern such as host[1-3], host[2,5].

    • For multiple installer versions, use one of the following options:

      • --installerversion=<version> to select the version. You need this option only if there are multiple installer versions in the local/<installerdir> location.

      • --installer=<filename> to explicitly select an installer. Use an absolute file name for this option.

See ecclusterupgrade Options for all ecclusterupgrade options.

Following is an example of an ecclusterupgrade command. This command upgrades two agents:

ecclusterupgrade.exe --installer=c:\tmp\CloudBeesAccelerator-7.1.1.48690-Windows-Install.exe --hosts="agent1 agent2"

Upgrading the Electric Agent/EFS on a single cluster host

The Electric Agent/EFS upgrade process for a single host machine is similar to a new Electric Agent/EFS installation, with one important exception, which is detailed below. To upgrade the Electric Agent/EFS on a single cluster host:

  1. Sign in as Administrator.

  2. Ensure that no builds are running.

  3. Copy the installer executable to the agent machine to a location such as c:\temp.

    Do not run the installer from a directory path that contains spaces (such as the Windows desktop).

  4. Double-click CloudBeesAccelerator-<version>.

    The Welcome screen appears after the installation packages are extracted.

  5. Click Next to continue.

  6. On the Do you want to upgrade CloudBees Build Acceleration with the same settings? screen, select Yes and then click Next.

    If you want to automatically initialize Visual Studio for ECloudInternalUser users on your agent hosts, select No to enter custom upgrade mode and then select the Initialize Visual Studio for ECloudInternalUsers checkbox on the next screen that appears. (Using this checkbox can add up to 30 minutes to the installation time, depending on the number of agents and the number of installed Visual Studio versions.)
  7. On the Which components do you want to install? screen, select Electric Agent.

  8. Click Next to continue to the next screen.

    The Installing screen displays while the upgrade progresses. When the upgrade is finished, the Wizard Complete screen appears.

  9. Click Finish.

  10. When the Really Reboot? popup appears, click Yes to reboot your system.

Installation is complete. The installation log file is in the installation directory’s root by default.

Upgrading eMake

To upgrade an eMake installation, you simply overwrite the existing eMake version using the same procedure as your initial eMake installation.

If you are uninstalling eMake before an upgrade, if eMake and the Cluster Manager are installed on the same machine, uninstalling eMake removes the Cluster Manager.

Using the ecconfig command

Open a command-line window to use ecconfig. The following table is the output from running ecconfig.exe -help.

Argument Description

-cm <host>:<port>

Host and port number of the Cluster Manager that the agent host should point to

-numagents <number>

Number of agents to start. If you modify the number of agents, you must restart the agents for your change to take effect. After the restart, the server database is updated, and the agents become active

-agentusers "<username1>/<password1> <username2>/<password2> …​ <usernameN>/<passwordN>"

Agent user names and passwords

You must specify the same number of username-password pairs as the number of agents. The argument must be encapsulated in quotes

-agentuser "<agentID> <username>/<password>"

User name and password for a specific agent , where <agentID> is the numerical ID of the agent to configure (between 1 and <numagents> )

-lsfhost <value>

y or n. Type y to specify that this machine is part of an LSF grid or n for no

-secureconsole <value>

y or n. Type y to secure the agent console port or n for no

-tempdir <path>

Location where agents will store temporary files. Leave blank for the system temporary directory

-help or -?

Print this message