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.
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.
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.
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 Cloud Shell or REST APIs may require users to provide their tenant alias (or development team alias) to be authenticated 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.
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:
In the Account Portal:
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.
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.
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.
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.
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, 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.
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.
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.
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.
To avoid downtime, upgrade Platform roles in the following order:
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.
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.
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.
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.
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.
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.
Linux: RPM folder, all RPMs located in this folder should be installed on Platform Linux servers
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.
The following steps should be followed for upgrading the Platform roles on Windows servers.
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
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.
In this screen you will need to input the location of your Platform’s Environment Descriptor JSON file. Click Next to proceed.
In this screen, click Install to begin installing the new MSI.
The MSI will begin installing.
Follow the steps in the Install the Platform on Linux Servers of the manual Linux installation instructions to upgrade your Linux servers.