Application Description

The purpose of the Application Description is to enable an application's discovery, configuration, and deployment on edge devices. To deploy an application the end user specifies values for the parameters given in an Application Description (e.g., through a UI of the WFM) to instantiate an ApplicationDeployment, which defines the desired state for an application. The structure of the ApplicationDescription object to be provided in the YAML document specified in this page. Some examples are provided also at the bottom of this page.

Object structure

ApplicationDescription Attributes

Attribute	Type	Required?	Description
apiVersion	string	Y	Identifier of the version of the API the object definition follows.
kind	string	Y	Specifies the object type; must be `ApplicationDescription`.
metadata	ApplicationMetadata	Y	Metadata element specifying characteristics about the application deployment. See the Metadata Attributes section below.
deploymentProfiles	[]DeploymentProfileDescription	Y	Deployment profiles element specifying the types of deployments the application supports. See the Deployment section below.
parameters	map[string][Parameter]	N	Parameters element specifying the configurable parameters to use when installing, or updating, the application. See the Parameter section below.
configuration	Configuration	N	Configuration element specifying how parameters should be displayed to the user for setting the value as well as the rules to use to validate the user's input. See the Configuration section below.

Detailed class view: ApplicationDescription

ApplicationMetadata Attributes

Attribute	Type	Required?	Description
id	None	N	None
name	None	N	None
description	None	N	None
version	string	Y	The application's version.
catalog	Catalog	Y	Catalog element specifying the application's metadata for enabling its discovery. See the Catalog section below.

Detailed class view: ApplicationMetadata

Catalog Attributes

Attribute	Type	Required?	Description
application	CatalogApplicationMetadata	N	Application element specifying the application specific metadata. See the Application Metadata section below.
author	[]Author	N	Author element specifying metadata about the application's author. See the Author Metadata section below.
organization	[]Organization	Y	Organization element specifying metadata about the organization/company providing the application. See the Organization Metadata section below.

Detailed class view: Catalog

CatalogApplicationMetadata Attributes

Attribute	Type	Required?	Description
descriptionFile	string	N	Link to the file containing the application's full description. The file should be a markdown file.
icon	string	N	Link to the icon file (e.g., in PNG format).
licenseFile	string	N	Link to the file that details the application's license. The file should either be a plain text, markdown or PDF file.
releaseNotes	string	N	Statement about the changes for this application's release. The file should either be a markdown or PDF file.
site	None	N	None
tagline	string	N	The application's slogan.
tags	[]string	N	An array of strings that can be used to provide additional context for the application in a user interface to assist with task such as categorizing, searching, etc.

Detailed class view: CatalogApplicationMetadata

Author Attributes

Attribute	Type	Required?	Description
name	None	N	None
email	string	N	Email address of the application's creator.

Detailed class view: Author

Organization Attributes

Attribute	Type	Required?	Description
name	None	N	None
site	None	N	None

Detailed class view: Organization

DeploymentProfileDescription Attributes

Attribute	Type	Required?	Description
id	None	N	None
description	None	N	None
requiredResources	Resources	N	Required resources element specifying the resources required to install the application. See the Required Resources section below. The consequences (e.g., aborting / blocking the installation or execution of the application) of not meeting these required resources are not defined (yet) by margo.
type	string	Y	Defines the type of this deployment configuration for the application. The allowed values are `helm.v3`, to indicate the deployment profile's format is Helm version 3, and `compose` to indicate the deployment profile's format is a Compose file. When installing the application on a device supporting the Kubernetes platform, all `helm.v3` components, and only `helm.v3` components, will be provided to the device in same order they are listed in the application description file. When installing the application on a device supporting Compose, all `compose` components, and only `compose` components, will be provided to the device in the same order they are listed in the application description file. The device will install the components in the same order they are listed in the application description file.
components	[]Component	Y	Component element indicating the components to deploy when installing the application. See the Component section below.

Detailed class view: DeploymentProfileDescription

Configuration Attributes

Attribute	Type	Required?	Description
sections	[]Section	Y	Sections are used to group related parameters together, so it is possible to present a user interface with a logical grouping of the parameters in each section. See the Section section below.
schema	None	N	None

Detailed class view: Configuration

Section Attributes

Attribute	Type	Required?	Description
name	None	N	None
settings	[]Setting	Y	Settings are used to provide instructions to the workload orchestration software vendor for displaying parameters to the user. A user MUST be able to provide values for all settings. See the Setting section below.

Detailed class view: Section

Setting Attributes

Attribute	Type	Required?	Description
parameter	string	Y	The name of the parameter the setting is associated with.
name	None	N	None
description	None	N	None
immutable	boolean	N	If true, indicates the parameter value MUST not be changed once it has been set and used to install the application. Default is false if not provided.
schema	None	N	None

Detailed class view: Setting

Schema Attributes

Attribute	Type	Required?	Description
name	None	N	None
dataType	string	Y	Indicates the expected data type for the user provided value. Accepted values are string, integer, double, boolean, array[string], array[integer], array[double], array[boolean]. At a minimum, the provided parameter value MUST match the schema's data type if no other validation rules are provided.

Detailed class view: Schema

TextValidationSchema Attributes

Attribute	Type	Required?	Description
allowEmpty	None	N	None
minLength	integer	N	If set, indicates the minimum number of characters the value must have to be considered valid.
maxLength	integer	N	If set, indicates the maximum number of characters the value must have to be considered valid.
regexMatch	string	N	If set, indicates a regular expression to use to validate the value.
name	None	N	None
dataType	string	Y	Indicates the expected data type for the user provided value. Accepted values are string, integer, double, boolean, array[string], array[integer], array[double], array[boolean]. At a minimum, the provided parameter value MUST match the schema's data type if no other validation rules are provided.

Detailed class view: TextValidationSchema

BooleanValidationSchema Attributes

Attribute	Type	Required?	Description
allowEmpty	None	N	None
name	None	N	None
dataType	string	Y	Indicates the expected data type for the user provided value. Accepted values are string, integer, double, boolean, array[string], array[integer], array[double], array[boolean]. At a minimum, the provided parameter value MUST match the schema's data type if no other validation rules are provided.

Detailed class view: BooleanValidationSchema

NumericIntegerValidationSchema Attributes

Attribute	Type	Required?	Description
allowEmpty	None	N	None
minValue	None	N	None
maxValue	None	N	None
name	None	N	None
dataType	string	Y	Indicates the expected data type for the user provided value. Accepted values are string, integer, double, boolean, array[string], array[integer], array[double], array[boolean]. At a minimum, the provided parameter value MUST match the schema's data type if no other validation rules are provided.

Detailed class view: NumericIntegerValidationSchema

NumericDoubleValidationSchema Attributes

Attribute	Type	Required?	Description
allowEmpty	None	N	None
minValue	None	N	None
maxValue	None	N	None
minPrecision	integer	N	If set, indicates the minimum level of precision the value must have to be considered valid.
maxPrecision	integer	N	If set, indicates the maximum level of precision the value must have to be considered valid.
name	None	N	None
dataType	string	Y	Indicates the expected data type for the user provided value. Accepted values are string, integer, double, boolean, array[string], array[integer], array[double], array[boolean]. At a minimum, the provided parameter value MUST match the schema's data type if no other validation rules are provided.

Detailed class view: NumericDoubleValidationSchema

SelectValidationSchema Attributes

Attribute	Type	Required?	Description
allowEmpty	None	N	None
multiselect	boolean	N	If true, indicates multiple values can be selected. If multiple values can be selected the resulting value is an array of the selected values. The default is false if not provided.
options	[]string	Y	This provides the list of acceptable options the user can select from. The data type for each option must match the parameter setting’s data type.
name	None	N	None
dataType	string	Y	Indicates the expected data type for the user provided value. Accepted values are string, integer, double, boolean, array[string], array[integer], array[double], array[boolean]. At a minimum, the provided parameter value MUST match the schema's data type if no other validation rules are provided.

Detailed class view: SelectValidationSchema

Resources Attributes

Attribute	Type	Required?	Description
cpu	CPU	N	CPU element specifying the CPU requirements for the application. See the CPU section below.
memory	string	N	The minimum amount of memory required. The value is given in binary units (`Ki` = Kibibytes, `Mi` = Mebibytes, `Gi` = Gibibytes). This is defined by the application developer. After deployment of the application, the device MUST provide this amount of memory for the application.
storage	string	N	The amount of storage required for the application to run. This encompasses the installed application and the data it needs to store. The value is given in binary units (`Ki` = Kibibytes, `Mi` = Mebibytes, `Gi` = Gibibytes, `Ti` Tebibytes, `Pi` = Pebibytes, `Ei` = Exbibytes). This is defined by the application developer. After deployment of the application, the device MUST provide this amount of storage for the application
peripherals	[]Peripheral	N	Peripherals element specifying the peripherals required to run the application. See the Peripheral section below.
interfaces	[]CommunicationInterface	N	Interfaces element specifying the communication interfaces required to run the application. See the Communication Interfaces section below.

Detailed class view: Resources

CPU Attributes

Attribute	Type	Required?	Description
cores	double	Y	The required amount of CPU cores the application must use to run in its full functionality. Specified as decimal units of CPU cores (e.g., `0.5` is half a core). This is defined by the application developer. After deployment of the application, the device MUST provide this number of CPU cores for the application.
architectures	[]string	N	The CPU architectures supported by the application. This can be e.g. amd64, x86_64, arm64, arm. See the CpuArchitectureType definition for all permissible values. Multiple arcitecture types can be specified, as the deployment profile may support multiple CPU architectures.

Detailed class view: CPU

Peripheral Attributes

Attribute	Type	Required?	Description
type	string	Y	Defines the type of this deployment configuration for the application. The allowed values are `helm.v3`, to indicate the deployment profile's format is Helm version 3, and `compose` to indicate the deployment profile's format is a Compose file. When installing the application on a device supporting the Kubernetes platform, all `helm.v3` components, and only `helm.v3` components, will be provided to the device in same order they are listed in the application description file. When installing the application on a device supporting Compose, all `compose` components, and only `compose` components, will be provided to the device in the same order they are listed in the application description file. The device will install the components in the same order they are listed in the application description file.
manufacturer	string	N	The name of the manufacturer. If `manufacturer` is specified as a requirement here, it may be difficult to find devices that can host the application. Please use these requirements with caution.
model	string	N	The model of the peripheral. If `model` is specified as a requirement here, it may be difficult to find devices that can host the application. Please use these requirements with caution.

Detailed class view: Peripheral

CommunicationInterface Attributes

Attribute	Type	Required?	Description
type	string	Y	Defines the type of this deployment configuration for the application. The allowed values are `helm.v3`, to indicate the deployment profile's format is Helm version 3, and `compose` to indicate the deployment profile's format is a Compose file. When installing the application on a device supporting the Kubernetes platform, all `helm.v3` components, and only `helm.v3` components, will be provided to the device in same order they are listed in the application description file. When installing the application on a device supporting Compose, all `compose` components, and only `compose` components, will be provided to the device in the same order they are listed in the application description file. The device will install the components in the same order they are listed in the application description file.

Detailed class view: CommunicationInterface

DeploymentProfile Attributes

Attribute	Type	Required?	Description
type	string	Y	Defines the type of this deployment configuration for the application. The allowed values are `helm.v3`, to indicate the deployment profile's format is Helm version 3, and `compose` to indicate the deployment profile's format is a Compose file. When installing the application on a device supporting the Kubernetes platform, all `helm.v3` components, and only `helm.v3` components, will be provided to the device in same order they are listed in the application description file. When installing the application on a device supporting Compose, all `compose` components, and only `compose` components, will be provided to the device in the same order they are listed in the application description file. The device will install the components in the same order they are listed in the application description file.
components	[]Component	Y	Component element indicating the components to deploy when installing the application. See the Component section below.

Detailed class view: DeploymentProfile

Component Attributes

Attribute	Type	Required?	Description
name	None	N	None
properties	ComponentProperties	Y	A dictionary element specifying the component packages's deployment details. See the Component Properties section below.

Detailed class view: Component

Parameter Attributes

Attribute	Type	Required?	Description
name	None	N	None
value	None	N	The parameter's default value. Accepted data types are string, integer, double, boolean, array[string], array[integer], array[double], array[boolean].
targets	[]Target	Y	Used to indicate which component the value should be applied to when installing, or updating, the application. See the Target section below.

Detailed class view: Parameter

Target Attributes

Attribute	Type	Required?	Description
pointer	string	Y	The name of the parameter in the deployment configuration. For Helm deployments, this is the dot notation for the matching element in the `values.yaml` file. This follows the same naming convention you would use with the `--set` command line argument with the `helm install` command. For compose deployments, this is the name of the environment variable to set.
components	[]Component	Y	Component element indicating the components to deploy when installing the application. See the Component section below.

Detailed class view: Target

Examples

Following examples have been automatically validated against the schema of this class.

ApplicationDescription-helm_and_compose

apiVersion: margo.org/v1-alpha1
kind: ApplicationDescription
metadata:
  id: com-northstartida-digitron-orchestrator
  name: Digitron orchestrator
  description: The Digitron orchestrator application
  version: 1.2.1
  catalog:
    application:
      icon: ./resources/ndo-logo.png
      tagline: Northstar Industrial Application's next-gen, AI driven, Digitron instrument orchestrator.
      descriptionFile: ./resources/description.md
      releaseNotes: ./resources/release-notes.md
      licenseFile: ./resources/license.pdf
      site: http://www.northstar-ida.com
      tags: ["optimization", "instrumentation"]
    author:
      - name: Roger Wilkershank
        email: rpwilkershank@northstar-ida.com
    organization:
      - name: Northstar Industrial Applications
        site: http://northstar-ida.com
deploymentProfiles:
  - type: helm.v3
    id: com-northstartida-digitron-orchestrator-helm.v3-a
    description: This allows to install / run the application as a Helm chart deployment.
      The device where this application is installed needs to have a screen and a keyboard (as indicated in the required peripherals).
    components:
      - name: database-services
        properties:
          repository: oci://quay.io/charts/realtime-database-services
          revision: 2.3.7
          wait: true
          timeout: 8m30s
      - name: digitron-orchestrator
        properties:
          repository: oci://northstarida.azurecr.io/charts/northstarida-digitron-orchestrator
          revision: 1.0.9
          wait: true
    requiredResources:
      cpu:
        cores: 1.5
        architectures:
          - amd64
          - x86_64
      memory: 1024Mi
      storage: 10Gi
      peripherals:
        - type: gpu
          manufacturer: NVIDIA
        - type: display
      interfaces:
        - type: ethernet
        - type: bluetooth
  - type: compose
    id: com-northstartida-digitron-orchestrator-compose-a
    components:
      - name: digitron-orchestrator-docker
        properties:
          packageLocation: https://northsitarida.com/digitron/docker/digitron-orchestrator.tar.gz
          keyLocation: https://northsitarida.com/digitron/docker/public-key.asc
parameters:
  idpName:
    targets:
      - pointer: idp.name
        components: ["digitron-orchestrator"]
      - pointer: ENV.IDP_NAME
        components: ["digitron-orchestrator-docker"]
  idpProvider:
    targets:
      - pointer: idp.provider
        components: ["digitron-orchestrator"]
      - pointer: ENV.IDP_PROVIDER
        components: ["digitron-orchestrator-docker"]
  idpClientId:
    targets:
      - pointer: idp.clientId
        components: ["digitron-orchestrator"]
      - pointer: ENV.IDP_CLIENT_ID
        components: ["digitron-orchestrator-docker"]
  idpUrl:
    targets:
      - pointer: idp.providerUrl
        components: ["digitron-orchestrator"]
      - pointer: idp.providerMetadata
        components: ["digitron-orchestrator"]
      - pointer: ENV.IDP_URL
        components: ["digitron-orchestrator-docker"]
  adminName:
    targets:
      - pointer: administrator.name
        components: ["digitron-orchestrator"]
      - pointer: ENV.ADMIN_NAME
        components: ["digitron-orchestrator-docker"]
  adminPrincipalName:
    targets:
      - pointer: administrator.userPrincipalName
        components: ["digitron-orchestrator"]
      - pointer: ENV.ADMIN_PRINCIPALNAME
        components: ["digitron-orchestrator-docker"]
  pollFrequency:
    value: 30
    targets:
      - pointer: settings.pollFrequency
        components: ["digitron-orchestrator", "database-services"]
      - pointer: ENV.POLL_FREQUENCY
        components: ["digitron-orchestrator-docker"]
  siteId:
    targets:
      - pointer: settings.siteId
        components: ["digitron-orchestrator", "database-services"]
      - pointer: ENV.SITE_ID
        components: ["digitron-orchestrator-docker"]
  cpuLimit:
    value: 1
    targets:
      - pointer: settings.limits.cpu
        components: ["digitron-orchestrator"]
  memoryLimit:
    value: 16384
    targets:
      - pointer: settings.limits.memory
        components: ["digitron-orchestrator"]
configuration:
  sections:
    - name: General
      settings:
        - parameter: pollFrequency
          name: Poll Frequency
          description: How often the service polls for updated data in seconds
          schema: pollRange
        - parameter: siteId
          name: Site Id
          description: Special identifier for the site (optional)
          schema: optionalText
    - name: Identity Provider
      settings:
        - parameter: idpName
          name: Name
          description: The name of the Identity Provider to use
          immutable: true
          schema: requiredText
        - parameter: idpProvider
          name: Provider
          description: Provider something something
          immutable: true
          schema: requiredText
        - parameter: idpClientId
          name: Client ID
          description: The client id
          immutable: true
          schema: requiredText
        - parameter: idpUrl
          name: Provider URL
          description: The url of the Identity Provider
          immutable: true
          schema: url
    - name: Administrator
      settings:
        - parameter: adminName
          name: Presentation Name
          description: The presentation name of the administrator
          schema: requiredText
        - parameter: adminPrincipalName
          name: Principal Name
          description: The principal name of the administrator
          schema: email
    - name: Resource Limits
      settings:
        - parameter: cpuLimit
          name: CPU Limit
          description: Maximum number of CPU cores to allow the application to consume
          schema: cpuRange
        - parameter: memoryLimit
          name: Memory Limit
          description: Maximum number of memory to allow the application to consume
          schema: memoryRange
  schema:
    - name: requiredText
      dataType: string
      maxLength: 45
      allowEmpty: false
    - name: email
      dataType: string
      allowEmpty: false
      regexMatch: .*@[a-z0-9.-]*
    - name: url
      dataType: string
      allowEmpty: false
      regexMatch: ^(http(s):\/\/.)[-a-zA-Z0-9@:%._\+~#=]{2,256}\.[a-z]{2,6}\b([-a-zA-Z0-9@:%_\+.~#?&//=]*)$
    - name: pollRange
      dataType: integer
      minValue: 30
      maxValue: 360
      allowEmpty: false
    - name: optionalText
      dataType: string
      minLength: 5
      allowEmpty: true
    - name: cpuRange
      dataType: double
      minValue: 0.5
      maxPrecision: 1
      allowEmpty: false
    - name: memoryRange
      dataType: integer
      minValue: 16384
      allowEmpty: false

ApplicationDescription-helm_only

apiVersion: margo.org/v1-alpha1
kind: ApplicationDescription
metadata:
  id: com-northstartida-hello-world
  name: Hello World
  description: A basic hello world application
  version: "1.0"
  catalog:
    application:
      icon: ./resources/hw-logo.png
      tagline: Northstar Industrial Application's hello world application.
      descriptionFile: ./resources/description.md
      releaseNotes: ./resources/release-notes.md
      licenseFile: ./resources/license.pdf
      site: http://www.northstar-ida.com
      tags: ["monitoring"]
    author:
      - name: Roger Wilkershank
        email: rpwilkershank@northstar-ida.com
    organization:
      - name: Northstar Industrial Applications
        site: http://northstar-ida.com
deploymentProfiles:
  - type: helm.v3
    id: com-northstartida-hello-world-helm.v3-a
    components:
      - name: hello-world
        properties:
          repository: oci://northstarida.azurecr.io/charts/hello-world
          revision: 1.0.1
          wait: true
parameters:
  greeting:
    value: Hello
    targets:
    - pointer: global.config.appGreeting
      components: ["hello-world"]
  greetingAddressee:
    value: World
    targets:
    - pointer: global.config.appGreetingAddressee
      components: ["hello-world"]
configuration:
  sections:
    - name: General Settings
      settings:
        - parameter: greeting
          name: Greeting
          description: The greeting to use.
          schema: requireText
        - parameter: greetingAddressee
          name: Greeting Addressee
          description: The person, or group, the greeting addresses.
          schema: requireText
  schema:
    - name: requireText
      dataType: string
      maxLength: 45
      allowEmpty: false

JSON Schema

View JSON Schema in new tab or download