Platform Upgrades

This page describes the processes around upgrading a Platform to a new version. It will talk about things you should know before you start an upgrade, the different upgrade paths, how your Platform will function during 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 a 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. Note that some functionality may be limited in Portals to preserve guest application stability during the upgrade.

When performing an upgrade, you have a lot of flexibility in how you chose to upgrade your Platform. You can allow the Platform handle the upgrade, manually execute the upgrade on your Platform servers yourself, or a combination of both. The available upgrade paths 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 for you. 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 are performed by the Platform. This phase includes steps to clean up upgrade processes and make sure your Platform has upgraded successfully.

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) to be authenticated during an upgrade.

Blocked Actions during an Upgrade

Although users can access Platform Interfaces during upgrades, to maintain application stability, certain actions are 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 is unavailable to them, an upgrade alert banner message will appear on all Apprenda Interfaces during an upgrade. This banner will appear during the as soon as an upgrade is started 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 you must resolve the problem manually by adding more capacity before the upgrade can continue.

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. Use the Manual upgrade path and place a subset of servers into Maintenance, upgrade them, and then transition the servers Online. Repeat this for other server groups until you’re entire Platform ahs been upgraded. 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 is 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 by 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

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. Your Platform may require more 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. Your Platform may require more 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 are in use)

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

To avoid downtime, upgrade Platform roles in the following order:

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

Perform the upgrade by role, not by server. You should upgrade all roles of a given type 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 that you upgrade of all roles on a server without following the described order, may result in guest application downtime.

1. Platform Coordination and Cache

Perform Platform Coordination and Cache role upgrades 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.