Skip to content

App Device Contract

These are the requirement and Guidelines for the Industrial Edge Release 06/25 including IEDK 1.25.0.

NOTICE

For feedback, requests, or to propose changes to this document, please use the official forum at https://community.mendix.com/link/space/industrial-edge.

Overview

This document defines the key factors and components that influence compatibility between an Industrial Edge Device and the Industrial Edge applications deployed on it. It provides a structured specification of the compatibility contract, including the roles of stakeholders, critical system components, environmental prerequisites, and validation mechanisms essential for reliable deployment and consistent runtime behavior.

The primary objective is to:

  • Identify and categorize the technical and operational compatibility aspects that affect application performance and stability on Industrial Edge Devices.
  • Establish a common understanding of compatibility expectations across all stakeholders, including application developers, device builders, and system integrators.
  • Specify corresponding test and validation approaches that ensure mismatches between application requirements and device capabilities are detected early and mitigated effectively.

This specification serves as a foundational reference for:

  • The internal Industrial Edge team to define concrete next steps and work packages.
  • Application developers to design and package apps that are compatible with a wide range of Industrial Edge Devices.
  • Device manufacturers to configure and validate their devices according to expected compatibility criteria.
  • System integrators to align device and application configurations for seamless integration.

By providing a clear, testable structure for compatibility evaluation, this document helps reduce unexpected deployment failures and promotes consistent behavior of Industrial Edge applications across diverse device environments.

Scope and Limitations

  • This document focuses on identifying and structuring the key factors and components that define the boundaries of device and application compatibility within the Industrial Edge ecosystem.

  • It outlines the supported configuration space for both devices and applications, helping stakeholders understand which combinations are validated and considered reliable for deployment.

  • While the aim is to reduce incompatibility issues, the document acknowledges that exhaustive testing across all possible device–application permutations is not feasible. Therefore, only a well-defined set of documented and validated configurations are officially supported.

  • The document does not replace detailed interface specifications or product documentation but serves as a high-level compatibility framework to guide testing, development, and integration activities.

Hardware Architecture

Minimum Reference System Requirements

Component Specification
Processor Architecture: x86-64 or ARMv7
Core count: 1
Network Interface 1 NIC
Memory 2 GB
Storage 8 GB

Key Considerations

  • Supported Processor Architectures:
    The platform supports both x86-64 and ARMv7 processor architectures. Application images must be built for and match the target architecture. Cross-deployment is not supported.

  • Hardware Feature Allocation:
    Additional device features such as network interfaces, GPUs, and GPIOs can be allocated to Docker containers using the Resource Manager.

  • Memory Requirements:
    The recommended minimum memory for devices is 2 GB, covering the orchestration runtime (IE Runtime) as well as the deployed applications. Developers should monitor and optimize their applications’ memory consumption to maintain system reliability.

  • Storage and Endurance:
    Devices, especially ARM-based platforms, may have limited and endurance-constrained storage. Applications should minimize unnecessary write operations and actively manage storage usage (e.g., logs, temporary data, persistent storage) to prolong device lifetime and ensure stable operation.

Operating System and Kernel

Reference System Requirements

Component Specification
Base Distribution Debian 12
Linux Kernel Latest stable (vanilla) kernel
Cgroup Version v2

Key Considerations

  • Reference Distribution:
    All target devices should use Debian 12 as the base operating system. Docker images should also be based on Debian 12 to ensure system compatibility.

  • Optional Real-Time & CPU Resource Management Capabilities:
    Support for real-time kernel, advanced CPU resource management, and related system tuning is optional and depends on the device’s capabilities.
    These features are only applicable if both the device and the application support them.
    The presence and compatibility of such advanced features are evaluated automatically by the capability matchmaking system, which ensures that applications requiring real-time resources are only deployed to capable devices.

    • For devices supporting Resource Manager:
      • Real-time kernel (e.g., PREEMPT_RT)
      • Cgroup v2 enabled
      • tuned for kernel tuning and CPU affinity
      • Power management QoS or application-configurable low-latency power settings
    • If the device does not support these features, real-time and advanced CPU resource settings are simply not required.

  • Responsibility Split:

    • Device Builders configure kernel and power management defaults.
    • Application Developers may further adjust power management policies via the Resource Manager when specifically supported.

!!! info "NOTICE For more information on leveraging advanced resource management (like GPU, GPIO, NIC), real-time adjustments, and power management in the context of Resource Manager, please consult the Resource Manager documentation for device builders or application developers.

Filesystem Hierarchy Standard (FHS) Compliance

Reference System Requirements

Path Behavior Permissions Reference
/tmp Reset on reboot 1777 FHS 3.0 §3.18

Key Considerations

  • Device Builder Guidance:
    It is recommended to follow the FHS specification when configuring the device operating system and filesystem layout. Ensuring directories such as /tmp are set up according to Debian and FHS defaults promotes reliability and provides a stable reference environment for application execution.

  • Application Developer (App Partner) Guidance:
    Applications should be designed to interact harmoniously with FHS-compliant directory structures on the host. This includes using /tmp for temporary files that are cleared on reboot. Patterns for bind mounts and persistent data should align with the FHS hierarchy where practical.

  • Collaboration for Optimal Operation:
    Close alignment between device builders and application partners around FHS best practices fosters robust interoperability and reliable operation. Adhering to established filesystem conventions simplifies maintenance and troubleshooting, and ensures that applications work smoothly across a range of supported devices.

Docker Runtime and Configuration

Reference System Requirements

Component Specification
Docker Engine docker.io 20.10.24+dfsg1-1+deb12u1 (for Debian 12)
Docker Compose Runtime v2.32.1
Compose File Version 2.1 - 2.4
Storage Driver overlay2

Key Considerations

  • Docker Engine:
    The system standardizes on Docker Engine version 20.10.24+dfsg1-1+deb12u1 as provided with Debian 12. It is recommended to always use this or a compatible package version to ensure stability, maintainability, and security alignment with the host OS.

  • Docker Compose:
    Application deployment and orchestration should use Docker Compose with supported Compose file schema versions 2.1 through 2.4.
    The runtime uses Compose v2.32.1, and compatibility should be validated if using additional Compose features.

  • Compose Directives:
    Only specific Docker Compose directives are recommended in the Industrial Edge Runtime environment.
    For a comprehensive and up-to-date list, refer to the contract defined in the Supported Compose Directives.

  • Docker Engine Configuration:

    • Storage Driver: The reference configuration uses the overlay2 storage driver for optimal performance and compatibility with Debian 12.

  • Filesystem Mounts and Overlay:

    • The overlay2 storage driver is required; verify that the kernel and filesystem support for overlay2 is enabled on the device.
    • When using bind mounts or persistent storage, ensure locations comply with FHS recommendations as per Section 2.

  • Compatibility and Best Practices:

    • Validate all Compose files against the supported schema and directive list.
    • Always test deployments on reference runtime versions to ensure compatibility.
    • Avoid deprecated or unsupported directives and features for long-term maintainability.

  • Extended Documentation:
    For full details on configuring Docker Engine for Industrial Edge and supported Compose options, see:

Privileges and Security Capabilities

Key Considerations

  • Linux Capabilities
    Capabilities such as CAP_SYS_ADMIN grant elevated privileges to containers, allowing operations like mounting filesystems or modifying kernel parameters. While some applications may require such capabilities, granting them increases the security risk and may not be permitted in all environments. Carefully assess each required capability against the device's security policy.
#### Security Modules: AppArmor vs. SELinux By default, our reference system (Debian 12) uses **AppArmor** as the supported security module for mandatory access control. Please be aware that AppArmor and SELinux are mutually exclusive—they cannot operate simultaneously on the same host. SELinux is typical on RHEL-based systems, while AppArmor is standard on Debian-based systems. - All example profiles, Compose `security_opt` settings, and troubleshooting in this documentation reference AppArmor. - Systems using SELinux are not currently tested or supported. If SELinux is active, AppArmor-based security options will not be available. - Device builders are responsible for ensuring that the appropriate security module (AppArmor for Debian) is enabled. - If your deployment environment requires SELinux, please coordinate with the Siemens Edge team and raise a discussion in [the forum](https://community.mendix.com/link/space/industrial-edge). <-->

  • Best Practices
    Elevated privileges or additional capabilities should be granted only if strictly necessary and if no alternatives exist. All such security-relevant settings should be documented, and customers must be informed if their usage is required.

  • Runtime Policy Enforcement
    The platform transparently communicates any application-imposed privilege or capability requirement to users, leveraging an open policy engine for evaluation. If application restrictions or exceptions exist, these are clearly shown to the user during deployment.

#### Example snippet (docker-compose.yaml) 
cap_drop:
  - ALL
cap_add:
  - SYS_ADMIN         # e.g., needed for namespace changes
  - SYS_CHROOT        # for mount namespace operations
  - SYS_PTRACE        # to access nsfs namespace information
  - DAC_READ_SEARCH   # to scan /proc/[$PID]/fd
  - DAC_OVERRIDE      # access to engine unix domain sockets
  - NET_RAW
  - NET_ADMIN
pid: host
security_opt:
  - apparmor:unconfined
!!! info "NOTICE" Granting additional capabilities or elevated privileges should only be considered when absolutely necessary. The platform always notifies users of such requirements and makes the security implications transparent. <-->

Networking and Connectivity

Reference System Requirements

Capability/Model Supported Features
Docker Network Modes bridge, host, none, custom Docker bridges
Edge Reverse Proxy API/UI exposure via Industrial Edge reverse proxy proxy-redirect
Inter-App Communication MQTT broker on internal network Databus
Layer 2 (L2) Access Supported with relevant capabilities (e.g., PROFINET)

Key Considerations

  • Edge Reverse Proxy Exposure:

    • Usage: Apps may expose APIs or UIs via the Industrial Edge reverse proxy by requesting corresponding routes.
    • Constraint: Only one app can occupy a given host port at a time. Simultaneous exposure of multiple apps on the same port is not supported.
    • Best Practice: Apps should define unique routes and endpoints. If dynamic route assignment or UI multiplexing is required, future runtime enhancements may provide improved support.

  • Direct Host Port Exposure:

    • Usage: Apps can bind directly to host device ports, enabling direct client/service access.
    • Constraint: Port conflicts can occur between apps or with host services. There is no built-in reserved port range management for protocols like DDS or OPC UA GDS.
    • Best Practice: Avoid using fixed host ports unless necessary. Leverage platform features for managed or automatic port assignment where available.

  • Docker Networking and Isolation:

    • Supported Modes: bridge, host, and none are supported. Custom bridges are permitted, but bridge name collisions and initialization order must be handled with care.
    • Security: Apps should not configure bridges already used by other deployments to maintain network isolation. Misuse can compromise isolation or cause startup issues.
    • Host Networking: Running containers with the host network can reduce network isolation. Host-level firewalls may prevent some services from being externally reachable. Exercise caution and follow principle of least privilege.

  • External Connectivity:

    • Usage: Apps can connect to external devices/services, with optional support for per-app proxy settings.
    • Constraint: Security risk of uncontrolled external access. Proxy and policy enforcement may differ across system components.
    • Best Practice: Restrict external connectivity to necessary endpoints only. Define explicit egress rules as required.

  • Inter-App Communication (MQTT):

    • Usage: Apps may communicate via MQTT topics using a shared broker on the internal network.
    • Security Concern: By default, all apps on the internal network can access any topic. Fine-grained topic access control is not enforced unless implemented at application level.
    • Best Practice: Use secure authentication, limit topic access in app configuration, and design for least privilege.

  • Developer Guidance:

    • Design apps to use only the minimum required network features.
    • Always handle application network isolation and endpoint uniqueness proactively.
    • Engage with device builders to reserve ports, interfaces, or network names as needed for deterministic and secure operation.

NOTICE

For more details on supported Docker networking features and security best practices, refer to the Industrial Edge documentation and the official Docker networking reference.

Reference System Overview

Hardware Architecture

Component Minimum/Reference Specification Notes
Processor x86-64 or ARMv7, 1 core Application images must match device architecture
Memory 2 GB Covers IE Runtime plus typical app workloads
Storage 8 GB Consider endurance, esp. for ARM/flash devices
Network Interface 1 NIC

Operating System and Kernel

Component Minimum/Reference Specification Notes
Base Distribution Debian 12 Align container base images for maximum compatibility
Linux Kernel Latest stable (vanilla) kernel Real-time kernel optional, capability-based
Cgroup Version v2
Filesystem Layout FHS-compliant; /tmp /tmp: reset on reboot

Docker Runtime and Configuration

Component Minimum/Reference Specification Notes
Docker Engine docker.io 20.10.24+dfsg1-1+deb12u1 For Debian 12
Docker Compose Runtime v2.32.1 Supports compose file versions 2.1–2.4
Compose File Versions 2.1–2.4 Only specific directives supported
Supported Compose Directives See Supported Compose Directives
Storage Driver overlay2 Filesystem and kernel must support overlay2

Networking and Connectivity

Capability/Model Supported Features Notes
Docker Network Modes bridge, host, none, custom bridges Network isolation and constraints apply
Reverse Proxy API/UI exposure via Edge reverse proxy One app per host port
Direct Host Port Binding Supported Port/reserved range conflicts possible
External Connectivity Connect to external devices/services Per-app proxy optional, policy enforcement varies
Inter-App Communication MQTT broker (shared topics) No broker-level authentication by default

Security and Capabilities

Component Requirement/Support Notes
Linux Capabilities Only as required (e.g., CAP_SYS_ADMIN, etc.) Elevation is restricted, must be justified
Policy Enforcement Open policy engine reports/blocks violations User notification for privilege or network exceptions

CHANGELOG

[Initial Release] - 2024-06-05

  • Added a grouped, category-based reference system table summarizing all key requirements and features.
  • Created initial documentation sections for hardware, OS/kernel, Docker, networking, and security.
  • Established minimum baseline for application and device compatibility in Siemens Industrial Edge environments.