8. System Architecture¶
As discussed in Introduction, the Grid Edge Interoperability & Security Alliance specification describes four types of interoperability: ADM, API, LEE, and VEE. These types of interoperability live in a general system context, which is shown below in Figure 8.1.
Figure 8.1 GEISA Architecture¶
GEISA is focused on interoperability and security. Where it is possible to maintain interoperability without specifying aspects of the implementation, details are left to the implementer.
In a full implementation of the GEISA architecture, there is a GEISA Edge Management System (EMS) that implements the ADM interface as described in Application & Device Management. The EMS implements a network protocol based interface and is able to use that protocol to interact with ADM interface conformant GEISA platform implementations. Internal details of the EMS are beyond the scope of this specification. GEISA simply requires that a conformant EMS expose the required functions to the system operator in some meaningful way, and that it implements the specified network protocol and transactions in response to user commands. An EMS could provide a GUI, a command line interface, or an API and still be considered conformant.
Interacting with the GEISA EMS is one or more platform implementations. An ADM-conformant platform interface will be able to communicate with the GEISA EMS using the ADM protocol and transactions. In Figure 8.1 above, the ADM conformant implementation is shown as the GEISA Edge Management Agent. Implementation details are beyond the scope of this specification. Implementers may provide a standalone EMA within their platform, or integrate EMA functions within other elements of their platform as they see fit.
GEISA ADM elements are shown in red in
Figure 8.1 above.
The system operator is able to use the GEISA EMS to deploy and activate GEISA edge applications to GEISA platform implementations. A fully conformant GEISA platform implementation will provide both a GEISA-conformant EE / execution environment and a GEISA-conformant API / application programming interface.
GEISA defines two different execution environments:
Platforms may offer one or both of these execution environments (EE).
While the GEISA API should be accessible from both EEs, there is no expectation that code written for one EE will operate on the other without being ported.
Note
It is possible, though not planned at this time, that GEISA may support additional execution environments in the future.
LEE GEISA applications are provided as GEISA-specific application container images, as detailed in Application Isolation. An LEE conformant GEISA implementation is able to mount a container image and grant that container the rights the system operator permitted the application in the deployment manifest. The Application Isolation Implementation used by the platform implementation is out of scope, but conformant implementations MUST be able to enforce the permissions and controls the GEISA specification requires.
An LEE-conformant GEISA implementation must provide a set of Linux Base Libraries and Core Services to containers running in the environment to minimize the size of each provided application container image. The goal of GEISA LEE conformance is to provide a consistent and efficient execution environment to edge applications running on the platform. Platform implementers may use any GNU/Linux variant they see fit, provided it meets the requirements noted in Operating System; however, for security and efficiency reasons, implementers SHOULD NOT use full general purpose GNU/Linux operating system distributions. Implementers SHOULD use distributions specifically built for embedded environments and should excise any unnecessary system components and/or services.
GEISA LEE elements are shown in blue in Figure 8.1
above.
VEE GEISA applications are provided as loadable VEE archives, as detailed in Virtual Execution Environment. A VEE conformant GEISA implementation is able to launch the archive in a VEE as necessary and grant the application the rights which the system operator permitted to the application in the application deployment manifest.
The VEE used by the platform implementation is out of scope of this specification, but conformant implementations MUST be able to enforce the permissions and controls the GEISA specification requires, and support the APIs required by the GEISA specification.
Note that GEISA VEE elements are not currently shown in
Figure 8.1 above.
General operating system functions such as file system access, math libraries, and network socket APIs are provided by the GEISA LEE or VEE discussed above. The GEISA API facilitates access to platform capabilities that are not serviced by the LEE’s or VEE’s respective APIs. The GEISA API is described in detail in Application Programming Interface (API). The GEISA API will provide access to metrological data, sensor data, billing data, actuators, and, for GEISA ADM conformant implementations, message exchange with the EMS.
GEISA API conformant platform implementations MUST provide an implementation of the message bus described in Application Programming Interface (API) and MUST respond appropriately to all required API transactions. Connecting the GEISA API implementation to the underlying platform is out of scope for the GEISA specification.
Platform implementers may use any supporting implementation they see fit; however, implementers SHOULD consider the security implications of the implementation and ensure they are robust against both unintended abuse and deliberate attacks.
GEISA API elements are shown in green in
Figure 8.1 above.
8.1. Application Isolation¶
Note
Application Isolation is required of all GEISA execution environments. This section discusses what execution environments must achieve. Requirements specific to a given EE are covered in the respective EE chapters.
GEISA applications shall be isolated from each other and the core platform for the following reasons:
To ensure that one application cannot impact another application.
To ensure that one application cannot see the artifacts, resources, data, state, or existence of another application.
To ensure that applications cannot impact the platform or workloads outside of the GEISA implementation.
Because the GEISA specification defines multiple execution environments, the Application Isolation Implementation (AII) is expected to vary between execution environments and may vary from one platform to another within an execution environment. Regardless of AII (e.g. LXC container, systemd, VEE, etc.), an authenticated application manifest shall control access to platform resources and the GEISA API. Additionally, it shall enforce the principle of least-privilege.
The application isolation implementation of GEISA conformant platforms shall ensure that:
Applications run in isolation (e.g. independent processes, threads, virtual machines as appropriate for the EE)
Applications run with least privilege
Application access permissions are deny by default
Application-to-application communication are denied by default
Applications cannot access other application’s memory or other resources
Applications cannot access the platform’s local file-system
Applications cannot impact the performance of the platform
Applications cannot impact the stability of the platform
Applications cannot impact the performance of other applications
Applications cannot impact the stability of other applications
Applications cannot consume more than their allocated resources
Applications cannot directly access platform hardware, such as UART, SPI, I2C, GPIO, or actuators
Applications can only share data with other applications when specifically granted permission
Note
This version of the GEISA specification does not provide a mechanism for application discovery, but it does provide a mechanism for application to application communication (see App-to-App Communication). To take advantage of application to application communications, applications will need to be written to offer or consume services. This is an out-of-band design / deployment choice, rather than something facilitated within the specification.
8.1.1. Application Manifest¶
The same application manifest is used across all AII. Because of this, all AII SHALL support the same controls, in support of the settings defined in the application manifest, even if their underlying implementation is substantially different. Application manifests are documented in Application Manifests.
8.1.2. Networking Controls¶
The AII must control access to the network interface. By default, applications are not granted any network access. The application manifest may indicate that a given application is allowed to natively access the local network interface.
The AII shall control:
Whether direct network access is allowed.
Which network interfaces an application may access (none by default), including HAN/LAN and FAN/WAN interfaces.
The allowed average network volume an application may use over a daily period (e.g., 24 hours).
Allowed destination peers (IP/proto/port) for IP-based communications.
8.1.3. API Controls¶
These permissions relate to controlling application access to the GEISA API provided by the platform. See Application Programming Interface (API) for details. Each defined API shall have its own set of permissions.
8.1.4. Resource Management¶
The AII shall enforce resource limits according to the manifest. AII resource limits shall include the following:
CPU limit (% of CPU)
Memory Limit (in 1KiB units)
Persistent Storage Limit (in 1KiB units)
Non-Persistent Storage Limit (in 1KiB units)
Note
An Application or Deployment manifest can be modified and re-deployed during an Application upgrade or administrative change. Changes to the resource requirements SHOULD not require an Application restart, but an EE implementation MAY stop, modify, and restart an Application if necessary.
If the persistent storage limit is increased, an implementation MUST honor that change and provide the application with a larger volume or limit without loss of existing persistent data. If that limit is reduced, an implementation SHOULD attempt to honor that change and reduce the volume or limit, however if the Application is using more than the new limit an alarm or exception SHOULD be raised to the EMS and the action MUST be aborted, leaving the Application running with the previous manifest.
8.2. Versioning¶
GEISA endeavors to support forwards and backwards compatibility across its requirements and APIs. Because of the wide breadth that GEISA covers (as discussed above), it can be challenging to understand how versions are maintained. The Grid Edge Interoperability & Security Alliance has endeavored to ensure that minor changes can be accommodated in a fully backwards compatible way, and that major changes are well defined so that implementations can detect exactly which transactions are supported if they choose to support multiple versions.
8.2.1. Specification¶
GEISA is first and foremost, versioned at the specification level. Each version of the specification includes a specific set of requirements. GEISA uses a three digit versioning system: major.minor.patch. Corrections to the specification that do not change APIs or functionality, but simply clarify meaning or intent (“patches” as it were) are indicated by incrementing the patch number. Additions to the functions or behavior described in the specification that do NOT break or change existing behaviors, are indicated by incrementing the minor number. Changes to the architecture, breaking changes, or major new additions (e.g., adding a new execution environment), are indicated by incrementing the major number. All builds of the GEISA specification also include a commit identifier, allowing users to see the exact source files that were used to generate the specification, and to see each and every change that was made.
8.2.2. LwM2M Transactions¶
The ADM pillar uses LwM2M as the basis of the management API
between platform implementations and an Edge Management System (see
Operations for discussion). LwM2M object definitions each contain a
version identifier (
ObjectVersion). OMA does not allow any changes to the
object definition without updating the ObjectVersion field. LwM2M objects
are maintained in a GitHub Repository. For convenience, the Grid Edge Interoperability & Security Alliance includes a
pinned reference to the LwM2M object repository within the GEISA specification
repository. As a result, it is possible to use the commit ID of the GEISA
specification to sync to the specific versions of the LwM2M objects associated
with that version of the GEISA specification.
8.2.3. Manifests¶
Application and Firmware Manifests are defined in JSON schemas. These schemas include a version number. The version number is updated when changes are made.
8.2.4. MQTT API & Protobufs¶
GEISA uses protobuf schemas to define the transactions exchanged over the MQTT
API . By design, protobuf allows new fields to be added
without breaking existing implementations. This allows older implementations
to accept messages with new fields gracefully, provided that the API
transaction does not require the use of the new fields. The Grid Edge Interoperability & Security Alliance requires
that any new mandatory fields or other breaking changes to the MQTT API MUST
introduce a new topic hierarchy. Changes affecting only one API area MAY use
a versioned topic, such as
geisa/api/billing/v2/data, while broader
versioning of the API MUST introduce a new versioned hierarchy, such as
geisa/api/v2/billing/data.
The topic names are provided in the specification, and the associated protobuf schemas are held within the specification repository. As a result, it is possible to determine exactly which version of a schema is associated with a given version of the GEISA specification.
8.2.5. ReST APIs¶
GEISA ReST APIs use versioned URI paths, such as /geisa/adm/v1/.
Breaking changes to a ReST API MUST introduce a new versioned URI path,
such as /geisa/adm/v2/. Compatible changes MAY retain the existing
URI version.