Upgrading from BuildMaster v5

BuildMaster v5 was a release designed to modernize the platform and software, introducing a variety of changes through nine different releases. This article is a compilation of all upgrade notes from BuildMaster 5.0 to 5.8 and covers the changes that may affect your installation, configuration, and customizations of BuildMaster. 

Change Summary

The following table summarizes all of the changes introduced throughout v5, and more details can be found below. In addition to these changes, there are two important things to note:

• Major SDK Changes will require a rebuild
• All extensions will need to be reloaded

Upgrade Process

You can upgrade from any BuildMaster 5.x version to the latest BuildMaster 6.1 simply by downloading and running the installer.

Risk Mitigation

Although the risks vary depending on which 5.x version you're upgrading from, you should take the following precautions to avoid downtime:

• Make sure your BuildMaster database has been backed up prior to upgrading
• Make sure your encryption key has been backed up before upgrading
• Make sure the installation's \Extensions directory is backed up before upgrading

Rollback

Since there are changes in the database, a rollback requires uninstalling BuildMaster and then restoring your BuildMaster instance.

.NET 4.5.2 Required

BuildMaster 5.0 introduced a requirement that .NET Framework 4.5.2+ or higher be installed on the BuildMaster server and for all BuildMaster agents. This is a highly compatible, direct update to . NET Framework 4, and is already included in Windows 8 and Windows Server 2012. For older machines, simply download .NET 4.5 from Microsoft and install the update.

User Experience Changes

BuildMaster 5.0 introduced a Web Interface Overhaul to focus on Release Automation. In addition to color, font, and basic layout updates, the first thing you'll notice is the continued shift toward application release automation. Although we will continue to support the "create a build and deploy to production" workflow indefinitely, this workflow is becoming increasingly unpopular as CI servers like TeamCity, Jenkins, TFS, etc. become the preferred build tool and universal package managers like ProGet become the preferred artifact store.

The most noticeable change is in terminology: "promotions" are now "deployments", and "workflows" are now "pipelines". 

New Execution Engine / Legacy Plans

BuildMaster 5.0 has added the Inedo Execution Engine (OtterScript) for deployment plans. To mitigate upgrade risk, this new execution engine has been implemented in parallel with the legacy execution engine. Although the new execution cannot run a legacy plan (and the legacy engine cannot run a new OtterScript plan), you can convert legacy plans to OtterScript on a plan-by-plan basis and then edit the corresponding pipeline to use the new plan. 

See Legacy Plans in BuildMaster 5.0

Workflows Renamed to Pipelines

BuildMaster 5.0 renamed Workflows to Pipelines. While conceptually similar, the feature was completely reimplemented, and pipelines are quite a bit more versatile. There are a few notable changes:

• Stages vs. Environments - a workflow represents a sequence of environments, while a pipeline is a sequence of stages; a stage can target zero or more environments 
• Targets - in addition to an environment, a target also specifies servers; this means you do not have to explicitly name the servers you want to use in your plans 
• Build Step Removed - there is no longer a specific build step; you can simply add a stage and add a build importer to it 
• Gates - these are the same as the pre-deployment checklist 

Deprecated Features Removed

BuildMaster 5.0. The Notifiers and Triggers that were replaced with Event Listeners in BuildMaster 4.4 were removed; there were warnings about them in several versions (especially in 4.9). The Global environment approvals were also removed; these were also deprecated in BuildMaster 4.4. 

Roles were Renamed to Tasks and Rebuilt

BuildMaster 5.0

As part of the UX revision, Roles have been renamed to Tasks, and role names have been updated to sound more like tasks.  Permission Updates in BuildMaster 5.0 provide more details about this change. 

BuildMaster 5.5

The five integrated tasks ( Administer, Coordinate Releases, Manage Application, View Application, and Deploy to Environment) have been rebuilt, which means that any customizations made to these tasks will be lost. If you did not heed the warning about modifying built-in tasks, you should rename the tasks to something else before upgrading. Custom tasks are not affected.

Also, the Environments_Manage attribute has been renamed to Infrastructure_Manage, and the Environments_View attribute has been removed altogether.

UTC for Deploy Artifact Action

BuildMaster 5.0 now uses UTC times to compare artifacts on destination servers. This may cause BuildMaster to deploy the full artifact on the first deployment after upgrading as timestamps are no longer matched using local time.

New Agent Model / Legacy BuildMaster Agents

BuildMaster 5.1 added support for the Inedo Agent and renamed the previous agents to the Legacy BuildMaster Agent. See Upgrading Legacy BuildMaster Agents to The Inedo Agent for more information.

New Feature: Resource Credentials

BuildMaster 5.1 added a new feature called Resource Credentials that is used for passwords and other secrets. See Resource Credential documentation for more information.

Resource Credentials for SSH-based Servers

BuildMaster 5.1 removed support for having SSH-based servers store the credentials and/or private keys on the server itself. Instead, a resource credential must be created, and then associate with the server. Existing SSH-based servers will still function but when you edit a server, you will need to associate it with a resource credential.

New SSH Library

BuildMaster 5.1 changed the SSH library used to communicate with Linux-based servers. This should have no functional impact, and although the new library (libssh2) is popular and actively maintained compared to the old library (SSH.NET), the library change poses some risk for use on Linux-based servers.

Encryption Key

BuildMaster 5.1. To encrypt resource credentials, an encryption key is used; this will be created during the upgrade and added to the web and service configuration files. This encryption key must be added to your backup plan, or you will not be able to decrypt resource credentials on a resto

New Feature: Server Roles (Replacing Server Groups)

BuildMaster 5.2 introduced the Server Roles feature as a replacement for Server Groups, and Server Groups will be hidden unless you have Legacy Plans

In Legacy Plans, the Server Groups feature allowed actions or action groups to target multiple servers. Because Operations in OtterScript plans cannot target a server group (although you can iterate over servers to provide exactly the same functionality), they provide no value to non-legacy users and are hidden from UI if no legacy plans exist.

Servers can still be grouped using Server Roles, which is a new feature in this release. Roles can be the target of a pipeline stage and can be iterated just like server groups.

New Feature: API Keys (Replacing ApiKey)

BuildMaster 5.2 introduced the API Keys feature. If you have configured an ApiKey for BuildMaster in All Settings, it will automatically be converted to an API Key with Native API access. 

New Features: Infrastructure Configuration Import/Export & Synchronization

BuildMaster 5.2 introduced the Configuration Import/Export and Infrastructure Synchronization features.

New Features: Release Templates

BuildMaster 5.3 introduced the Release Templates feature in conjunction with deprecating the existing variables that are used on releases and release packages.

New Feature: Configuration Variables / Legacy Variables

BuildMaster 5.3 introduced a new variables feature called Configuration Variables. Any existing configuration or release template variables you created are now legacy variables in the UI; Release Templates and Configuration Variables were implemented side by side to replace them.

See Legacy Configuration and Release Variables for more information

New Feature: Agentless Windows Servers

BuildMaster 5.4 introduced a new agentless means of communicating with Windows servers via PowerShell remoting channels.

Changes to the Internal Artifact Disk Store Structure

Although accessing artifact files directly in the artifact disk store (i.e. ArtifactsBasePath) is unsupported, many users wrote external scripts and tools that rely on doing exactly this.

In previous versions of BuildMaster, artifacts were stored using the following structure:

\«application-id»
  \«release-number»
    \«package-number»
      \«deployable-id»
        \«artifact-name».zip

As of BuildMaster 5.4, newly-created artifacts will be stored in the following manner:

\A«application-id»
  \R«release-id»
    \B«package-id»
      \«artifact-name».zip

If you rely on these internal paths, you'll have a problem with newly created artifacts. Of course, you should set the external tool to not use these paths... but in the meantime, there are two options you can use:

• Use Legacy Storage Path - both the Create Artifact Operation and Create Artifact Legacy Action have a new property called Use Legacy Storage Path that defaults to false. When set to true, the artifact will be stored using the earlier convention
• Create Legacy Artifact Storage Symlinks - if you're in a bind because you didn't know something in the pipeline depended on it (e.g., a production deployment), the simplest quick fix may be to use the tool built into the service executable (bmservice.exe), which creates symbolic links for all existing "new path" artifacts in the old, expected location. Just run bmservice.exe, select the option, and the problem should be fixed immediately. Then change your plans to use the "Use Legacy Storage Path" property, or (ideally) fix your external tool

New Feature: Variables Management API

BuildMaster 5.4 added the Variables Management API which lets you update configuration variables with a simplified API endpoint.

New Features: Pipeline Variables and Variables as JSON

BuildMaster 5.5 introduced variables to pipelines and pipeline stages, as well as the ability to bulk edit configuration variables as JSON documents.

New Feature: Release Management API

BuildMaster 5.5 added the Release and Package Deployment API offers a simple mechanism for creating releases, creating release packages, and deploying release packages.

New Feature: Issue Sources

BuildMaster 5.6 added the Issue Sources Feature to replace the Issue Tracking Providers, which are now considered a legacy feature.

Source Control Operations & Providers as a Legacy Feature

BuildMaster 5.6 has deprecated the "provider model" in favor of using Resource Credentials and Global Variables for configuration and tool-specific Operations. So instead of "Get-Latest using SVN", it would be "SVN-Checkout". Therefore, both Issue Tracking Providers and Source Control Providers are considered legacy features.

New Features: Calendars, Deployment windows, and Release target dates

Buildmaster 5.7 introduced several related features: Calendars, Deployment Windows, and Release Target dates.

Configuration file deployment changes

BuildMaster 5.7 introduced changes to configuration file deployment, with the biggest change in behavior being the removal of %-syntax variable support when deployment occurs in an OtterScript plan. The behavior was previously undefined, e.g. sometimes it performed the replacement, whereas other times it did not. See the full Configuration File Assets documentation for more information and specification.

Edition Name Changes

BuildMaster 5.7. What used to be called "BuildMaster Enterprise" is now "BuildMaster Standard." The only change in the software is that the license key pages mention Standard instead of Enterprise. This does not change the functionality.

New Feature: Text Templating

BuildMaster 5.8 allows you to use the Apply-Template operation to perform advanced text replacement. Templating is part of the SDK, so it can also be used by custom extensions.

This feature can be used in combination with Configuration Variables as the simplest mechanism to deploy configuration files.

New Feature: Updated LDAP and Active Directory

BuildMaster 5.8 added a new and improved LDAP and Active Directory integration, which makes maintaining user and group permissions easier than before. Complex multi-domain active directory structures with multiple domains can now be set up easily, as our new integration allows you to define permissions in a third-party LDAP directory or in an active directory domain forest. If you choose to use an active directory domain, you can also enable built-in Windows Integrated Authentication, which eliminates the web-based login prompt.

The optional new "LDAP and Active Directory" user directory is served from the InedoCore extension (v5.8.0+) and bundled with the installer. The current user directory settings are not changed and require additional configuration within BuildMaster to use them. Refer to the LDAP and Active Directory documentation for configuration options and, if necessary, troubleshooting steps.

New Feature: Plan Versioning

BuildMaster 5.8 added Plan Versioning, where a history of edits is kept within BuildMaster; this allows approved team members to view the version history or even roll back to a previous version. You can also easily view the differences between the two versions on the Plan Version Listing page. The differences between the two selected plans are highlighted so that the changes made can be quickly identified.

SDK Changes

BuildMaster 5.0 and BuildMaster 5.1 shipped with a new SDK with breaking changes. This means extensions 5.0 extensions will not work with any version except 5.0, however, 5.1 will work with later versions.

BuildMaster 5.2 through BuildMaster 5.7 shipped with a new SDK, but all additive changes.

Although the SDK is mostly the same (even from v4), the notable changes are as follows.

• Operations are the v5-equivalent of Actions. However, you do not need to develop an Operation to use these in OtterScript plans, thanks to the special Execute-LegacyAction operation.
• StoredProcs to DB - the utility class that provided access to the database API is now called DB. This new class is much more performant, supports transactions, has better type safety, and supports asynchronous queries. In nearly all cases, simply renaming StoredProcs to DB will be sufficient.
• 5.1+ Agent service interfaces were moved into the Inedo.Agents namespace in the Inedo.Agents.Client assembly
• 5.1+ IRemoteZip has been included, its two methods folded into IFileOperationsExecuter
• 5.2+ The VariableFunctionPropertiesAttribute was obsoleted in the BuildMaster 5.2 SDK. If you have a custom variable function and wish to compile against this SDK, use them LegacyAliasAttribute instead of the LegacyAlias property, and a TagAttribute instead of the Category property. The Scope property was ignored since v5.
• 5.5+ The SDK changes are additive, to support additional dynamic list variables features. If you have a custom editor that inherits from PromotionRequirementEditorBase, that will no longer be displayed in the UI. It needs to be refactored to use PromotionRequirementEditor or the appropriate editor attributes.

See the Writing a Simple Operation Using the BuildMaster SDK tutorial and the BuildMaster SDK Reference for more details.

Extensions Changes

The following extensions are supported in BuildMaster v5. Extensions with an asterisk (*) have actions that have not yet been converted to operations, though they will still function fine in an OtterScript plan using the Execute-LegacyAction operation.

Note that the JUnit extension was merged with the Java extension.

Un-migrated Community Extensions

Some of the extensions developed by and for the community have not been updated to the new SDK and therefore will not work in v5. Although it is trivial to recompile/republish them, many of these extensions do not meet our usability/quality standards or do not support newer versions of the tool they're integrating with. Therefore, we would prefer to work with a user familiar with the tool to bring it up to date.

If you are using any of these extensions, just let us know and we will recompile and publish them to work for v5.

BuildMaster 5.0: All Extensions Must be Upgraded

Because the breaking SDK changes from v4, you will need to upgrade all of your extensions after you upgrade BuildMaster. This is quite easy from the Admin > Extensions page.

BuildMaster 5.1: All Extensions Must be Upgraded

Because the breaking SDK changes from 5.0, you will need to upgrade all of your extensions after you upgrade BuildMaster. This is quite easy from the Admin > Extensions page.

BuildMaster 5.3: Core Functionality Moved to BuildMasterCore Extension

Most operations and variable functions have been moved to the built-in extensions; if nothing works after the upgrade, then most likely the extensions could not be loaded due to permissions errors. However, once the extensions are loaded, there is no functional difference.

BuildMaster 5.6: GitLegacy and GitHubLegacy Extensions

This largest upgrade impact will be for users with the Git and GitHub extensions. Users with these extensions must download the GitLegacy and GitHubLegacy extensions to maintain existing functionality. This may occur post-upgrade via the Extensions Overview page within BuildMaster, or by visiting the Inedo Den and downloading directly at http://inedo.com/den

BuildMaster 5.7: New Extension Loader

The extensions loader has changed since v5.6 for parity with Otter's romp extension loader. There should be no observable functional changes as extension load paths and temporary paths are the same.