Upgrade¶

In this document:

Purposes
Versioning in APS
Upgrade Strategies
Upgrade Procedure
Developing a Package Update
Upgrade Workflow in the Platform
Upgrades processed by the APS Controller
Upgrades processed by the Application

Purposes ¶

This document compiles all data related to the upgrade processes in APS applications. In the following table are a select few cases when an APS application needs an upgrade.

Root Cause	Affected APS Components	Example
New service added	- New service declared in metadata - New APS type - New relations with existing APS types - Provisioning logic of the new service - New UI views and existing UI views	The subscription must include references to available configurations (offers).
Business related resources must be able to get access to each other’s properties	- New relationship between APS types - Permissions in APS types - UI view	On the view presenting VPSes, the server owner must be displayed.
A new custom operation added to a service	- Custom operation in the APS type - Provisioning logic of the service - UI view that enables the feature to users	The VPS owner is allowed to start and stop the VPS.

Note

An APS application is uniquely identified by its ID as specified in package metadata. The upgrade process assumes that the same application ID in a current APS package is used as in APS packages that are updates of the current package.

Warning

APS does not support upgrade of packages from APS 1 to APS 2.

Versioning in APS ¶

In APS packages, versions are assigned to the following components:

Component	Example	Description	Influence on upgrade
APS specification	<application… `version="2.0"`>	Defines the package format	Note The application upgrade process described here 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	- Typically, the same `version` as the integrated cloud application. - `release` distinguishes packages with the same `version`. - The package version must be updated in a new package before importing it to the platform.
APS type version	“id”: `"http://.../vps/1.0"`	Version of APS resources	Upgrades all APS resources based on the updated APS type.

Specification Version¶

The 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.

The APS version is also specified in each APS type definition by means of the apsVersion property, for example:

{
  "apsVersion": "2.0",
  "name": "vps",
  ...
}

Package Version¶

The package version is specified by two elements in package metadata:

The <version> element normally must correspond to the version of the integrated cloud application.
The <release> element indicates a package release and changes each time there is a need to update the package without changing the application version.

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

For the normal upgrade process, the new package version must be higher than any other package versions with the same application ID that are already stored in the APS package repository.

APS Type Version¶

Each *.schema file in an APS package defines an APS type. The APS type ID contains the APS type version. In the following example, the APS 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"
  ],...
}

APS type ID http://aps-standard.org/samples/vpscloud/vps/1.0 contains its version - 1.0. If in a new package the APS type version is increased and the application instance is updated to the new package, then the APS controller will make all APS resources based on this APS type bound to its new version.

Among other APS types, each APS package must contain APS type definition for APS resources representing APS application instances. This APS type implements the core Application APS type 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 APS type implements the core Application APS type, whose ID is http://aps-standard.org/types/core/application/1.0. Thus, it declares itself as the APS type that must be used for provisioning an application instance through the root application service declared on an APS connector. This service must accept the upgrade call during the upgrade process. In the above example, the APS type ID is http://aps-standard.org/samples/vpscloud/1.0, and the version is 1.0.

Each application instance in the platform is upgraded independently, meaning different application instances can be based on different package versions. Therefore, there is no restriction on having different versions of an APS type defined by different package versions on the same platform.

Upgrade Strategies ¶

Formal Upgrade Specification¶

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 in this document.

Major and Minor Upgrades¶

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 backward compatible . It means, after an upgrade, there is no need to change the APS type ID in existing requests for APS resources. For example, if an APS type is upgraded from http://www.odin.com/mailbox/1.0 to http://www.odin.com/mailbox/1.4, the APS controller returns the upgraded APS resource representation even if it receives the http://www.odin.com/mailbox/1.0 APS type in the request. The returned APS resource is bound to the new APS type version.

However the reverse, forward compatibility , is not supported. For example, when APS type http://www.odin.com/mailbox/1.5 is requested, the APS controller will not return APS 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 incompatible APS types.

The following examples illustrate the cases when it is better to use minor upgrade and when a major upgrade is necessary.

Example 1: A Minor Upgrade¶

Initially there is a vps APS 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 decides to add the optional property “description”. Since the property is not required, the APS resources will be backward compatible after the APS type upgrade. That is why, the developer does a 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",
      },
      ...
  }
}

Note

In the current version of the platform, we recommend not changing the version when an APS type is updated in the backward-compatible manner as described in this example. This avoids upgrading all existing APS resources based on the updated APS type. If you follow this recommendation, the previous code must be rewritten using the current version of the APS type:

{
  "apsVersion": "2.0",
  "name": "vps",
  "id": "http://aps-standard.org/samples/vpsclouds/vps/1.0",
  ...
  "properties": {
      "name": {
        "type": "string",
      },
      "description": {
        "type": "string",
      },
      ...
  }
}

With such a version-less update, the existing APS resources will not have the new property description until you add it by a PUT request.

Example 2: A Major Upgrade¶

Following multiple requests from providers, the developer decides to make the “description” a required property. Evidently, the VPSes created earlier will not be compatible with the new APS type version since they may do not have a description. That is why, the developer does 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
      },
      ...
  }
}

Backward Compatible Upgrades of APS Types¶

In an APS type, there are three kinds of components that can be upgraded. The following upgrades are considered as backward compatible and therefore do not require changing of the APS type version.

Relations:
- Adding weak (non-required) relations
Operations:
- Adding custom operations

Properties:

Adding optional (non-required) properties
Adding required properties with the default attribute (this requires the upgrade of the existing APS application instance after importing the updated APS package)

In general, changing attributes of a property is an incompatible upgrade. However, changes of specific attributes that affect only the platform UI and do not affect other API clients, as presented in the following table, are backward compatible:

ATTRIBUTE	TYPE	DEFAULT	DESCRIPTION
`description`	string	null	Used to provide the full description of a resource in the platform UI. You can add this attribute but you cannot change it.
`headline`	boolean	false	Indicates whether the property is used to represent an APS resource in the platform’s auto-generated UI, when creating a resource type.
`title`	string	null	Used as a short description in the platform UI. You can add this attribute but you cannot change it.

Note

New relations, custom operations, and required properties (with the default attribute) can be used only after upgrading the existing APS application instance. This is possible if the version of the newly imported APS package containing those changes is increased and the upgrade configuration allows for the upgrade.

Upgrade Procedure ¶

To upgrade an APS application, it is necessary to update the APS package and then upgrade the application in the platform in accordance with the workflow.

Developing a Package Update ¶

Generally, the procedure of updating a package resembles the package development steps, but it requires developers to do only those steps that make the necessary updates. The following diagram presents candidates for an update along with the corresponding files and metadata.

The recommended steps look as follows:

Draw the updated resource diagram, reflecting major changes:
- Some APS types and respective services are added or deleted
- Relations are renamed, added, removed, or updated
Update APS types to change the following:
- Change the implements section
- Add or delete properties
- Update attributes of properties
- Declare new custom operations or remove some of custom operations
- Update arguments of custom operations
Update the provisioning logic of APS connectors:
- Create or update classes implementing services declared in metadata
- Create or update methods implementing operations declared in APS types
- Modify the upgrade() method in the application root service
Update the user interface:
- Add or update navigation tree declaration in metadata
- Update UI scripts
Update localization and text translation:
- Add or update localization files
Update the metadata:
- Update the declaration of the UI navigation
- Add or remove the declaration of services as necessary
  
  Warning
  
  It is not possible to change the service ID declared in the metadata, because it looks as if you removed a service and added a new one.
- Increase the package version
- Specify the range of old packages that this package can upgrade

Updating a Resource Diagram¶

It is necessary to draw a new resource diagram to clearly reflect the following updates:

Adding or removing APS types
Adding or removing links
Changing link properties that make a link weak or strong, collection or singular

The example below indicates the following updates:

../../../../_images/update-resource-diagram.png

A new APS type named offer appears.
The new APS type will have two relations, cloud and vpses, with existing APS types.
When updating the application, it is necessary to add new links to corresponding provisioned APS resources. This concerns cloud and vps APS resources.

Updating APS Types¶

An APS type can be updated in the following ways, each leading to declaration of a new APS type or a new APS type version as well as to updates in the provisioning logic on the APS application endpoint:

Adding or removing APS types
Changing the implements section (adding or removing of an implemented APS type or changing the version of an implemented APS type)
Adding or removing properties and operations
Updating properties
Updating operations

Note

1. When updating an APS type, the APS controller will bind the corresponding APS resources of the updated application instance to the new APS 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 connector.

Updating the Provisioning Logic of APS Connectors¶

The provisioning logic can be updated or fixed by updating provisioning scripts or other APS types of executables inside the APS package. Respective updates must be performed on the APS connectors.

Warning

The APS controller refuses an update that requires removing a service if there are APS resources provisioned through it.

Updating Metadata¶

The updates described earlier may require update of metadata. The following list contains specifics of metadata updates.

The package version must be increased. If the version of the integrated application is increased, then the <version> element in metadata must be increased accordingly, and it makes sense to reset the <release> element. Otherwise, only increase the <release> element.
In the changelog, a new record should be added. It must reflect the changes in the package that help service providers make decision on application update.
Variables specified in navigation trees require updating if the versions of APS types they are referring are updated.
Changes in application services, such as addition, removal, and renaming, require respective updates in metadata.
To specify old packages that can be updated by this new package, the <upgrade> elements must be modified accordingly, as described in the next section.

Upgrade Section¶

Package Matching¶

The <upgrade> section declares a range of previous package versions that the current package can upgrade. Its match attribute defines this range using 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 the 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>

A 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>

Renaming Relations¶

The <upgrade> section allows you to change relation names in APS types. For this purpose, this 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, the same names cannot be used 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 APS type was linked to the user APS 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:
1. In the vps schema definition, rename the myuser relation to user.
2. Update the vps APS type version to 1.1.
3. In the metadata definition, specify the relation renaming: <relation new=”user” old=”myuser”/>
4. Update the package version to 1.1.
In package version 1.0, the vps APS type was linked to the user APS type through the myuser link. In the next package version 1.1, the vps APS type implements the standard UserService APS type that has the user relation definition. This means, the vps APS type inherites the user link and there is no need to use the old myuser relation.

The new package must go through the following changes:
1. Make the vps APS type implement the UserService APS type.
2. In the vps schema definition, remove the myuser relation.
3. Update the vps APS type version to 1.1.
4. In the metadata definition, specify the relation renaming: <relation new=”user” old=”myuser”/>
5. Update the package version to 1.1.

Updating the User Interface¶

The following updates can be applied to a custom UI.

Updating Navigation tree in the <presentation> section of metadata.
Adding, modifying, or deleting UI scripts in the ui folder of the package.

Updating Text Translation¶

Updating text translation to different languages is the same as described in the Internationalization and Localization section.

Modifying an Upgrade Script¶

If an 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.

Building a Package¶

To build the updated package, use the APS build utility as described in Building Package. Pay attention to the package version that must be higher than the package versions to be updated.

Upgrade Workflow in the Platform ¶

Once an updated package is imported to the platform, an administrator of the platform can initiate the upgrade of an APS application instance to the new version of the package.

Preliminary, the provider staff must ensure:

There are no failed tasks in the platform related to the application being upgraded.
The application provisioning logic, for example, PHP scripts, is updated on the APS connector.

The APS controller processes the upgrade internally and then calls the upgrade method of the application root service (implementing the core application APS type) on the APS connector. The upgrade method is executed on the APS connector to bring the application APS resources in compliance with the updated package. Once the APS connector responds, the APS controller runs the post-upgrade operations to complete this upgrade.

Upgrades processed by the APS Controller ¶

Base Process¶

The aps.status property of the application APS resource indicates whether the upgrade process is started as illustrated in this diagram:

The upgrade process for a selected APS application instance is initiated from the control panel of the platform. This makes the APS controller go through the following steps.

Switch the application APS resource status to upgrading.
Update the aps.package.id property in the application instance, thus binding the application instance to the new package.
Call the upgrade method of the application APS resource and wait for the response. An application specific transfer from the current version to the new one must be done by the application instance itself. This operation can take a considerable amount of time. The application instance can communicate with the APS controller to get, register, or change application APS 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 must use the APS types updated by the new package, however the result depends on the operation:
- When the application requests (GET operation) for an APS resource from the controller, the APS resource bound to the current APS type is returned.
- When the application requests for creating (POST) or updating (PUT) an APS resource, the APS controller will return the APS resource bound or re-bound to the new APS type.
Warning

1. A custom operation declared in an APS type whose version is being changed cannot be called. 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 omit this header in the request to make the APS controller generate a new one.

2. In production, you must avoid having APS application instances bound to different package versions as explained in APS Application Instance Upgrade.
After the application completes its upgrade, perform internal post-upgrade operations. The goal is to ensure the correct transfer of all APS resources to the new package with new APS type definitions. The APS controller achieves this by a number of validation operations.
- Verify if every required property is assigned a value. If there is a required property that is empty and no default value is specified in its APS type, complete the whole upgrade process with error message “Required property ‘x’ has no value”.
- Ensure proper links between APS resources:
  - For each declared required relation, there is a link to an APS resource.
  - APS resources are linked according to the declaration of relations in APS types.
- Unregister all APS resources of the services that are dropped in the new package.
- Process major upgrades:
  - Delete properties whose APS type must change, for example, the CPU property was a number before upgrade, but must be an array of numbers after the upgrade.
  - Delete the links based on relations that are omitted in the new package.
- Process minor upgrades:
  - Assign default values to upgraded or new properties that are required but not assigned a value.
Change the status of the application APS resource to ready.

Upgrades processed by the Application ¶

Preupgrade¶

An application developer may need to prepare the application to the upgrade process, for example, by updating the upgrade method on the APS connector 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.

Upgrade¶

The upgrade() method of the APS application instance defines the update activity on the application side. This method is executed on the newly upgraded version of the APS connector installed on the endpoint host. It is the first call on the new code.

Note

The POST request must contain APS resource representation with the old version in the body on input (from the APS controller to the APS connector) and new version on output (from the APS connector to the APS controller).
If it is necessary to assign a value to a new property which is not defined in the old version of the APS type, the application must explicitly assign the APS resources to the new version of the APS type. This allows for operating the new property.

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

When designing the upgrade method, the application integrator can use the following actions.

Update the properties of all APS resources whose current properties do not match the new APS type. For this purpose, use:
- PUT /aps/2/application/{service-id}/{resource-id} to update APS resource properties
- POST /aps/2/application/{service-id} to register a new APS resource
Update new properties of the application instance (core application APS 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 APS type automatically, before sending the result to the APS controller. This means you only need to change properties, not the APS type:
```
public function upgrade() {
   ...
    $this->newProp = "some value";
    ...
}
```

Update properties of APS resources that did not exist in the old APS types. This is possible only along with updating the APS resources to the new APS 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 APS 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 switch the APS resource to the new APS type */
      $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 APS type version the APS resource is currently bound to, meaning you do not need to specify the APS type explicitly. PHP runtime also changes the APS type version automatically in the updateResource method if it is called inside the upgrade method. Therefore, the example can be changed to the following:

public function upgrade() {
   ...
   $apsc = \APS\Request::getController();

   /* Here APS 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 the upgrade with PHP runtime article for more information.

Link and unlink APS resources to match the new APS types. To do this, use:
- POST /aps/2/resources/{resource-id}/{relation} to link or re-link a resource {resource-id}
- DELETE /aps/2/resources/{resource1-id}/{relation}/{resource2-id} to unlink resources

← Deployment

Special Operations →

CloudBlue Commerce API

Previous topic

Next topic

Upgrade¶

Purposes ¶

Versioning in APS ¶

Specification Version¶

Package Version¶

APS Type Version¶

Upgrade Strategies ¶

Formal Upgrade Specification¶

Major and Minor Upgrades¶

Example 1: A Minor Upgrade¶

Example 2: A Major Upgrade¶

Backward Compatible Upgrades of APS Types¶

Upgrade Procedure ¶

Developing a Package Update ¶

Updating a Resource Diagram¶

Updating APS Types¶

Updating the Provisioning Logic of APS Connectors¶

Updating Metadata¶

Upgrade Section¶

Package Matching¶

Renaming Relations¶

Updating the User Interface¶

Updating Text Translation¶

Modifying an Upgrade Script¶

Building a Package¶

Upgrade Workflow in the Platform ¶

Upgrades processed by the APS Controller ¶

Base Process¶

Upgrades processed by the Application ¶

Preupgrade¶

Upgrade¶

CloudBlue Commerce API

Previous topic

Next topic

Upgrade¶

Specification Version¶

Package Version¶

APS Type Version¶

Formal Upgrade Specification¶

Major and Minor Upgrades¶

Example 1: A Minor Upgrade¶

Example 2: A Major Upgrade¶

Backward Compatible Upgrades of APS Types¶

Updating a Resource Diagram¶

Updating APS Types¶

Updating the Provisioning Logic of APS Connectors¶

Updating Metadata¶

Upgrade Section¶

Package Matching¶

Renaming Relations¶

Updating the User Interface¶

Updating Text Translation¶

Modifying an Upgrade Script¶

Building a Package¶

Base Process¶

Related Upgrades¶

Preupgrade¶

Upgrade¶