In this document:
This document compiles all data related to the upgrade processes in APS applications. In the following table, you will find some cases when an APS application needs upgrade.
Root Cause | Affected APS Components | Example |
---|---|---|
New service added | - New service declared in metadata
- New resource type
- New relations with existing types
- Provisioning logic of the new service
- New UI views and existing UI views
|
Subscription must include reference to allowed configurations (offers) |
Business related resources must be able to get access to properties of each other | - New relation between resource types
- Permissions in resource types
- UI view
|
On the view presenting VPSes, server owner must be displayed
|
New custom function added to a service | - Custom function in the resource type
- Provisioning logic of the service
- UI view that enables the feature to users
|
VPS owner is allowed to start and stop the VPS |
Note
APS application is uniquely identified by its ID as specified in package metadata. Upgrade process assumes using the same application ID in a current APS package and in APS packages that are updates of the current package.
Warning
Currently, APS does not support upgrade of packages from APS 1 to APS 2.
In APS packages, versions are assigned to the following components:
Component | Example | Description | Influence on upgrade |
---|---|---|---|
APS specification | <application… version=”2.0”> | Defines package format | Note Described here application upgrade process is valid for APS 2 |
Package version | <version>1.0</version>
<release>1</release>
VPS_Cloud-1.0-1.app.zip
|
- Application version
- Package release
- Package version combines both above
|
- Equals packaged application version
- Distinguishes packages with the same application version
- Must be updated before importing new package
Does not affect the upgrade process
|
Type version | “id”: “http://…/vps/1.0” | Version of APS resources | Upgrades all resources based on the updated type |
APS version is specified in the root <application> element inside the APP-META.xml
file, for example:
<application xmlns="http://aps-standard.org/ns/2" version="2.0">
This document is valid for APS version 2.x. Refer to Metadata Descriptor (APP-META.xml) for more details.
APS version is also specified in each type definition by means of the apsVersion property, for example:
{
"apsVersion": "2.0",
"name": "vps",
...
}
Package version is specified by two elements in package metadata:
The package version contains both of the above elements in the form of {version}-{release}. With the following sample metadata
<application>
...
<version>2.0</version>
<release>6</release>
...
</application>
the package release would be 2.0-6.
Note
When importing an APS package, the APS controller expects the package version to be higher than any other package versions with the same application ID that are already stored in its package repository.
Each schema in an APS package defines an APS type. Type ID contains the type version. In the following example, a type for VPSes is declared.
{
"apsVersion": "2.0",
"name": "vps",
"id": "http://aps-standard.org/samples/vpscloud/vps/1.0",
"implements": [
"http://aps-standard.org/types/core/resource/1.0"
],...
}
Type ID “http://aps-standard.org/samples/vpscloud/vps/1.0” contains its version - 1.0. If in a new package the type version is increased and the application instance is updated to the new package, then the APS controller will make all resources based on this type bound to its new version.
Among other types, each APS package must contain type definition for resources representing APS application instances. The type implements the core Application resource as in the following example.
{
"apsVersion": "2.0",
"name": "cloud",
"id": "http://aps-standard.org/samples/vpscloud/1.0",
"implements": [
"http://aps-standard.org/types/core/application/1.0"
],...
}
In the above definition, the type implements the core application resource type, whose ID is “http://aps-standard.org/types/core/application/1.0”. Thus, it declares itself as the type that must be used for provisioning an application instance through the root application service declared on an APS application endpoint. APS controller expects this service to accept the upgrade call during the upgrade process. In the above example, the type ID is “http://aps-standard.org/samples/vpscloud/1.0”, and the version is 1.0.
Each application instance in a hosting platform is upgraded independently. It means, different application instances can be based on different package versions. Thus, there is no restriction on having different versions of an APS type defined by different package versions on the same hosting platform.
To specify if a package can upgrade other packages of the same application, the <upgrade> meta element must contain an RQL statement identifying upgradable packages as explained later.
The version element in an APS type has the following structure: major[.minor]. Depending on the upgraded part, we call the upgrade correspondingly: major or minor.
Minor upgrades are backwards compatible BWCB. It means, after upgrade, there is no need to change type ID in existing requests for resources. For example, if a type was upgraded from http://www.odin.com/mailbox/1.0 to http://www.odin.com/mailbox/1.4, the APS controller will return the upgraded resource representation even if it receives the http://www.odin.com/mailbox/1.0 type in the request. The returned resource is bound to the new type version.
However the reverse, forward compatibility FWCB is not supported. For example, when APS type http://www.odin.com/mailbox/1.5 is requested, the APS controller will not return resources bound to http://www.odin.com/mailbox/1.4.
Different major versions are not compatible, that is http://www.odin.com/mailbox/1.0 and http://www.odin.com/mailbox/2.0 are two different non-compatible types.
The following examples illustrate the cases when you would better use minor upgrade and when major upgrade is necessary.
Initially there was a vps type containing a number of properties. Its version is 1.0.
{
"apsVersion": "2.0",
"name": "vps",
"id": "http://aps-standard.org/samples/vpscloud/vps/1.0",
...
"properties": {
"name": {
"type": "string",
},
...
}
}
The developer decided to add the optional property “description”. Since the property is not required, the resources will be backward compatible after the type upgrade. That is why, the developer decided to do minor upgrade to version 1.4, as follows.
{
"apsVersion": "2.0",
"name": "vps",
"id": "http://aps-standard.org/samples/vpsclouds/vps/1.4",
...
"properties": {
"name": {
"type": "string",
},
"description": {
"type": "string",
},
...
}
}
Following up multiple requests from providers, the developer decided to make the “description” a required attribute. Evidently, the VPSes created earlier will not be compatible with the new type version, since they may do not have a description. That is why, the developer has to do a major upgrade, for example, to version 2.0 as follows.
{
"apsVersion": "2.0",
"name": "vps",
"id": "http://aps-standard.org/samples/vpsclouds/vps/2.0",
...
"properties": {
"name": {
"type": "string",
},
"description": {
"type": "string",
"required": true
},
...
}
}
In an APS type, there are three kinds of components that can be upgraded. The following upgrades of them are considered as minor.
Adding optional (non-required) properties
Changing attributes as specified in the table below:
Property attribute | Minor upgrade |
---|---|
name | CANNOT be changed. |
type | CANNOT be changed. |
required | Change from false to true, only if the default value is specified |
readonly | Change from true to false |
final | Change from true to false |
encrypted | Change from true to false, only if required=false |
default | Can be changed |
format | Can be changed, but it’s up to the developer to make sure that backwards compatibility of clients that may rely on the format will be kept, for example, change from ‘ip-address’ to ‘ipv4’ is safe, but not vice versa |
pattern | Can be changed, but it’s up to developer to make sure that backwards compatibility of clients that may rely on the format will be kept |
title | Can be changed |
description | Can be changed |
minLength | If decreased |
maxLength | If increased |
minItems | If decreased |
maxItems | If increased |
uniqueItems | Change from true to false |
enum | Can be changed |
enumTitles | Can be changed |
To upgrade an APS application, it is necessary to update the APS package and then upgrade the application on the hosting platform in accordance with the workflow.
Generally, the procedure of updating a package resembles the package development steps, but it requires developers to do only those steps that make necessary updates. The following diagram presents candidates for update along with corresponding files and metadata.
Correspondingly, the sequence of recommended steps looks as follows.
Draw the updated resource diagram, reflecting clearly major changes:
Update APS types (types) to change the following:
Update provisioning logic of APS application endpoint:
upgrade()
method in the application root serviceUpdate localization and text translation:
Update declaration of UI navigation
Add or remove declaration of some services
Warning
It is not possible to change the service ID declared in metadata, since it would look as if you removed a service and added a new one.
Increase package version
Specify the range of old packages that this package can upgrade
It is necessary to draw a new resource diagram to clearly reflect the following updates:
The example below indicates the following updates:
An APS type can be updated in the following ways, each leading to declaration of a new type or a new type version as well as to updates in the provisioning logic on the APS application endpoint:
Note
1. When updating an APS type, the APS controller will bind the corresponding resources of the updated application instance to the new type version.
2. Each APS type is bound to its own application service. Thus, its update might require update of the service declaration in metadata as well as update of the service on the APS application endpoint.
Provisioning logic can be updated or fixed by updating provisioning scripts or other types of executables inside the APS package. Respective updates must be performed on the APS application endpoint.
Warning
APS controller refuses an update that requires removing a service if there are resources provisioned through it.
Updates described earlier may require update of metadata. The following list contains specifics of metadata updates.
The <upgrade> section declares a range of previous package versions that the current package can upgrade.
Its match
attribute defines this range by means of the version
and release
parameters.
It is possible to specify an exact package version or
a range of packages that can be updated by the new package. Therefore,
the match
attribute contains an RQL expression that will be evaluated against metadata of the
installed packages with the same application ID.
Note
If the update specification is absent, the APS controller assumes that updates are not supported by the package at all.
For exact version comparison, the APS controller compares package versions as specified in the Package Version section of the specification with help of the =lt=, =gt=, =ge=, =gt=, =eq= and =ne= RQL operators.
In metadata, update statements define packages that can be updated as illustrated in the following examples.
Match exact package version. In the following example, the update is applicable for version 6.0-2.
<application>
...
<upgrade match="version =eq= 6.0, release =eq= 2"/>
..
</application>
Range of package versions. In the following example, the update is applicable for all versions starting from 1.0-0 and up to 2.0-7.
<application>
...
<upgrade match="(version =ge= 1.0, version =lt= 2.0) or (version =eq= 2.0, release =le= 7)" />
...
</application>
The <upgrade> section allows changing relation names in APS types. For this purpose, the section includes <service> sections, one per each service (APS type). A <service> section contains the <rename> section with <relation> rename elements.
The following example illustrates how to rename two relations from their old names to the new names:
<upgrade match="version=ge=1.0">
<service id="offers" spec="version=eq=2.2">
<rename>
<relation new="servers" old="vpses"/>
<relation new="application" old="root"/>
</rename>
</service>
</upgrade>
Warning
In the above definition, it is not allowed to use concurrently the same name as new
in one <relation> element
and as old
in another.
The above example also illustrates how to specify the APS version that the system must support to apply the requested renaming.
Let us consider the following two major cases.
In package version 1.0, the vps type was linked to the user type through the myuser relation. In the new package version 1.1, the relation is renamed to user.
The new package must go through the following changes:
In package version 1.0, the vps type was linked to the user type through the myuser link. In the next package version 1.1, the vps type implements the standard APS type user/service that has the user relation definition. It means, the vps type inherites the user link and there is no need in the old myuser relation.
The new package must go through the following changes:
The following updates can be applied to custom UI.
ui
folder of the package.Update of text translation to different languages is the same as described in the Internationalization and Localization section of the APS specification.
If APS application is to be updated, this update can be automated by modifying the upgrade method of the root appliation service. The method must await for its call from the APS controller.
To build the updated package, use the APS build utility available in command line or embedded in the APS IDE. Pay attention to the package version that must be higher than the package versions to be updated.
Once an updated package is imported to the APS controller, an administrator of the hosting platform can initiate upgrade of an APS application instance to the new version of the package.
Once the new package is imported to the hosting platform, the provider staff can start upgrade of a selected application instance. Preliminary, they ensure:
APS controller processes the upgrade internally and then calls the upgrade
method of the application root service (implementing the core application type) on the application endpoint.
The upgrade
method is executed on the application side to bring the application resources in compliance
with the updated package. Once the application responded, the APS controller completes post-upgrade
operations.
The aps.status property of the application resource indicates if the upgrade process is started as illustrated in the diagram:
The upgrade process for a selected APS application instance is initiated from the control panel of the hosting platform. This makes the APS controller go through the following steps.
Switch the application resource status to upgrading.
Updates aps.package.id
in the application instance, thus binding the application instance
to the new package.
Call the upgrade method of the application resource and wait for the response. Application specific transfer from the current version to the new one must be done by the application instance itself. Potentially, this operation can be pretty long. The application instance can communicate with the APS controller to get, register, or change some application resources. This is the only period, when the application instance has access to both versions of APS types, the current one and the new one. In all its operations, the application should use the types updated by the new package, however the result depends on the operation:
Warning
It is not allowed to call a custom operation declared in an APS type whose version is being changed.
If absolutely necessary, the application can schedule a separate post-upgrade task that will call the required
custom operation,
but the respective REST request must not use the same APS-Transaction-ID header
as in the initial upgrade
operation. The application can just omit the header in the request
to make the APS controller generate a new one.
Once the application completes its upgrade, perform internal post-upgrade operations. The goal is to ensure correct transfer of all APS resources to the new package with new type definitions. The APS controller achieves it by a number of validation operations.
Change status of the application resource to ready.
An application developer may need to prepare the application to the upgrade process, for example, by updating the
upgrade
method on the endpoint host and adding some auxiliary files. In such a case,
copy the updated application provisioning scripts to the application endpoint folder in accordance with
the second step in the update workflow.
The upgrade()
method of the application resource defines the update activity on the
application side. This method is executed on the new, just upgraded, version of the application
installed on the endpoint host.
In fact it is the first call on the new code.
Note
Sample request:
POST /wordpress/80a4b75e-58a7-40e4-a148-dff560e5fa4a/upgrade
{
"aps": {
"type": "http://www.odin.com/web/wordpress/2.0",
"id": "80a4b75e-58a7-40e4-a148-dff560e5fa4a",
"package": {
"id": "b6d35786-8a3b-4931-8122-342aa2130320",
"href": "/aps/2/packages/b6d35786-8a3b-4931-8122-342aa2130320"
}
},
"admin_name": "admin",
"admin_email": "admin@example.com",
"title": [
"The test blog title1",
"The test blog title2"],
...
}
Response:
HTTP/1.1 200 OK
Note
When designing the upgrade
method, the packager can define the following actions.
Update properties of all resources whose current properties do not match the new type. For this purpose, use:
Update new properties of the application instance (core application resource) assuming these properties are not defined in the old version of the application. When using PHP runtime, redefine these properties along with the APS type version as in the following example:
public function upgrade() {
...
$this->newProp = "some value";
$this->aps->type = "http://mycompany.com/myapp/cloud/2.0";
...
}
Since versions 2.0-383, 2.1-302, and 2.2-115, PHP runtime updates the type automatically, before sending the result to the APS controller. So, you only have to change properties but not the type:
public function upgrade() {
...
$this->newProp = "some value";
...
}
Update properties of resources that did not exist in the old types. It is possible only along with updating the resources to the new type. When using PHP runtime, it looks as in the following example that defines the new parameter1 property:
public function upgrade() {
...
$apsc = \APS\Request::getController();
/* Here resources are still based on the old version */
$resources = $apsc->getResources("implementing(http://mycompany.example.com/myapp/srv-1/1.0)");
foreach ($resources as $resource) {
/* We need to explicitly change resource APS type to the new one */
$resource->aps->type = "http://mycompany.example.com/myapp/srv-1/2.0";
/* Define the property as needed */
$resource->parameter1 = "some value";
/* Request the APS controller to apply both changes */
$apsc->updateResource($resource);
}
...
}
Since versions 2.0-383, 2.1-302, and 2.2-115, PHP runtime provides the getTypeByServiceId
method to get the type version resource currently has, so you don’t have to specify the type explicitly.
Also, PHP Runtime changes type version automatically in updateResource method, if it is called inside the upgrade
method.
So, the example can be changed to the following:
public function upgrade() {
...
$apsc = \APS\Request::getController();
/* Here resources are still based on the old version */
$resources = $apsc->getResources("implementing(".$this->getTypeByServiceId("vpses").")");
foreach ($resources as $resource) {
/* Define the property as needed */
$resource->parameter1 = "some value";
/* Request the APS controller to apply changes */
$apsc->updateResource($resource);
}
...
}
Refer to upgrade with PHP runtime article.
Link and unlink resources to match the new types. Therefore, use: