This is documentation for Apprenda 7 and 8.
Documentation for newer version is available at

Platform Upgrades


The following applies to upgrades from Platform version 7.0.0 to a later version. If you are on a Platform version before 7.0.0, see the upgrade documentation for those versions.

This page describes the processes around upgrading your Platform to a new version. It will also explain the different upgrade paths, how your Platform will function during an upgrade, and things you should know before you start an upgrade.

To perform an upgrade, also see more about upgrading from the command line and upgrading through the Apprenda Install Wizard.

Overview of Upgrades

Upgrade Paths

You can perform an upgrade of your Platform without downtime for guest applications or the Platform services guest applications rely on. During upgrades, Platform portals, APIs, and command line interfaces are accessible by Platform users so there is no disruption in work on the Platform during the upgrade, although some related functionality may be limited to preserve guest application stability.

You have a lot of flexibility in how you chose to upgrade your Platform by letting the Platform handle the upgrade, manually executing the upgrade on your Platform servers, or a combination of both. The two paths of the upgrade process are Automatic and Manual.

In an Automatic upgrade, the Platform will make as many decisions as possible around the order in which servers are upgraded and preform most of the upgrade steps. The Manual upgrade allows Platform Operators  control over the order in which servers are upgraded and preform the upgrade steps. Both paths may be entirely scripted through a combination of Platform APIs and tools such as the Platform Operations REST API, Apprenda.Wizard executable, and the Apprenda Maintenance Mode. 

Upgrade Process

To understand the upgrade process, it is easiest to break it up into three phases: preparation, services and roles upgrade, and finalization.

Manual and Automatic upgrades paths start out the same way, initiated through the Apprenda Installation Wizard. Once an upgrade is started, you enter the preparation phase where you will provide information about your Platform, select your upgrade path, and set some configuration settings depending on your chosen path. In this phase the Platform will run some validation and preparation steps for the upgrade.

When the preparation phase is complete, you transition into the services and roles upgrade phase. In this phase the Platform roles and services will be upgraded by either the Platform in an Automatic upgrade or Platform Operators in a Manual upgrade. After all eligible servers are upgraded, the finalization phase of the upgrade will begin. Here the last steps of the upgrade will be performed.

Accessing the Platform during an Upgrade

During the upgrade, Apprenda Interfaces like the Apprenda Portals, APIs, and command line interfaces will remain accessible to your Platform users and applications. This will allow Platform Operators, Developers, and multi-Tenant users the ability to manage applications and servers throughout the upgrade as well as keep applications functioning correctly during upgrades.

Apprenda Interfaces

  • Developer Portal
  • System Operation Center (SOC)
  • Account Portal
  • Authentication page
  • Application Management REST API (which supports the Apprenda Cloud Shell, Visual Studio Extension, and Developer Portal)
  • Platform Operations REST API (which supports the Apprenda Maintenance Mode command line interface)

Apprenda Cloud Shell or REST APIs may require users to provide their tenant alias (or development team alias) in order to be authenticated.

Blocked Actions during an Upgrade

Although users can access Platform Interfaces during upgrades, in order to maintain application stability, certain actions will be blocked while an upgrade is in progress.

  • Promoting an application
  • Patching an application
  • Deleting a published application (non-published applications and application versions can be deleted)
  • Starting an application (applications can be stopped, but can’t be restarted)
  • Removing or disabling a Tenant
  • Creating a Tenant and onboarding a Tenant to a new application
  • Enabling and disabling sticky sessions
  • Repairing UIs
  • Adding or removing Platform Operators

Note: Uploading an application archive is not explicitly blocked during an upgrade, however, Developers will only be able to upload an application archive through the Application Management REST API, Apprenda Cloud Shell, or the Additional Controls section of the Developer Portal. Archive upload will not be permitted through the main section of the Developer Portal.

To alert users that an upgrade is occurring and that some functionality may be unavailable to them, an upgrade alert banner message will appear on all Apprenda Interfaces during an upgrade. This banner will appear during the preparation phase of the upgrade.

In the Developer Portal and System Operations Center:

Developer Protal and SOC upgrade banner

In the Account Portal:

Account Portal upgrade banner

Upgrading Apprenda Interfaces

Regardless of the upgrade path, the Apprenda Interfaces are upgraded by the Platform during the finalization phase of the upgrade. At the time this step is preformed, there must be enough web servers available to deploy the new workloads to the Platform, separate from the web servers currently hosting the Apprenda Portals. This means that you must have at least twice the number of web servers as the most deployed Apprenda Interface available to host the new Platform version Interfaces.

During the preparation phase of the upgrade, you are able to configure how the Platform should act in the event that there is not enough capacity on the Platform to upgrade the Interfaces without downtime. If you choose to allow downtime for Apprenda Interfaces, then the Interfaces will be unavailable only while they are being upgraded (they will be available during other parts of the upgrade). If you choose not to allow downtime and there is not enough capacity to upgrade the Portals when this step occurs, then the upgrade will stop and the problem must be resolved manually by adding more capacity before continuing.

Although capacity may not appear to be an issue when starting an upgrade, the need for Apprenda Interface downtime may arise if servers are placed into Maintenance during the upgrade and capacity of the Platform decreases. If you want to change your configured setting for Apprenda Interfaces downtime, you can do so by restarting the Apprenda Installer (or re-running the upgrade command in the command line). For the best experience for your users, it is recommended to not allow downtime for Apprenda Interfaces and instead resolve any capacity issues that may arise.

Using Maintenance during Upgrades

In general, servers may be upgraded regardless of their state (Online, Reserved, or Maintenance) and a server’s state may be changed at any time during the upgrade. However, the Maintenance state in particular can be leveraged during upgrades to help manage, test, and organize a Platform upgrade. Since no workloads are hosted on servers in Maintenance, the server can be upgraded and new Platform version functionality tested without affecting application workloads.

Although Maintenance can be a helpful tool for managing upgrades, it should be noted that servers in Maintenance must be upgraded manually. An Automatic upgrade will not upgrade servers in maintenance. Additionally, servers in Maintenance must be fully upgraded before they can be taken out of Maintenance.

Upgrading in Groups

You may wish to upgrade Platform servers in smaller, more controlled groups of your choosing. This can be easily done by using the Manual upgrade path and placing a subset of servers into Maintenance, upgrading them, and then transitioning the servers Online before moving onto another group of servers. While the servers are in Maintenance, you will also have the opportunity to perform additional non-Platform repairs to your servers. Important workloads can also be tested on a newly upgraded server by transitioning the server into Reserved and deploying the workload to the server.

Failure Recovery

Maintenance can be used as a way to recover from a server failing to upgrade. The failed server can be placed into Maintenance, removing the current workloads for redeployment to another server, until the failure can be resolved and the server is successfully upgraded. If you wish, the server may remain in Maintenance throughout the rest of the upgrade. Upgrades can completed with non-upgraded servers in Maintenance and the servers can be upgraded after the upgrade completes.

In the Automatic upgrade, you can chose to have the Platform transition any failed server into Maintenance as a default recovery method for upgrade failures.

Potential Downtime

Placing servers into Maintenance reduces the available hosting resources of your Platform. If too many servers are transitioned into Maintenance, applications may begin experiencing downtime due to lack of available hosts. When placing servers into Maintenance during an upgrade, make sure that there will be enough resources to host your applications and maintain normal Platform activity.

Switching Between Manual and Automatic Upgrade Paths

At any point during an upgrade you are able to switch between upgrade paths. To do so, restart the Apprenda Installer and the upgrade can be continued be selecting the alternate upgrade path. Upgrade configuration settings may also be changed by restarting the upgrade. Once validation passes, the upgrade will resume from the point at which it was stopped.

To know which servers have already be upgraded, the current version of every server is shown on the Servers page in the SOC.

Before Upgrading

Before upgrading, Platform Operators are able to block the same set of actions that the Platform blocks during upgrades. By using a Platform Registry Setting, Platform Operators are able to block potentially destructive actions from being started too close to when an upgrade will begin. Set the Platform.PendingUpgrade setting to True to show the upgrade alert banner and block all actions that will normally be blocked in an upgrade. Blocked actions that are already in progress when this setting is enabled will continue as normal until the actions are complete. This setting will be set to false by the Platform after the upgrade completes.

Prerequisites for Upgrades without Downtime

In order to upgrade without experiencing downtime for guest applications, the following requirements must be met. If at any point during an upgrade the Platform does not meet the general prerequisites below, applications may experience downtime.

  • Platform must have at least 2 Windows nodes. More may be required depending on how many Apprenda Interfaces and guest applications are deployed and the resource capacity of your Platform servers
  • If your Platform includes Linux servers, there must be at least 2. More may be required depending on how many guest applications are deployed and the resource capacity of your Linux servers
  • No database nodes running a non-Enterprise version of SQL (brief windows of downtime may occur in non-Enterprise versions)

Additional Notes

  • When upgrading a server, it may appear in the System Operations Center as “Needs Attention.” This will happen because there is a brief loss of communication as the server is upgraded and you can safely ignore it. If the problem persists for more than a few seconds, then there might be a different issue with the server and it should be investigated. 

About Automatic Upgrades

Performing an Automatic upgrade means that aside from choosing some configuration options, the Platform will handle all decisions around the upgrade, including the order in which servers are upgraded. In an Automatic upgrade, servers will be upgraded one by one to minimize the risk of application downtime.

To begin an automatic upgrade, use the Apprenda.Wizard executable either through the Installer interface or the command line.

About Manual Upgrades

The Manual upgrade workflow means Platform Operators are responsible for upgrading the individual Platform roles on all servers by installing the Platform role MSIs or RPMs for the new Platform version. Aside from some validation and configuring steps, the Platform will not be involved in upgrading any server. Noted that this process can be completely scripted using the Apprenda.Wizard executable command-line interface.

Once the preliminary upgrade steps are completed through the Apprenda.Wizard command-line or user interface, follow the steps below to upgrade Platform servers.

Manual Upgrade Order

In order to avoid downtime, Platform roles should be upgraded in the following order:

  1. Platform Coordination and Cache
  2. Application/Web
  3. Load Manager

The upgrade should be performed by role, not by server. This means that all roles of a given type should be upgraded according to the order listed above before moving onto the next role. For example, all servers acting as a Platform Coordinator (or Platform Cache) should have their Platform Coordination (or Cache) role upgraded before moving onto upgrading the Windows or Linux containers on Application and Web servers. Please note that upgrading server by server, meaning the upgrade of all roles on a server without following the described order, may result in guest application downtime.

1. Platform Coordination and Cache

Platform Coordination and Cache role upgrades should be performed first.

When upgrading Platform Coordination servers, be mindful of the cluster availability. It is recommended that the majority of servers acting as Platform Coordinators remain up throughout the upgrade. This means that Platform Operators should not upgrade more than n/2 -1 (where n is the total number of Platform Coordinators) in parallel to make sure that enough Platform Coordinators are available to maintain normal Platform activity.

Platform Cache roles may be upgraded in parallel, but it is recommended that at least one cache server remain available while upgrading.

2. Application/Web

Application/Web servers are any servers with Windows or Linux Container processes managing guest applications. If the servers being upgraded are in Maintenance, the upgrade may be performed in parallel. However, if the servers being upgraded still hosting application workloads, then it is recommended to understand the resource requirements of your Platform during the upgrade and only upgrade servers in numbers that leave enough capacity resources for scaling applications or new deployments.

Linux Servers

If your Platform includes Linux servers, they should be upgraded at this time. Linux Containers must be upgraded in between the upgrade of Windows Containers to ensure proper scaling capabilities of your Linux applications. This means that Platform Operators should start upgrading Linux Containers after at least one Windows container is upgraded and complete upgrading the Linux Containers before the last Windows Container is upgraded.

3. Load Managers

Load Managers should be the last Platform role upgraded. Servers may be upgraded in parallel, however it is recommended that at least one servers remain available at all times.

Performing a Manual Upgrade on a Platform Role

Use the following steps to upgrade your Platform servers.

MSI and RPM Location

Before upgrading a role, the MSI or RPMs must be available to the server you wish to upgrade. The target MSIs and RPMs can be found in the Binaries/Apprenda/System/Node directory of your upgrade package or in the Apprenda/[PlatformVersionNumber]/System/Nodes directory in your Platform Repository share (on Linux servers in the “Apprenda System” Platform Repository) after the preparation phase of the upgrade is complete. MSIs will be located in individual folders named for the Platform Role they will upgrade. RPMs are all located in a single RPM folder.

Platform Role



Windows: WindowsContainer/ApprendaWindowsContainer.msi

Linux: RPM folder, all RPMs located in this folder should be installed on Platform Linux servers



Load Managers


Platform Coordinator



Environment Descriptor File

This is a JSON file created by the Platform during the preparation phase of the upgrade. The file describes the Platform and defines important tokens that are used for MSI and RPM installation. The environmentDescriptor.json file will be available in the Apprenda directory of the Platform Repository Share (configured at installation) after the preparation phase of the upgrade is complete. This file should be made available to all nodes before the upgrade can be performed.

Manual Windows Upgrade

The following steps should be followed for upgrading the Platform roles on Windows servers.

Running the MSI from the Command Line

You can run the MSIs through the command line by executing the msiexec command with the location of the MSI you wish to install and the path to the Environment Descriptor file. An example installation command is below.

msiexec /quiet /qn /i ApprendaWindowsContainer.msi EnvironmentDescriptor= environmentDescriptor.json /l*V

Running the MSI Interface

To upgrade a Platform role, open the MSI installer on the server to are upgrading and click Next from the Welcome page. On the licensing page, read and accept the license, then click Next.

MSI Licensing screen

In this screen you will need to input the location of your Platform’s Environment Descriptor JSON file. Click Next to proceed.

MSI Environment Descriptor input screen

In this screen, click Install to begin installing the new MSI.

MSI Install screen

The MSI will begin installing.

MSI Installing screen


  • Due to a known Microsoft bug, “Files in Use” errors can be safely ignored should you receive any notifications during the MSI upgrade.

Manual Linux Upgrade

Follow the steps in the Install the Platform on Linux Servers of the manual Linux installation instructions to upgrade your Linux servers.