Application Packaging Standard

Last updated 18-Mar-2019

Update

Like in the case of the initial development, the application update phase usually includes updates of the same three parts: metadata, provisioning logic, and presentation logic.

../../../_images/start-step-env.png ../../../_images/start-step-overview.png ../../../_images/start-step-develop.png ../../../_images/start-step-deploy.png ../../../_images/start-step-provisioning.png ../../../_images/start-step-update-b.png

Purposes

This document demonstrates how to update both the provisioning logic and presentation logic in a package as well as how to update the APS application deployed and provisioned on your platform.

Let us assume that we need to add one more property to the VPSes and it will be the “Operating System (OS)”, for example, “CentOS-7” or “Windows-2012”. The subscribers will be able to select one of them when they request provisioning of a VPS.

This requires the following updates in the APS package:

  1. In the provisioning logic:
    • In the vps APS type, add one more property called os.
    • In the vps ID, increase the minor part of the version.
    • In the other APS types, update the links to the vps type to specify the new vps version.
  2. In the presentation logic:
    • In the resource model and store, update the vps version.
    • In the list of servers, add the new property as a column to the table.
    • In the server creation view, require a subscriber to select an OS.
  3. In the metadata:
    • Increase the package version.
    • Specify the older versions of the APS application that the package is able to update.

Provisioning Logic

Declare the new os property in the vps APS type and then increase the type version.

Follow these steps.

  1. In the scripts/vpses.php file, add a new section to define the new property:

    /**
     * @type("string")
     * @title("OS")
     * @description("Operating System")
     */
    public $os;
    
  2. In the scripts/vpses.php file, increase the minor part of the APS type version. For example, if it was 1.0, make it 1.1 or higher:

    /**
     * @type("http://aps-standard.org/samples/starter1p/vps/1.2")
     * @implements("http://aps-standard.org/types/core/resource/1.0")
     */
    class vps extends APS\ResourceBase {
       ...
    }
    
  3. In the scripts/managements.php file, update the vpses link to comply with the updated version of the vps type:

    /**
     * @link("http://aps-standard.org/samples/starter1p/vps/1.2[]")
     */
    public $vpses;
    

You can compare the new contents with the sample file.

Presentation Logic

Server List

The ui/servers.js file must show the new os property in a separate column. Also, you should take into account the updated version of the vps type.

Follow these steps.

  1. Update the VPS store to comply with the new version of the vps type:

    var vpsStore = new Store({
       apsType: "http://aps-standard.org/samples/starter1p/vps/1.2",
       target: "/aps/2/resources/"
    });
    
  2. In the column definition of the aps/Grid, add the definition of the new “Operating System” column:

    columns: [{
          field: "name",
          name: "Name"
       }, {
          field: "os",
          name: "Operating System"
       }
    ]
    

This completes the update of the view. You can compare your file contents with the sample servers.js file.

Server Creation

The ui/server-new.js file must request a customer to select one of operating systems from a list.

Follow these steps to update the script.

  1. In the array of the defined modules, add the aps/Memory module and add the corresponding Memory attribute to the main callback function:

    define([...,
          "aps/Memory", ...
       ],
       function(...,
          Memory, ...
       )
    
  2. Create an aps/Memory object and inside it define a list of operating systems that a customer can use for a new VPS:

    var oses = new Memory({
       idProperty: "value",
       data: [
          { value: "centos7",      label: "CentOS 7" },
          { value: "windows2012",  label: "Windows 2012 Server" }
       ]
    });
    
  3. Add the new property to the VPS model and define the default value for it as follows:

    this.vpsModel = getStateful({
          "aps": {
             "type": "http://aps-standard.org/samples/vpsdemo/vps/1.2"
          },
          "name": "",
          "os": "centos7"
    });
    

    Note

    Pay attention to the updated version of the vps type

  4. In the widget definition, add one more input aps/Select widget that will allow a customer to select one of operating systems from the selection list. Sync the selected value with the VPS model as follows:

    ["aps/Select", {
       id: this.genId("srvNew_os"),
       label: "Operating System",
       store: oses,
          value: at(this.vpsModel, "os"),
          required: true
    }]
    
  5. In the onSubmit handler, update the version of the vps type:

    var vpsStore = new Store({
       apsType: "http://aps-standard.org/samples/vpsdemo/vps/1.2",
       target: "/aps/2/resources/" + aps.context.vars.management.aps.id + "/vpses"
    });
    

This completes the update of the view. You can compare your file contents with the sample server-new.js file.

Metadata

To update an APS application on the platform from an APS package, you should increase the package version to make it higher than the version of the current APS application you wish to update. In addition, you must specify in the metadata a range of the old versions that the package can update.

Open the APP-META.xml file in an editor and follow these steps.

  1. Increase the version property:

    <version>2.0</version>
    
  2. Allow upgrade of all previous versions by adding the <upgrade> element just above the first <service> element as explained in the Upgrade Section:

    <upgrade match="version=ge=1.0, release=ge=0"/>
    

Testing

Update the deployment image, build the updated APS package and then use it to update the APS application on the platform as explained in the next sections.

Update Deployment Image

Every time you update the package version, you must create a new image with the updated tag. If the folder name is project-starter, enter inside it and execute the same commands you run during the deployment:

  1. Create an image with the tag equal to the new APS package version:

    # docker build -f deploy-image/Dockerfile\
     -t platform-docker-repo.ap.int.zone/odin/starter:2.0-0 .
    
  2. Push the image to the Docker registry:

    # docker push platform-docker-repo.ap.int.zone/odin/starter:2.0-0
    

Build Package

Use one of the methods to build the APS package from the updated projects, for example:

$ aps build project-starter

The name of the output file must reflect the new version, for example:

Simplest_demo_project-2.0-0.app.zip

Update APS Application Instance

In the PCP, use the following actions to update the deployed and provisioned APS application.

  1. Navigate to Services > Applications.

  2. Click Import Package, select local file, and click Choose File to browse for the updated APS package on your local computer.

  3. Click Submit to complete the import.

  4. In the list of applications, wait for update of the application version to the new one by clicking the refresh icon on top right of the screen.

    ../../../_images/app-updated-version.png
  5. Open the updated application.

  6. On the Instances tab, select the instance you want to update.

  7. Click Upgrade.

  8. Click the refresh icon on top right of the screen to ensure the application version was successfully updated for the instance.

Test Application

Verify the updates in the customer control panel.

  1. In the list of servers, notice the new OPERATING SYSTEMS column:

    ../../../_images/start-update-list-oldvps.png

    Evidently, it must be empty for the servers created before the update.

  2. Add a new VPS and select an OS for it:

    ../../../_images/start-update-vps-new.png

The list of servers will show the assigned OS for the new VPS:

../../../_images/start-update-list.png

Conclusion

You went through the main APS application life cycle steps, including the simple project planning, development, deployment, and provisioning. After that, you got skills in the application update process.

If you experienced any issues in the APS application development, or wish to compare your package with a functional package, or for any other test and training reasons, download the sample packages:

The Integration Procedures document provides more complex scenarios illustrating the main integration points of the platform. Most probably, you will find out there some solutions that help you integrate your cloud applications.