zededa/edge-sync repository overview

⁠Edge Sync

⁠Overview

Edge-sync acts as a HTTP server, which serves EVE regular HTTP requests and user HTTP requests.

In order for EVE to communicate to the edge-sync over the HTTP (in this implementation we do not support certificates, thus plain HTTP is supported only) the edge-sync URL should have the “http://” prefix.

CMD ["/usr/bin/edge-sync", "--available-edge-config-path", "/root/.edge-sync/available-edge-configs", "--edge-config-path", "/root/.edge-sync/edge-configs", "--ds-path", "/root/.edge-sync/datastore", "--http-port", "1180", "--ds-http-port", "8100"]

The edge-sync utility should be started with the following options specified:

--available-edge-config-path -- path points to the directory where edge device configurations will be stored as protobuf files with device UUID as a folder name --edge-config-path -- path points to the directory where edge device configurations will be moved as protobuf files with device UUID as a folder name --ds-path -- path to the data-store images --http-port -- HTTP port of the edge-sync server --ds-http-port -- HTTP port of the data-store server

$ ./edge-sync --available-edge-config-path .edge-sync/available-edge-configs
--edge-config-path .edge-sync/edge-configs
--ds-path .edge-sync/datastore
--http-port 1180
--ds-http-port 8100

Application should start and create two HTTP instances on 1180 and 8100 TCP ports.

All interaction with a user happens over the HTTP protocol (the protocol is explained below) and responses are provided in human readable JSON format.

Important to note that current edge-sync implementation uses persistent storage (filesystem) only for storing the imported edge node configurations. All states (metrics and info messages) of the devices are stored in run-time, i.e. in RAM. Devices are considered online if there is a recent ‘metrics’ update from an edge node (current document does not specify the actual timeout, this depends on the implementation).

⁠Logging

This utility uses the logrus library to log to stdout. The standard log events include connecting and disconnecting a new edge node. Using --debug flag will enable more verbose logging.

⁠Edge-sync Application Protocol

This section describes the supported protocol of HTTP instances, created by the edge-sync application.

⁠EVE HTTP protocol

EVE https protocol has URL prefix defined as ‘api/v2/edgedevice’ and the following API endpoints:

POST /id/$UUID/compound-config - the CompoundEdgeDevConfigRequest message sent from the device and the ConfigResponse with CompoundEdgeDevConfig message sent from Controller to Device in response.

POST /id/$UUID/info - the ZInfoMsg message sent from Device to Controller when there is a state change for an object (device, app instance, etc)

POST /id/$UUID/metrics - the ZMetricMsg message sent from Device to Controller periodically to report on resource usage etc.

where $UUID is an edgedevice UUID. (API description is copied from the eve/api/APIv2.md)

The current edge-sync vision does not plan to change the core protocol between EVE and Zedcloud, so that edge-sync implementation can copy and reuse the protocol definitions.

⁠Edge-sync HTTP protocol

In the phase 1 there is no room for UI implementation, but for the customer it should be still possible to interact with edge-sync by calling the generic console tools (like curl or wget) in a simplified manner.

Edge-sync http protocol has URL prefix defined as ‘api/v1/user’ and has the following API endpoints:

POST /config - imports device config bundle, where each file in the bundle is a protobuf config response. cURL call can be the following:

   $ curl -F [email protected] http://$URL/api/v1/user/config

For example this ‘config-bundle.json’ contains only one configuration:

{
       "localOperatorConsoleBlobList": [
              {
                     "devId": "d8bf6b3a-917f-44dc-bdae-7542e7f7de88",
                     "config": "0adf4b0adc4b0a ….. “
              }
       ]
}

POST /config - imports device config bundle, where each file in the bundle is a protobuf config response. cURL call can be the following:

   $ curl -F [email protected] http://$URL/api/v2/user/config

For example this ‘config-bundle.json’ contains only one configuration:

{
       "localOperatorConsoleBlobList": [
              {
                     "devId": "d8bf6b3a-917f-44dc-bdae-7542e7f7de88",
                     "config": "0adf4b0adc4b0a ….. “
              }
       ]
}

POST /id/$UUID/config/apply - will move the device config from available folder to apply folder

   $ curl -X POST http://$URL/api/v1/user/id/$UUID/config/apply

GET /devs/config/available - returns list of UUIDs in JSON format of all the devices for which new config is available. cURL call can be the following:

   $ curl http://$URL/api/v1/user/devs/config/available

GET /devs - returns list of UUIDs in JSON format of all the online devices. cURL call can be the following:

   $ curl http://$URL/api/v1/user/devs

GET /id/$UUID/info - returns a JSON object with fields representing all ZInfoTypes for the device specified by the $UUID. Each field then contains either one ZInfoMsg with devID for the key or a map of ZInfoMsg with their respective unique identifier as keys. Here is an example:

{
  "ZInfoTypes_ZiDevice": { // ZInfoType
    "0d4fc51a-9d6a-4d1e-92fa-d6b0ec1aa79d": { // device ID
      "ztype": 1,
      "devId": "0d4fc51a-9d6a-4d1e-92fa-d6b0ec1aa79d",
      "InfoContent": {
        "Dinfo": {
          ...
        }
      },
      "atTimeStamp": {
        "seconds": 1744806496,
        "nanos": 527934738
      }
    },
  },
  "ZInfoTypes_ZiApp": {}, // ZInfoType
  "ZInfoTypes_ZiNetworkInstance": { // ZInfoType
    "48d89d2d-4ca7-4947-aa1d-5e6981708443": { // unique identifier
      "ztype": 6,
      "devId": "0d4fc51a-9d6a-4d1e-92fa-d6b0ec1aa79d",
      "InfoContent": {
        "Niinfo": {
          ...
        }
      },
      "atTimeStamp": {
        "seconds": 1744806492,
        "nanos": 904528481
      }
    },
    "be89d4e3-a7c3-4f70-a5d2-f9a4d91d8787": { // unique identifier
      "ztype": 6,
      "devId": "0d4fc51a-9d6a-4d1e-92fa-d6b0ec1aa79d",
      "InfoContent": {
        "Niinfo": {
          ...
        }
      },
      "atTimeStamp": {
        "seconds": 1744806492,
        "nanos": 904488515
      }
    }
  },
  ...
}

Edge-sync implementation returns ‘404 Not Found’ response if the device is not online. cURL call can be the following:

   $ curl http://$URL/api/v1/user/id/$UUID/info

GET /id/$UUID/metrics - returns ZMetricMsg in JSON format for the device specified by the $UUID. Edge-sync implementation returns ‘404 Not Found’ response if the device is not online. cURL call can be the following:

   $ curl http://$URL/api/v1/user/id/$UUID/metrics

POST /id/$UUID/command/{shutdown|graceful-poweroff|graceful-reboot|collect-info} - issues device command

   Supported commands are:

         shutdown          - shuts all application down
         graceful-poweroff - shuts all application down and powers the device off
         graceful-reboot     - shuts all application down and reboots the device
         collect-info      - runs collect-info script on the device and uploads the generated output to a pre-configured data store

   $ curl -X POST http://$URL/api/v1/user/id/$UUID/command/{shutdown|graceful-poweroff|graceful-reboot|collect-info}

POST /id/$UUID/app/$APPUUID/command/{purge|restart} - issues application command

   Supported commands are:

         purge    - purges application
         restart  - restarts application

   $ curl -X POST http://$URL/api/v1/user/id/$UUID/app/$APPUUID/command/{purge|restart}

All responses for the GET endpoints should be in JSON human readable format.