Upgrading from BuildMaster v3 and v4

KB#1151: Last Updated Nov 19, 2018

BuildMaster v3 and v4 are semi-retired , which means that we will provide very limited support to users who have not yet upgraded, and will provide assistance in performing upgrades. However, we will no longer ship maintenance releases, patches, or other changes.

This means you should upgrade when possible, and this article provides guidance on how to upgrade from these older versions.

  1. Decide: Upgrade or Retire?
  2. Plan to update to 4.9.10
  3. Backup,upgrade to 4.9.10, then test
  4. Upgrade SQL Server, if necessary
  5. Plan to upgrade to v6
  6. Upgrade to v6

1. Upgrade or Retire?

As an alternative to upgrading, you start with a fresh instance of BuildMaster, "retire" your old version, and manually migrate your applications. While retiring your old instance will offer a fresh start, if you don't dedicate sufficient resources to the migration effort, you'll end up with two actively installations of BuildMaster. The "legacy" instance will go the way of COBOL… which may mean it could stick around beyond your retirement, and left in the hands of your poor predecessors to maintain.

If you've configured a lot of relatively small applications with relatively infrequent deployments, you should definitely upgrade. While you won't be able to test or otherwise verify each of these applications, they will probably still work… and if they don't, you can fix them on an as-needed basis.

2. Plan to Upgrade to 4.9.10

BuildMaster v5 was a transformative change to the product, and deprecated several legacy features and introduced some breaking changes, including a platform change (.NET 4.0 to 4.5). - BuildMaster v6 wasn't nearly as big of a change, however.

BuildMaster 4.9.10 will provide upgrade guidance by identifying deprecated features and blockers that would prevent you from successfully upgrading to v6.

Note that, because v6 was published much later than 4.9.10 was released, it will refer to BuildMaster v5 instead of v6. The same guidance applies, and you should still plan to directly upgrade to v6 from 4.9.

Regardless of what version you're currently on, you should plan to upgrade directly to 4.9.10. Do not plan to do "incremental" upgrades, as that will only increase the risk of agent auto-updates failing and other problems.

Depending on what version you're currently using, there may be a lot of changes between that and 4.9.10. Although we've already fixed all of the reported v3 and v4 bugs, you should still plan to do a full regression test after upgrading to 4.9.10. You will need to use this same plan when upgrading to v6.

Develop Regression Test Plan

Immediately after upgrading to 4.9.10, and then to v6, you should run a fairly comprehensive regression test. While it's impractical to test deployment of production applications, you can certainly set up a "test application" that validates a lot of the functionality you're using, and make sure it behaves the same after each upgrade.

Ensure all servers are "green"

If you have servers configured in BuildMaster that are no longer in use, they should be deactivated or deleted. Otherwise, BuildMaster will attempt to contact and upgrade these servers after you upgrade, and that may cause more headaches later

Upgrading from v3 to v4.9.10

BuildMaster v4 introduced three notable breaking changes that probably won't impact you, but that are worth noting nonetheless:

  • Changed platform to .NET 4.0 (from .Net 2.0); this is already preinstalled on all supported Windows servers
  • Removed support for mono-and WCF-based agents; you should migrate to Self-hosed or SSH agents (provided by Linux estension in v3) prior to upgrade
  • Changed date storage from local to UTC time; this will cause timestamps recorded during daylight savings time to be off by one hour

Because of the platform change, you will need to manually update all agents. See KB #1064: Upgrading Agents for BuildMaster 4.0 for guidance.

In addition, several extensions were deprecated or renamed in v4:

  • DotNet2 - now included in WindowsSDK extension
  • GeneralRecipes – renamed to Tutorials, but will be deprecated in v5
  • HTTP and Linux - now included in the core product
  • SFTP – deprecated in favor of the SSH agent

SDK & API Changes

If you have custom BuildMaster extensions or other tools that interact with the BuildMaster API, you may need to recompile extensions and/or tweak your tools to function with v4.9.10, and then again for v6. Depending on how extensively you use, it may be worth it to wait until after you upgrade to v6

3. Backup, Upgrade to 4.9.10, then Test

Prior to performing the upgrade, you should perform a backup of your installation. The current backing-Up BuildMaster instructions will be relevant, with the exception of the "Encryption Key"; this was introduced in v5.

To upgrade, simply run the 4.9.10 installer. Do not select the automatic backup option, as you will have already backed up the installation. Once the installation completes, the service will start, the agents will begin automatically updating.

Prior to executing your test plan, make sure all of the agents are in a "ready" state. Like with all v3 and v4 upgrades, the auto-update process may take some time. If you're seeing a lot of failures, and restarting the BuildMaster service doesn't help, you may need to manually upgrade the agents. The good news is, in v5 this process is much smoother.

After the agents are "green", run your test plan to identify issues to resolve.

4. Upgrade SQL Server if necessary

BuildMaster v3 and v4 bundled SQL Server 2005 Express, which is no longer supported by Microsoft. As such, we have stopped supporting it in our products.

If you're still using SQL Server 2005, you will need to upgrade it to at least SQL Server 2008, though you should use the latest version when possible to ensure patches and updates from Microsoft.

Because this is often handled by a DBA or infrastructure team, this article will not discuss how to upgrade SQL Server. We're happy to help if you'd like assistance, please contact us as needed.

5. Plan to upgrade to the latest v6

BuildMaster 4.9.10 has a significant number of non-functional changes from code/database refactoring in preparation for the v5 release. As such, we recommend continuing to use this version until you are confident that it works as well as the previous version. We have had very few issues reported from users about these non-functional changes.

Once you are confident that BuildMaster 4.9.10 is functioning adequately, you can begin planning for v6.

The first step in doing this is follow the upgrade guidance provided in the software by identifying deprecated features and blockers that would have prevented you from successfully upgrading to v5. These will apply when you upgrade to v6.

After that, you should review the upgrade notes to learn about the major changes that were introduced through v5 and the upgrade notes for v6.

Just remember: plan to upgrade directly to the latest v6. The changes in the v5 article primarily serve as informational, to let you know what to expect between v4 and v6.

Upgrade to the latest v6

Prior to performing the upgrade, you should perform a backup of your installation. The current backing-Up BuildMaster instructions will be relevant, with the exception of the "Encryption Key"; this was introduced in v5.

To upgrade, simply run the the Inedo Hub installer. This should detect your current installation and be able to upgrade it.

Do not select the automatic backup option, as you will have already backed up the installation. Once the installation completes, the service will start, the agents will begin automatically updating.

Prior to executing your test plan, make sure all of the agents are in a "ready" state. Like with all v3 and v4 upgrades, the auto-update process may take some time. If you're seeing a lot of failures, and restarting the BuildMaster service doesn't help, you may need to manually upgrade the agents. The good news is, we've greatly improved this process since.

After the agents are "green", run your test plan to identify issues to resolve.

Next Steps: Legacy Feature Migration

From here, you should start planning to move away from legacy features in BuildMaster. Take a look at KB #1144: BuildMaster Legacy Features for some guidance on how to do this.