Configure Capability

Overview

Device Builders can integrate Industrial Edge on their devices with minimal effort. Disabling unrequired services in the capability file and only using Runtime Container leads to an easier setup experience. Or, if required, enable the services in the capability file.

Devices with already existing services for Device Management can also run Industrial Edge Applications by configuring them in the capability file. The Device Builder can disable the pre-implemented function of the Industrial Edge Device and enable the required ones. The apiCapability field allows to implement the IED services. To implement the apiCapability functionality for the respective services, the associated services must be enabled.

Summary

This document will provide a step-by-step approach to how a Device Builder can integrate the dockerized edge solution and deploy/run the Industrial Edge Apps on any device. So this device becomes an Industrial Edge Device. It will also provide information about all the parameters which are available in the capabilities file, which is used to enable the required functionalities.

Deploying via Docker Compose

Prerequisites: Docker should be installed and running on the device OS. Docker compose can optionally be installed for more comfort while starting the Edge Runtime Container.

1. You may install the version of docker which is >= 18.09.1, from Install Docker Engine
    - apt install docker.io | docker-ce | docker-engine | moby-engine
2. You may optionally install the latest version of docker from Install Docker Compose
    - curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
    -chmod +x /usr/local/bin/docker-compose

Deploying via Docker Run

1. Download the IERT-compose zip from IEHUB from IEDK which contains the following.

   • capabilities_all_disabled.json here
   • edge-iot-core-container_1.10.0-4_amd64_docker_compose.yaml here
   • edge-iot-core-container_1.10.0-4_amd64.tar.xz - IERuntime Container Image tarball

   NOTICE

   For using edge-iot-core-container_1.10.0-4_amd64_docker_compose.yaml rename it to docker-compose.yml.

2. Rename capabilities_all_disabled.json file to capabilities.json and copy the capabilities.json to /etc on host filesystem.

3. You may have to load the image tar file
   • docker load -i <image tar file>
4. Modify the below-listed parameter values
   • HostIps : Supply it with the current IP Address of the system

5. Run Industrial Edge Services

   • docker-compose up -d <YMLFile>
   • or to deploy via Docker Run Command

           - Run the downloaded image using proper arguments and environment variables
               docker run
               -itd
               --restart=always
               -e HostIps='x.x.x.x'
               -v /etc/ssl/certs/:/etc/ssl/certs/
               -v /var/lib/docker/volumes:/host-system/var/lib/docker/volumes
               -v /var/lib/docker/containers:/var/lib/docker/containers
               -v /var/run/docker.sock:/var/run/docker.sock
               -v /var/lib/docker/edge-iot-core/Database:/var/lib/redis
               -v /var/lib/docker/edge-iot-core/Data:/data
               -v /var/lib/docker/edge-iot-core/Data:/var/lib/docker/edge-iot-core/Data
               -v /var/lib/docker/edge-iot-core/apps:/etc/nginx/conf.d/apps
               -v /var/lib/docker/edge-iot-core/app_engine:/etc/app_engine
               -v /var/lib/docker/edge-iot-core/profile.d:/etc/profile.d/
               -v /var/run/devicemodel:/var/run/devicemodel
               -v /etc/pki/tls/certs/:/etc/pki/tls/certs/
               -v /etc/pki/tls/private/:/etc/pki/tls/private/
               -v /dev/log:/dev/log
               -v /var/log/journal:/host-system/var/log/journal:ro
               -v /etc/capabilities.json:/data/app_engine/Configuration/capabilities.json
               --publish 443:443
               --publish 9443:8443
               --pid=host
               --name edge-iot-core <image-name>
   

NOTICE

The HostIps field in JSON file contains comma-separated IP addresses.

Capability configuration

This section defines the services that are needed to be enabled/ disabled according to the implementation of the Edge Services. Following are the IEDK services.

• host.edgemanagerservice
• host.ntpservice
• host.networkservice
• host.systemservice
• host.onboardservice
• host.resourcemanager
• host.proxyservice

IEDK Services Enabled

Impact on IED

No IEDK services are enabled

The following are the disabled functions: NTP Configurations - Set/Get NTP or NTP Health Status Network Configuration Docker Network Configurations If the API is used, it will return the error "503 ServiceNotImplemented". Network Device Kit Service: The LAN Network is set by default i.e. the Host Address obtained from the docker-compose file and cannot be edited. The L2 Network cannot be assigned visible if the Network services capability is disabled. System Device Kit Service: When The system service is disabled, the Application Setting, Shutdown, and Reboot functionalities will return the error "SystemServiceNotImplemented". The logs will be available and can be downloaded, but they will only have container logs and not the system logs as the system service is disabled. The jobs for Shutdown or Reboot are created by the IEM when the System services capability is disabled or the apiCapability for ShutDown or Reboot is switched to false. Then jobs will be skipped with the error message ”Shutdown operation not supported on the device.”. The apiCapability HardReset and Reset functionality of System services is independent of the system service and is visible even when System service capability is disabled. The operation-quality-info from the Statistics will return the default value. The system info i.e CPU, Memory, and Storage will not reflect on the IED UI. Onboard Device Kit Service: The IED box will be onboarded and activated. Edgemanager Service : The Docker network is disabled. Applications can be installed, uninstalled, started, stop and restart. IED Remote Access Setting will not work if IED is onboarded at IEM Pro, IEM Cloud and IEM Virtual because it needs the Edgemanager service to be enabled. IED Remote Access Setting will work if IED is onboarded at IEM-OS based IEM. Also, IED certificates are uploaded successfully, but the user will have to reload the docker daemon manually via SSH. If not updated manually it will give the error "Unable to download image due to invalid certificates of docker registry server." at the time of app installation. Resource manager Service : Allocating resources to apps, e.g., CPU cores, network interfaces, or GPUs, is disabled. Proxy Service : The Proxy management is disabled

|

• host.edgemanagerservice

|

• With only edgemanager service enabled, where the device builders can use their own implementation.
• In case the system has NGINX configured, the IED certificate updates will get reflected in the system NGINX.
• Applications can be installed from storage successfully. With the Device Builder implemented edgemanager service, it should list all offline app details for provided mounted paths.
• Support for onboarding from USB stick is provided.

| |

• host.resourcemanager

|

• With only the resource manager service being enabled, the user can allocate available resources as required, e.g., CPU cores, network interfaces, or GPUs.

| |

• host.proxyservice

|

• With only the proxy service being enabled, user can manage proxy functionality on the Edge Devices.

NOTICE

1. The host.edgemanagerservice services must be enabled to restart the docker daemon after proxy configuration changes are applied.
2. The host.proxyservice needs to ensure that the proxy server's port is not set as a custom port.
3. Compatible host.edgemanagerservice version is greater than or equal to 1.24.0-1
4. host.proxyservice depends on the redsocks_0.5-3_amd64.deb, redsocks_0.5-3_debian11_amd64.deb, redsocks_0.5-3_debian12_amd64.deb

||

• host.edgemanagerservice
• host.ntpservice
• host.networkservice
• host.systemservice
• host.onboardservice
• host.resourcemanager
• host.proxyservice

|

• Device Builder needs to implement all the services, so the IED can be used as a fully integrated Industrial Edge Device.

|

NOTICE

1. The IED is expected to show an unexpected behavior if the device kit services are enabled or disabled other than mentioned combinations.
2. It is the stakeholder's responsibility to ensure that the capability file is not misconfigured.

Industrial Edge Management Compatibility

If the device capabilities are configured such that one of the following scenarios is true:

• host.systemservice service is disabled
• The apiCapability GetResourceStats of the host.systemservice service is false

Refer to the following IEDK & IEM Version Compatibility Matrix:

	IEDK version <= 1.13.0-2	IEDK version >= 1.13.0-3
IEM version <= 1.12.3	No compatibility issues	Creation of app install/update jobs on IEM will stop Must update to IEM version >= 1.12.4
IEM version >= 1.12.4	No compatibility issues	No compatibility issues

Known Issues

1. When the device is onboarded and also when IEM certificates are imported, the user needs to reload the docker daemon manually via SSH to update the IEM certificates.
2. If the edgemanager service is disabled, you must manually reload the Docker daemon via SSH
   • if you want to update the IED certificates when the device is onboarded.
   • when IED certificates are imported.
   • to perform a hard reset and soft reset.