12.4. Application Manifests

GEISA’s application management system follows a model similar to Amazon IoT Greengrass or Microsoft Azure IoT in that applications have a recipe, manifest, or other set of metadata describing the requirements and dependencies.

GEISA handles application meta-data by defining two manifests for each application: a vendor manifest and an operator manifest.

The vendor application manifest provides information about the application to the operator and the edge management system, including any external dependencies and minimum resource requirements. The vendor manifest is used by a GEISA ADM conformant edge management system to inform the operator about the application and to facilitate the secure import of the application.

The operator application manifest is based on the vendor application manifest allowing the operator to customize and tune the application permissions and resource allocations to match their execution environment, intended use case, and security requirements prior to deployment to the execution environment.

GEISA vendor and operator application manifests SHALL include:

  • Vendor assigned Application ID

    • Vendor assigned application IDs use https://en.wikipedia.org/wiki/Reverse_domain_name_notation Reverse DNS Name Notation, similar to Java packages

    • GEISA recommends tld.companyname.geisa.appname for application IDs, for example, org.lfenergy.geisa.waveformanalyzer.

  • Name of the application

  • Description of the application

  • Version Number of the application

  • Hash of the application image

    • The GEISA EE shall not activate an application unless the hash of the image matches the hash in the meta-data

GEISA vendor manifests SHALL include:

  • Compatibility:

    • GEISA API Minimum Version

    • GEISA LEE Minimum Version (null for unsupported)

    • GEISA VEE Minimum Version (null for unsupported)

    • Waveform Access Required (boolean)

    • GEISA LEE CPU arch string as returned by the Linux arch command:

      • ARM 32-bit: armv7l, armv6l

      • ARM 64-bit: aarch64

      • RISC-V 32-bit: riscv32

      • RISC-V 64-bit: riscv64

      • x86 32-bit: i686

      • X86 64-bit: x86_64, amd64

    • GEISA LEE C library required:

      • glibc

      • musl

      • uClibc

      • uClibc-ng

    • For VEE, a string of the JVM version:

      • Java 8: java8

      • Java 11: java11

      • Java 17: java17

      • Java 21: java21

  • System Resources Required:

    • CPU usage in percent

    • RAM in KiB

    • Persistent Storage in KiB

    • Non-persistent Storage in KiB

    • Max threads/processes

  • Off-Device Communication

    • Each application that performs off-device communication MUST specify the classes, destinations, and daily volume of that communication.

    • See Off-Device Communication for details.

    • Daily volumes are specified in Byte units, and daily messages are in message units.

Note

Application messaging is provided through the API and does not require direct access to a network interface.

Note

Requests for IP socket communication in a vendor manifest are subject to operator approval in the deployment manifest. Operators may approve, narrow, replace, or deny requested destination classes, endpoints, ports, and volume limits according to deployment policy.

  • External Dependencies

    • GEISA applications should be as self-contained as possible, with all necessary dependencies, except for the base libraries provided by the EE, contained with the application artifacts.

    • GEISA does not provide a mechanism for loading arbitrary packages. The external dependencies element in the manifest is used exclusively to indicate that one application depends on another.

    • Vendor-assigned Application ID of the application this application depends on.

  • Default Application Configuration

    • GEISA applications may need basic information to initialize such as the URL of a server, or settngs such as the frequency of reportng. The default application configuration provides an initial set of values that can be used by the system operator when creating the operator manifest.

Note

The system operator should be able to change the configuration information without needing to redeploy the application.

  • Default Launch Strategy

    • Includes details such as whether the application should automatically be restarted if it fails, and how many failures with a given period of time constitues a permanent failure.

      • Auto restart (boolean)

      • Max failures – number of failures within the restart period after which the application will not be restarted

      • Restart period – elasped time, in minutes, before the failure count is reset. The first failure starts the timer. If the configured maximum number of failures occurs before the restart period is over, the application is not restarted. Otherwise, the failure count is reset.

  • Vendor Signature

    • Base64 Encoded Signature of the compact JSON encoding of the vendor application manifest.

Note

ToDo: Add details on the signature mechanism.

Here is an example of an vendor application manifest.

 1{
 2  "geisa-vendor-app-manifest": {
 3    "org.lfenergy.geisa.HelloWorld": {
 4      "author": "Some Company",
 5      "name": "Hello World Application",
 6      "description": "Killer application that writes 'hello world' to the log",
 7      "version": "1.0.0",
 8      "artifacts": {
 9        "image-size": 748340,
10        "uncompressed-size": 2494464,
11        "image": "helloworld-1.tgz",
12        "sha256": "00beeaeeca59f9177d88a13132f7c0686616fe728d85f20ddbd15352abd10988"
13      },
14      "compatibility": {
15        "GEISA-API": "1.0.0",
16        "GEISA-LEE": "1.0.0",
17        "GEISA-VEE": null,
18        "CPU": "aarch64"
19        "LIB": "musl"
20      },
21      "resources": {
22        "app-cpu": 30,
23        "app-ram": 40,
24        "storage-persist": 20,
25        "storage-nonpersist": 5,
26        "threads": 50,
27        "AMI": false,
28        "HAN": true,
29        "waveform": true
30      },
31      "communication": {
32        "message": {
33          "daily-messages": 30
34        },
35        "operator": {
36          "daily-volume": 2048,
37          "outbound": [
38            "tcp:[3fff:421:32::/48]:443",
39            "udp:[3fff:421:2:661::/64]:4242",
40            "tcp:198.51.100.0/24:999"
41          ]
42        },
43        "internet": {
44          "daily-volume": 51200,
45          "outbound": [
46            "tcp:[2001:db8:44:12::/64]:443",
47            "udp:203.0.113.66:2256"
48          ]
49        }
50        "local": {
51          "outbound": [
52            "tcp::9999",
53            "tcp::502"
54            "udp::51234"
55            "udp::5540"
56          ]
57          "inbound": [
58            "tcp::5540",
59            "udp::5540",
60          ]
61          "inbound-multicast": [
62            "255.255.255.255",
63            "224.0.0.251",
64            "ff02::fa",
65            "ff02::fb",
66          ]
67        }
68      },
69      "external-dependencies": [
70        null
71      ],
72      "default-configuration": {
73        "knob": 36,
74        "setting": "blue",
75        "turbo encabulator active": true
76      },
77      "default-launch-strategy": {
78        "auto-restart": true,
79        "max restarts": 5,
80        "restart period": 60
81      }
82    }
83  }
84}