Application Package

The Application Package, which is used to distribute an application to be deployed as workloads on edge devices, comprises the following elements:

• The Application Description: a YAML document with the element kind defined as ApplicationDescription, which is stored in a file (for example named margo.yaml) and contains information about the application's metadata (e.g., name, version, author, etc.), the application components (e.g., Helm charts, Compose Archive), which are defined in deployment configurations, and configurable application parameters. There is only one YAML file in the package root of kind ApplicationDescription.
• The resources, which are additional files associated with the application (human-readable description, icon, release notes, or license file) that may be used to provide more information about the application (e.g., in a UI such as an application catalog of a WFM).

The Application Package is distributed via an Application Registry and is bundled within a repository according to the OCI distribution specification. All files (i.e., Application Description and resource files) belonging to the Application Package are referenced as layers (the equivalent term blobs is nowadays preferred and will be used in the rest of this document) by a manifest inside the repository. The blob of the Application Description file is marked with a mediaType value as application/vnd.margo.app.description.v1+yaml. The blobs of resource files are marked with an according mediaType (see list here), e.g., an icon in jpeg format is marked with the mediaTye application/vnd.margo.app.icon.v1+jpeg. This is illustrated in the figure below and formally defined here.

An application aggregates one or more components. Therefore, the deployment profiles specified in the Application Description can be defined as Helm Chart components AND/OR Compose Archive components.

Each component links to one or more OCI Container Images. The components referenced in the Application Description are stored in a Component Registry, and the linked container images are provided via a Container Image Registry. Registries can be remote (i.e., Internet-accessible) or local (i.e., accessible within a local network infrastructure of the devices).

The components are being deployed as workloads on the edge devices:

• To target devices, which deploy workloads using Kubernetes, components need to be defined as Helm charts using Helm (version 3).
• To target devices, which deploy workloads using Compose, components need to be packaged as Compose Archives, i.e., a tarball file containing the compose.yaml file and any additional artifacts referenced by the Compose file (e.g., configuration files, environment variable files, etc.). Margo recommends to digitally sign this package and to specify the location of the public key in the ApplicationDescription (see keyLocation here). When digitally signing the package PGP encryption MUST be used.

If either one cannot be implemented it MAY be omitted but Margo RECOMMENDS defining deployment profiles as both Helm chart AND Compose components to strengthen interoperability and applicability.

Note A device running the application will only install the application using either the Compose Archives or the Helm Charts, but not both.

Margo will provide more detailed discussion and specification on the following points:

Investigation Needed: Question: do we need to specify the location of a SHA256 hash for the Compose Archive also (similar to the PGP key) in the ApplicationDescription? We will also discuss how we should handle secure container registries that require a username and password.

Investigation Needed: We need to determine what impact, if any, using 3rd party helm charts has on being Margo compliant.

Investigation Needed: Missing in the current specification are ways to define dependencies (e.g., application dependencies) as well as required infrastructure services such as storage, message queues/bus, reverse proxy, or authentication/authorization/accounting.

Relevant Links

Please follow the subsequent link to view the technical reference of the ApplicationDescription format:

• Application Description