BuildMaster 6.2 Upgrade Notes

KB#1766: Last Updated December 13, 2019

What’s in this Update?

BuildMaster 6.2 is a major upgrade, with a number of breaking changes and significant new features. Review this article carefully before deciding when and how to upgrade.

Beta Note: although BuildMaster 6.2 is installed by default on new installations, and we’ve been using it on our public instance for a while, we still consider BuildMaster 6.2 to be a pre-release, as there are unfinished features, documentation, and various UI bugs that we are working out

Release Development Status

BuildMaster 6.2 is installed by default on a new installation; we still need to complete a few features before supporting direct upgrades, however.

Legacy feature removal Complete (6.2-m1)
Enhanced pipeline feature Complete (6.2-m1)
Rafts feature Completed (6.2-m2)
Nested applications feature Not started
Direct upgrade support Not started

We will update this table periodically.

Breaking Change: Legacy Features Removed

All of the legacy components in BuildMaster have been removed. See KB #1144 BuildMaster Legacy Features for a complete list of legacy features. Most of these features have been hidden by default on new installations since v5 (2016). If you’re still using any of them, pay special attention to the migration strategies in this document.

Upgrade Impact (when available): all of the features in the linked document will no longer be available, and all legacy executions logs (from legacy deployment plans) will be removed. To retain legacy execution data, you can export applications; those will be reimported as non-legacy executions.

New Feature: Releases are now Optional (m1)

Builds have always been tightly coupled to releases in BuildMaster, but there are many situations where builds and deployments ought to be performed without being part of a formal “release,” such as:

  • Early/testing builds created via [Continuous Integration] processes that will never be released
  • Simple applications (such as documentation or other static content) that don’t require a change management process outside of source control or merge requests
  • Deployment of imported artifacts imported from drop paths or continuous integration servers

To better support this workflow and make it easier to get started adopting BuildMaster, we’ve added the ability to create builds that aren’t associated with any release at all.

Impact: It’s now possible to create a build with no release at all. The UI is still under development for this, so this is something that you may end up doing by accident in the course of evaluating BuildMaster 6.2. This also involved a number of internal changes that could cause deployment runtime errors.

Upgrade Impact (when available): This will have minimal impact, as it’s expanding options of what you can do with Builds

New Feature: Enhanced Pipeline Deployments & UX (m1)

When promoting a build to a pipeline stage, this promotion itself is now run using the OtterScript runtime. This enables more advanced deployment scenarios and allows you to control more aspects of deployment using custom OtterScript. The Pipeline Editor and UX was also rewritten and improved.

  • Run pre-deployment scripts to configure variables used later in the deployment, shut down-services, or otherwise prepare for deployment
  • Use variable expressions for target servers or roles
  • Run post-deployment scripts that can clean-up after deployment, send notifications, etc.
  • Have a single, unified logging experience for the entire deployment to help diagnose problems

Impact: Instead of using Pipeline Stage event listeners, post-deployment-step tasks are recommended. As always with new code, the new execution model may have bugs related to pipeline stage deployments.

Upgrade Impact (when available): Pipeline Stage Event Listeners are executed very differently now, and custom ones may not execute

New Feature: Support for Externalized Assets (m2)

Deployment plans, OtterScript modules, scripts (PowerShell/sh), and pipelines can now be stored in external repositories called Rafts. This allows these resources to be stored in places other than BuildMaster’s database, such as in a Git repository or a file system directory.

Impact: Prior to 6.2, all of these assets were stored in BuildMaster’s internal database, and were generally referenced by a surrogate key (i.e. a pipeline id) instead of by name; while we never supported referencing these identifiers, if you did, they will no longer work

Upgrade Impact (when available): All of the underlying storage tables (Pipelines, Deployment Plans, Templates, etc.) will be migrated to the RaftItems table.

New Feature: Nested Applications (m3)

Applications can now be logically nested in other applications, allowing for a more natural hierarchical organization scheme.

How do I Upgrade?

Currently, upgrading from BuildMaster 6.1 or earlier is not supported. Note that this is only temporary, and the future we will simply block upgrades of installations that use legacy features.

The Inedo Hub should not display BuildMaster 6.2 as an upgrade option, and it will crash if you accidentally attempt to upgrade a 6.1 installation (e.g. by installing on top of an old one). This is to ensure there is no loss of data from the dropped legacy features.

However, it is still possible to upgrade using the application import/export feature. See migration strategies below.

Upgrade & Migration Strategies

Because of the large number of changes in this release, performing a direct upgrade from BuildMaster 6.1 is risky, especially if you have been using BuildMaster since before v5.

Option 1: Direct Upgrade

This isn’t currently supported; in the future we will provide a mechanism for performing an in-place upgrade, but for now you will need to start with a fresh install.

Important: All of the options listed below require a fresh install of BuildMaster 6.2. Install a new instance of BuildMaster and familiarize yourself with its changes before migrating.

Option 2: Fresh Start/Manual Migration

If you don’t have many applications in BuildMaster, or aren’t happy with the way you are currently use it, you may want to use your new BuildMaster 6.2 instance at first in a testing capacity in order to develop better plans/practices for your applications.

Review the getting started guide, run through the tutorial, and take a look at some of the example application templates; you may discover a new and better way to use BuildMaster in your organization. In this case, it may work better for you to simply “start over” or to manually copy bits of existing plans as needed.

Option 3: Individual Application Import

Export a single application from BuildMaster at a time into a universal package, and import that package into your new BuildMaster 6.2 instance. This will give you a good opportunity to discover any issues and to gradually migrate your applications to the new instance as you are able.

Generally, this approach will work best if you have a large number of applications, and some of them rely on legacy features that have been removed in BuildMaster 6.2. This way, you can bring over applications as the legacy dependencies are removed to take advantage of new features and capabilities, while still retaining the original instance for risk mitigation.

Option 4: All Application Import

Export all applications from BuildMaster, and import them all into the new BuildMaster 6.2 instance.

This is only a good option if you’re not using any of the removed legacy features in any of your applications.

Additional Migration Notes

  • Consider exporting your infrastructure from the original instance and importing into the new one before doing anything else. This will prevent you from having to recreate servers, roles, and environments in the new instance. Of course, if you really want to start fresh, you may want to skip this.
  • Upgrade your Inedo Agents to the latest version, and set the Agents.InstanceId advanced configuration setting to a unique value in your new BuildMaster 6.2 instance. This will allow your second instance to reuse the same agents without any interference.
  • Consider enabling CEIP. BuildMaster 6.2 is still qualified as prerelease, and this is the easiest way for you to provide feedback to us while we are still working on it. This data is also very valuable in case you come across any bugs or performance issues.
  • Don’t forget about permissions! Make sure you copy over any required permissions, or start from scratch if your original list has gotten too complicated.