Application Development
- 1 1 Overview
- 2 2 Example
- 3 3 Application Definition Sections - General
- 3.1 3.1 id & version
- 3.2 3.2 displayName, shortDescription & longDescription
- 3.3 3.3 Media / teaserImage
- 3.4 3.4 isPublic Flag
- 3.5 3.5 isCompatibleWithMultiMachineEdgeDevice Flag
- 3.6 3.6 storageLimit
- 3.7 3.7 userSettings
- 3.8 3.8 cloudResources: Webhooks to external systems
- 3.8.1 3.8.1 Install Webhook
- 3.8.2 3.8.2 Uninstall Webhook
- 3.9 3.9 containers
- 4 4 Container definitions
- 4.1.1 Container user & group
- 4.1.2 Networking
- 4.1.3 Resource restrictions
- 4.1.4 Configurations
- 4.2 4.1 name
- 4.3 4.2 image
- 4.4 4.3 startupOrder
- 4.5 4.4 commandLine
- 4.6 4.5 mappedFiles
- 4.7 4.6 ports
- 4.8 4.7 environment
- 4.9 4.8 propertiesDesired
- 4.10 4.9 labels
- 4.11 4.10 resourceSettings
- 5 5 Variable Replacement
- 6 6 Application Management Resource Limits
1 Overview
Each Edge Application is defined by a specific set of information within the symmedia Hub. The containers to be deployed, along with the required metadata such as descriptions to be displayed in the portal UI, required configurations, etc., are defined in a single JSON document called the Application Definition. Its format is based on the Deployment Manifest (the specification can be found here: https://docs.microsoft.com/en-us/azure/iot-edge/module-composition?view=iotedge-2020-11) and extends it with additional data required by the Hub.
The Hub aggregates all installed applications for an Edge Device, creates resources and transforms them into an IoT Hub compliant Deployment Manifest, which is then deployed.
For documentation and illustration purposes, each section also describes how settings in the application definition affect the generated deployment manifest. If you have deployed IoT Edge modules manually using Visual Studio Code, you will recognize the format.
This document also describes the configuration settings and actions performed for each resource type that can be generated.
Application Definition
In the development phase, an App Definition (json document) is created.
Some important rules are highlighted here:
The ID needs to be unique. A prefix should be added that identifies you as developer. i.e. “SymTestApp”
If you upload a Definition with the same ID then you update your App with a new Version.
The Version needs to follow the Semantic Versioning rules. See https://semver.org/
Some fields are required, for example displayName, shortDescription and longDescription
Hardware Requirements need to be defined. The values need to be selected carefully. On the one hand, enough resources are required to run the App and on the other hand the App needs to fit on the Edge Device together with other installed Apps.
A storageLimit is defined for the entire App
CPU and RAM limitations are set for each container
When defining ports, it needs to be considered that the ports on container side need to be above 1024 as otherwise root privileges would be required which is not allowed.
2 Example
This section provides a quick overview of a valid Application Definition example. The sections are described in detail below.
3 Application Definition Sections - General
3.1 id & version
The id field is a unique identifier for the app. Together with the version field it describes a unique application definition. Once an application has been published in a specific version, it cannot be changed afterwards. To correct mistakes or update the container versions, a new application version should be published. Once a new version is published, the new version will automatically be set as the current version, and the Operators will see an option to upgrade the installed Apps to the new version.
The id should have a prefix to prevent name-clashes.
The version has to follow semantic versioning and match this regex:
An visualization with examples can be found here: https://regex101.com/r/vkijKf/1/
3.2 displayName, shortDescription & longDescription
displayName: Title of the Application
shortDescription: Text in the Application card in the Applications overview
longDescription: Text in the detail view of an Application
The fields each consist of multiple fields, one for each language this field has been translated for, the lowercase ISO-639-1 code of the language being the key, the translated text being the value. This field is supposed to originate in the app service for each app, the deployment service is not using this field, it is meant for web GUIs to offer the display name in multiple languages. At the moment, only the “en” text is displayed. The translation feature is coming soon in the UI.
All of these fields have to define at least an english (en) translation.
3.3 Media / teaserImage
Here an URL to an image is defined which will be displayed as Image for the Application.
3.4 isPublic Flag
Public Apps are visible and installable for Operator-controlled Assets independently of the compatibility (over Machine Model). All Service Providers can mark public Apps as compatible to their machine models to provide public Apps to Service Provider-controlled Assets. When an Application Version is marked as public (or not) then all other Versions are also changed.
3.5 isCompatibleWithMultiMachineEdgeDevice Flag
Apps that are marked with this flag are compatible with Edge Devices that are in Pairing Mode MULTI and can be assigned to multiple Assets. The default of this flag is false meaning that it can not be installed on Assets that are linked to a Multi Edge Device. When an Application Version is marked as Multi Edge Device compatible (or not) then all other Versions are also changed. During development it is important to consider that Apps that are compatible with Multi Edge Devices need to function independent of Assets.
3.6 storageLimit
Maximums storage that the whole App is allowed to consume. That is the sum of all container storages and volumes. This value will be shown in the UI. More details are explained in Chapter 6.
3.7 userSettings
This section is an array containing the settings a user is offered during app installation.
The values the user has offered can be used as placeholders in different locations in the AppDefinition. The name of the setting is the name that needs to be used fo the placeholder. To provide a value to a container it needs to be added as environment parameter (see 4.7). It is also possible to use the value for the port definition as described in the example.
The settings can be defined as mandatory and they can have validations and default values. Each entry has these fields:
Field | Description |
|---|---|
name | The name of the user setting. The value of the setting can be referenced in the remainder of the App Definition by using ${name}. Only valid within the application. |
displayText | Like the "displayName" field in the application descriptor, this is a localized string, and is used for web guis to display the name of the setting. The deployment service is ignoring this field. |
default | The default value given no value was provided. Can only be a string. The value should be prefilled in any web gui. If the field is not present (or null) then no default is provided. |
validation | A regex describing a valid setting. It is recommended that the regex starts and end with ^ and $ respectively. Note: The validation is not yet used by the Application Management. |
required | A boolean specifying wether this settings needs to be provided or not. If it is true, but no value was provided, the default is used. |
The section can also be empty if no settings need to be specified.
3.8 cloudResources: Webhooks to external systems
In the cloudResources section webhooks can be defined that are excecuted during the installation or uninstallation of an Application.
3.8.1 Install Webhook
Calls a specified external webhook in the symmedia backend before deploying an Application on the Edge Device and waits up to 60 seconds for it to return. The webhook can return a list of new token replacement values containing 0-n entries. Those values can then be used in ${TOKEN} replacements further on. Returned entries must not collide with any existing or built-in token key, or deployment fails.
Webhooks are commonly used to prepare data mapping tables in an app’s cloud backend, or to create resources like blob containers on the fly and return the SAS-Token values back.
Under ideal circumstances, install webhooks are only called once until the user either removes the app and installs it again, the provided settings change, or the application version changes. Webhooks should be prepared to be called more than once with the same data.
The cloud resource type is "Webhook". The following fields need to be present:
Field | Description |
|---|---|
id | Used for logging purposes only |
type | always “Webhook” |
schemaVersion | The schema version of this entry and the webhook event schema the webhook supports. Currently must be set to 1 (as integer value) |
url | The publicly accessible URL that is to be called via POST. You should protect the URL with a secret authentication token and add it to the query part of the URL. (i.e. ?code=xxxxxxx) like it is done with function level authenticated Azure Functions. Currently the secret validation token must be stored in the App Definition. A future version is planned where this can be set independently and is stored securely in an Azure Key Vault. |
providedParameters | An array of strings that contain the keys of all current tokens that need to be passed to the function in the POST body (see request / response schema below). Any user settings, system variables (like PROXY settings), or values generated from the cloud resources specified earlier in the Application’s Definition can be used. |
The provided URL will be called up to 3 times with 2 second waiting interval. If the execution fails, or does not complete in 60 seconds, the deployment / installation is marked as failed.
An example:
The webhook is called as HTTP POST with the following content:
Note: Webhooks need to verify that the “event” field is what they expect. The event field can be “Install” or “Uninstall”, but might also take on different values in the future. In case a value is not understood, the webhook must return a success but ignore the event.
The webhook needs to return content following this schema:
Or in case of an error:
3.8.2 Uninstall Webhook
When an application is removed, the according webhook is called again, with an event of “Uninstall”. The uninstall webhook is usually only called once per uninstall, but webhooks should be prepared to be called more than once.
Please note that the “providedParameters” field is not provided during an uninstall event.
NOTE: This can be changed on request.
3.9 containers
This section is an array defining the containers that are deployed as part of this application. The details of each container entry are described in the next section.