Upgrading to BuildMaster 6.2

KB#1766: Last Updated May 26, 2020

This document is for BuildMaster 6.1 users only

Using v3 or v4? see KB#1151 Upgrading from BuildMaster v3 and v4 for upgrade options

Using v5? upgrade directly to v6.1 (KB#1163 Upgrading to BuildMaster 6.1)

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.

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: 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 re-imported as non-legacy executions.

New Feature: Releases are now Optional

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, and your deployment plans may be expecting referenced builds in other applications to have a release number.

New Feature: Enhanced Pipeline Deployments & UX

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.

Upgrade Impact: Existing Pipeline Stage Event Listeners are executed very differently now, and custom ones may not execute

New Feature: Support for Externalized Assets (Rafts)

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: All of the underlying storage tables (Pipelines, Deployment Plans, Templates, etc.) will be migrated to the RaftItems table and existing tables dropped.

Updated Feature: Resource Credentials

Resource credentials have been updated to split the concept of “secure resources” (third-party connection information) and “secure credentials” (secrets). This way,
connections to external systems can be configured in a consistent manner, but use different types of credentials depending on the API.

Impact: existing credentials are not touched and should function as the did in previous versions, and may be converted to the “split” style in the UI.

How do I Upgrade?

Before upgrading to v6.2, you should come up with a migration plan. See the
6.2 Migration documentation for more information.

Performing a Direct Upgrade

Only direct upgrades from v6.1 are supported, and require additional prerequisites.

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. As such, we recommend that you install a new instance of BuildMaster and familiarize yourself with its changes before upgrading.

Upgrade Process

You can only upgrade from BuildMaster v6.1. To upgrade:

  1. Run the Legacy Feature Detector and ensure there are no features
  2. Download and run the Inedo Hub from my.inedo.com/downloads or use the latest traditional installer
  3. Remove old (Legacy SDK) extensions as appropriate
  4. Install the 6.1 extensions

Risk Mitigation

  • Make sure that your BuildMaster database is backed up prior to upgrade
  • Make sure that your Encryption Key is backed up prior to upgrade
  • Make sure that the installation’s \Extensions directory is backed up prior to upgrade

Rollback

Because there are database changes, a rollback will require uninstalling BuildMaster, and then restoring your BuildMaster instance.

Migrating to a New Instance

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 1: 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 2: 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 3: 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. This data is very valuable in case you experience 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.