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.

Top-level Attributes

Metadata Attributes

Metadata about the application.

Catalog Attributes

Catalog metadata for displaying the application.

ApplicationMetadata Attributes

Metadata specific to the application.

Author Attributes

Information about the application's author.

Organization Attributes

Information about the providing organization.

DeploymentProfile Attributes

Represents a deployment configuration for the application.

Helm Exceptions

Applications can be deployed as Helm charts using either Helm version 3 or version 4 using Chart APIVersion v2 only.

In order to facilitate the required deployment options for Helm charts, Margo does not support Helm functions requiring direct communication with the Kubernetes API.

Your Helm based application MUST NOT rely on the following Helm functions:

• Lookup: The lookup template function queries live resources in the target Kubernetes cluster at render time, for example to fetch ConfigMaps, Secrets, or other objects. This requires direct API access and cluster credentials during rendering.
• Hooks: Hooks (pre/post install, upgrade, delete, rollback, test, etc.) execute additional Kubernetes resources or jobs at specific points in the release lifecycle. Helm waits for these resources to reach a ready state by monitoring them via the Kubernetes API, and the hooks themselves may perform privileged or arbitrary operations in the cluster.
• CRD management via Helm: Installing or managing Custom Resource Definitions (CRDs) with Helm requires checking for the presence of CRDs and registering new APIs with the cluster, which involves API calls and may require elevated permissions.

Note: This function list is based on the current Helm v3 and v4 implementations. Additional functions may be added later if Helm introduces new functions requiring communication with the Kubernetes API to work.

DeviceConstraints Attributes

Device constraints specifying the minimum device capabilities and eligibility rules required for the application.

Workload fleet manager implementations are not required to guarantee a workload can be deployed to a selected device. Ultimately, this responsibility falls to the device to determine if a workload can be deployed or not.

Workload fleet manager implementations MAY choose to implement device eligibility matching in order to reduce the risk of deployment failures because of incompatibility between what a workload requires and what a device provides.

If a workload fleet manager chooses to implement device eligibility matching they MUST follow the matching rules define below to match the application description's device constraint requirements with device's reported capabilities.

• A workload fleet manager MUST evaluate deviceConstraints before selecting a target device for a deployment profile.
• A device that does not satisfy the minimum required CPU, memory, and storage defined in the capacityRequirements MUST NOT be selected for that profile.
• If eligibilityRules are present, a device that does not satisfy the required rule evaluation MUST NOT be selected for that profile.
• If no available device satisfies the profile's required constraints, the deployment MUST be reported as not placeable according to the implementation's existing status model.

If a workload fleet manager chooses to implement device eligibility matching they MAY choose to find only the first suitable device or all suitable devices.

CapacityRequirements Attributes

Minimum device capacity required by the deployment profile.

The following rules MUST be applied when performing capacity requirements matching:

• cpu.cores is the minimum number of CPU cores required on the target device.
• cpu.architectures, when present, restricts acceptable CPU architectures.
• memory is the minimum memory required by the deployment profile.
• storage is the minimum storage required by the deployment profile.
• A device MUST satisfy all specified capacityRequirements to remain eligible for further evaluation.

The capacity requirements device constraint is intended to make it easier for application suppliers to indicate the most common workload constraints. Application suppliers MAY use either the capacityRequirements or a propertySelector eligibility rule to describe their capacity constraints. Application suppliers SHOULD avoid using both simultaneously. If both are used, validation logic MUST treat them as independent rule definitions and not try to correlate what is defined in the capacityRequirements with what is defined in the properSelector.

CPU Attributes

CPU element specifying the CPU requirements for the application.

EligibilityRule Attributes

A rule matching properties and supplier-defined labels reported through the device capabilities.

Eligibility rules

The following rules MUST be applied when performing eligibility rule matching:

eligible devices =
    OR over each rule in eligibilityRules:
        AND(
            propertySelector matches   (TRUE if propertySelector is omitted),
            labelSelector matches      (TRUE if labelSelector is omitted)
        )

• Each eligibility rule is evaluated using a logical OR.
  • A least one eligibility rule MUST evaluate to true to be considered a match.
  • If eligibilityRules is omitted, the deployment profile has no additional selector-based constraint beyond capacityRequirements, if present.
• The propertySelector and labelSelector expressions are combined using a logical AND.
  • An eligibility rule MAY contain a propertySelector, labelSelector or both.
  • All property selector and all label selectors expressions MUST evaluate to true to be considered a match.
• All matchExpressions within a single property or label selector are combined using logical AND.
  • All match expressions MUST evaluate to true to be considered a match.

Property selector key format

propertySelector.matchExpressions[].key MUST be a JSON Pointer as defined by RFC 6901, evaluated relative to the device capabilities properties object.

Examples:

• /vendor
• /id
• /modelNumber

Property selectors MUST resolve to a device capability property whose value is either:

• a string, number, or boolean
• an array of strings, or numbers
• an array of objects

If a property selector resolves to any other JSON type, the expression MUST evaluate to false.

If a property selector resolves to an array of objects, ContainsAll or ContainsAny must be used, or else the expression MUST evaluate to false.

Label selector key format

labelSelector.matchExpressions[].key MUST be the exact label key to evaluate within the device capabilities labels dictionary.

This label selector MUST resolve to a device capability label whose value is either:

• a string, number, or boolean
• an array of strings, or numbers

If a label selector resolves to any other JSON type, the expression MUST evaluate to false.

Selector Attributes

A set of match expressions evaluated with AND semantics.

MatchExpression Attributes

An expression used to match a device's reported capabilities properties or labels.

The following rules MUST be followed when evaluating match expressions:

String comparisons MUST be exact and case-sensitive.

For the In and NotIn operator:

• values MUST be present
• values MUST contain one or more strings or numbers, or one boolean
• values MUST be the same data type when indicating more than one.

For the Exists and DoesNotExist operator:

• values MUST be omitted

For the Gt and Lt operator:

• values MUST be present
• values MUST be parsable as numbers
• values MUST only contain a single number

For the ContainsAll and ContainsAny operator:

• itemSelector MUST be present
• itemSelector.matchExpressions MUST contain one or more expressions
• values MUST be omitted
• Keys within itemSelector.matchExpressions are JSON Pointers relative to each array element (not absolute)
• Expressions within itemSelector.matchExpressions are combined using AND logic for ContainsAll and OR logic for ContainsAny

Object Array Item Matching

ContainsAll and ContainsAny operators enable matching on properties of objects within an array. These operators are used when the device capability property referenced by key resolves to an array of objects.

ContainsAll (array element with all conditions):

Evaluates to true when at least one array element satisfies all conditions specified in itemSelector.matchExpressions. All expressions within the itemSelector are combined using AND logic.

Example: Match a device that has at least one GPU peripheral manufactured by NVIDIA:

propertySelector:
  matchExpressions:
    - key: /peripherals
      operator: ContainsAll
      itemSelector:
        matchExpressions:
          - key: /type
            operator: In
            values: ["gpu"]
          - key: /manufacturer
            operator: In
            values: ["NVIDIA"]

ContainsAny (array element with any condition):

Evaluates to true when at least one array element satisfies any condition specified in itemSelector.matchExpressions. Expressions within the itemSelector are combined using OR logic.

Example: Match a device that has at least one peripheral that is either a GPU or a high-speed NIC:

propertySelector:
  matchExpressions:
    - key: /peripherals
      operator: ContainsAny
      itemSelector:
        matchExpressions:
          - key: /type
            operator: In
            values: ["gpu", "nic"]

Interaction with other expressions:

Multiple matchExpressions within the same propertySelector remain AND'd together. For example:

propertySelector:
  matchExpressions:
    - key: /vendor
      operator: In
      values: ["Vendor Name"]
    - key: /peripherals
      operator: ContainsAll
      itemSelector:
        matchExpressions:
          - key: /type
            operator: In
            values: ["gpu"]

This evaluates to true only when the device vendor matches AND the device has at least one GPU peripheral.

Component Attributes

A class representing a component of a deployment profile.

ComponentProperties Attributes

The expected properties for all OCI-based deployment types (Helm and Compose) are indicated below.

Defining configurable application parameters

To allow customizable configuration values when installing an application, the application description defines the parameters and configuration sections giving the application vendor control over what can be configured when installing, or updating, an application. The configuration section describes how the workload orchestration software vendor must display parameters to the user to allow them to specify the values. The schema section describes how the workload orchestration software vendor must validate the values provided by the user before the application is installed or updated.

Note: At this point the specification only deals with parameter values provided by the user as part of installing, or updating, the application. We anticipate parameter values to come from other sources, such as the device, in the future and not only from the user.

Parameter Attributes

Defines a configurable parameter for the application. This object is used to build a property bag, i.e. parameters, defined in application description. See parameters attribute under ApplicationDescription Attributes section for better understanding.

Target Attributes

Specifies where the parameter applies in the deployment.

Configuration Attributes

Configuration layout and validation rules.

Section Attributes

Named sections within the configuration layout.

Setting Attributes

Individual configuration settings.

Schema Attributes

Defines data type and rules for validating user provided parameter values. Subclasses (see below) define for each data type their own set of validation rules that can be used. The value MUST be validated against all rules defined in the schema.

• TextValidationSchema Attributes

(Subclass of Schema)
Extends schema to define a string/text-specific set of validation rules that can be used.

• BooleanValidationSchema Attributes

(Subclass of Schema)
Extends schema to define a boolean-specific set of validation rules that can be used.

• NumericIntegerValidationSchema Attributes

(Subclass of Schema)
Extends schema to define a integer-specific set of validation rules that can be used.

• NumericDoubleValidationSchema Attributes

(Subclass of Schema)
Extends schema to define a double-specific set of validation rules that can be used.

• SelectValidationSchema Attributes

(Subclass of Schema)
Extends schema to define a specific set of validation rules that can be used for select options.

Enumerations

These enumerations are used as vocabularies for attribute values of the ApplicationDescription.

CpuArchitectureType

SelectorOperator

Application Description Examples

Example 1: Simple Application Description

A simple hello-world example of an ApplicationDescription is shown below:

apiVersion: v1
id: com-northstartida-hello-world
metadata:
  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
    id: com-northstartida-hello-world-helm-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:
    # Maps to deployment configuration param,
    # e.g., helm install ... --set global.config.appGreeting="Hello"
    - 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

Example 2: Application Description with Deployment Profiles for Helm and Compose

An example of an ApplicationDescription defining deployment profiles for both cases, Helm chart as well as Compose, is shown below.

apiVersion: v1
id: com-northstartida-digitron-orchestrator
metadata:
  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
    id: com-northstartida-digitron-orchestrator-helm-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
    deviceConstraints:
      capacityRequirements:
        cpu:
          cores: 1.5
          architectures:
            - amd64
        memory: 1024Mi
        storage: 10Gi
      eligibilityRules:
        - propertySelector:
            matchExpressions:
              - key: /peripherals
                operator: ContainsAll
                itemSelector:
                  matchExpressions:
                    - key: /type
                      operator: In
                      values: ["gpu"]
                    - key: /manufacturer
                      operator: In
                      values: ["NVIDIA"]
              - key: /interfaces
                operator: ContainsAll
                itemSelector:
                  matchExpressions:
                    - key: /type
                      operator: In
                      values: ["ethernet", "bluetooth"]
  - type: compose
    id: com-northstartida-digitron-orchestrator-compose-a
    components:
      - name: digitron-orchestrator-docker
        properties:
          repository: oci://northstarida.azurecr.io/compose/digitron-orchestrator
          revision: 1.0.9
parameters:
  idpName:
    value: "test"
    targets:
      # Maps to deployment configuration param,
      # e.g., helm install ... --set idp.name="test"
      - pointer: idp.name
        components: ["digitron-orchestrator"]
      # Maps to environment variables, e.g., IDP_NAME=test docker compose ...
      - pointer: IDP_NAME
        components: ["digitron-orchestrator-docker"]
  idpProvider:
    targets:
      - pointer: idp.provider
        components: ["digitron-orchestrator"]
      - pointer: IDP_PROVIDER
        components: ["digitron-orchestrator-docker"]
  idpClientId:
    targets:
      - pointer: idp.clientId
        components: ["digitron-orchestrator"]
      - pointer: IDP_CLIENT_ID
        components: ["digitron-orchestrator-docker"]
  idpUrl:
    targets:
      - pointer: idp.providerUrl
        components: ["digitron-orchestrator"]
      - pointer: idp.providerMetadata
        components: ["digitron-orchestrator"]
      - pointer: IDP_URL
        components: ["digitron-orchestrator-docker"]
  adminName:
    targets:
      - pointer: administrator.name
        components: ["digitron-orchestrator"]
      - pointer: ADMIN_NAME
        components: ["digitron-orchestrator-docker"]
  adminPrincipalName:
    targets:
      - pointer: administrator.userPrincipalName
        components: ["digitron-orchestrator"]
      - pointer: ADMIN_PRINCIPALNAME
        components: ["digitron-orchestrator-docker"]
  pollFrequency:
    value: 30
    targets: 
      - pointer: settings.pollFrequency
        components: ["digitron-orchestrator", "database-services"]
      - pointer: POLL_FREQUENCY
        components: ["digitron-orchestrator-docker"]
  siteId:
    targets:
      - pointer: settings.siteId
        components: ["digitron-orchestrator", "database-services"]
      - pointer: 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

Custom runtimes and deployments

Note: See the Custom Runtimes and Deployments page for additional details.

An application and device supplier MAY collaborate to enable deploying workloads using a format other than Margo's specified deployment types.

If suppliers choose this option, they MUST follow these rules:

• The deployment profile type MUST be set to custom.
• Device constraint eligibility rules MUST be defined with label selectors matching the supplier's agreed-upon key/value label pairs reported in the device's capabilities document.
• The workload artifacts MUST be packaged in an OCI blob. The specific details for how this OCI blob is created are the responsibility of the suppliers to agree upon.

Specification extensions

Note: See the specification extensions page for additional details.

The Application Description document supports the following specification extension scenarios:

Collaboration between application and workload fleet manager suppliers

To make use of specification extensions defined by a workload fleet manager supplier, the extension property MUST be added to the Application Description YAML document's root.

The workload fleet manager MUST ignore any unknown specification extensions targeting a workload fleet manager supplier. Importing an application description with unknown specification extensions MUST NOT result in a failure because of the included specification extensions.

The workload fleet manager MUST NOT propagate these specification extension properties to the device via the Application Deployment yaml document.

Collaboration between application and device suppliers

To make use of specification extensions defined by a device supplier, the extension property MUST be added to the root of either the deploymentProfile or component objects.

The workload fleet manager MUST import an application description with specification extensions targeting a device supplier without resulting in a failure because of the included specification extensions.

The workload fleet manager MUST propagate these extension properties to the device via the Application Deployment yaml document.