Table Of Contents

System Environment

The SystemEnvironment type implements the base environment. It was designed for deploying applications on top of a bare operating system.

System Environment Interface

The system environment type (download) implements the base environment type and adds an optional relation collection to the IP address type:

{
    "apsVersion": "2.0",

    "name": "SystemEnvironment",

    "id": "http://aps-standard.org/types/infrastructure/environment/system/1.1",
    "implements": [ "http://aps-standard.org/types/infrastructure/environment/1.0" ],
    
    "relations": {
        "ipAddresses": {
            "type": "http://aps-standard.org/types/ip-address/1.1",
            "collection": true
         }
    }
}

It also has own provisioning logic as explained in this document.

Provision into System Environment

Meta Description

Any APS package compatible with the system environment type must contain one or more <code> sections in the declaration of the root application service that implements the core application type. This section in the APP-META.xml file looks similar to the following:

<service id="application">
    <!-- The schema must declare implementation of the APS core application type -->
    <schema path="myApp.schema"/>

    <!-- Below statements are required for application to support deployment in
         the http://aps-standard.org/types/infrastructure/environment/system/1.0 -->
    <code engine="exec" path="scripts/provision.sh">
       <arg>--unattended</arg>
       <arg>--aps</arg>
    </code>
    <code engine="exec" path="scripts/provision.exe">
       <arg>--unattended</arg>
       <arg>--windows-specfic-arg</arg>
    </code>
</service>

Note

If multiple <code> sections are declared, the system environment uses the first binary in the list compatible with the platform where the package is being deployed.

The above section declares the following:

  • Path to the schema of the root application type, myApp.schema, used for creating application instances.

  • Application provisioning engine (an executable file), for example, scripts/provision.sh, exposed for the system environment as the application endpoint. This allows the system environment to function as a proxy, redirecting REST requests and responses to and from this engine.

  • Arguments that the system environment must pass to the application provisioning engine when calling it.

  • Environment should select one of engine="exec" code blocks, if path attribute matches one of .bat .exe .cmd .ps1 it will fit for windows platform, all other for linux or mac

The myApp.schema referred in the above example may look as follows:

{
    "apsVersion": "2.0",
    "name": "MyApp",

    "id": "http://myApp.example/types/myapp",
    "implements": [
        "http://aps-standard.org/types/core/application/1.0"
    ],

    "properties"  : { ... },

    "relations": {
        /* The below declaration is very important -
           Mandatory dependency on the System Environment type means that this
           application supports deploying into that type of environment */
        "env": {
            "type": "http://aps-standard.org/types/infrastructure/environment/system/1.0",
            "required": true
        }
    }
}

Key points:

  • Since this is the application root service, it implements the APS core application type.

  • The root application resource, actually application instance, must have the required relation with a system environment.

Provisioning Flow

The provisioning logic of the system environment follows the application provisioning workflow and it is conceptually presented by the following diagram:

../../../../../_images/system-environment-1.png

  1. Once the APS controller has received a request for creating an application instance, it starts with creating links required by the application. In accordance with the relation declared in the above example, the application instance must relate to a system environment. If there is such environment, the APS controller requires it to create a link with the application. If there is no proper environment, the APS controller will create it first, and then requires creating the link.

  2. Following its provisioning logic, the system environment requests the APS controller for the application package using the /aps/2/packages interface in order to install the APS application inside the environment.

  3. The environment system extracts the package contents into a folder within the environment.

  4. Following meta description of the root service, the system environment starts the application provisioning engine to install the APS application instance, for example:

    cd packages/<app_id>
./scripts/provision.sh --unattended --aps

  5. The application provisioning engine installs the APS application instance and, optionally, can expose its direct endpoint URL. If it does not expose its endpoint, the system environment exposes the application endpoint on its own URL. In the latter case, the system environment will proxy all REST requests and responds between the APS controller and the application instance.

Once the link provision request is processed by the System Environment, the APS controller issues a resource provisioning request to the APS application endpoint registered earlier.

Proxy Concepts

System environment can function as a proxy following these concepts:

  1. The endpoint exposed by the system environment is protected by the APS network security system as all other APS REST endpoints.

  2. The system environment handles all requests from the APS controller to the application on its endpoint.

    ../../../../../_images/system-environment-3.png

  3. When the system environment gets a REST request on its endpoint, it forwards it to the STDIN input flow of the application provisioning engine using the following logic:

    • It changes current directory for the folder where the package is deployed.

    • It starts the application provisioning engine with administrator permissions, that is root on Linux or Administrator on Windows.

  4. Once the provisioning engine accomplishes processing, the system environment reads both STDOUT and STDERR of the engine and interprets the exit code:

    • In case of successful execution, the engine returns code 0, and the system environment sends the collected STDOUT contents back to the APS controller in response to a REST request.

    • In case of an unsuccessful result, the system environment sends HTTP 500 response with wrapped STDOUT and STDERR contents in the body back to the APS Controller,.

Consider the following example. The APS controller requests a resource provisioning:

POST /vpses HTTP/1.1
Content-length: 123
Content-type: application/json

  {
      "aps": {
         "type": ".../environment/system/1.0",
         "id": "b798d00e-dc8c-463a-aa6d-f2a4b39b1881"
      },
      "name": "VPS-101",
      ...
  }

  • In successful scenario, the provisioning script must provide a REST response with headers and, optionally, with body on its STDOUT. The system environment redirects this response to the APS controller as is, for example:

    HTTP/1.1 200 OK
Content-length: 123
Content-type: application/json

{
    "aps": {
       "type": ".../environment/system/1.0",
       "id": "b798d00e-dc8c-463a-aa6d-f2a4b39b1881"
    },
    "name": "VPS-101",
    ...
}

  • In case of failure, the system environment wraps the STDOUT and STDER contents into the standard HTTP 500 response, for example:

    HTTP/1.1 500 Environment Internal Error
Content-length: 123
Content-type: application/json

{
    "error": "packageRequestFailure",
    "message": "Application script abcd.sh has been failed",
    "code": 200,
    "stdout": "Error executing script provision.sh",
    "stderr": "Can’t load library libabcd.so"
}

Exposing Direct Endpoint

To avoid proxy and, thus, to improve performance, the APS application can expose its own direct endpoint. For this purpose, it notifies the APS controller using an update endpoint request. From that moment, the APS controller will send all requests to the application resource through the newly exposed application endpoint.