SPEKTRA Edge Devices Service API

Devices service manages the edge devices connecting to the SPEKTRA Edge system. The service is typically operated by a user with the device-operator role or a higher.

Full API Specifications (with resources):

• Version v1alpha2
• Version v1

Device Management (Device Resources)

Devices on SPEKTRA Edge have their information managed by Device resources. Configuration values and status information for each device are stored in the Device resource. This resource is used by the agent running on the device where the SPEKTRA Edge OS is installed.

Devices are usually managed by being tied to a service account. When the actual SPEKTRA Edge device boots, the agent in the device connects to the Devices service using the stored service account. By using the service account associated with the device resource, it determines which device resource to download configuration values from and stores status information for that device resource.

The simplest Device resource can be created with the following command; since the Device resource is a Project scope resource, the Project must be specified for creation.

## Create a device with ID DEVICE
## display name is "Test Device
cuttle devices create device --project $PROJECT \
  --display-name "Test Device" \
  $DEVICE

Device Metrics

The SPEKTRA Edge device periodically reports hardware metrics information (e.g., CPU utilization), which is stored as time-series data on the Monitoring service; see the Monitoring chapter for instructions on how to use the Monitoring service.

Device Logs

Logging from an SPEKTRA Edge device can be done in two ways: logs from the point of command execution can be streamed in real time via the SPEKTRA Edge controller, or logs sent by the device can be stored in the SPEKTRA Edge backend and retrieved from there as needed. The other is to store the logs sent by the device in the SPEKTRA Edge backend and retrieve the logs from there as needed.

To use the former real-time device logs, use the command:

cuttle devices logs --follow`

In this case, the system logs from the time the command was executed (as described in /var/log/syslog) can be obtained without any additional configuration.

cuttle devices logs --follow $DEVICE

The latter, which stores logs in the SPEKTRA Edge backend and retrieves data from it, requires prior configuration to enable the feature. This feature is currently available without additional subscription, but may be paid for in the future. Log data is stored for up to 90 days.

To perform logging, set the spec.loggingConfig field in the Device resource.

cuttle devices update device $DEVICE_ID \
  --update-mask spec.loggingConfig \
  --spec '{"loggingConfig": {"enableJournalExport": true, "priority":7}}'

To get docker.service and droplet.service only:

{"units": ["docker.service", "droplet.service"]}

Use the cuttle devices logs --archival command to retrieve the stored logs.

    cuttle devices logs --archival --since 60 $DEVICE_ID

Remote terminal access to SPEKTRA Edge devices

SPEKTRA Edge devices provide remote terminal access as standard.

For macOS and Linux environments

In macOS and Linux environments, the cuttle command can be used to remotely login to a device. The cuttle devices ssh command is used for terminal access. The argument of the command is the value of NAME as displayed in cuttle devices list devices.

The following is an example of access when NAME is projects/$PROJECT/regions/eu1/devices/test-device.

cuttle devices ssh projects/$PROJECT/regions/eu1/devices/test-device

For Windows environment

The cuttle devices ssh command cannot be used as-is in a Windows environment due to technical limitations. Please refer to the official Microsoft documentation on how to install WSL2.

Port forwarding with SPEKTRA Edge devices

To use a device with SPEKTRA Edge OS installed as a “jump box”, use the cuttle devices forward-port command.

The following example forwards local port 8080 to port 80 on 192.168.10.1 using the device projects/$PROJECT/regions/eu1/devices/test-device as a jump box. With this command running, open localhost:8080 in your web browser to access 192.168.10.1:80 (you will normally see the home gateway operation screen).

cuttle devices forward-port \
  projects/$PROJECT/regions/eu1/devices/test-device \
  8080 tcp://192.168.10.1:80/

Device Auto-registration Settings (Provisioning Policy)

Device resources can be created individually by users, but this can be complicated if there are many devices. To solve this problem, a mechanism to automatically register devices can be used.

The Provisioning Policy resource is a resource that stores settings for auto-registering devices. When an SPEKTRA Edge device with a Provisioning Policy set is booted, a corresponding Device resource is automatically created based on the settings.

Like the Device resource, the SPEKTRA Edge device identifies a Provisioning Policy tied to it using a service account. See the “Provisioning SPEKTRA Edge Devices” section for specific instructions for tying service accounts.

The following example is a cuttle command that creates a new Provisioning Policy.

cuttle devices create provisioning-policy \
  --project $PROJECT \
  --spec '{"mode": "UNATTENDED", \
           "identityFieldPaths": ["status.deviceInfo.hardwareInformation.system.serialNumber"]}' \
  test-provisioning-policy

Device resource template values

The Provisioning Policy generates a Device resource for each new hardware. At this time, by setting a value in the Provisioning Policy’s spec.template, it is possible to automatically set the value of the Device resource to be generated.

The following example shows the configuration of a Provisioning Policy when labels and log settings are automatically configured for the generated Device resource.

cuttle devices create provisioning-policy \
  --project $PROJECT \
  --spec '{"mode": "UNATTENDED", \
           "identityFieldPaths": ["status.deviceInfo.hardwareInformation.system.serialNumber"], \
           "template": {"metadata": {"labels": {"device": "raspberry-pi"}}, \
                        "spec": {"loggingConfig": {"priority":7, \
                                                   "enableJournalExport":true}}}}' \
  test-provisioning-policy

SPEKTRA Edge Device Provisioning

Download SPEKTRA Edge OS image

SPEKTRA Edge OS can be downloaded from the following URL. Note that the files used depend on the architecture of the hardware used. Currently, amd64 (x86) or Raspberry Pi 4 are supported.

The image of version 2.1.0 can be downloaded from the following URL

• https://downloads.edgelq.com/images/2.1.0/generic-amd64/spektra-edge_generic-amd64_2.1.0.raw (generic amd64)
• https://downloads.edgelq.com/images/2.1.0/raspberrypi-arm64/spektra-edge_raspberrypi-arm64_2.1.0.raw (Raspberry Pi)

SPEKTRA Edge OS Image Customization

The SPEKTRA Edge OS provided to the public does not contain information tied to a specific Project. Therefore, to automate provisioning, the OS image must be customized and a configuration file must be inserted.

Create a configuration (Provisioning Policy) for automatic registration

Create a Provisioning Policy on the Devices endpoint to configure how new devices will be registered with the system. When a new device is registered with the system, a Device resource is created for each device based on the settings in this resource.

cuttle devices create provisioning-policy \
  --project $PROJECT \
  --spec '{"mode": "UNATTENDED", \
           "identityFieldPaths": ["status.deviceInfo.hardwareInformation.system.serialNumber"]}' \
  test-provisioning-policy

Generate service account and key for Provisioning Policy

In order for a new device to register using the above Provisioning Policy, it must use the service account (and its key) associated with the applicable Provisioning Policy.

The following command generates a service account and stores the downloaded key in /tmp. The jq command is used to format some values.

cuttle devices provision-service-account-to-provisioning-policy \
  -o json \
  provisioning-policy \
  --name projects/$PROJECT/regions/us-west2/provisioningPolicies/test-provisioning-policy | \
jq .serviceAccount > /tmp/service_accont_key.json

Customize image files

Customize the downloaded SPEKTRA Edge OS image using the following command. This command must be used with sudo on Linux.

sudo -E cuttle os edit \
  --image-file lqd_1.0.2.raw
  --password $PASSWORD \
  --endpoint-domain stg01b.edgelq.com \
  --project-service-account-key /tmp/service_accont_key.json

The main options available with the cuttle os edit command are

--disk-mapping: disk mapping file

The disk mapping file is written in YAML format and is configured when using HDDs or SSDs other than the boot media. If you use only boot media, you do not need to specify this option.

The file contents are largely divided into diskmappings and bindmounts, the former being partition mount settings and the latter being bind mount settings.

The diskmappings specifies which disk (disk) and where (mountpoint) it should be mounted. If the partition is unformatted, it will be automatically formatted using the specified size (size) and file system (filesystem). Note that if you specify -1 for the size option, all available space will be used, but only for the tailmost partition.

The bindmounts lists which directories (mountsource) are to be bind-mounted where (mountpoint).

Below is the default disk mapping file for x86 devices. By default, the tailmost EDGELQ_DATA partition is expanded to its maximum size at SPEKTRA Edge OS startup. Also, /var/lib/docker, /var/lib/droplet, and /var/log are bind-mounted in /isodevice/data where EDGELQ_DATA is mounted, so that files stored in these directories will be boot persistent in the media.

Note that the default disk mapping file has different settings for each platform. For example, the Raspberry Pi requires a separate partition to store firmware, etc., so a dedicated setting is used.

diskmappings:
  - disk: /dev/disk/by-partlabel/EDGELQ_DATA
    mountpoint: /isodevice/data
    size: -1
    filesystem: ext4
  - disk: /dev/disk/by-partlabel/EDGELQ_ISOS
    mountpoint: /isodevice/isos
    filesystem: ext4
  - disk: /dev/disk/by-partlabel/EDGELQ_BOOT
    mountpoint: /isodevice/boot
    filesystem: ext4
bindmounts:
  - mountsource: /isodevice/data/docker
    mountpoint: /var/lib/docker
  - mountsource: /isodevice/data/droplet
    mountpoint: /var/lib/droplet
  - mountsource: /isodevice/data/log
    mountpoint: /var/log

--network-agent: network configuration file

The network configuration file is the Netplan configuration file. The default configuration file has DHCP enabled, so there is no need to specify this option if static IP or WiFi settings are not required.

The following is the default configuration file.

network:
  version: 2
  renderer: networkd
  ethernets:
    default-en:
      match:
        name: en*
      dhcp4: yes
    default-eth:
      match:
        name: eth*
      dhcp4: yes

Static IP Configuration Example

The following configuration example sets 192.168.1.30/24 for the eth0 interface.

network:
  version: 2
  renderer: networkd
  ethernets:
    enp2s0:
      dhcp4: no
      addresses: [192.168.1.30/24]
      gateway4: 192.168.1.1
      nameservers:
        addresses: [192.168.1.1]

Example of WiFi setup

The following setup connects the wlan0 interface to the NTT-WIFI network (SSID) using WIFI-PASSWORD as the password.

network:
  version: 2
  renderer: networkd
  wifis:
    wlan0:
      dhcp4: yes
      access-points:
        "NTT-WIFI":
          password: "WIFI-PASSWORD"

Please refer to the Netplan manual for other possible settings (some settings are not supported).

--ntp: NTP configuration file

The NTP configuration file is the systemd-timesyncd configuration file. Specify this option if you want to use an NTP server other than the default.

For information on how to write the configuration file, see man timesyncd.conf or Arch Linux website.

If the NTP server is not properly configured, the SPEKTRA Edge OS and applications running on it may stop working. If a TLS (HTTPS) certificate verification error occurs, make sure that the NTP server is properly configured and that the system clock is not out of sync.

Write SPEKTRA Edge OS to media

Image files can be written to media with any application.

On Linux, for example, you can use the dd command (replacing sdX with the appropriate device name).

sudo dd if=lqd_1.0.2.raw of=/dev/sdX

In a Windows environment, Raspberry Pi Imager or Balena Etcher can also be used.

SPEKTRA Edge Device Startup

The media on which the customized OS image is written can be used as boot media without modification. When the device is booted while connected to the network, it is automatically registered to the SPEKTRA Edge controller.

The list of registered devices can be viewed with the following command

cuttle devices list devices --project $PROJECT

Hardware update procedure

This section describes how the operation is performed in the event of a hardware failure, assuming that the device has been provisioned using a Provisioning Policy, and that the relevant Provisioning Policy has a Deduplication Field with a serial number set.

How to respond to hardware failure

Hardware failure can be divided into two categories: failure of the boot media (SD card or USB memory) on which the SPEKTRA Edge OS is installed, and failure of the hardware itself (such as the Raspberry Pi). Depending on which of these two elements is being replaced, the method of response will vary.

If only the hardware is replaced and the OS media is identical

Insert the existing boot media into the new hardware and boot. In this case, the service account information remaining on the boot media takes precedence over the serial number, so the existing Device resource is used as is (the resource serial number is overwritten).

If the hardware is identical and only the OS media is replaced

Point the new boot media to the existing hardware to boot. In this case, the new boot media does not have a service account to identify the Device resource, so the serial number is used to identify the existing Device resource. Since there is no change in the serial number on the same hardware, the existing Device resource will be used.

When replacing both hardware and OS media

If both are replaced at the same time, a new Device resource will be created since there is no way to identify the existing Device resource. To avoid this behavior, perform the following operations on the OS image (after copying the files) before writing to the SD card.

## remove an existing service account
cuttle devices remove-service-account-from-device device --name $DEVICE
## edit the image file (create service account for the device in question and
## write it)
cuttle os edit cuttle os edit \
  --image-file $IMAGE_FILE_NAME \
  --device-name $DEVICE