Learn SPEKTRA Edge

• 1: Get started
• 2: How SPEKTRA Edge works
• 2.1: Shared responsibility
• 3: Applications
• 3.1: Develop an application
• 3.2: Deploy an application
• 3.3: Configure applications via configuration maps
• 3.4: Deploy with private container registries
• 3.5: Deploy to multiple devices
• 3.6: Access your deployed application
• 3.7: Monitor and control applications
• 4: Devices & SPEKTRA Edge OS
• 4.1: Overview
• 4.2: Device setup & provisioning
• 4.3: Provisioning policies
• 4.4: Zero-touch provisioning
• 4.5: Install the droplet agent (.deb package)
• 4.6: Storage
• 4.7: Networking
• 4.7.1: Configure device networking with Netplan
• 4.7.2: Connection fallback
• 4.7.3: Proxy configuration
• 4.7.4: Connectivity & ports
• 4.7.5: Time synchronization
• 4.8: Security
• 4.8.1: Disk encryption
• 4.8.2: TPM & device attestation
• 4.8.3: Secure Boot
• 4.8.4: SSH access
• 4.8.5: User accounts
• 4.8.6: USB device control
• 4.8.7: Remote access
• 4.9: Operations
• 4.9.1: OS upgrades
• 4.9.2: Rolling out across a fleet
• 4.9.3: Reboot, shutdown & recovery
• 4.9.4: Health checks
• 4.9.5: Status & indicators
• 4.9.6: Boot & shutdown hooks
• 4.9.7: Running workloads
• 4.9.8: Transfer files
• 4.10: Troubleshooting
• 5: Monitoring & alerts
• 5.1: The Device overview page
• 5.2: Device logs
• 5.3: Manage alerts
• 5.4: Alert metrics and what to monitor
• 5.5: AI Alerting
• 5.6: Device metrics reference
• 5.7: Audit logs
• 6: Secrets
• 7: Accounts & access
• 7.1: Organizations and projects
• 7.2: User authentication
• 7.3: Service accounts
• 7.4: Manage resource limits
• 8: Solutions
• 8.1: Service Experience Insights
• 9: cuttle CLI
• 9.1: Installing the cuttle CLI
• 9.2: Authenticating with the cuttle CLI
• 9.3: Configuring the cuttle CLI
• 9.4: Operating with the cuttle CLI
• 9.5: Help commands
• 10: Glossary

1 - Get started

Let’s start deploying your first application on your device with SPEKTRA Edge. Here is the summary of the process:

1. Setting up your Raspberry Pi device and bringing it online on the SPEKTRA Edge dashboard.
2. Deploying a Nginx application on the device.
3. Verifying your application through the SPEKTRA Edge dashboard.

Once you’ve completed this guide, you’ll gain the fundamental knowledge how to deploy your applications on your device with SPEKTRA Edge platform.

What you need

• a Raspberry Pi device — see supported devices if you need to use other hardware
• a tool to flash SPEKTRA Edge OS onto the device, such as the Etcher OS image flasher
• access to the SPEKTRA Edge dashboard

And also, the cuttle CLI command is necessary to complete this guide, which is used to access the Nginx application from the local machine for the verification purpose. However, it is not required for deploying applications on SPEKTRA Edge.

Create a project

Let’s first create a project, which manages the group of devices. It’s the one stop shop to deploy and manage your devices and applications in a unified fashion.

To create your first project, log into your SPEKTRA Edge dashboard and click Create project on your right.

Enter a project name and the region close to your devices, and click Create:

You’ll then be redirected to the summary of projects, which you can select one you just created and add your first Raspberry Pi.

Add a device and download OS

SPEKTRA Edge builds a custom SPEKTRA Edge OS image configured for the Raspberry Pi device, which allows it to be provisioned for SPEKTRA Edge platform in the later stage.

Start by clicking Add device on the project overview and select Download bootable OS with default configuration option under the register devices section.

Select the Raspberry Pi device type with the supported OS version. Click Download once you give the root login password.

Device provisioning

Now, let’s flash the downloaded SPEKTRA Edge OS image to the device.

Here are the steps to follow to flash the OS image and boot the device:

• SD card
• On-board eMMC

Once it’s connected to the network, the new device should be shown as online and you should be able to develop application on it.

Let’s check the device serial number and other device information to double check if it’s the correct device. Click the name of the device to go to the Device overview page.

Here, you can check the device information including:

• Device status
• Device type
• OS version
• Device serial number
• IP addresses

Now, let’s set the device name for easy reference. Select the Edit details option of the Device overview pull-down menu shown by hovering over the vertical triple dots right next to the Device overview page title.

Let’s deploy your first application on this device.

Deploy your application

Now the device is ready, let’s deploy a Nginx application on your device.

SPEKTRA Edge provides the docker compose environment on your device so that the applications can be declared and deployed through the standard docker compose file format.

First, click the Deploy pod on the project overview page.

Select Deploy on a single device option and provide the following information:

1. Application name
2. Application description
3. Docker compose file

   services:
     app:
       image: nginx:latest
       ports:
       - 8080:80

4. Target device to deploy

Then, click Deploy to deploy your first application.

Congratulations. You just deployed the first application on your device through SPEKTRA Edge!

Verify your application

Now check the application through the applications overview page.

Here, you can see the application you just deployed successfully running on your device.

Click the application name on the page above and scroll down to the Logs section of the application detail page to check the application logs by clicking the Start button.

Here you can see your application successfully running on your device.

Accessing your application

You can access your application from your local machine with the SPEKTRA Edge port-forwarding feature.

Go to the application page and copy the port-forward command located under the Docker compose section.

Open the terminal on your local machine. Paste the command you just copied onto your terminal and run it to enable the port-forwarding to access your application from the local machine.

Here is the example port-forward command for your reference. It enables your application, which is listening on device’s port 8080, reachable through your local machine’s port 8080.

cuttle devices forward-port \
  projects/your-project/regions/us-west2/devices/raspberry-pi-5 \
  8080 tcp://127.0.0.1:8080

With the above port-forwarding command running, point your browser to http://localhost:8080 to access your application from your local machine.

Next steps

Great job! You successfully deployed and verified your first application running on your device with SPEKTRA Edge.

You got there without needing to know how the platform works underneath — but that understanding is what turns this into a fleet of 1,000 devices rather than one. How SPEKTRA Edge works explains what you just did: why you targeted a device instead of logging into it, and what the platform was doing on your behalf while you clicked.

From there, go deeper on whichever part you need:

• Develop an application — build and publish your own image, instead of deploying a public one.
• Deploy an application — the full deployment flow, including configuration and private registries.
• Monitor & control — status, metrics, and logs for a running application.

2 - How SPEKTRA Edge works

SPEKTRA Edge runs containerized applications on fleets of edge devices — hardware sitting in shops, factories, vehicles, or offices, far from a data centre and often on unreliable networks.

You do not administer those devices one at a time. You describe what a device should look like and what should run on it, and the platform makes it so, whether you have one device or ten thousand.

This page gives you the mental model behind that. If you have been through Get started, it explains what was actually happening while you clicked; if you have not, nothing here depends on it.

The shape of the system

There are three sides to it: the tools you work with, the platform itself, and your devices out in the field.

flowchart LR
    %% --- What you use ---
    subgraph YOU["You"]
        DASH["Dashboard"]
        CLI["cuttle CLI"]
        API["Your own code<br/>(gRPC / REST)"]
    end

    %% --- The platform ---
    subgraph PLATFORM["SPEKTRA Edge platform"]
        SVC["Core services<br/>identity, devices, applications,<br/>monitoring, logging, limits"]
    end

    %% --- The edge ---
    subgraph EDGE["Your devices"]
        D1["Device<br/>droplet + pods"]
        D2["Device<br/>droplet + pods"]
    end

    DASH --> SVC
    CLI --> SVC
    API --> SVC
    SVC <-->|"desired state down,<br/>status, metrics, logs up"| D1
    SVC <-->|"desired state down,<br/>status, metrics, logs up"| D2

Everything the dashboard shows you, it reads through the platform API. The cuttle CLI uses that same API, and so can your own code — see Integrate. That means most of what you do in the dashboard can be scripted and automated.

The objects you work with

Four things account for most of what you will do.

flowchart TD
    P["Project<br/><i>your fleet, pinned to a region</i>"]
    D["Device<br/><i>one piece of hardware</i>"]
    A["Distribution<br/><i>an application and where it should run</i>"]
    PO["Pod<br/><i>a running container on a device</i>"]

    P --> D
    P --> A
    A -->|"scheduled onto<br/>matching devices"| PO
    D -->|"hosts"| PO

• A project is your fleet. It groups devices, applications, and the people who can touch them, and you pick the region it lives in when you create it.
• A device is one piece of hardware running SPEKTRA Edge OS, or your own Linux machine with the agent installed.
• A distribution is an application plus a rule for where it should run. You target devices by label rather than by name, so growing the fleet does not mean editing deployment lists.
• A pod is the actual running container on a device. The droplet runtime on each device starts pods, keeps them running, and reports back.

Devices pull their configuration, they are not pushed to

This is the part that most often surprises people coming from conventional server management.

You never “run a command on a device” in the normal course of operating a fleet. Instead you record the state you want on the platform, and each device continuously pulls that state and makes itself match. A device that was offline when you made a change picks it up when it reconnects; no retry queue, no partial rollout to reconcile by hand.

Two practical consequences:

• Changes are durable. A device that reboots, or gets replaced, comes back to the state you described.
• Editing a device by hand does not stick. Changes to the read-only system image are lost on reboot. See how persistence works.

What the platform gives you

You get these as part of the platform, rather than assembling them yourself.

Each one has a full API reference under Service APIs. You will also see these names in audit entries, in IAM role definitions, and in cuttle commands.

Regions

The platform runs in multiple regions, and a project belongs to one of them. Pick the region closest to your devices when you create a project: it is the region your devices talk to, so proximity matters for latency and for how quickly a device picks up a change.

Next steps

• Applications — build an image, deploy it, configure it, and watch it run.
• Devices — set up hardware and operate it.
• Build a service — if you want to publish your own service on the platform rather than consume it.

2.1 - Shared responsibility

SPEKTRA Edge runs your containers on your hardware. That splits ownership in a way that is obvious once stated and a frequent source of surprise until then: the platform is responsible for getting your workload running and keeping the device healthy, and you are responsible for what is inside the workload.

This page draws the line. Most questions of the form “does SPEKTRA Edge handle X for me?” are answered by finding X in one of the two columns below.

The division

What this means in practice

A few consequences come up often enough to state directly.

Deploying a third-party workload does not normally require anything from us. If the software ships as a container and expects a normal Linux environment, you package it, point a distribution at some labelled devices, and bind-mount its data directory. Platform changes only become necessary when a workload needs something the platform does not expose — unusual hardware, a kernel module, a privileged network mode, or a lifecycle the container model does not cover. If you are unsure, the question to ask is whether the workload needs anything outside its container.

Nothing about your application’s traffic is automatic. The platform’s own connection is encrypted and, where configured, proxied. Your application’s connections are not: they do not inherit the device proxy settings, they are not encrypted on your behalf, and the platform does not terminate TLS for them.

The TPM is not a general-purpose key store for your application. The device TPM is used for device identity and to seal the disk-encryption key, releasing it only when the boot state is as expected. An application that wants to generate or hold its own keys in the TPM has to talk to the TPM itself and speak the relevant protocol. The platform neither manages those keys nor mediates that access. See TPM attestation.

File permissions behave exactly as they would anywhere else. The platform adds no special handling. If the image runs as a non-root UID and the bind-mounted host directory is owned by root, the container cannot write to it — the same as on any Docker host. See Storage.

Related

• How SPEKTRA Edge works — the mental model this page divides up.
• Applications — building and deploying the part you own.
• Devices — operating the part we manage with you.

3 - Applications

An application on SPEKTRA Edge is a container, described with a standard Docker Compose file and deployed to devices you select by label. The device’s droplet runtime pulls the image, starts the containers, and keeps them running.

This section follows one application from source code to a running, observable workload. If you have not deployed anything yet, Get started does a shorter version of the same journey end to end.

In this section

1. Develop

   Write the application, build a container image, and push it to a registry.

2. Deploy

   Describe the application in a compose.yaml file and deploy it to a device from the dashboard.

3. Configuration

   Supply configuration to a running application with config maps and volumes, so the same image behaves differently in different places.

4. Private registry

   Pull images from Amazon ECR, Azure Container Registry, Google Artifact Registry, or any registry that needs credentials.

5. Multiple devices

   Label your devices and deploy to all of them at once, instead of one at a time.

6. Access applications

   Reach a running application — from your workstation, from the device’s local network, or from another container.

7. Monitor & control

   Watch status, metrics, and logs, and restart or edit a deployment.

What you need

Everything in this section assumes:

• access to the SPEKTRA Edge dashboard
• a project with at least one provisioned device — see Get started
• Docker Compose locally, to verify before you deploy

The cuttle CLI is needed only for reaching a deployed application from your own machine; you do not need it to deploy.

3.1 - Develop an application

This page describes how to develop applications for the SPEKTRA Edge platform.

SPEKTRA Edge utilizes the Docker containers to package and deploy applications for your devices. We follow the standard docker build process for creating applications so that you can benefit from the knowledge and experience you may already have through the prior application development process. Once the image is built, you publish it to one of the container registries to make devices to retrieve and run it on the device.

What you need

To build and publish the application image to the registry, you need:

1. Docker Engine on your local machine
2. access to the container registry

Follow the Docker installation guide to install Docker Engine on your machine. For the container registry access, please consult your container registry documentation, e.g. Docker Hub quickstart guide.

Dockerfile

SPEKTRA Edge application development starts with a Dockerfile.

Here is a quote from the official Docker documentation:

Docker builds images by reading the instructions from a Dockerfile. A Dockerfile is a text file containing instructions for building your source code. The Dockerfile instruction syntax is defined by the specification reference in the Dockerfile reference.

Those are the typical instructions used in Dockerfile:

• FROM <image>

  initializes a new build stage and sets the base image for subsequent instructions.

• RUN <command>

  executes any commands to create a new layer on top of the current image.

• WORKDIR <directory>

  sets the working directory for any RUN, CMD, ENTRYPOINT, COPY, and ADD instructions that follow it in the Dockerfile.

• COPY <src> <dest>

  copies new files or directories from <src> and adds them to the filesystem of the image at the path <dest>.

• CMD <command>

  sets the command to be executed when running a container from an image.

Python Flask application example

Let’s take a look at the example Dockerfile, which builds the simple Python Flask application:

# syntax=docker/dockerfile:1
FROM ubuntu:22.04

# Prepare the python environment on the image.
RUN apt-get update && apt-get install -y python3 python3-pip
RUN pip install flask==3.0.*

# Copy the Flask app to the image.
COPY hello.py /

# Run the Flask app.
ENV FLASK_APP=hello
EXPOSE 8000
CMD ["flask", "run", "--host", "0.0.0.0", "--port", "8000"]

with the following hello.py file:

from flask import Flask
app = Flask(__name__)

@app.route("/")
def hello():
  return "Hello World!"

Place those two files on your current directory.

$ tree .
.
├── Dockerfile
└── hello.py

1 directory, 2 files

then, run the following command to build your application image.

docker build --tag test:latest .

You can give any tag name here, for example awesome:v1.0.0, but pick the one you can remember, as you will reference it when you push it to the container registry.

Now, your application image is ready. Let’s publish it to the container registry next.

Push to registry

Repositories let you share container images to be downloaded by the devices.

In this section, we’ll use the Docker Hub as the container registry, as it’s free and publicly accessible. Please consult your container registry documentation in case you use other one.

You can create a free account on Docker Hub. Please follow the Docker Hub quickstart guide to create one if you haven’t created.

Here is the simple step to publish your application to the Docker Hub:

1. Login to the Docker Hub:

   docker login
   

2. Re-tag the image you build in the previous step to point to the Docker Hub repository you own:

   docker tag test:latest <hub-user>/<repo-name>:<tag>
   

3. Push the image to the registry:

   docker push <hub-user>/<repo-name>:<tag>
   

Please consult the official Docker documentation if you get error with those commands.

Next steps

Once you develop your application and publish it to the registry, it’s time to deploy it on your device. Please move on to the deployment document next.

3.2 - Deploy an application

Once you have developed and published your application image to a container registry, it is time to deploy it to your device.

SPEKTRA Edge provides the Docker compose environment on your device so that you can declare your application in the standard Docker compose file format to run it on your device.

Let’s create a compose.yaml file for the application we developed in the previous section and deploy it on your device through the SPEKTRA Edge dashboard.

What you need

To deploy your application on your device, you need:

• the Docker Compose environment on your local machine, for local verification
• access to the SPEKTRA Edge dashboard
• a device provisioned through the SPEKTRA Edge dashboard

And also, the cuttle CLI command is necessary to complete this tutorial, which is used to access the application from the local machine for the verification purpose. However, it is not required for deploying applications on SPEKTRA Edge.

Local verification

Let’s create and verify compose.yaml file on your local machine.

compose.yaml

Here is the compose.yaml file to deploy the application we developed in the previous section.

services:
  app:
    image: spektraedge/awesome:latest
    ports:
    - 8000:8000

Let’s go over the file line-by-line.

• services

  This is the top level element of the compose file to abstract the definition of a computing resource within an application which can be scaled or replaced independently from other components.

  You can take a look at the official documentation for more detail.

• app

  This is the name of the service, which represents the service definition. We name it app here but it’s free to use different names.

• image

  image specifies the image to start the container from. image must follow the Open Container Specification, as

  [<registry>/][<project>/]<image>[:<tag>|@<digest>].

• ports

  The ports is used to define the port mappings between the host machine and the containers. This is crucial for allowing external access to service running inside containers.

  This example exposes the container application’s port 8000 to be accessible through the local machine’s port 8000.

  Please take a look at the official document for the ports attribute definition.

SPEKTRA Edge compose conventions

Your compose file runs on the device through a managed pod driver, which behaves slightly differently from a plain docker compose up in your project folder. Keep these two conventions in mind when authoring compose.yaml.

• Use absolute host paths for bind mounts. The driver stores each pod’s compose file in its own state directory on the device and runs docker compose from there, so a relative bind-mount source is resolved against that internal directory — not a project folder you control. Docker then auto-creates the missing path there and the agent logs a repeating failed to read compose file ...: is a directory error. Use an absolute host path on a persistent filesystem instead. On SPEKTRA Edge OS that is /isodevice/data, which survives power cycles and OS upgrades (on a .deb install, use an absolute path on your host’s own persistent storage). Better still, mount configuration through a configuration map and host volume:

  services:
  app:
    volumes:
      # Avoid — relative source resolves inside the driver's state directory:
      # - ./config:/etc/app/config
      #
      # Prefer — an absolute path on the persistent data partition:
      - /isodevice/data/myapp/config:/etc/app/config

• Do not set container_name. The driver tracks and reconciles containers using its own naming convention (derived from the pod name). A custom container_name no longer matches that convention, so the agent treats the container as potentially unmanaged and falls back to re-scanning manifests to re-associate it. Omit container_name and let the driver assign names.

docker compose up

With the compose.yaml file ready on your local machine, run docker compose up command in the directory where the file locates:

$ tree .
.
└── compose.yaml

1 directory, 1 file

$ docker compose up
[+] Running 2/0
 ✔ Network sample_default  Created                                        0.0s
 ✔ Container sample-app-1  Created                                        0.0s
Attaching to app-1
app-1  |  * Serving Flask app 'hello'
app-1  |  * Debug mode: off
app-1  | WARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead.
app-1  |  * Running on all addresses (0.0.0.0)
app-1  |  * Running on http://127.0.0.1:8000
app-1  |  * Running on http://172.20.0.2:8000
app-1  | Press CTRL+C to quit

Here you can see the application running and listening on the port 8000 on your local machine.

Point your browser to http://localhost:8000 to verify your application.

Deploy to your device

With the compose.yaml ready, let’s deploy your application on your device through the SPEKTRA Edge dashboard.

Go to the project overview page and click Deploy pod.

Select Deploy on a single device option and provide the following information.

1. Application name
2. Application description
3. Docker compose, compose.yaml file for your reference
4. Target device to deploy

Then, click Deploy to deploy your application.

Congratulations!

You now deployed your application on your device through the SPEKTRA Edge dashboard.

Verify your application

You can verify your application’s health from the SPEKTRA Edge dashboard.

The application page provides the following statistics:

• Application’s overall status
• Each container’s status
• Each container’s CPU utilization
• Each container’s memory utilization
• Application’s logs

You can also restart the application by clicking the Restart option of the drop down menu right next to the application’s name:

The same thing from your terminal:

cuttle applications restart \
  projects/your-project/regions/us-west2/pods/nginx

Naming a service after the pod restarts only that container, and cuttle applications pods start|stop|restart gives you the other two actions.

Or you can edit the applications, e.g. compose.yaml, by clicking the Edit option of the drop down menu right next to the application’s name:

Now, let’s access your application from your local machine by utilizing the SPEKTRA Edge port-forwarding feature. Simply copy the cuttle command provided by the dashboard located under the Docker compose section:

Open the terminal on your local machine. Paste the command you just copied onto your terminal and run it to enable the port-forwarding to access your application from the local machine.

Here is the example port-forward command for your reference. It enables your application, which is listening on device’s port 8000, reachable through your local machine’s port 8000.

cuttle devices forward-port \
  projects/your-project/regions/us-west2/devices/raspberry-pi-5 \
  8000 tcp://127.0.0.1:8000

With the above port-forwarding command running, point your browser to http://localhost:8000 to access your application from your local machine.

You will get the same result you got during the local verification.

Next steps

With the application running on your device, learn how to supply it with configuration, so the same image can behave differently in different places.

3.3 - Configure applications via configuration maps

Let’s learn how to configure applications via configuration maps on SPEKTRA Edge.

A configuration map allows you to decouple environment-specific configuration from your application images, so that your applications are easily portable.

You can map the application configuration to the particular containers under the application with the following steps:

1. Create a configuration map
2. Create an application with docker compose volumes service attribute to describe the configuration to be mounted on the container through the following two levels of indirection:
   1. Configuration map volume to map the configuration map to the application
   2. Host volume to mount the configuration to the host environment so that the application can mount the configuration to the particular container.

We’ll use the Nginx application and source the configuration file through the configuration map to demonstrate how to use the configuration map on SPEKTRA Edge.

What you need

To go through this page, you need the following.

• access to the SPEKTRA Edge dashboard
• an active project
• a device provisioned under the project

And also, the cuttle CLI command is necessary to complete this tutorial, which is used to access the Nginx application from the local machine for the verification purpose. However, it is not required for deploying applications on SPEKTRA Edge.

Application files

compose.yaml

It’s a simple Nginx application with mapping the port 8000 with the configuration directory mounted through the volumes attributes.

services:
  app:
    image: nginx:alpine
    ports:
    - 8000:8000
    volumes:
    - /isodevice/data/nginx/conf.d:/etc/nginx/conf.d

nginx.conf

Here is the Nginx configuration file, which will be mapped to the application through the SPEKTRA Edge configuration map.

It’s a simple configuration file, which make it listen on the port 8000, instead of port 80. Since we override the default configuration, we also sets the content root to the default Nginx content directory with root directive.

server {
  listen 8000;
  root /usr/share/nginx/html;
}

Deploy the application

Let’s deploy the application with the configuration map on SPEKTRA Edge.

Here are the steps to follow:

1. Create a configuration map
2. Create the application with two new resources:
   • the configuration map volume to map the configuration map created above to the application
   • the host volume to mount the configuration to the host environment for the load balancer container to mount the configuration file to.

Let’s do it.

Create a configuration map

Let’s create a configuration map to store the Nginx configuration file on SPEKTRA Edge.

First, select the Config maps option of the Applications pull-down menu.

Then, create a configuration map by pasting the nginx.conf file content in the data key value field with the default.conf as the data key name.

Make sure you set:

• nginx-conf as the configuration map name
• default.conf as the configuration data key name

Those names are important because it’s referenced by the other object in the later steps.

Create the application

With the Nginx configuration map ready, let’s deploy the application.

Here is what we’ll do:

1. Paste the docker compose file content to the Docker Compose field
2. Create a volume config map for the Nginx configuration file mapping
3. Create a host volume to mount the above configuration map to the device

We’ll go over those points step-by-step below but first, let’s have a Deploy pod page ready by clicking the Deploy pod button on the Project overview page.

Docker compose file

Let’s paste the docker compose file to the Docker Compose field of the Deploy pod page.

Volume configuration map

The next is the volume configuration map, which maps the Nginx configuration file we created before to the application as a volume.

Here is the key points to highlight:

• Select the correct configuration map
  • projects/your-project/regions/us-west2/configMaps/nginx-conf for this example
• Specify the correct select key of the configuration map item
  • default.conf in this example, as we specified as the key value name for the Nginx configuration file when we created the configuration map.
• Use default.conf for the path name of the select key
  • This is the file name which will be shown in the container. Nginx expects this file name as the default Nginx configuration file.

Host volume

This is the last item to configure on the Deploy pod page.

It mounts the volume configuration map we create above to the host environment of the device. This file will be mounted to the Nginx load-balancer container through the docker compose file we explained before.

Again, there are a couple of things to make it right.

• the volume name should match the name of the volume configuration map we created above
  • nginx-conf in this example
• the Volume mount path should be matched to the one specified in the docker compose
  • /isodevice/data/nginx/conf.d in this example

Click to deploy

With all those configuration set, click the Deploy button on the Deploy pod page to deploy the application on your device.

With a minute or so, you should be able to see the application running on your device, as below.

Verify the application

Let’s verify the application by accessing it through the port forwarding.

Go to the application overview page by clicking the name of the app, Three tier web app in this example, on the Project overview page.

From there, copy the port forward command by clicking the Copy port forward as Cuttle command button on the application overview page.

Run the command on your local terminal window to make your application accessible from your browser.

cuttle devices forward-port \
  projects/your-project/regions/us-west2/devices/pp-quick-202410-dmphwxuzhh8nyw \
  8000 tcp://127.0.0.1:8000

Please note that the device name above will be different for your case.

Point your browser to http://localhost:8000 and you should be able to see the page below.

Next steps

Congratulations on configuring the Nginx application with the configuration map on SPEKTRA Edge.

If your image lives somewhere that needs credentials, continue with private registry.

3.4 - Deploy with private container registries

Let’s learn how to deploy applications from the private container registries.

SPEKTRA Edge supports private container registries, such as Amazon Elastic Container Registry, Azure Container Registry, or Google Artifact Registry, as the application container registries.

In this document, we’ll learn how to configure the application on SPEKTRA Edge to run the container image hosted on the Azure container registry, a private container registry offered by Microsoft Azure.

What you need

Please have those ready before proceeding:

• Docker Engine and Azure CLI on your local machine
• access to the SPEKTRA Edge dashboard
• a device provisioned under your project on SPEKTRA Edge
• access to Azure portal and Azure Container Registry

Push to private registries

We’ll first publish the application image to the Azure container registry.

We’ll use the same application we developed in the develop section. Here is the Dockerfile and hello.py files for your reference.

# syntax=docker/dockerfile:1
FROM ubuntu:22.04

# Prepare the python environment on the image.
RUN apt-get update && apt-get install -y python3 python3-pip
RUN pip install flask==3.0.*

# Copy the Flask app to the image.
COPY hello.py /

# Run the Flask app.
ENV FLASK_APP=hello
EXPOSE 8000
CMD ["flask", "run", "--host", "0.0.0.0", "--port", "8000"]

from flask import Flask
app = Flask(__name__)

@app.route("/")
def hello():
  return "Hello World!"

Copy those two files and place those under the directory like below.

$ tree .
.
├── Dockerfile
└── hello.py

1 directory, 2 files

Under that directory, run the following docker build command to create the application image tagged with the Azure container registry and repository name for the publication in the following step.

docker build --tag spektraedge.azurecr.io/awesome .

Publish the image to the Azure container registry with docker push command.

docker push spektraedge.azurecr.io/awesome:latest

Once it’s pushed, go to the Azure portal and double check if the application image correctly published on Azure container registry.

Now, you’re ready to configure the application to pull the image from the Azure container registry. But before that, let’s talk about the image secrets next.

Image secrets

The image secrets is a special secret resource maintained by the SPEKTRA Edge platform. It’s meant to be used for storing the credentials to access the private container registries. Hence, we’ll configure the image secrets next before configuring the applications.

Let’s create one here.

Go to the Secrets page by selecting the Secrets from the Applications pull-down option from the left navigation menu.

1. Secret display name
2. Secret data key name
3. Secret data key value

Secret display name

This is a case-insensitive alpha-numeric secret name referenced later by the application configuration. Give it a descriptive name for the better secret management.

Secret data key name

This field should be .dockerconfigjson. This follows the Kubernetes convention.

Secret data key value

This field contains the base64 encoded private registry credential with the following JSON format.

{
  "auths": {
    "$REGISTRY_URL": {
      "username":"$USERNAME",
      "password":"$PASSWORD"
    }
  }
}

In case of the Azure container registry, you can generate the above JSON string by the following shell script with Azure CLI

echo \
  {\"auths\":\
    {\"$(az acr show --name $REGISTRY_NAME --query loginServer --output tsv)\":\
      {\"username\":\"$(az acr credential show --name $REGISTRY_NAME --query username --output tsv)\",\
       \"password\":\"$(az acr credential show --name $REGISTRY_NAME --query passwords[0].value --output tsv)\"\
      }\
    }\
  }

where you set $REGISTRY_NAME environment variable to your Azure container registry name, e.g. spektraedge in this example.

Convert to base64

Once you have those three values ready, you paste those in the respective fields and click Convert to Base64 button of the Add secret page.

Create the image secret

Click Create to create the image secret for the Azure container registry.

Deploy the application

For the application deployment, we’ll follow the standard application deployment explained in the previous section except one field, the image secrets.

On the Deploy pod page, select the image secret you created in the previous step and just click Deploy as usual.

Next steps

Congratulations on mastering the deployment with the private container registry on SPEKTRA Edge!

So far you have deployed to one device at a time. Next, learn how to deploy to multiple devices at once.

3.5 - Deploy to multiple devices

Let’s learn how to deploy the application on multiple devices on SPEKTRA Edge.

There are two steps for this process to work:

1. Set a device label to the target devices
2. Create a pod template with selecting the label above as the target device label

With that, let’s get to work.

What you need

To deploy applications on multiple devices on SPEKTRA Edge, you need:

• access to the SPEKTRA Edge dashboard
• devices provisioned under your project on SPEKTRA Edge

Set device labels

Let’s set the device label on multiple devices to group those together as the deployment target.

Open the Update device details page of the Device overview page by selecting the Edit details option of the Device menu.

Set the device label, task:multi-devices in this example, on the Update device detail page as a label to group multiple devices together.

Please do the same for other devices as well before moving on to the deployment step next.

Deploy with pod templates

Once you set the device labels on your target devices, now is the time to deploy applications on all those devices in one-shot with a pod template.

The pod template is a template to apply application deployment against multiple devices, similar to the template field of the deployments manifest in Kubernetes.

Let’s create one to see it in action. We’ll use the same application we used for the single device deployment to demonstrate how easy and similar deploying applications on multiple devices.

Go to the Project overview page and click Deploy pod button.

Use the Pod template option in Deploy pod page this time and select the target devices by providing the device label, task:multi-devices in this example, in the Target device labels to deploy field, in addition to the other application information similar to one for the single device deployment.

Click Deploy to deploy it on multiple devices.

Once it’s done, you should be able to see applications all running on the target devices, five devices in this example, from the Project overview page.

Next steps

Congratulations on successfully deploying the application on multiple devices in a single-shot on SPEKTRA Edge.

Next, learn how to access a running application from your own machine to check it is behaving.

3.6 - Access your deployed application

Let’s learn the ways to reach an application running on your device with SPEKTRA Edge.

Once you deploy an application, its containers run on the device and publish ports according to your Docker compose file. How you reach those ports depends on where you are relative to the device. This page covers the three common cases:

1. From your workstation, anywhere — through the platform’s secure port forwarding (no inbound ports open on the device).
2. From the device’s local network — directly to a published port.
3. From another container — service-to-service inside the same application.

services:
  app:
    image: nginx:alpine
    ports:
    - 8000:8000

From your workstation (port forwarding)

This is the recommended way to reach an application on a remote device. It works from anywhere, over the device’s existing outbound connection to the platform, so no inbound ports need to be open on the device or its network.

You need the cuttle CLI installed for this method.

1. Open the application’s Application overview page in the dashboard (see Monitor & control).
2. Click Copy port forward as Cuttle command to copy a ready-made command.
3. Run it in your local terminal. For example:

cuttle devices forward-port \
  projects/your-project/regions/us-west2/devices/your-device \
  8000 tcp://127.0.0.1:8000

This forwards the device’s port 8000 to 127.0.0.1:8000 on your machine. Point your browser at http://localhost:8000 and you’ll reach the application as if it were running locally.

The first argument is the full device name (it includes the project and region); the dashboard fills this in for you when you copy the command.

From the device’s local network

If your client (a browser, another machine, a PLC, etc.) is on the same local network as the device, you can reach a published port directly using the device’s IP address:

http://<device-ip>:<published-port>

For the Nginx example above, that would be http://<device-ip>:8000.

This is the natural choice when the application is meant to serve other equipment on-site — for example, a local dashboard, an API consumed by nearby machines, or a gateway service.

A few things to keep in mind:

• The port must be published in the compose file (the ports entry). A container port that isn’t published is only reachable from inside the device.
• By default a published port is reachable on all of the device’s network interfaces. If you only want it on a specific interface, bind it explicitly in the compose file, for example 127.0.0.1:8000:8000 to keep it on the device itself.
• Make sure the chosen host port doesn’t collide with another application or a system service on the device.

From another container

Containers within the same application can talk to each other over the application’s internal network using their service name as the hostname — they don’t need to publish ports for this. For example, an app service can reach a redis service at redis:6379.

Only publish a port (with ports) when something outside the application needs to reach the container. Internal service-to-service traffic should stay on the internal network.

Persisting data behind your application

If your application stores data (uploads, a database, configuration), mount it under the device’s persistent data area so it survives restarts and power cycles:

services:
  app:
    image: nginx:alpine
    ports:
    - 8000:8000
    volumes:
    - /isodevice/data/nginx/conf.d:/etc/nginx/conf.d

See Configuration for a full walk-through of mounting configuration and host volumes.

Which method should I use?

Next steps

Learn how to monitor and control your application — view its status, metrics, and logs — from the SPEKTRA Edge dashboard.

3.7 - Monitor and control applications

Let’s learn how to monitor and control applications on SPEKTRA Edge.

What you need

To go through this page, you need the following.

• access to the SPEKTRA Edge dashboard
• an active project
• a device provisioned under the project
• an application running on the device
• the cuttle CLI installed locally, to use port forwarding

With these, let’s dive in managing applications on SPEKTRA Edge.

Application overview

Application overview page is the main dashboard to manage applications on SPEKTRA Edge.

To get there from the Project overview page, click the Manage pods button located in the Pods section of the Project overview page.

Click the name of the application you want to manage, counter in this example, to get to the Application overview page of the application.

Here on the Application overview page, you can do the majority of the tasks to manage applications, such as:

• observing the application’s status
• checking the application’s Docker compose file content
• monitoring the application’s resource usages, such as CPU and memory
• examining the application’s logs
• controlling your application

It also offers the cuttle port forward command, which you can copy and run on your local machine to access your application through the SPEKTRA Edge port forwarding capability.

Application statuses

Here is the list of application statuses monitored on SPEKTRA Edge.

Container states

Here is the list of Container’s state, which is the composition of the application status explained above. The Containers section of the Application overview page shows the container states.

Application metrics

You can monitor the container’s resource usage on the dashboard.

Go to the Containers usage section of the Application overview page and select the type of resource you want to monitor. Click the right side of the time range section to specify the duration of the time-series to be shown on the graph.

Application logs

You can retrieve each container’s logs on the dashboard.

Specify the name of the container you want to show the logs by clicking the pull down menu of the Logs section on the Application overview page.

Click Start to retrieve the live logs of the container.

You can also download the logs by clicking the Download icon on the Logs menu bar.

Control applications

You can control applications from the dashboard.

Here is the list of operations you can perform:

• delete
• restart

Click the vertical three-dots right next to the application’s name in the Application overview page to show the pull-down menu and select the operation you want to perform.

Next steps

That completes the application lifecycle: you can build an image, deploy it, configure it, reach it, and watch it run.

Next, turn to the hardware underneath. Devices covers setting up and operating the machines your applications run on.

4 - Devices & SPEKTRA Edge OS

SPEKTRA Edge OS is the operating system that runs on your edge devices. It is purpose-built for unattended, remotely managed fleets: it boots into a known, read-only system, keeps your configuration and data on dedicated persistent storage, and reconciles its settings from the SPEKTRA Edge platform so you can manage thousands of devices the same way you manage one.

This guide explains how the OS is structured and how to configure it so that you can set up and operate your own devices. Most settings are applied from the SPEKTRA Edge dashboard (or through the API); a few are chosen when you create the install image.

What you need

To follow this guide, you need the following.

• access to the SPEKTRA Edge dashboard
• an active project
• a device (or hardware you intend to provision) under the project

In this section

The guide is grouped by what you are trying to accomplish.

• Overview — how the OS is laid out, how persistence works (what survives a reboot and what survives an upgrade), and which hardware platforms are supported.
• Device setup & provisioning — take hardware from blank to managed: create an install image, onboard the device, set the administrator password, and confirm the device is online.
• Provisioning policies — the reusable template that decides what a device becomes when it first connects.
• Zero-touch provisioning — onboard hardware that nobody technical ever touches, including registration sessions and hardware replacement.
• Install the droplet agent (.deb package) — bring an existing Debian or Ubuntu machine under management without the full OS image.
• Storage — the default disk layout, and how to add your own partitions and mounts or expand to the full disk.
• Networking — wired, Wi-Fi, and cellular connectivity, uplink fallback, proxies, ports, and time synchronization.
• Security — disk encryption, device attestation, Secure Boot, SSH access, the administrator account, USB control, and remote access.
• Operations — OS upgrades and rollback, reboot and recovery, logging, health checks, status indicators, hooks, workloads, and file transfer.
• Troubleshooting — playbooks for the failures you are most likely to hit, with causes in the order worth checking.

Related

• cuttle CLI — drive everything described here from the command line instead of the dashboard.

4.1 - Overview

This section explains the ideas you need before configuring a device: how the OS is structured, how persistence works, and which platforms are supported.

A managed, reconciled operating system

SPEKTRA Edge OS is designed to be operated remotely and at scale. Instead of logging into each device to make changes by hand, you describe the desired state of a device on the SPEKTRA Edge platform, and the device continuously reconciles itself to match. This is the same model whether you manage one device or thousands.

Two consequences are worth keeping in mind from the start:

• The system runs from a read-only image. The core operating system is not meant to be modified in place. This keeps every device in a known, consistent state and makes upgrades and rollback reliable.
• Your configuration and data live on separate, persistent storage. Anything you need to keep across reboots is stored outside the system image.

How persistence works

Understanding what persists is the single most useful thing to know about the OS, because it explains why some changes “disappear” and others stick.

There are three kinds of storage on a device:

The practical rules that follow:

• Ad-hoc changes to the live system do not persist. If you log into a device and edit a file that belongs to the system image, your change is gone after the next reboot. This is intentional.
• To make a durable change, use the configuration mechanisms described in this guide — the dashboard/API for most settings, and files in the configuration area for the rest.
• Upgrades and rollback are safe by design. Because the system image is swapped as a unit while your configuration and data are preserved, you can move between OS versions without losing your setup. See OS upgrades.

Settings supplied as files

Most configuration reaches a device through the dashboard or the API. A few things are instead provided as files in /isodevice/config, which is why they survive both reboots and upgrades.

File-based configuration exists for the cases the dashboard does not cover, such as hooks, and for baking defaults into an image. For anything the dashboard or API can set, prefer that route so the configuration is centrally tracked. When disk encryption is enabled, these files are protected at rest.

Supported platforms

SPEKTRA Edge OS is built for the hardware families below. When you create an image or register hardware, the platform identifies the target by its device type, which combines the hardware family with the CPU architecture.

The device type determines which OS images are compatible with a given device. You select it when creating an install image and when pinning an OS version.

Which device types are actually offered is a property of your SPEKTRA Edge deployment, not a fixed list, so treat the dashboard as authoritative. To see the catalog from the command line:

cuttle devices list device-types -o json

Related

• Device setup & provisioning — the choices embedded in an install image, which become a device’s starting configuration.
• Storage — the default disk layout, and adding your own partitions and mounts.

Next steps

Continue with device setup & provisioning to bring hardware online, or jump to the area you need from the guide overview.

4.2 - Device setup & provisioning

This section takes a device from blank hardware to a managed device: creating an install image, onboarding the device so it joins your project, setting the administrator password, and confirming it is online.

Setup at a glance

1. Create an install image for the target device type, with the defaults you want baked in (encryption, network, storage, time).
2. Write the image to installation media and boot the device from it.
3. Onboard the device so it obtains an identity and joins your project.
4. Set the administrator password for local and console access.
5. Verify the device is online on the dashboard.

The rest of this page covers each step.

Create an install image

You create install images from the SPEKTRA Edge dashboard. An image carries the OS itself plus a set of defaults, so a device is useful the moment it boots.

Write the image and boot

Write the downloaded image to your installation media, then boot the target hardware from that media. The device boots into SPEKTRA Edge OS, applies the embedded configuration, and begins onboarding.

Onboarding methods

Onboarding is how a device obtains its identity and joins your project. There are three approaches; choose based on how much you want to pre-arrange versus letting devices self-register.

Zero-touch provisioning

With zero-touch provisioning, a device that has never been configured can find the right SPEKTRA Edge deployment, prove its hardware identity, and receive its credentials automatically — no per-device setup required. This is the preferred method for large fleets and for hardware that is shipped directly to a site.

Zero-touch provisioning relies on the device’s hardware security module to establish a trustworthy identity. See TPM & device attestation for how that identity is verified.

Provisioning policy

A provisioning policy lets devices self-register into a project using a shared credential and a template that describes how each new device should be configured. Policies operate in one of two modes:

The policy template carries the desired device configuration (network, SSH, logging, and so on), so every device created through the policy starts from the same baseline.

Pre-registering hardware

You can pre-register specific hardware ahead of time and bind it to a provisioning target. A field technician can then bring the hardware online using a registration token without needing project credentials in hand. This is useful when installation is performed by someone who should not have broad access to the project.

Set the administrator password

Each device has a local administrator account used for console and SSH access. Where its first password comes from depends on how the device was installed:

• Building your own image, as in this guide — you set the password at image creation, so it applies to every device built from that image, or when preparing installation media on a per-device basis. There is no default password to worry about.
• A SPEKTRA Edge appliance, shipped with the OS already installed — the hardware serial number is accepted until you set a password. Set one on first login, because a serial number is not a secret.

The password must be non-empty, and it is stored only as a salted hash on the device’s configuration storage. See User accounts for details and for how to reset a lost password.

Verify the device is online

Once the device boots and onboards, it appears in the dashboard under your project. A device is Online when the platform detects it as connected.

On the device overview page you can confirm:

• connection status (Online / Offline)
• device information — OS version, hardware details, disks, and network interfaces
• reported IP addresses

If a device does not come online, start with the connectivity requirements and the troubleshooting playbooks.

Related

• Device overview — how the OS is laid out, and what survives a reboot or an upgrade.
• Security — disk encryption, attestation, and the administrator account.

Next steps

With the device online, configure it for your use case:

• set up storage
• configure networking
• review and tighten security

4.3 - Provisioning policies

A provisioning policy is the answer to “what should happen when a device I have never seen before connects and claims to belong to me?” It decides whether the device is accepted at all, what it is called, what configuration it starts with, and what it is allowed to do.

It is the most important object in fleet onboarding, because it is the only place where a device’s initial state is defined once and applied to every device that follows. Get it right and adding the four-thousandth device is the same amount of work as the second.

What a policy controls

Acceptance mode

The mode decides what happens at the moment a device presents itself.

Unattended is what makes zero-touch provisioning zero-touch: hardware arrives at a site, is powered on, and joins. It also means anything holding valid credentials for the policy joins, so the credential is the security boundary.

Manual approval is the right choice while you are still establishing trust in a process, or where devices are installed by third parties. The cost is that someone must be watching the queue — devices sit unprovisioned until they are approved, and a forgotten queue looks exactly like a broken deployment to the person on site.

Identity and access

Each policy is associated with a service account, and a device must hold a key for that account to provision itself. This is the credential baked into the install image or delivered during a registration session.

When a device is provisioned it gets its own service account, bound to a role the policy specifies. Left unset, this defaults to the standard device agent role, which is what a normal SPEKTRA Edge OS device needs.

Grant a narrower role if your devices genuinely need less. This is the single most valuable hardening step available in a policy, because a device is a physical object in a place you do not fully control: whatever role you grant here is what an attacker holding the hardware can use.

Policies can also attach conditions to that role binding — an IP condition restricting where the credential works, for instance — which is worth considering when devices sit at known sites.

Naming

Rather than naming devices by hand, a policy provides name templates so that identity is derived from the hardware itself. A device’s name is fixed permanently at creation, so this matters: a name derived from the serial number stays meaningful, while a sequential counter tells you nothing when you are looking at an alert at three in the morning.

The display name is separate and can be changed later. Put the human-friendly, possibly-changing description there — site, position, purpose — and keep the name derived from something immutable.

The device template

The policy carries a template for the device spec, and this is what turns a blank machine into a configured one. Anything you can set on a device you can set here:

• network configuration, including netplan and multi-WAN behavior
• SSH access — authorized keys, allow and deny lists, whether password login is permitted at all
• disk encryption
• USB device control
• health checks
• log forwarding level
• labels, which is how the device becomes targetable by application deployments and alerting policies
• NTP servers

Set labels in the template deliberately. Labels are how you later target application deployments, group alerts, segment queries, and stage OS rollouts — and adding them at provisioning time is far less work than labeling a fleet retrospectively.

Matching known hardware

A policy can specify which hardware identity fields — serial number, for example — should be used to match a connecting device against device records that already exist.

This is what makes pre-registration and hardware replacement work. If you have already created a record for a serial number you expect to receive, the device attaches to that record instead of creating a second one, arriving with the configuration and labels you set in advance.

Without matching configured, a device that is wiped and reinstalled may appear as a new device rather than the one you already know, leaving you with duplicate records for one physical machine.

How many policies

One policy per class of device is the shape that tends to work — where a class is a group that should start life configured the same way.

Reasonable reasons to split: different hardware types, different network environments, different security postures, different sites with different SSH keys. A poor reason is a group you merely want to manage together, which is what labels are for.

Since the template applies only at creation, a policy is also effectively a record of “how devices onboarded in this period were configured”. Creating a new policy rather than heavily editing an existing one keeps that history legible.

Related

• Device setup & provisioning — creating install media and the onboarding paths available.
• Zero-touch provisioning — using a policy to onboard hardware nobody technical ever touches.
• SSH access and disk encryption — the settings the ones to get right in a template.

4.4 - Zero-touch provisioning

Zero-touch provisioning is for the case where the person installing the hardware is not the person who administers it — and may know nothing about SPEKTRA Edge at all. A box arrives at a shop, a warehouse, or a customer site. Someone plugs it in. It joins your fleet, correctly configured, and appears in your dashboard.

The point is not to save the few minutes of configuring a device. It is that configuring devices at all does not scale to hundreds of sites, and every manual step at the far end of a supply chain is a step that will sometimes be done wrong.

How it works

Three things have to line up: the device must know where to connect, it must prove it is entitled to join, and the platform must know what to turn it into.

flowchart TB
    POLICY["<b>Provisioning policy</b><br/>what the device becomes"]
    HW["<b>Hardware record</b><br/>which devices are expected"]
    IMAGE["<b>Install image</b><br/>where to connect, and credentials"]

    DEVICE["Device powered on at site"]
    JOIN["Device joins the fleet<br/><i>named, configured, labelled</i>"]

    POLICY --> JOIN
    HW --> JOIN
    IMAGE --> DEVICE
    DEVICE --> JOIN

The provisioning policy does the configuring. What zero-touch adds is the other two pieces: getting credentials onto hardware without an administrator present, and telling the platform in advance which hardware to expect.

Choosing an approach

These are not exclusive. A common shape is to pre-register the hardware you know about and run a registration session for the rest.

Pre-registering hardware

If you know what is coming — because you ordered it, or your supplier sent a manifest — create the hardware records before the devices arrive. Each records the identifying details of one physical machine: serial number, manufacturer, product, and where relevant the SIM identifiers for a cellular device.

Two things then become true. The device attaches to the record you already created, arriving with the configuration and labels you set in advance instead of as an anonymous new arrival. And hardware that is not on your list is visible as such, which is the difference between a fleet and a collection of things that connected.

For this to work the policy must specify which hardware fields to match on — see matching known hardware.

Running a registration session

When you do not know the serial numbers in advance, someone at the receiving end has to tell you — and a registration session is how they do it without needing an account, training, or access to your project.

You create a session; the platform emails a link; the recipient opens it on a phone, scans the QR code on each device, and submits. The scanned hardware appears in your project, matched to the policy you chose.

Creating a session

A session specifies:

What the recipient does

The recipient needs a phone with a camera and no knowledge of SPEKTRA Edge. They open the link, see the name of the policy and the time window, scan each device’s QR code, review the list, and submit. They can return to the link to see the status of what they registered.

Devices move through states as they come up — scanned, registered, then provisioning, connecting, and provisioned — so the person on site can see whether the thing they installed actually worked, which is the difference between a clean handover and a phone call.

Practical advice

• Keep the window tight. A session open for a week because that is the default is a credential valid for a week. Set it to the day the installation is scheduled.
• One session per site or batch, not one standing session reused all year. It bounds the damage from a leaked link and it tells you which batch a device came from.
• Send it close to the time. A link sitting in an inbox for a fortnight is a link that may be forwarded.
• Check the results yourself. The session records what was registered; compare it against what you expected to receive; do not assume the count matches.

Verifying hardware identity

For higher assurance than a serial number, devices with a TPM can prove their identity cryptographically at provisioning time, so that a device claiming to be a particular machine can be checked rather than believed. See TPM attestation.

This is worth the additional setup where devices are installed by third parties, or where the consequence of an impostor joining the fleet is serious.

Replacing hardware

When a device fails, the replacement should inherit the original’s identity — its name, configuration, labels, and the applications targeted at it — rather than arriving as a new device you have to configure to match.

Hardware replacement does this: the new machine takes over the existing device record, and the deployments and alerting policies that referenced it continue to apply. Because the record persists, its history persists too, which is what lets you notice that one site has replaced three units this year.

The replacement can be registered either by scanning it on site through a session, in the same way as an initial installation, or directly if you have its details.

When devices do not appear

A device that never registers is nearly always one of a small number of causes. In roughly the order worth checking:

1. The policy mode. A policy in the unspecified mode accepts nobody and reports nothing. This looks exactly like a network problem.
2. The approval queue. If the policy requires manual approval, the devices may be waiting, not failing.
3. Connectivity. The device needs outbound access to the platform, possibly through a proxy. See connectivity and ports.
4. Session expiry. A registration link outside its window will not work, and the person on site may not be able to tell you why.
5. Hardware matching. If the device was expected but arrived as a new record, the policy’s identity fields may not cover the field your supplier populated.

See the troubleshooting playbooks for working through a device that is provisioned but not connecting.

Related

• Provisioning policies — what devices become once admitted.
• Device setup & provisioning — creating the install media itself.
• TPM attestation — cryptographic hardware identity.

4.5 - Install the droplet agent (.deb package)

Most fleets run the purpose-built SPEKTRA Edge OS image. If instead you want to bring an existing Debian/Ubuntu Linux under management, you can install the droplet agent from a .deb package. The machine then joins your project and runs managed workloads, while you keep your own operating system.

This page walks you through the whole flow: install the package, create a provisioning policy and a service account, grant the service account a role, download its key, convert the key into a project_config.json, and place that file where the agent reads it.

What you need

• Architecture: x86-64 (amd64) or ARM64 (arm64). These match the supported platforms for the OS image.
• Operating system: a Debian-based Linux (Debian or Ubuntu) with systemd and root/sudo access.
• Package dependency: wireguard (pulled in as a dependency of the package).
• Container runtime: Docker with Docker Compose, used by the default pod driver to run workloads.
• Platform access: the SPEKTRA Edge dashboard and an active project, with permission to manage provisioning policies, service accounts, service account keys, and role bindings.
• Local tools: jq (used to build project_config.json).

Default-enabled functions

The packaged systemd unit starts the agent with the pod driver and with OS management disabled:

droplet run --driver compose --disable-os-management \
  --device-service-account-file /etc/droplet/device_config.json \
  --project-service-account-file /etc/droplet/project_config.json \
  --use-journald-compatible-log

As a result, on a .deb install:

If you want to enable additional capabilities, edit the ExecStart line in /lib/systemd/system/droplet.service (each capability has its own --disable-* flag) and reload with sudo systemctl daemon-reload.

Not available with the package install

The .deb agent runs on your operating system, so the platform features that are properties of SPEKTRA Edge OS itself are not available. You remain responsible for the host OS. In particular, the following are not supported:

What you do get is device onboarding, remote workload/pod management, and telemetry — see Default-enabled functions.

Install the package

Copy the .deb matching your architecture onto the host and install it:

sudo dpkg -i droplet_<version>_<arch>.deb
# resolve dependencies (e.g. wireguard) if dpkg reports any
sudo apt-get install -f

The package:

• installs the agent binary at /usr/bin/droplet,
• installs the service unit at /lib/systemd/system/droplet.service,
• creates the working directory /var/lib/droplet,
• enables and starts the droplet service automatically.

At this point the service is running but has no identity yet. It will keep retrying until you supply project_config.json, which you provide in the next section.

Create the agent’s identity (project_config.json)

The agent onboards using a project-scoped project_config.json. There are two ways to obtain it — pick one:

• Reuse from an existing device (fastest). If you already have a device that onboards against the same project and provisioning policy, its project_config.json is a shared credential you can copy as-is. Grab it from that device — /etc/droplet/project_config.json on a package install, or /isodevice/config/project_config.json on SPEKTRA Edge OS — and skip straight to Install the identity file. See Reuse across devices for why this is safe.
• Create from scratch. If this is a new project or you want a dedicated credential, follow the numbered steps below to create a provisioning policy, a service account with the right role, and a key, then convert it.

The steps below cover the create-from-scratch path.

Step 1 — Create a provisioning policy

A provisioning policy lets a device self-register into your project. Create one in the dashboard and choose a mode:

The policy also defines the role bound to each newly created device identity (default: services/devices.edgelq.com/roles/v1-device-agent). See provisioning concepts for background.

Step 2 — Create a service account

In the dashboard, open your project and create a Service Account (for example fleet-provisioner). This is the shared, project-scoped identity that devices will present in order to self-provision.

Step 3 — Assign the provisioning role and attach it to the policy

For the service account to be allowed to provision devices, it needs the Device provisioner role:

services/devices.edgelq.com/roles/v1-device-provisioner

This role grants the provisionDeviceViaPolicy and requestProvisioningApproval permissions (scoped by project, region, service account, and provisioning policy).

1. Bind the Device provisioner role to the service account from Step 2.
2. Associate the service account with the provisioning policy from Step 1, so devices using this account are matched to that policy.

Step 4 — Create and download a service account key

Open the service account → Service Account Keys → Create. On creation the dashboard downloads a JSON key file (shown only once). Save it as service-account-key.json. It looks like:

{
  "type": "service_account_key",
  "client_email": "fleet-provisioner@<project>.<region>.serviceaccounts.iam.edgelq.com",
  "private_key_id": "projects/.../serviceAccountKeys/<key>",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
}

Step 5 — Convert the key to project_config.json

The agent expects the key wrapped in a config with a droplet service set. Build it from the downloaded key, setting defaultDomain to the controller endpoint your device connects to (for example apis.edgelq.com, or your dev/staging domain):

jq --arg domain "apis.edgelq.com" '{
  accounts: [ { serviceAccount: (. + {type: "service_account"}) } ],
  activeAccountName: .client_email,
  serviceSets: [ { name: "droplet", defaultDomain: $domain } ],
  activeServiceSetName: "droplet"
}' service-account-key.json > project_config.json

The result:

{
  "accounts": [
    {
      "serviceAccount": {
        "type": "service_account",
        "client_email": "fleet-provisioner@<project>.<region>.serviceaccounts.iam.edgelq.com",
        "private_key_id": "projects/.../serviceAccountKeys/<key>",
        "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
      }
    }
  ],
  "activeAccountName": "fleet-provisioner@<project>.<region>.serviceaccounts.iam.edgelq.com",
  "serviceSets": [ { "name": "droplet", "defaultDomain": "apis.edgelq.com" } ],
  "activeServiceSetName": "droplet"
}

Notes:

• activeAccountName must equal the client_email.
• Keep private_key on one line with its \n escapes intact (valid JSON).
• defaultDomain is the controller endpoint the agent connects to — not the IAM host inside the email.

Install the identity file

Whether you reused an existing project_config.json or created one above, install it where the packaged service reads it, and lock down its permissions (it contains a private key):

sudo install -o root -g root -m 600 project_config.json /etc/droplet/project_config.json
sudo systemctl restart droplet

Reuse across devices

project_config.json is a shared, project-scoped credential — it is not tied to any single machine. That means:

• You can reuse an existing project_config.json taken from another device that already onboards against the same project and policy.
• You can copy the same file to many devices. Each device presents this shared identity only to self-provision; on success it receives its own, device-scoped identity (/etc/droplet/device_config.json) and uses that from then on.

This is why a single install image or a single copied config can serve an entire fleet, with no per-device credential preparation.

Verify

1. Watch the agent logs:

   journalctl -u droplet -f
   

   The agent should load the project config and attempt self-provisioning.

2. In the dashboard, under your project:

   • Unattended: a new Device appears automatically.
   • Manual approval: a pending provisioning request appears — approve it.

3. Once provisioned, the device shows as Online and reports its OS version, hardware, and network details.

If the device does not come online, check the connectivity requirements and the troubleshooting playbooks.

Next steps

With the device online, deploy your first workload to it in Applications.

Related

• Device overview — how a device is modelled on the platform.
• Networking — network configuration, proxies, and time sync.
• Operations — upgrades, reboots, and status indicators.

4.6 - Storage

This section describes how device storage is laid out by default and how to add your own partitions and mounts or expand storage to use the whole disk.

Default disk layout

A device’s primary disk is divided into a small number of areas, each with a distinct role:

The data area takes the remaining space on the disk, so most of the disk is available to your workloads. The configuration and data areas hold everything you set up; the boot and system-image areas belong to the OS and are managed for you across upgrades.

Configuring additional partitions and mounts

You can attach extra storage and control where it is mounted using a storage mapping. The mapping is a YAML document that lists the partitions a device should ensure exist and where each should be mounted, plus any bind mounts that redirect a directory to persistent storage.

You can provide the storage mapping when you create an install image (so it applies from first boot) or push it from the dashboard. On the device itself it lives at /isodevice/config/disk_mapping.yaml.

Mapping format

A storage mapping has two sections: diskmappings (partitions to ensure and mount) and bindmounts (directories to redirect).

diskmappings:
  - disk: /dev/sdb
    partition_number: 1
    mountpoint: /mnt/extra
    size: 50G
    filesystem: ext4
  - disk: /dev/sdb
    partition_number: 2
    mountpoint: /mnt/scratch
    size: -1            # use all remaining free space
    filesystem: ext4

bindmounts:
  - mountsource: /mnt/extra/registry
    mountpoint: /var/lib/registry

The fields for each diskmappings entry:

Behavior to keep in mind:

• If a partition already exists, it is mounted as specified; size and filesystem are ignored (existing data is not reformatted).
• If a partition does not exist and there is room, it is created with the requested size and filesystem, then mounted.
• A partition with size: -1 grows to fill the free space available on its disk.

Logical mount names

For convenience, a few common destinations can be referenced by name instead of an absolute path:

Bind mounts

A bind mount redirects a directory onto persistent storage so its contents survive reboots and upgrades. By default, the standard runtime directories (container storage, logs, and the agent’s working directory) are already bound to the data area; add your own entries only when you want additional directories to persist or to live on a separate disk.

Expanding storage

When you install onto a disk that is larger than the image, the data area can be grown to use the extra space:

• During installation you can request that the last partition be expanded to fill the disk.
• A storage mapping entry with size: -1 grows the data partition to consume the remaining free space.

This lets a single image target disks of different sizes while still using all available capacity for workloads and data.

Related

• Settings supplied as files — where the storage mapping document goes on a device.
• Create an install image — baking a storage mapping into an install image.

Next steps

• Turn on disk encryption to protect the configuration and data areas.
• Configure networking for the device.

4.7 - Networking

This section covers how a device connects to the network and to the SPEKTRA Edge platform: how you describe network configuration, how the device falls back between connections, how to route through a proxy, what the device needs to reach on the network, and how time is kept in sync.

Network configuration model

Device networking is described as a Netplan-format YAML document. This is a clean, declarative way to configure wired, Wi-Fi, and cellular connections, as well as advanced setups such as bonds, bridges, VLANs, and tunnels.

You can supply the network configuration when you create an install image (so the device has connectivity from first boot) and you can update it later from the dashboard. When you push configuration from the platform, you choose how it combines with what is already on the device:

On the device, the baseline configuration — the one a device falls back to if a pushed configuration fails — lives at /isodevice/config/interfaces.yaml. See connection fallback.

The device reports its observed network state back to the platform — active interfaces, IP addresses, and carrier information — which you can view on the device overview page.

Wired, Wi-Fi, and cellular

All three connection types are configured through the same network configuration document:

• Wired connections typically use DHCP by default and need no configuration to come up.
• Wi-Fi connections are configured with the network name and credentials.
• Cellular connections are configured for the modem; a device can also be associated with a SIM in the platform for inventory and activation tracking.

See the Netplan documentation for the exact YAML for each type.

Connection fallback

A field device often has more than one way to reach the network, and its configuration can be changed remotely. To keep a configuration mistake or a link outage from taking a device permanently offline, the OS has several layers of fallback — network configuration fallback, uplink (interface and cellular) failover, and proxy fallback. These are covered in detail on the Connection fallback page.

In this section

• Netplan configuration — a worked example of pushing network configuration from the dashboard, using Wi-Fi on a Raspberry Pi.
• Connection fallback — how the device stays reachable across bad config pushes, link outages, and proxy failures.
• Proxy configuration — route device traffic through an HTTP/HTTPS proxy.
• Connectivity & ports — what the device must be able to reach, and what it listens on.
• Time synchronization — set NTP servers and understand default time behavior.

Related

• Settings supplied as files — placing a Netplan file on configuration storage.

4.7.1 - Configure device networking with Netplan

Device networking on SPEKTRA Edge is configured with Canonical Netplan, which provides a clean, YAML-based configuration and supports a wide range of Linux networking managers. You edit that YAML from the dashboard and the platform pushes it to the device.

This page walks through one concrete case — adding a Wi-Fi interface to a Raspberry Pi as a secondary uplink — so you can see the whole push-and-verify loop end to end. The same flow applies to wired interfaces, VLANs, bonds, and cellular; only the YAML differs.

What you need

To go through this page, you need the following.

• access to the SPEKTRA Edge dashboard
• an active project
• a device provisioned under the project

Configure Wi-Fi networking

Go to the Device overview page by clicking the device name on the Project overview page.

Then, click the Edit details option of the Device actions to open the Update device details page.

Go to the Network agent section of the Update device details page and use the Merge option to add the new Wi-Fi specific configuration.

Verify Wi-Fi networking

Go to the Device overview page and check the IP address as well as the ISP information for the wireless interface.

Related

• Settings supplied as files — the file-based alternative to pushing from the dashboard.

Next steps

Congratulations on configuring the Wi-Fi networking of your Raspberry Pi with SPEKTRA Edge.

With that, let’s move on to proxy configuration if your devices reach the internet through a forward proxy, or to OS upgrades.

Onwards.

4.7.2 - Connection fallback

Devices are often deployed where connectivity is imperfect: a misapplied network change, a flaky uplink, or a proxy that goes down. SPEKTRA Edge OS has several fallback behaviors that keep a device reachable and recoverable. This page explains the three that matter most: network configuration fallback, uplink (interface and cellular) failover, and proxy fallback.

Network configuration fallback

When you push a new network configuration to a device, there is always a risk that the new configuration is wrong and takes the device offline — which would also prevent you from pushing a correction.

To guard against this, a device can fall back to a known-good network configuration that was established when the device was set up. If a platform-supplied configuration leaves the device unable to reach the platform, the device can revert to this baked-in configuration so it can be reached again.

You can control this behavior:

Uplink failover (interfaces and cellular)

A device can have more than one uplink — for example wired Ethernet plus cellular, or wired plus Wi-Fi. When multiple uplinks are configured, the device prefers the primary uplink and uses the others as backups, switching to a working uplink when the preferred one is unavailable.

A common, robust pattern is:

1. Wired Ethernet as the primary uplink (DHCP).
2. Wi-Fi or cellular as a backup that takes over when the wired link is down.

Cellular is especially useful as a last-resort uplink because it does not depend on local site infrastructure. Associate a SIM with the device during hardware registration, configure the cellular connection in your network YAML, and the device can fall back to it to stay manageable.

Proxy fallback

When a device is configured to reach the platform through a proxy, it still needs to stay reachable if that proxy becomes unavailable. The device evaluates the available paths to the platform and uses a working one, so a single failed proxy does not necessarily cut the device off from management.

This means you can introduce a proxy for normal operation without making it a single point of failure for device management, provided a viable path to the platform remains.

Putting it together

The three mechanisms guard different failures, so they stack: each one catches what the ones above it cannot.

flowchart TD
    GOAL(["Device must stay<br/>reachable by the platform"])

    GOAL --> L1{"Is the pushed network<br/>configuration working?"}
    L1 -->|"no"| F1["Revert to the known-good<br/>configuration from setup"]

    L1 -->|"yes"| L2{"Is the preferred<br/>uplink up?"}
    L2 -->|"no"| F2["Fail over to a backup uplink<br/>(Wi-Fi or cellular)"]

    L2 -->|"yes"| L3{"Is the proxy<br/>reachable?"}
    L3 -->|"no"| F3["Use another viable path<br/>to the platform"]

    L3 -->|"yes"| OK(["Managed normally"])

For a remote, hard-to-reach device, a resilient setup combines all three:

• Keep network configuration fallback enabled so a bad push self-corrects.
• Provide a backup uplink (cellular is ideal) so a single link failure does not isolate the device.
• If you use a proxy, ensure a viable path to the platform remains so proxy problems do not block management.

Related

Next steps

• Review what must be reachable in Connectivity & ports.
• Configure a proxy in Proxy configuration.

4.7.3 - Proxy configuration

If your devices reach the internet through a forward proxy, configure the proxy so that both the device’s connection to the SPEKTRA Edge platform and your workloads’ traffic are routed correctly.

What you can set

Proxy configuration consists of the standard proxy settings:

In addition, you can specify which network interfaces the device should use to reach the platform through the proxy, so control-plane traffic uses the intended path.

Where to set it

You can configure the proxy:

• at image creation, so devices use the proxy from first boot, or
• from the dashboard for a device that is already online.

Which traffic uses the proxy

“The device uses a proxy” is three separate behaviors, and they do not all work the same way. The distinction matters most for the third row.

Configure the proxy from the dashboard

To go through this section, you need:

• access to the SPEKTRA Edge dashboard
• an active project
• a device provisioned under the project
• the name and the port number of the proxy server

Go to the Device overview page of the target device under your project by clicking the name of the device on the Project overview page.

Open the Update device details page by clicking the Edit detail option of the device menu option.

Configure the proxy server in the HTTP and/or HTTPS proxy server section of the Update device details page.

You can configure the device to bypass the proxy servers for the particular communication, e.g. the node local communication in the example below.

Save the page and you are good to go. The device goes through the proxy server for the HTTP and HTTPS traffic.

What the proxy must allow

The device’s connection to the platform is gRPC over HTTP/2, carried inside a TLS session on port 443. That places two requirements on the proxy.

It must allow CONNECT to port 443. The device does not send ordinary HTTP requests to the platform; it asks the proxy to open a tunnel and then runs TLS inside it. A proxy that only forwards HTTP methods, or that restricts CONNECT to a narrow destination list, blocks the device.

It must not terminate or inspect TLS. A proxy doing TLS inspection substitutes its own certificate for the platform’s. The device validates the platform certificate against its trust store, does not find the inspection certificate there, and the handshake fails.

Fallback behavior

The device determines the best route to the platform and will fall back to a direct connection when the proxy is not usable, so a proxy outage does not necessarily take a device offline. If you require that all traffic traverse the proxy, ensure direct egress is blocked at the network level rather than relying on device configuration.

no_proxy recommendations

Add to no_proxy any destinations that must not go through the proxy, such as:

• on-site services the device talks to directly (local registries, local APIs)
• link-local and private ranges used on the device’s LAN

Related

• Create an install image — setting a proxy before a device first boots.

Next steps

• Review connectivity & ports to confirm what the device must reach through (or around) the proxy.

4.7.4 - Connectivity & ports

This page lists what a device needs to reach on the network and what it accepts on its own interfaces, so you can plan firewall rules for the sites where your devices run.

Outbound connectivity (required)

A device reaches the SPEKTRA Edge platform over secure, outbound connections. Devices do not need any inbound connections from the platform — all communication is initiated by the device.

All platform traffic is TLS on TCP 443. Allow the whole edgelq.com domain rather than individual hostnames: a device is directed to different service endpoints depending on its project and region, and the set changes as the platform grows.

At minimum, allow outbound TCP 443 to *.edgelq.com and outbound UDP 123 to your time sources. If you use a proxy, the device’s platform traffic egresses through it.

Match subdomains at any depth

Platform hostnames carry several labels, so the rule has to match more than one level below edgelq.com.

Many firewalls and proxies treat *.edgelq.com as matching every subdomain at any depth, which is what you want. Some treat * as exactly one label — and on those, *.edgelq.com matches a two-label name but not a deeper one, which lets a device get far enough to onboard and then stops it.

If your equipment behaves that way, express the rule as a domain-suffix match on edgelq.com instead. Squid spells this .edgelq.com; most next-generation firewalls offer a “domain suffix” or “subdomain” match type.

DNS

The device must be able to resolve every destination above. A device on a network with filtered or split-horizon DNS can pass a connectivity test to a raw IP address and still fail to reach the platform. If you run internal resolvers, confirm they resolve edgelq.com names and your registry’s name.

Inbound (on the device)

By default a device exposes only what is needed to administer it locally:

The device also responds to local network discovery (mDNS) so it can be found by name on the local segment; this can be turned off with the device discovery setting.

Any ports your workloads expose are determined by the workloads you deploy, not by the OS.

Remote access does not require inbound ports

Operator actions such as opening a remote shell, transferring files, or streaming logs are carried over the device’s existing outbound connection to the platform. You do not need to open inbound ports to use them. See Remote access.

Firewall planning checklist

• Allow outbound TCP 443 to *.edgelq.com (directly or via proxy), matching subdomains at any depth.
• Confirm the device can resolve those names with the resolvers it will actually use on site.
• Allow outbound TCP 443 to your container registry, if you deploy from a private one.
• Allow outbound UDP 123 to your NTP sources.
• Allow outbound UDP to your chosen STUN servers (or accept that external IP discovery is unavailable).
• If traffic passes through a proxy, confirm it permits HTTP CONNECT to port 443 and does not terminate TLS — see Proxy configuration.
• Decide whether local TCP 22 (SSH) should be reachable on your LAN.
• Open any ports your workloads require, per workload.

Related

• Proxy configuration — if egress must go through a proxy.
• Connection fallback — what happens when a path fails.
• Networking — the rest of this section.

4.7.5 - Time synchronization

Accurate time is important for secure connections, certificate validation, log correlation, and device attestation. Devices keep their clocks synchronized over the network using NTP.

Default behavior

Devices use chrony as their NTP client. Out of the box a device ships without a custom time configuration, so it synchronizes against the public pools that its Linux distribution configures by default — typically ntp.ubuntu.com and the 0–2.ubuntu.pool.ntp.org pools. A device with internet access therefore keeps accurate time without any configuration.

Treat those pool names as a default that can change with the distribution, not as a contract. If you need to know exactly what a given device is using, read /etc/chrony/chrony.conf on the device, and set your own sources if the answer matters to your firewall rules.

Setting custom NTP servers

If your environment requires specific time sources — for example, internal NTP servers on an isolated network — you can provide your own NTP configuration. You can set it:

• at image creation, so it applies from first boot, or
• by placing a chrony-format configuration at /isodevice/config/chrony.conf on the device.

When custom NTP settings are provided, they take effect early in the boot process so the device’s clock is correct before it contacts the platform.

When a device cannot reach a time source

A device with no reachable NTP source keeps running, but its clock is left to drift against whatever the hardware clock holds. Once the drift is large enough, certificate validity checks start to fail, and the symptom you see is a device that appears offline in the dashboard even though its network is otherwise healthy — the TLS handshake to the platform cannot complete.

This failure is easy to misread, because the device can still reach the internet. If a device will not come online, check its clock before you go looking at firewall rules. See Troubleshooting.

Recommendations

• On networks without internet access, always configure reachable internal NTP servers; otherwise the device cannot correct its clock, which can cause secure connections and attestation to fail.
• Make sure outbound UDP 123 to your time sources is allowed — see Connectivity & ports.

Related

• Connectivity & ports — NTP egress a device needs.
• Troubleshooting — when a device will not come online.
• Networking — the rest of this section.
• Settings supplied as files — where a custom NTP configuration goes on a device.
• Create an install image — setting initial time sources in an install image.

4.8 - Security

SPEKTRA Edge OS is built for devices that run unattended, often in physically exposed locations. This section explains the security controls available to you and how to configure them.

Security at a glance

Defaults worth knowing

• The initial administrator password depends on how the device was installed. An appliance shipped with the OS installed accepts its hardware serial number until you set a password, so set one on first login. Images you build yourself carry only the password you chose. See User accounts.
• The device accepts only outbound connections to the platform; no inbound platform connection is required. See Connectivity & ports.
• Disk encryption is optional and is chosen when you create an image.

In this section

• Disk encryption — encrypt data at rest, with automatic unlock and a recovery passphrase.
• TPM & device attestation — hardware-backed identity and integrity verification.
• Secure Boot — verify the boot chain in firmware.
• SSH access — control shell access, keys, and source restrictions.
• User accounts — the administrator account and password recovery.
• USB device control — allow only approved USB devices.
• Remote access — operator access through the platform and what is recorded.

4.8.1 - Disk encryption

Disk encryption protects the data at rest on a device, so that a lost or stolen device does not expose your configuration or workload data. This page explains what is encrypted, how a device unlocks itself, and how to recover access.

What is encrypted

When encryption is enabled, the two areas that hold your information are encrypted:

• the configuration area (device settings, identity, administrator password, hooks)
• the data area (container images, workload data, logs)

The boot and system-image areas are not encrypted; they contain only the operating system, which is public and identical across devices.

Enabling encryption

Encryption is chosen when you create an install image. You can also set an initial recovery passphrase at that time. Because enabling encryption affects how the disk is laid out, it is selected at image creation rather than toggled on a running device.

How a device unlocks itself

Encrypted devices unlock automatically at boot using the device’s hardware security module (TPM). The encryption keys are bound to the device’s hardware and to the integrity of its boot state, so the disk unlocks only on the same device, booted normally. There is no passphrase to type at the console during a normal boot, which is what allows encrypted devices to run unattended.

Because the keys are tied to the hardware, moving an encrypted disk to different hardware will not unlock it. This is the intended protection.

Recovery passphrase

In addition to automatic hardware unlock, a device can hold a backup recovery passphrase. This is a human-known passphrase you can use to unlock a device if automatic unlock is unavailable — for example after certain hardware changes.

Recommendations:

• Set a recovery passphrase (at least 12 characters) when you enable encryption.
• Store it securely, separately from the device.
• Treat it as a break-glass credential — it can unlock the encrypted areas.

Recovery scenarios

Related

• TPM & device attestation — the hardware module that backs automatic unlock.
• User accounts — administrator password and reset.
• Create an install image — enabling encryption and setting a recovery passphrase at image time.

4.8.2 - TPM & device attestation

Devices use a hardware security module — a TPM (Trusted Platform Module) — to establish a strong, hardware-rooted identity and to protect sensitive material. This page explains what the TPM is used for and how attestation works during provisioning.

What the TPM is used for

• Device identity. The TPM holds keys that uniquely and verifiably identify the device. These keys cannot be copied off the device.
• Attestation. During provisioning, the device proves its identity and reports its integrity to the platform before it receives credentials.
• Disk unlock. When disk encryption is enabled, the TPM stores the keys that unlock the encrypted areas, bound to the device’s boot state.

Attestation during provisioning

When a device onboards using zero-touch provisioning or a provisioning policy, it presents hardware-backed identity to the platform and responds to a challenge that proves the keys really live in this device’s TPM. Only after this succeeds does the device receive its credentials. This is what makes it safe to ship unconfigured hardware directly to a site: an attacker cannot impersonate a device without its TPM.

For attestation to succeed, the platform must trust the device’s TPM. This is established through the manufacturer’s certificates, which an administrator registers in the platform so that devices from a given manufacturer or product line can be verified.

Attestation configuration and status

You can configure attestation expectations for a device, and the device reports its measured integrity values back to the platform, where you can review them on the device. Use this to confirm that devices booted in the expected state.

What you need

• The device must have a functioning TPM.
• The device’s clock must be reasonably accurate for the secure exchange to succeed — see Time synchronization.

Related

• Disk encryption — uses the TPM for automatic unlock.
• Secure Boot — complements attestation by verifying the boot chain.

4.8.3 - Secure Boot

Secure Boot is a firmware feature that ensures a device only runs boot software that is cryptographically signed and trusted. SPEKTRA Edge OS supports Secure Boot so that the boot chain — from firmware through to the operating system — is verified before it runs.

Why use Secure Boot

Secure Boot protects against tampering with the boot path. Combined with disk encryption and device attestation, it raises the bar for an attacker with physical access: the device will refuse to boot modified or untrusted boot software.

What you need to do

On most generic x86 hardware, SPEKTRA Edge OS works with Secure Boot enabled using trust that is already present in the firmware, so you can simply leave Secure Boot enabled in the device’s firmware (UEFI) settings.

To enable or disable Secure Boot, enter the device’s firmware setup at boot and change the Secure Boot setting, as you would for any UEFI system. Refer to your hardware vendor’s documentation for how to reach firmware setup.

Locked-down firmware and certificate enrollment

Some hardware is locked down to trust only a specific set of signing certificates. In those environments you may need to enroll the SPEKTRA Edge signing certificate into the firmware’s trusted database so that the device will boot the OS.

If you operate such hardware, contact your SPEKTRA Edge representative for the signing certificate and enrollment guidance for your platform.

If a device will not boot with Secure Boot on

If a device fails to boot only when Secure Boot is enabled:

1. Confirm the firmware is up to date.
2. If the firmware requires explicitly trusted certificates, enroll the SPEKTRA Edge signing certificate (see above).
3. As a diagnostic step, temporarily disable Secure Boot to confirm it is the cause, then re-enable it once trust is established.

Related

• TPM & device attestation — proving a device is what it claims to be.
• Disk encryption — protecting data at rest.
• Security — the rest of this section.

4.8.4 - SSH access

A device runs an SSH server so you can reach its console for administration. You control whether SSH is enabled, how users authenticate, and where connections may originate. SSH settings are managed from the dashboard (or the API) and applied to the device automatically.

Enabling or disabling the SSH server

You can turn the SSH server off entirely for devices that should never accept direct shell access. With the server disabled, you can still administer the device through remote access over the platform connection.

Authentication

You can control how users authenticate:

Authorized keys

You can provide one or more authorized public keys. Each key entry supports the usual SSH key options, including:

• marking a key as a certificate authority, so SSH certificates it signs are accepted
• restricting a key to specific source addresses
• forcing a specific command
• applying restrictions and principals

Using a certificate authority is recommended for fleets: you can issue short-lived SSH certificates to operators instead of distributing individual keys to every device.

Restricting where connections come from

You can limit which source addresses may connect:

• an allow list of addresses/ranges permitted to connect
• a deny list of addresses/ranges that are blocked

This is the closest thing to a host firewall for SSH and is the recommended way to limit exposure when SSH must remain reachable on a LAN.

Brute-force protection

The device protects the SSH service against repeated failed login attempts by temporarily banning offending sources. You can tune this behavior through the device configuration, including:

• the ban duration applied to an offending source
• an ignore list of trusted sources that are never banned

Recommendations

• Prefer key or certificate authentication and disable passwords where possible.
• Use source restrictions to limit who can reach SSH.
• Keep an ignore list for your own management hosts so administrative tooling is not banned.

Related

• User accounts — the administrator account used for login.
• Remote access — administer devices without exposing SSH on the LAN.

4.8.5 - User accounts

Each device has a local administrator account used for console and SSH access. This page explains how its password is set and stored, and how to recover access if the password is lost.

The administrator account

The administrator account (admin) has the privileges needed to operate the device locally. It is the account you use on the console, and over SSH if you enable password authentication.

Where the initial password comes from

This depends on how the device was installed, and the difference matters: one of these paths gives you a device that is reachable with a credential you did not choose.

SPEKTRA Edge appliances

An appliance arrives with the OS already installed, so it needs a credential you can use on first boot. That credential is the hardware serial number. It works only while no administrator password has been set: once you set one, the serial number stops being accepted.

sudo change-password

Images downloaded from the dashboard

When you download an install image from the dashboard you supply the administrator password at that point, and it applies to every device built from that image.

Vanilla image files

A vanilla image file downloaded directly has no administrator password in it. You configure one with cuttle while customizing the image, before writing the installation media:

sudo -E cuttle os edit \
  --image-file spektra-edge_generic-amd64_$VERSION.raw \
  --password $PASSWORD

The device then has the password you supplied, and there is no default credential at any point. See Create an install image for the surrounding workflow.

Devices running the droplet agent from a .deb

Installing the agent onto a machine you already run does not create or manage local accounts, and does not change how that machine authenticates logins. Its existing users, passwords, and SSH configuration continue to apply, and nothing on this page does. See Install the droplet agent.

How the password is stored

The password must be non-empty. It is stored only as a salted hash on the device’s configuration storage — the plaintext password is never written to the device. When the configuration area is encrypted, the stored hash is protected at rest as well.

Changing the password on a running device

On a device you can still sign in to, change the password from its console:

sudo change-password

It prompts for the current password before accepting a new one, so it changes a password; it does not recover a lost one. The only exception is a device that has no password set yet, such as a new appliance, where it asks only for the new password.

Resetting a lost password

Because the password is stored on the device’s configuration storage rather than inside the read-only system image, it can be reset without reinstalling. Every route needs physical access to the storage, though: a lost password cannot be reset over the network.

Point cuttle at the disk holding the configuration partition to write a new password to it directly:

sudo cuttle os change-password $PASSWORD --out-device /dev/sdX

Re-imaging the device is the other option, and the one to choose if you also want to reset the rest of its configuration.

On a SPEKTRA Edge appliance the configuration partition is inside the unit, so resetting a lost password means either removing the disk to run the command above against it or re-imaging. Neither the serial number nor the platform can recover it: the serial number is refused once any password is set, and there is no remote password reset.

If the device is still reachable through the platform, you can continue to operate it via remote access while you arrange physical access — managing a device does not depend on its local administrator password.

Recommendations

• On an appliance, set an administrator password before anything else. Until you do, the serial number is a working credential.
• Use a strong, unique administrator password per fleet or per device.
• Enable disk encryption so the stored password hash and all configuration are protected at rest.
• Prefer SSH key or certificate authentication over passwords for routine access. If you do enable SSH password authentication, make sure every device in scope has a password you chose first.

Related

• SSH access — preferred over password login.
• Device setup & provisioning — where the administrator password is first set.
• Security — the rest of this section.
• Create an install image — setting the initial administrator password.

4.8.6 - USB device control

USB device control lets you restrict which USB peripherals a device will accept, protecting against unauthorized devices being plugged into hardware in the field. It is configured from the dashboard (or the API).

How it works

When USB device control is enabled, the device accepts only USB peripherals that match your allow rules; everything else is rejected. When it is disabled, USB devices are accepted normally.

Allow rules

Each allow rule describes the USB devices it permits. You can match on:

Rules can match a specific value or one of a set of values, so you can, for example, allow a specific approved peripheral on any port, or allow only devices connected to a particular internal port.

Recommendations

• Enable USB device control on devices in physically exposed locations.
• Allow only the specific peripherals your deployment needs (for example, an approved cellular modem or sensor), and reject everything else.
• Account for peripherals that are part of the device itself when writing rules, so enabling control does not disable required internal devices.

Related

• Remote access — reaching a device without physical access.
• Security — the rest of this section.

4.8.7 - Remote access

You can administer devices remotely through the SPEKTRA Edge platform without exposing any inbound ports on the device. Operator actions are carried over the device’s existing outbound connection to the platform.

What you can do remotely

Through the platform you can:

• open a remote shell on a device
• transfer files to and from a device
• stream system logs and container logs
• start, stop, and restart workloads
• reboot or shut down a device

These work from the dashboard and from the cuttle command-line tool.

No inbound ports required

Because remote access rides on the device’s outbound connection to the platform, you do not need to open inbound ports or expose the device to reach it. This is what lets you administer devices behind NAT or restrictive firewalls. See Connectivity & ports.

Relationship to SSH

SSH access governs direct connections to the device’s SSH server on the local network. Remote access through the platform is separate and works even when SSH is restricted to a LAN or disabled entirely — making “SSH disabled on the device, administer through the platform” a viable hardening posture.

Auditing

Operator access through the platform is associated with the authenticated user who initiated it, so administrative actions can be attributed. Combine remote access with your organization’s account controls to govern who may reach devices.

Related

• SSH access — how shell access is authenticated and restricted.
• Device overview — opening a terminal from the dashboard.
• Security — the rest of this section.

4.9 - Operations

This section covers running devices day to day: upgrading the OS and rolling back, rebooting and recovering, checking device health, reading status indicators, running scripts at boot and shutdown, deploying workloads, and moving files on and off a device.

In this section

• OS upgrades — move devices to a new OS version, and roll back.
• Fleet rollout — stage an upgrade across many devices, measure its progress, and stop it going wrong.
• Reboot, shutdown & recovery — power actions and recovery options.
• Health checks — define probes and read device conditions.
• Status & indicators — interpret device status, metrics, and LED states.
• Boot & shutdown hooks — run your own scripts at defined points in the device lifecycle.
• Running workloads — deploy containers to a device, and start, stop, or restart them.
• Transfer files — copy files to and from a device, and collect a debug bundle.

Related

• Logging — forward system and container logs, and pull logs on demand. Covered under Monitoring & alerts.

4.9.1 - OS upgrades

You upgrade a device’s operating system by setting the OS version you want; the device downloads the new version, switches to it, and reboots. Because the system image is separate from your configuration and data, your setup is preserved across the change, and you can roll back to a previous version.

How upgrades work

1. You set the target OS version for a device (or a group of devices) from the dashboard.
2. The device downloads the requested version and prepares it alongside the current one.
3. The device switches to the new version and reboots.
4. After reboot, the device reports its new version, and your configuration and data are intact.

A device keeps more than one OS version on disk — the one it is running and the one it can fall back to — which is what makes switching versions and rolling back fast and safe.

flowchart TB
    subgraph BEFORE["Before"]
        direction TB
        A1["System image slot A<br/><b>running 2.1.0</b>"]
        B1["System image slot B<br/><i>previous version</i>"]
    end

    subgraph AFTER["After upgrade and reboot"]
        direction TB
        A2["System image slot A<br/><i>kept for rollback</i>"]
        B2["System image slot B<br/><b>running 2.1.2</b>"]
    end

    KEEP["Configuration + data<br/><i>untouched throughout</i>"]

    BEFORE -->|"1. download 2.1.2 into the spare slot<br/>2. switch<br/>3. reboot"| AFTER
    KEEP -.-> BEFORE
    KEEP -.-> AFTER

Rolling back is the same operation in reverse: the previous version is still in the other slot, so the device does not need to download anything.

Release channels and compatibility

• OS versions are published per device type, so a device is only offered versions compatible with its hardware.
• Some upgrades may require a minimum current version before you can move to the target, to ensure a supported upgrade path.

Upgrade a device from the dashboard

To go through this section, you need:

• access to the SPEKTRA Edge dashboard
• an active project
• a device provisioned under the project

Go to the Device overview page of the target device under your project by clicking the name of the device on the Project overview page.

Open the Update device details page by clicking the Edit detail option of the device menu option.

Select the OS version, 2.1.2 in this example, and click Save to trigger the OS upgrade process.

The upgrade operation will start automatically and you will see the OS version transition information on the Device overview page.

After some time, you will see the device Offline, which indicates the device is restarting with the new OS version.

You will see the device up and running with the new OS version on the Device overview page once it boots up.

Rolling back

If a new version misbehaves, you can roll a device back to the version it was running before, or to its original factory version. Because the previous version is retained on the device, rollback does not require re-downloading it.

Set the desired (earlier) version the same way you set an upgrade; the device switches back and reboots.

Select the downgrade OS version, 2.1.0 in this example, and click Save to trigger the OS downgrade process.

The OS downgrade process automatically starts once you click the Save button of the Update device details page.

After a minute or so, you will see the device status Offline with the OS version transition information on the Device overview page.

You will see the device up and running with the new OS version once it boots up.

Encrypted devices

Managed upgrades preserve automatic unlock on encrypted devices — no manual action is required to keep an encrypted device unlocking across an upgrade.

If an upgrade does not complete

• Confirm the device has connectivity to download the new version (including through any proxy).
• A device that fails to start a new version can fall back to the retained previous version.
• See the troubleshooting playbooks for upgrade issues.

Related

• SPEKTRA Edge OS release notes — what changed in each OS version, so you can decide which version to move a device to.

4.9.2 - Rolling out across a fleet

Upgrading one device from the dashboard is straightforward. Upgrading four thousand is a different task, and the difference is not volume — it is that you need to know how it is going while it is happening, and be able to stop.

The two version fields

Everything about fleet rollout follows from one idea: a device has a version you asked for and a version it is running, and they are separate fields.

Setting the first is the whole of “starting an upgrade”. The device notices, at its next check-in, that the two disagree, downloads the version it has been asked for, switches, and reboots. Afterwards it reports the new version and the fields agree again.

This means a rollout is not a job the platform runs. There is no batch to monitor, no operation to poll. The desired state is written on each device, and each device converges on it independently, whenever it happens to be reachable. That is what makes it safe on a flaky network — and it is also why you need to measure progress by comparing the two fields.

Upgrade progress is also reported as a condition named OSReady in the device’s status, which is the more precise signal when you want to know whether a particular device is mid-upgrade, not simply behind.

Measuring a rollout

Both fields are filterable, so you can count any population you care about without enumerating devices.

# Devices asked for 2.1.2 but not yet running it: still in flight
cuttle devices list devices \
  --parent projects/$PROJECT/regions/- \
  --filter 'spec.osVersion="2.1.2" AND status.deviceInfo.osVersion!="2.1.2"' \
  --field-mask status.deviceInfo.osVersion \
  -o json

# Devices already there
cuttle devices list devices \
  --parent projects/$PROJECT/regions/- \
  --filter 'status.deviceInfo.osVersion="2.1.2"' -o json

# Devices never asked: not yet in the rollout
cuttle devices list devices \
  --parent projects/$PROJECT/regions/- \
  --filter 'spec.osVersion!="2.1.2"' -o json

Those three numbers are your rollout dashboard. The first should trend to zero; if it plateaus, the devices remaining in it are the ones to investigate.

Stage it with labels

Do not set the target version on the whole fleet at once. Use labels to define waves and promote one at a time.

Label devices according to how much you are willing to break:

Then promote a wave by setting the version on that label’s devices only. For a handful of devices the dashboard is quickest — set the OS version on each as described in OS upgrades. For a wave of any size, drive it through the API:

DEVICES=$(curl -s -H "Authorization: Bearer $API_KEY" --get \
  --data-urlencode 'filter=metadata.labels CONTAINS "wave:canary"' \
  --data-urlencode 'view=NAME' \
  "https://devices.apis.edgelq.com/v1/projects/$PROJECT/regions/-/devices" \
  | jq -r '.devices[].name')

for DEVICE in $DEVICES; do
  curl -s -X PUT -H "Authorization: Bearer $API_KEY" \
    -H 'Content-Type: application/json' \
    --data '{"spec":{"osVersion":"2.1.2"}}' \
    "https://devices.apis.edgelq.com/v1/${DEVICE}?updateMask=spec.osVersion"
done

Between waves, wait long enough for the devices to have actually checked in and converged — and confirm they did. A canary that has not reported the new version is not a passing canary; it is an unknown.

Choose canaries you can recover by hand. The point of a canary is that its failure is cheap, and a device you would have to send an engineer to is not cheap.

Devices that are offline

A device that is switched off or disconnected when you set the version does not miss the upgrade. It converges when it comes back, however much later that is, because the desired version is stored on its record rather than pushed to it.

This is usually what you want, with one consequence to plan for: a device offline for two months will upgrade the moment it reconnects, possibly skipping several versions and at an unpredictable time. If some of your fleet is intermittent, expect a long tail of stragglers instead of a rollout that finishes cleanly, and check for an upgrade path constraint if the version gap is large.

What to check before starting

• Confirm the version is available for every device type in the wave. OS versions are published per device type, and a mixed fleet may not have the same version available everywhere.
• Check upgrade path constraints. Some versions require a minimum current version, which matters most for the stragglers above.
• Confirm connectivity, including through any proxy — devices download the image themselves.
• Check that the devices manage their own OS. Devices running the droplet agent on your own Linux rather than SPEKTRA Edge OS do not self-upgrade; OS management is disabled for them, and their OS is your responsibility. They will not participate in a rollout, so exclude them from your counts; they are not stuck.

Stopping and rolling back

There is no “cancel rollout” button, because there is no rollout object — so stopping one means changing the desired state.

To stop it spreading, stop promoting waves. Devices you have not yet retargeted are unaffected.

To reverse devices already upgraded, set spec.osVersion back to the previous version. Because each device retains the version it was running, the rollback does not require a download and is quick.

To reverse devices mid-upgrade, set the version back and let them converge. A device that fails to start a new version can also fall back on its own, as described in OS upgrades.

Watching instead of polling

For anything beyond a few hundred devices, do not poll the counts on a loop. Open a watch on the device collection with a field mask covering just the two version fields and the OSReady condition, and update your view as changes arrive. Rollout progress is exactly the case watch exists for: a large collection where a small, unpredictable subset changes at a time.

Alert on the rollout, not just the fleet

The failure that costs you is not a device that fails to upgrade — you will see that in the counts. It is a device that upgrades successfully and then misbehaves.

Before starting, make sure you would notice: connectivity alerts so a device that upgrades and never returns raises something, and application health checks so a device that comes back with its workload broken is visible. Rolling out without those means the canary phase cannot tell you anything, because there is nothing watching it.

Related

• OS upgrades — the single-device flow and what survives an upgrade.
• Monitoring and alerts — noticing when an upgraded device goes wrong.

4.9.3 - Reboot, shutdown & recovery

This page covers power actions you can take remotely and the options for recovering a device that is not behaving as expected.

Reboot and shutdown

You can reboot or shut down a device remotely from the dashboard or with the cuttle command-line tool. These actions are carried over the device’s connection to the platform and require no inbound access to the device.

In the dashboard, open the device’s Device overview page, click the vertical triple dots next to the page title, and choose Reboot or Shutdown.

From the command line:

cuttle devices reboot projects/your-project/regions/us-west2/devices/pi03
cuttle devices shutdown projects/your-project/regions/us-west2/devices/pi03

Both commands warn you and wait for you to type yes, because workloads on the device — and anything depending on them — go down with it. Pass --force to skip the prompt in scripts.

A device that loses power or is reset returns to its configured state on next boot, because configuration and data are persistent and the system image is read-only.

Automatic recovery

The OS is designed to keep itself running unattended:

• It restarts automatically after an unexpected fault rather than waiting at an error.
• Workloads configured to run are brought back up after a reboot.
• If a network configuration change does not produce a working connection, the device can fall back to known-good network settings — see connection fallback.

Recovery options

When a device needs hands-on recovery, the options in increasing order of impact:

See User accounts for password reset and Disk encryption for encrypted-device recovery.

When a device is offline

If a device is offline and unreachable through the platform, work through the troubleshooting playbooks — most often the cause is connectivity, time, or a network configuration change.

Related

• Status indicators — reading what state a device is in.
• OS upgrades — how upgrades roll back if a device fails to boot.
• Disk encryption — recovery on an encrypted device.

4.9.4 - Health checks

Health checks let a device continuously verify that it — or something running on it — is healthy, and report the result to the platform. You define health checks from the dashboard (or the API).

Types of checks

You can define host-level checks of several types:

How results are used

Each check’s result contributes to the device’s reported conditions, which you can see on the device overview page. Use health checks to detect problems such as a dependent service being unreachable, a required peripheral missing, or a local endpoint failing — and to surface them centrally instead of discovering them per device.

Recommendations

• Check the things that matter for the device’s role (for example, the local application endpoint, or a sensor’s device file).
• Keep checks lightweight and give them sensible intervals so they reflect real health without adding load.

Related

• Status & indicators — how health surfaces on the device and dashboard.
• Alerts — get told when a check starts failing.
• Operations — the rest of this section.

4.9.5 - Status & indicators

A device reports its state both to the platform and, on supported hardware, through a physical LED. This page explains how to read each.

Connection status

On the platform, a device is shown as:

Device information and metrics

The device reports details and resource usage you can view on the dashboard, including:

• OS version, hardware details, disks, and network interfaces
• CPU, memory, and storage usage
• temperature

These help you spot devices that are low on storage, running hot, or pinned at high resource usage.

LED indicator

On hardware with a status LED, the device signals its lifecycle and health through the LED so an on-site technician can tell at a glance what state a device is in — for example, still starting up, working normally, or needing attention. Use the LED for quick on-site triage, and the dashboard for detail.

The LED is driven by SPEKTRA Edge OS, so it is not available on a device running the droplet agent installed from a .deb package. Everything else on this page — connection status, device information, metrics, and health check conditions — is reported by the agent and works on either installation. See Install the droplet agent.

Conditions from health checks

Health checks you define contribute to the device’s reported conditions, giving you application- and peripheral-level health alongside the built-in status.

Related

• Health checks — defining the checks that feed device conditions.
• Reboot and recovery — what to do when a device is stuck or offline.
• Troubleshooting — playbooks for the common failures.

4.9.6 - Boot & shutdown hooks

Hooks let you run your own scripts at defined points in the device lifecycle — for example to prepare hardware, mount a special device, or clean up on shutdown. They are the supported way to extend device behavior without modifying the read-only system image.

Available hooks

You can provide a script for each of these points:

How to provide a hook

Place your script at the path for the point you want to act on, and make it executable — a script that is not executable is skipped silently:

sudo install -m 755 my-script /isodevice/config/hooks/on-boot

Because /isodevice/config is configuration storage, the script persists across reboots and OS upgrades, and runs automatically at the corresponding point.

Guidelines

• Keep hooks fast and resilient. The on-boot and after-agent hooks are allowed five minutes each before they time out, and a slow boot hook delays startup. Make hooks idempotent and have them exit cleanly.
• Do not rely on modifying the system image. Use hooks to act on configuration and data, not to patch the OS — image changes do not persist.
• Log from your hook so you can see what it did via logging.
• Test on one device first before distributing a hook to a fleet.

Related

• How persistence works — the other settings supplied as files, and what survives an upgrade.
• Reboot, shutdown & recovery — when hooks run.
• Operations — the rest of this section.

4.9.7 - Running workloads

Devices run your applications as containers. You deploy and manage them from the SPEKTRA Edge platform; this page covers only how workloads interact with the OS. For the full application deployment workflow, see the Deploy guide.

How workloads use device storage

• Container images and workload data live on the device’s data area, which uses most of the disk.
• A workload can mount paths from the device into its containers when it needs access to host data or hardware.
• Credentials a workload needs (such as registry pull secrets) are delivered through the platform rather than stored in the image.

Networking for workloads

• Any network ports a workload exposes are determined by the workload itself, not by the OS — open them in your site firewall as needed. See Connectivity & ports.
• Workload traffic honors the device’s proxy configuration.

When storage runs low

Because container images and data share the data area, a device that fills its data area can fail to start new workloads. Watch storage usage in device metrics, and keep logging levels reasonable so logs do not consume the space your workloads need.

Start, stop, and restart a workload

You can restart a workload from the dashboard, using the Restart option on the application’s menu — see Deploy an application. From the cuttle command line you can do the same, and also act on a single service inside a pod:

# restart a whole pod
cuttle applications restart projects/your-project/regions/us-west2/pods/nginx

# start, stop, or restart one service in a pod
cuttle applications pods stop \
  projects/your-project/regions/us-west2/pods/nginx web

The command reaches the workload through the device the pod runs on, so the device has to be online. Stopping a pod this way stops its containers on the device; it does not remove the deployment, so the workload is brought back up when the device reboots.

Lifecycle across reboots and upgrades

Workloads configured to run are brought back up after a reboot, and persist across OS upgrades because their images and data are on persistent storage.

Related

• Deploy an application — how workloads get onto a device.
• OS upgrades — how workloads survive a version change.
• Operations — the rest of this section.

4.9.8 - Transfer files

You can copy files to and from a device through the platform, over the outbound connection the device already keeps open. Nothing listens on the device for this, so file transfer works on devices behind NAT or a restrictive firewall, exactly like a remote shell does.

Both the dashboard and the cuttle command-line tool use the same transfer service on the device, so it does not matter which one you use.

Before you copy files onto a device

A device’s system image is read-only, and anything you write outside the persistent areas is gone after the next reboot. Choose the destination accordingly:

See how persistence works for the full storage model.

From the dashboard

Open the device’s Device overview page and click the vertical triple dots next to the page title.

• Upload files — enter the destination directory in Path on device, then select or drag in one or more files. The files keep their own names under that directory.
• Download file — enter the full path of a single file in Path on device. The file downloads through your browser when the transfer completes.

Both actions need the connect to device permission (services/proxies.edgelq.com/permissions/projects.connect), the same permission that governs the remote terminal.

From the command line

cuttle devices scp takes the same two arguments as ordinary scp, with the device side written as <device-name>:<path>. Whichever argument carries the device name decides the direction — you cannot copy between two devices.

Upload a file:

cuttle devices scp ./hook.sh \
  projects/your-project/regions/us-west2/devices/pi03:/isodevice/config/hooks/

Download a file:

cuttle devices scp \
  projects/your-project/regions/us-west2/devices/pi03:/isodevice/data/report.csv \
  ./report.csv

Add -r to transfer a whole directory, and -v to print per-file progress:

cuttle devices scp -r -v ./bundle \
  projects/your-project/regions/us-west2/devices/pi03:/isodevice/data/

How paths are interpreted

On upload, a trailing slash on the remote path means “into this directory”:

• …:/isodevice/data/ keeps the local file name.
• …:/isodevice/data/report.csv renames the file on the device.
• With -r, a trailing slash creates the local directory itself on the device; without one, only its contents are copied into the remote path.

The remote path of an upload must be absolute — it has to begin with /.

On download, what matters is whether the local path already exists as a directory:

• If it does, the file is written into it under its remote name.
• If it does not, the local path is used as the output file name.
• With -r, an existing local directory receives the remote directory beneath it; a local path that does not exist yet is created and becomes the root of the downloaded tree.

Collecting files for support

To gather the logs and system state an investigation usually needs, use cuttle devices collect-debug-bundle rather than copying files one at a time.

Related

• Remote access — administering a device without inbound ports.
• Boot & shutdown hooks — the most common reason to upload a file.
• Storage — what lives where on the device’s disk.

4.10 - Troubleshooting

Playbooks for the problems you are most likely to hit. Each lists the usual causes in the order worth checking.

Collect a debug bundle

When you need to hand the problem to someone else — or keep a record of a device in its failed state — collect a debug bundle. The cuttle CLI asks the device to gather its logs and system state into an archive, then downloads it:

cuttle devices collect-debug-bundle \
  projects/your-project/regions/us-west2/devices/pi03

The bundle is saved in the current directory under a generated name. Use --filename to choose your own, and -v to follow the collection and download as they happen:

cuttle devices collect-debug-bundle --filename pi03-offline.zip -v \
  projects/your-project/regions/us-west2/devices/pi03

The device has to be reachable through the platform for this to work, so collect the bundle while the problem is visible rather than after a reboot has cleared it. If the device is not reachable at all, the playbooks below are the place to start. The command is not available on Windows.

A device will not come online

1. Connectivity. Confirm outbound TCP 443 to the platform is allowed (directly or via proxy). See Connectivity & ports.
2. Time. A badly wrong clock breaks secure connections and attestation. Ensure the device can reach an NTP source — see Time synchronization.
3. Network configuration. A recent network change may have broken connectivity; the device should fall back to its image network settings unless fallback is disabled. See connection fallback.
4. Onboarding. Confirm the device has valid provisioning credentials or a working onboarding method.

If the device plainly has working internet access, go to The device has internet access but still shows offline instead — the causes there all survive a successful ping.

The device has internet access but still shows offline

This is the most commonly misdiagnosed device problem, because the usual test — browsing from the same network, or pinging a public address — passes. General internet access does not prove that SPEKTRA Edge traffic works. The device needs a specific kind of connection, to specific names, with an accurate clock.

Work through these in order; each is a different failure that produces the same “Offline” indicator.

1. Name resolution. Confirm the device can resolve the platform names, using the resolvers it actually uses on site. Reaching an IP address proves nothing if DNS is filtered or split-horizon. See DNS.
2. The shape of the allowlist. On equipment that treats * as exactly one label, *.edgelq.com does not match the deeper hostnames a device is given after onboarding, so it connects once and then stops. See Match subdomains at any depth.
3. TLS inspection. If the network inspects TLS, the device cannot validate the platform certificate and the handshake fails. Destinations must be exempted from inspection — see Proxy configuration.
4. Proxy method support. The proxy must permit CONNECT to port 443. A proxy that handles only ordinary HTTP methods blocks the device even though browsers on the same network work fine. See What the proxy must allow.
5. The clock. A clock far enough off breaks certificate validity checks before anything else is attempted. See Time synchronization.
6. The right platform and region. Confirm the device is pointed at the environment and region that hold your project. A device configured for one and enrolled in the other connects to something, and never appears where you are looking.

A network change broke connectivity

• If network configuration fallback is enabled, the device should revert to its image network settings after a failed change.
• If fallback is disabled, push a corrected configuration, or recover the device on-site.
• Configure a backup uplink (such as cellular) so a wired/Wi-Fi mistake does not isolate the device — see uplink fallback.

An encrypted device will not unlock

• After a hardware change (motherboard/TPM), automatic unlock no longer matches. Use the recovery passphrase.
• If the recovery passphrase is lost and automatic unlock is unavailable, the device must be re-imaged (encrypted data is not recoverable).

Locked out of SSH

• Your management host may have been banned after failed logins. Add it to the SSH ignore list to prevent this.
• Check the source allow/deny lists — your address may not be permitted.
• Administer the device through remote access while you fix SSH settings.

A USB device is rejected

• USB device control is enabled and the device does not match an allow rule. Add a rule for it, or confirm an existing rule matches its ID, port, or interface.

An OS upgrade did not complete

• Confirm the device can download the new version (connectivity and any proxy).
• A device that fails to start a new version can fall back to the retained previous version; you can also roll back explicitly.

The device is out of storage

• Container images, workload data, and logs share the data area. Check storage usage in device metrics.
• Lower logging severity if logs are consuming space.

A change I made on the device reverted

• The change likely modified the read-only system image. Apply it through configuration instead — see how persistence works and settings supplied as files.

Next steps

Most of the checks above start with looking at a device. To do that without guessing, and to be told when something breaks rather than discovering it here, continue with Monitoring & alerts.

5 - Monitoring & alerts

Edge devices are, by definition, somewhere you are not. This section is about closing that gap: seeing what a device is doing, keeping the logs you need without drowning in the ones you don’t, and being told when something breaks rather than finding out from a customer.

There are two modes here, and it is worth knowing which one you are in. Looking at a device is what you do when you already suspect something. Alerting is what tells you to go look.

flowchart LR
    DEV["Devices and<br/>applications"] -->|"metrics"| M["monitoring.edgelq.com"]
    DEV -->|"forwarded logs"| L["logging.edgelq.com"]

    M --> LOOK["Device overview<br/><i>you go look</i>"]
    L --> LOOK

    M --> COND["Alerting condition<br/><i>threshold on a metric</i>"]
    COND --> POL["Alerting policy"]
    POL --> CH["Notification channel<br/><i>email, webhook, ...</i>"]
    CH --> YOU(["You are told"])

In this section

• Device overview

  A tour of the dashboard page for a single device: status, hardware details, resource metrics, live and historical logs, reboot, and terminal access.

• Device logs

  What a device forwards and at which severity, how to change it, and how to pull logs on demand instead.

• Alerts

  Alerting policies, conditions, and notification channels: the full path from a metric crossing a threshold to somebody being told.

• Alert metrics

  Which metrics are worth alerting on, and what a sensible threshold looks like for each.

• AI Alerting

  Letting the platform investigate a firing alert, and optionally remediate it, before it reaches you.

• Metrics reference

  The metric types devices report, with their kinds, units, and labels — what you need to query a metric or write an alerting policy as JSON.

• Audit logs

  Who did what, when, and what changed as a result.

What you need

• access to the SPEKTRA Edge dashboard
• a project with at least one provisioned device
• the cuttle CLI, for the parts that use it

If you are missing any of these, Get started sets them up.

5.1 - The Device overview page

Device overview is the dashboard page you will spend the most time on. For a single device it shows status, hardware details, resource metrics, and live logs, and it is where you reboot the device or open a terminal on it.

This page is a tour of that screen. For the fleet-wide view — alerting across many devices — see Alerts.

What you need

To go through this page, you need the following.

• access to the SPEKTRA Edge dashboard
• an active project
• a device provisioned under the project
• the cuttle CLI command configured on your machine

Device overview

Device overview page is the main dashboard to manage devices on SPEKTRA Edge.

To get there from Project overview page, click the Manage devices button located in the Devices section of the Project overview page.

Click the name of the device you want to manage to open its Device overview page.

Here on the Device overview page, you can do the majority of the tasks to manage devices, such as:

• observing the device’s status and device information, such as IP addresses, etc.
• getting the list of applications running on the device
• monitoring the device’s resource usage, such as CPU, memory, storage usage, as well as the device temperature.
• examining the device’s logs

Click Details tab of the Device overview page to show the detailed information about the device, such as:

• GPU type
• BIOS name
• Hard disk types and sizes
• MAC address of the network interfaces
• Network configuration

Device statuses

Here is the list of device statuses monitored on SPEKTRA Edge.

Device metrics

You can monitor the device’s resource usage on the dashboard, which includes:

• CPU
• Memory
• Storage
• Temperature

Click the Details tab of the Device overview page and scroll down to the Device metrics section. Select the metric type and the duration of time to show the time series of the resource usage.

Device logs

You can retrieve the device logs from the dashboard.

Go down to the Logs section of the Device overview page and click the Start button to retrieve the device logs. By default, you are observing the active logs and are kept updated whenever the new log come on the device.

To see the logs during the particular period, select the History option from the Device Logs menu and give the time range you’re interested in, then hit OK.

You can also download the logs for the further investigation by clicking the download icon on the Device Logs menu.

Control devices

You can reboot and shutdown the device from the dashboard.

Click the vertical triple dots right next to the Device overview title to show the pull down menu for the control options.

Select Reboot or Shutdown to take the actual action. Both ask you to confirm first — see Reboot, shutdown & recovery for what to expect, including why a shutdown may need someone on site.

The same menu is where you copy files on and off the device, with Upload files and Download file. See Transfer files.

Access devices

You can access the device console over SSH from the dashboard or the local terminal with cuttle command.

Access devices from dashboard

Go to the Terminal window of the Device overview page and click Connect button to access to the device console.

Access devices from your machine

You can access the device console from your local machine.

Click the Copy terminal as Cuttle command button in the Terminal window menu and paste it to the terminal of your local machine.

cuttle devices ssh projects/your-project/regions/us-west2/devices/pi03

The command you will get is different from the one above, as the different project name, etc.

Next steps

You can now read a single device’s status, metrics, and logs from the dashboard. Next, learn how to control what a device forwards, in Device logs.

5.2 - Device logs

Devices can forward their logs to the SPEKTRA Edge platform and you can also pull logs on demand. This lets you observe devices and workloads without logging into each one.

Forwarding logs to the platform

You can configure a device to forward its system logs and its container (workload) logs to the platform. The logging configuration lets you control:

• the minimum severity to forward, so you can keep volume manageable
• which system components to include
• whether container logs are exported

Forwarded logs are available on the dashboard and through the cuttle command-line tool.

Device log levels

SPEKTRA Edge supports the Syslog severity levels outlined in RFC5424 Section 6.2.1.

Here is the brief description of those log levels for your reference.

Setting the lower device log level means the device uploads the logs at that level and all the higher level logs.

Set it to the higher log level, e.g. Error, in case you want to reduce the logs forwarded by the particular devices.

Change device log levels

To go through this section, you need:

• access to the SPEKTRA Edge dashboard
• an active project
• a device provisioned under the project

Go to the Device overview page by clicking the device name on the Project overview page.

Open the Update device details page by clicking the Edit detail option of the device menu option.

Set the appropriate device log forwarding levels, e.g. Error, by selecting it in the Log forwarding minimum log level field.

That’s it!

Pulling logs on demand

Independently of forwarding, you can stream a device’s system or container logs on demand through remote access — useful for live troubleshooting without raising the forwarding level for the whole fleet.

Recommendations

• Forward at a moderate severity by default and raise it temporarily when investigating an issue.
• Use on-demand log streaming for live debugging rather than forwarding everything.
• Remember that logs stored on the device live on the data area; very verbose logging consumes data-area space.

Next steps

Congratulations on understanding various device logging levels supported on SPEKTRA Edge and how to change those.

Let’s move on to the next learning material, managing alerts on SPEKTRA Edge.

Onwards.

5.3 - Manage alerts

Let’s learn how to manage alerts on SPEKTRA Edge.

SPEKTRA Edge offers powerful alerting system built-in to monitor majority part of the system managed by the platform, includes devices and applications. The platform even allow you to extend the standard alert system by defining brand new alerts to meet your needs.

In this page, we will learn how to create standard alerts, the device connection status alert and the CPU utilization alert, to get familiar with the SPEKTRA Edge alerting system.

What you need

You need the following to setup the alerts on SPEKTRA Edge.

• access to the SPEKTRA Edge dashboard
• an active project
• a device provisioned under the project

Configure alerts

Let’s first understand how the alerting system is orchestrated in SPEKTRA Edge.

There are three main components in the SPEKTRA Edge alerting system.

1. alerting policies
2. alerting conditions
3. notification channels

The alerting policy is the top component to organize both the alerting conditions and the notification channels. It also contains the triggered alerts so that you can observe the historic alerts for the particular policy.

The alerting condition let you express the condition in which the alert happens, for example, the device loses the connection or the CPU utilization passes a certain threshold.

The notification channel expresses how and where the alert is sent, either through email or slack.

Please take a look at the following diagram to understand the relationship of those three components.

---
markmap:
  zoom: false
  pan: false
---

# Alerting policy

## Alerting conditions

- CPU utilization condition
- Memory utilization condition
- Disk utilization condition
- Device hardware temperature condition

## Notification channels

- Slack notification
- Email notification

## Triggered alerts

- CPU utilization alert fired at 11/10/2024 11:45 on device 5
- Memory utilization alert fired at 11/09/2024 09:45
  and resolved in 2 hours on device 2
- etc.

Let’s take a look at those more detail with the actual example.

Alerting policies

An alerting policy is the top level component to organize both the alerting conditions, notification channels, and the actual triggered alerts.

Select the Alerting policies option of the Alerts pull down-menu to go to the Alerting overview page.

Once you’re on the Alerting overview page, click the Create alerting policy button located at the top right corner.

Fill in the alerting policy name and click Create. We’ll fill in the notification channels in the later stage.

That’s it. Let’s move on to the alerting condition next.

Alerting conditions

Let’s create the alerting condition to detect the device connection status.

An alerting condition, as the name suggests, defines the condition to trigger alerts. It’s grouped in three different sections and we’ll go over those one-by-one in the following sections.

1. alert metrics
2. threshold conditions
3. time series configurations

But first, let’s open the Create alerting condition page by clicking the policy condition plus sign on the Alerting overview page.

Alert metrics

The alert metric section is the first thing to set on the Create alerting condition page. It gives you all the alerting options supported by the system. You could browse those to understand what are covered by the SPEKTRA Edge alerting system.

Let’s select the Device connected alert metric type for the device connection status alerting condition.

You don’t need to touch the resource filter section, which is automatically set by the system, unless you need the additional filtering.

Threshold conditions

The threshold conditions section is where to configure the alerting condition.

Here is the threshold condition for the device connection status alerting condition for firing alerts when the device is offline for more than five minutes.

Since the Online status is treated as number one and Offline as number zero, we use the Less than operator against the Online status to detect the device offline event. You set the duration time to five minutes to express the system to trigger alerts when the device is offline more than five minutes.

Time series configurations

The time series configuration section expresses how to aggregate data points for the targeted time series data. There are two time series aggregation functionalities here.

1. the alignment period with the per series aligner
2. the time-series grouping with the cross series reducer

Let’s take a look at the actual example to understand those two functionalities.

Here is the detailed description.

1. the alignment period to one minute with the Max per series aligner
2. resource.labels.device_id based grouping with the Min cross series reducer

The first aggregation is for the noise reduction. It treats the device is offline only when it’s offline for the entire one minute.

The second aggregation is to treat each devices under the project separately, which is the grouping part. Since there is only one state for the device connection, the reducer doesn’t mean anything. We’ll take a look at the other example and explain the usage of the reducer there.

Let’s click Save as you completed the device connection status alerting condition.

Here is the brief description of the typical aligners and reducers for your reference.

Great. Let’s move on to the notification channels next.

Notification channels

A notification channel allows you to configure how to notify alerts over multiple channels.

There are three types of notification channels supported by the SPEKTRA Edge.

1. Email
2. Slack
3. Webhook

Each channel will be created separately and be tied to the alerting policy to be operational. A single channel can be shared by multiple alerting policies

We will go over how to create all three channels below and link those to the alerting policy we’ve created in the previous step.

Select the Notification channels option of the Alerts pull-down menu to open the Alerting overview page.

Click the Create notification channel button to create a notification channel.

• Email
• Slack
• Webhook

To create the email notification channel, you need to

• select Email in the type field
• fill in the email address(es) in the Emails field

and click the Create button.

Click the Send button to send the test email notification to verify the configuration.

Enable the notification channel by clicking the Enabled switch once you verify receiving the test email notification from SPEKTRA Edge.

You need a webhook endpoint to configure the Slack notification channel on SPEKTRA Edge.

Go to the official slack api page and create your Slack app, if you don’t have one yet, by clicking the Create your Slack app button.

Once you have your Slack app, go to the Incoming webhooks section and activate the incoming webhooks by toggling the Incoming Webhooks switch On.

Create a new webhook endpoint by adding the new webhook to your Slack workspace.

Copy the webhook URL by clicking the Copy button of the newly created webhook URL.

Now, go back to the SPEKTRA Edge dashboard and set the webhook URL you just copied on the Create notification channel page after selecting the notification type to Slack.

Once the slack notification channel is created, let’s verify it by sending the test slack notification.

Go to the Notification channel overview page and click the Send button to send the test Slack notification.

Enable the notification channel by clicking the Enabled switch once you verify receiving the test Slack notification from SPEKTRA Edge.

To create the webhook notification channel, you need to

• select Webhook in the type field
• provide the webhook endpoint in the Webhook field
• add the Content-Type: application/json header in the Add headers field

and click the Create button.

Click the Send button to send the test webhook notification to verify the configuration.

Enable the notification channel by clicking the Enabled switch once you verify receiving the test webhook notification from SPEKTRA Edge.

Here is the sample alert JSON data sent over to the webhook endpoint for the device connection status alerting condition.

{
  "project": {
    "name": "projects/your-project",
    "title": "Your Project"
  },
  "events": [
    {
      "alertingCondition": {
        "name": "projects/your-project/regions/us-west2/alertingPolicies/device-connection-status-ny5lzm/alertingConditions/device-connection-condition-qv3w6g",
        "displayName": "Device connection condition",
        "spec": {
          "timeSeries": {
            "query": {
              "filter": "(resource.type = devices.edgelq.com/device AND metric.type = devices.edgelq.com/device/connected)",
              "selector": {
                "metric": {
                  "types": [
                    "devices.edgelq.com/device/connected"
                  ]
                },
                "resource": {
                  "types": [
                    "devices.edgelq.com/device"
                  ]
                }
              },
              "aggregation": {
                "alignmentPeriod": "60s",
                "perSeriesAligner": "ALIGN_MAX",
                "crossSeriesReducer": "REDUCE_MIN",
                "groupByFields": [
                  "resource.labels.device_id"
                ]
              }
            },
            "threshold": {
              "compare": "LT",
              "value": 1
            },
            "duration": "300s"
          },
          "trigger": {}
        }
      },
      "metricDescriptor": {
        "name": "projects/your-project/metricDescriptors/devices.edgelq.com/device/connected",
        "type": "devices.edgelq.com/device/connected",
        "metricKind": "GAUGE",
        "valueType": "INT64",
        "unit": "1",
        "displayName": "Device connected"
      },
      "alerts": [
        {
          "name": "projects/your-project/regions/us-west2/alertingPolicies/device-connection-status-ny5lzm/alertingConditions/device-connection-condition-qv3w6g/alerts/2024-11-20T01:33:00Z-5ftg31",
          "displayName": "Device connection condition  devices.edgelq.com/device {device_id:pp-quick-202410-bjr55hvm22jfhu}",
          "info": {
            "timeSerie": {
              "key": "BQHPAQoCGrEEHaQheAECGXc=",
              "metric": {
                "type": "devices.edgelq.com/device/connected"
              },
              "monitoredResource": {
                "type": "devices.edgelq.com/device",
                "labels": {
                  "device_id": "pp-quick-202410-bjr55hvm22jfhu"
                },
                "reducedLabels": [
                  "project_id",
                  "region_id"
                ]
              }
            },
            "observedValues": {}
          },
          "state": {
            "isFiring": true,
            "lifetime": {
              "startTime": "2024-11-20T01:33:00Z"
            },
            "needsNotification": true,
            "notificationCreated": true
          }
        }
      ]
    }
  ]
}

Enable alerting policies

With all those three components configured, We’re ready to enable the alerting policy to monitor the device connection status for all the devices under the project.

Go to the Alerting overview page by selecting the Alerting policies option of the Alerts pulldown menu.

Enable the alerting policy by sliding the Enabled switch to be on for the Alerting policy you created named Device connection status.

And also, let’s link the notification channels to the alerting policy so that we get notified whenever alerting status changes. Select the Edit details option of the alerting policy menu and provide the notification channels in the Notification channels field.

Great!

You’ve configured the alerting policy to detect the device offline status on SPEKTRA Edge.

Let’s simulate the offline connection status and observe what kind of information you can get from the SPEKTRA Edge alerting system.

Monitor alerts

Let’s pull the cable from one of your devices and see how the alert looks like.

After waiting for five minutes, you should be able to see the alert raised on the sidebar of the dashboard page.

Go to the Alerts page by selecting the Alerts option of the Alerts pull-down menu. You will see the Firing alert of the Device connection status alerting policy with the on-going alert duration and the device information.

Click the start time of the firing alert and get the detailed information of the alert. You can observe much more information of the alert firing including the link to the Device overview page of the device without the connection.

Example: CPU utilization alerting condition

Before wrapping up, let’s take a look at another example to understand how to configure alerting condition on SPEKTRA Edge.

Here is the CPU utilization alerting condition, which triggers alert whenever the average CPU utilization is more than 50% for half an hour.

Here is some of the highlight:

1. Threshold condition
   • Greater than is used as the comparison operator
   • 50% as the threshold value
   • 30 minutes as the duration time
2. Time series configuration
   • five minutes alignment period with Mean per-series aligner
   • Group by device_id with Mean cross-series reducer

Here is the summary of the time series configuration parameters.

1. using the Mean per-series aligner to get the average of the CPU utilization of the five minutes time period
2. using the Mean cross-series reducer to get the average of the multiple CPU time series to be treated as the devices CPU utilization data point

With those two aggregations, the system compares the aggregated data point to compare to the threshold condition, more than 50%, and raises an alert when it’s true for more than the duration time, 30 minutes.

Next steps

Congratulations on creating and monitoring alerts on SPEKTRA Edge. It’s a little long explanation but we hope you understand the insight of the SPEKTRA Edge alerting system as well as be ready to create your own alerting policies and conditions.

You know the machinery now. The harder question is which metrics are worth alerting on and where to set the thresholds — that is Alert metrics.

Onwards.

5.4 - Alert metrics and what to monitor

Let’s learn which metrics you can alert on with SPEKTRA Edge, and how to use them to keep an eye on remote devices without checking them by hand.

The Manage alerts page shows you how to build an alerting policy, using the Device connected metric as the example. This page focuses on the opposite question: which metric should you pick, and what each one is good for. Use it as a catalog when you create your own alerting conditions.

Why alert on more than “Device connected”

A device can stay connected and still be in trouble: a disk fills up, the CPU is pinned at 100%, a sensor overheats, an application stops responding, or a cellular link degrades to the point of dropping data. Connection status alone won’t tell you any of that.

By alerting on resource and health metrics, you get notified of these conditions before they turn into an outage, so you can act on a device that may be in a remote, hard-to-reach location.

Device metrics

These metrics describe the health of the device itself (resource type devices.edgelq.com/device).

Availability

A low Uptime value (for example, uptime resetting to near zero) is a good way to catch devices that are rebooting unexpectedly, even when they reconnect quickly enough that the connection alert never fires.

Compute

Sustained high CPU is the classic sign of a runaway process or an application consuming more than expected. Use a duration (for example, 30 minutes) so that short, legitimate spikes don’t trigger noise.

Memory

High memory utilization warns you before the device starts killing processes under memory pressure.

Storage

A full disk is one of the most common causes of failed application deployments and stalled log forwarding. Alert early (for example, at 85%) to leave time to clean up. The disk metrics are reported per mount point, so you can tell whether it’s the system area, the data area, or an additional partition that is filling up.

Hardware sensors

Thermal alerts are especially valuable for fanless or enclosed devices deployed in environments where ambient temperature isn’t controlled.

Network interfaces

These are grouped per interface, so you can monitor a specific uplink (for example, the wired interface) independently from others.

Cellular signal

For devices with a cellular modem, these metrics help you catch a connection that is slowly degrading before it fails.

A device on a weakening cellular link may still report connected, but alerting on signal quality lets you schedule maintenance (for example, repositioning an antenna) before it goes offline.

Health checks

If you configure host-level health checks on a device, their results are also available as metrics.

Health checks let you turn “is this specific service or endpoint reachable from the device” into an alert.

Application metrics

These metrics describe the applications (pods) running on your devices (resource type applications.edgelq.com/pod). Select Pod as the resource type when creating the alerting condition.

These let you alert on the workload itself — for example, an application that is unhealthy or consuming far more CPU than usual — rather than only on the device hosting it.

A recommended starting set

If you’re not sure where to begin, these conditions cover the most common problems for a fleet of remote devices:

Tips for fleet-wide alerts

• Group by device. In the time series configuration, group by resource.labels.device_id so each device is evaluated independently and a single policy covers your whole fleet. See the time series configuration section on the alerts page for details on aligners and reducers.
• Use a duration. Requiring a condition to hold for a few minutes filters out transient spikes and keeps notifications meaningful.
• Attach notification channels. Connect Slack, email, or a webhook so alerts reach you wherever you work. See notification channels.
• Let the platform tune thresholds for you. If picking exact thresholds is hard, consider AI Alerting, which adds anomaly detection and adaptive thresholds on top of these same metrics.

Next steps

Now that you know what to monitor, learn how the platform can investigate and even remediate alerts for you with AI Alerting.

5.5 - AI Alerting

Let’s learn how to use AI Alerting on SPEKTRA Edge to detect problems without hand-tuned thresholds, and to have an AI agent investigate and remediate alerts for you.

Managing remote devices means you can’t watch every dashboard all the time. AI Alerting is designed for exactly this: it notices unusual behavior on its own, figures out what is likely wrong, and either fixes it or escalates to a human with a written explanation.

This page has two parts:

1. Concepts — what AI Alerting is, its architecture, and how a fired alert is handled end to end. Read this first to build a mental model.
2. Setup — a hands-on walkthrough that builds one policy, field by field. Our example detects abnormal CPU behavior on devices and lets the AI agent restart the offending pod after your approval.

Concepts: what AI Alerting is and how it works

This part explains the moving pieces and how they fit together. No configuration yet — that’s Setup.

AI Alerting vs. Alerts

SPEKTRA Edge has two complementary alerting areas in the dashboard sidebar:

This page covers AI Alerting. You’ll find it under the AI Alerting entry in the sidebar (the AI Alerting overview page).

Architecture and end-to-end flow

AI Alerting reuses the same building blocks as classic Alerts — an alerting policy that groups conditions and notification channels — and adds two things on top:

1. Smarter conditions. In addition to fixed thresholds, a condition can use adaptive thresholds or anomaly detection. These are two different things — see Adaptive thresholds vs. anomaly detection below.

2. An AI agent that handles fired alerts. When an alert fires, the agent investigates, decides what is going on, and takes an action — see How the AI agent handles alerts below.

Putting those together, this is the end-to-end flow. However the alert is triggered — a fixed threshold, an adaptive threshold, or an anomaly detector — it enters the same AI handling pipeline: the agent gathers context (including your supporting docs and queries), decides what is going on, and then the outcome flows into whatever you configured — a notification, an automatic or approved remediation, or an escalation to a human.

flowchart TD
    %% --- Detection ---
    FT["Fixed threshold"]
    AT["Adaptive threshold"]
    AD["Anomaly detection"]
    FT --> FIRE
    AT --> FIRE
    AD --> FIRE
    FIRE(["Alert fires<br/>(after 'Raise after')"])

    %% --- Investigation ---
    FIRE --> INV["AI agent investigates"]
    LIVE["Metrics, logs,<br/>resource state"] --> INV
    DOCS["Supporting docs"] --> INV
    SQ["Supporting queries"] --> INV
    SSH["Read-only checks over SSH<br/>(if connectivity enabled)"] --> INV

    %% --- Decision ---
    INV --> DEC{"AI agent decides"}
    DEC -->|"transient blip"| IGN["Ignore"]
    DEC -->|"over-sensitive"| ADJ["Adjust condition"]
    DEC -->|"fixable"| REM["Remediation:<br/>Fix in SSH or Reboot"]
    DEC -->|"cannot resolve"| ESC["Escalate to operator"]

    %% --- Remediation approval gate ---
    REM --> AA{"Auto-accept<br/>enabled?"}
    AA -->|"no"| WAIT["Await operator approval"]
    AA -->|"yes"| APP["Apply automatically"]
    WAIT -->|"approved"| APP
    APP --> RECHECK{"Still firing?"}
    RECHECK -->|"yes"| ESC

    %% --- Outcomes notify channels ---
    IGN --> NOT
    ADJ --> NOT
    APP --> NOT
    ESC --> NOT
    NOT[["Notify channels:<br/>Slack / email / webhook"]]

Adaptive thresholds vs. anomaly detection

Both go beyond a fixed threshold, but they answer different questions.

Adaptive thresholds are still thresholds — an upper and/or lower bound. The only difference from a fixed threshold is that the platform computes the bound for you from recent history (by default, the last week) instead of you typing a fixed number. It looks at the range the metric actually reached, adds some buffer, and alerts when the value crosses that band. The question it answers is “is the value too high or too low right now?” — it just keeps the “too high / too low” line up to date as the device’s normal level drifts.

Anomaly detection is a learned model of behavior, not a bound. A small AI model (an LSTM autoencoder) is trained on the metric’s history and learns its normal shape over time — including how it rises and falls through the day. It then flags readings that don’t match that learned pattern. The question it answers is “does this look like how this device normally behaves?” — so it can catch a value that is unusual even though it never leaves the normal band (for example, CPU sitting flat at 40% overnight when it normally idles near 5%).

They also complement each other: while an anomaly detector is still training (or if it isn’t defined), the adaptive thresholds keep watch, so you have coverage from day one and sharper detection once the model is ready. A common setup is to enable adaptive thresholds and one or more anomaly detectors on the same condition.

How the AI agent handles alerts

When an alert fires — from any of the detection methods above — the AI agent runs a short loop: investigate → decide → act.

What the agent looks at

To diagnose an alert, the agent pulls together several sources of context:

• Live signals — the device’s metrics, logs, and resource state around the time of the alert.
• Supporting queries — predefined metric, log, or resource lookups attached to the policy. They run automatically when an alert fires and their results are handed to the agent, so it always starts with the data you consider relevant (see Add supporting queries).
• Supporting documents — natural-language references the agent reads while diagnosing (see the next section).
• Read-only device checks — only if you enabled agent connectivity, the agent may run safe, read-only commands on the device over the secure SSH tunnel.

How supporting documents are used

Supporting documents are natural-language references — runbooks, operational notes, known-issue write-ups — that you attach to a policy or condition. The agent reads them as context while diagnosing an alert; they are not code and they don’t run. They shape the agent’s understanding and its decision.

For example, a short runbook that says:

If the processor service spikes CPU right after a config push, it’s a known issue — restarting the pod is safe and resolves it.

lets the agent recognize the situation, explain it in its diagnosis, and confidently choose the Reboot remediation instead of escalating. Without that note, the same symptom might be escalated to a human because the agent has no way to know the restart is safe.

Good supporting documents are specific and action-oriented: they describe a symptom, what it usually means, and what a safe response is. They’re the main way you transfer your team’s operational knowledge to the agent. You attach them during setup (see Attach supporting documents).

What the agent decides and does

After investigating, the agent chooses one outcome:

1. Ignore — the cause looks transient and harmless.
2. Adjust — the condition was too sensitive; the platform retunes it.
3. Remediate — apply a Fix in SSH command or Reboot the affected pod. If auto-accept is off, the agent only proposes the fix and waits for an operator to approve it; if it’s on, the fix is applied automatically. If a remediation is applied and the alert keeps firing, the agent escalates.
4. Escalate — it can’t resolve the issue and hands off to a human.

Every step is recorded as an AI diagnosis note on the alert, so you can read how the agent reached its conclusion.

Guardrails: keeping the agent safe

A few guardrails are built in and worth knowing:

• The agent only connects to a device when you enable agent connectivity; otherwise it works from collected metrics and logs alone.
• You can restrict which command-line tools the agent may use during investigation, limiting it to a known-safe set.
• Remediations are limited to the kinds you allow (Fix in SSH and/or Reboot), and — unless you enable auto-accept — require your approval before anything runs.

Setup: create and configure a policy

Now the hands-on part. We’ll build the CPU example from the top of the page: detect abnormal device CPU, and let the agent restart the offending pod after your approval.

What you need

• access to the SPEKTRA Edge dashboard
• an active project
• a device provisioned under the project (and, for the reboot example, an application running as a pod on that device)
• optionally, one or more notification channels already created

Create the policy

Go to AI Alerting → Policies in the sidebar to open the AI Alerting overview page, then click Create policy in the top-right corner.

The Create policy page is a single form. We’ll walk through it top to bottom.

1. Choose a template and name the policy

• Template — start from a predefined set of conditions (for example, a base device or pod template). Templates come with sensible conditions already filled in, which you can tune later. For our example, pick a device template. Note that the template cannot be changed after the policy is created.
• Display name — a human-readable name, for example Device CPU anomaly.
• Description — optional free text describing what the policy is for.

2. Attach supporting documents and notification channels

• Supporting docs — attach the runbooks or notes the agent should read while diagnosing an alert (this is the feature described in How supporting documents are used). It’s optional but makes the agent noticeably better.
• Notification channels — select the same Slack, email, or webhook notification channels you use elsewhere. You can leave this empty and add channels later.

3. Enable the AI agent and pick remediations

This is the heart of AI Alerting. Turn on AI agent enabled to switch on AI-powered analysis and remediation for alerts raised by this policy. Two more controls appear once it is on:

For our example, enable the AI agent, enable connectivity, leave auto-accept off, and select both Fix in SSH and Reboot as allowed remediations.

4. Set the processing location and resource

• Remediations and Processing location sit side by side on the form. For Processing location, choose Backend (in the cloud) or Edge (on the device itself). Edge processing keeps detection working locally even when connectivity to the cloud is intermittent; Backend is the right choice for metrics that only make sense centrally (such as connectivity). This field cannot be changed after creation. For our anomaly-detection example, keep it on Backend — on-device anomaly detection is coming soon, but today anomaly models run in the backend (adaptive and fixed thresholds work in either location).
• Resource — the resource type this policy monitors, for example Device or Pod. The Reboot remediation is only available when the policy can identify a pod.

5. (Optional) Add supporting queries

Supporting queries are the predefined lookups described in What the agent looks at. They are gathered automatically and handed to the agent as context whenever an alert fires. Click Add query and choose a Type:

• Time series query — a metric lookup with a filter and aggregation (alignment period, per-series aligner, cross-series reducer, group-by fields).
• Log query — a log lookup with a filter.
• REST get / REST list query — fetch a resource (or a list of resources) from a SPEKTRA Edge service, using an endpoint, path, view, and field mask.

Filters use templates, so you can reference the alert’s labels with <label_key> placeholders (for example resource.labels.device_id="<device_id>"). The built-in <project_id> and <region_id> placeholders are always available.

When the form is complete, click Create to save the policy.

Add conditions

A policy without conditions never fires. Open your new policy from the AI Alerting overview page and add a time series condition (the template you picked may have already added some, which you can edit or delete).

Each condition defines one or more queries (metric filter + aligner + reducer) and how they turn into alerts. You can use fixed thresholds, adaptive thresholds, and anomaly detection — together if you like. For the difference, see Adaptive thresholds vs. anomaly detection.

Threshold and adaptive thresholds

Set a Threshold to alert when a value crosses a fixed bound. To make that bound adapt to the device’s own history instead of being a fixed number, turn on:

• Auto adapt upper — the platform maintains the upper bound for you.
• Auto adapt lower — the platform maintains the lower bound for you.

With adaptive thresholds you can still set hard guard rails (a maximum upper and a minimum lower bound) so the adaptive value never becomes too tolerant or too sensitive. The platform derives the adaptive bound from historic data (by default the last week) plus a configurable buffer.

Anomaly alerting

Add an entry to the Anomaly alerting list to catch deviations from the metric’s learned pattern. This trains a small AI model on the metric’s history, so it needs a training period before it starts detecting. The key fields are:

• Analysis window — the sliding window of data the model looks at each time.
• Training period — how much history the model learns from before it starts flagging deviations (at least one day).

A good starting pattern is one wide, coarse detector (a long analysis window with a larger step) to catch slow drifts, plus one narrow, fine detector to catch sudden spikes.

Raise after / silence after

For both methods you can set:

• Raise after (sec) — how long the condition must hold before an alert fires (noise reduction).
• Silence after (sec) — how long after violations stop before the alert clears.

Save the condition when you’re done.

Enable the policy

Back on the AI Alerting overview page, slide the Enabled switch on for your policy. Detection (and, once alerts fire, the AI agent) is now live.

Reading alert state

On the AI Alerting overview page, the alerts tables show the handling state:

Open an alert to see the full AI diagnosis, the proposed remediation, and the controls to Approve a remediation or Acknowledge the alert.

Choosing which events notify you

For AI Alerting you can pick exactly which lifecycle events send a notification on each channel, including:

• New firing — a new alert started.
• AI escalated to operator — the agent needs a human.
• AI remediation awaiting approval — a fix is proposed and waiting for you.
• AI remediation applied / Operator remediation applied — a fix was applied by the agent or by a person.
• Stopped firing — the alert cleared.

Next steps

Combine AI Alerting with well-chosen alert metrics for broad coverage, and route everything through your notification channels so you hear about remote devices the moment something looks wrong.

That completes monitoring. Next, Accounts & access covers who on your team can see and change all of this.

5.6 - Device metrics reference

The dashboard shows device metrics by friendly name — “CPU utilization”, “Memory used”, “Mobile Network RSRP”. To query one from the API, write an alerting policy as JSON, or export to an external system, you need its metric type instead: the identifier the platform actually stores it under.

This page lists them.

Reading the table

Metric type is the identifier to use in queries and alerting conditions.

Kind describes how values relate over time, and determines which aggregations make sense:

Value type is INT64, DOUBLE, or DISTRIBUTION. A distribution holds a bucketed spread of values, not a single number, so conditions on it must select a statistic instead of comparing directly.

Labels are the dimensions you can filter and group by, in addition to the resource labels every device metric carries.

All metrics on this page are reported against the monitored resource type devices.edgelq.com/device, whose device_id label identifies the device.

Connectivity and uptime

connected is the metric behind connectivity alerting, and the one most fleets alert on first. See Alerting on device metrics.

CPU

Because cpu_number is a label, per-core series are reported separately. Group across it for a whole-device figure, or a busy single core on an otherwise idle machine will read as low utilization.

Memory

The state label on memory/stats takes the values buffered, cached, free, used, shared, and available — so this one metric gives the whole breakdown instead of needing several.

Disk

Disk metrics are per mount point. On a device with separate system, data, and configuration areas that is what you want — but an alert must say which mount point it cares about, or a full data partition can hide behind an empty one.

Hardware sensors

Availability depends on the hardware: a device with no fan reports no fan speed. Which sensors exist is visible on the device’s detail page before you build an alert on one.

Alert on temperature for devices in uncontrolled environments — a cabinet in direct sun behaves differently in August.

Cellular signal

These are distributions, not single values, because signal strength varies continuously and a single sample is misleading. An alerting condition must pick a statistic from the distribution rather than compare the metric directly.

The cell identity labels make it possible to distinguish “this device has poor signal” from “every device on this cell has poor signal” — which are different problems with different fixes.

Health checks

These appear only for health checks you have configured, and the healthcheck_name label is the name you gave the check. Round-trip time is available for HTTP and ICMP checks.

Alerting on response time as well as status catches degradation before outright failure, which is usually the more useful signal.

Network interfaces

All six are cumulative counters, so alert on a rate rather than a value. A threshold on the raw number would fire on every device eventually, purely through uptime.

Drops are the interesting ones on cellular and Wi-Fi links, where a rising drop rate often precedes a connectivity alert and gives you earlier warning.

Discovering metrics yourself

This list covers metrics devices report. Applications, and any service you enable, contribute their own. The authoritative list for your project is the metric descriptors it holds, which you can read directly:

cuttle monitoring list metric-descriptors --project $PROJECT -o json

Each descriptor carries the same information as the tables above, so this is also the way to check units and label keys for a metric not listed here.

Next steps

• Alerting on device metrics — turning these into alerts.
• Monitor a device — where they appear in the dashboard.

5.7 - Audit logs

Every call made against your project is recorded: who made it, what they asked for, whether they were allowed, and what changed. This is the record you need when answering “who deleted that device”, when demonstrating compliance, and when working out why a configuration is not what you thought it was.

In the dashboard this appears as Event Logs.

Two records per change

Auditing produces two related kinds of record, and knowing which one answers your question saves a lot of scrolling.

The relationship is one-to-many: a single API call can modify several resources, so one activity log may have several resource change logs beneath it. They are tied together by a request ID that appears on both, which is what lets you go from “this device was modified” to “because this person called this method”.

That correlation is the main thing to know. Investigating an unexpected change means finding the resource change log, taking its request ID, and looking up the activity log that shares it.

What an activity log records

Because devices authenticate as service accounts, they appear here as principals in their own right — so the audit trail covers what your fleet did, not only what your people did.

Categories

Category is the most useful filter, because it separates the handful of records that represent real change from the very many that do not.

Two of these deserve attention.

SpecUpdate is the category for “somebody changed something”. Filtering to it removes the noise of devices reporting status — which is by far the highest volume of audit activity in any real fleet — and leaves deliberate configuration changes.

Rejected records attempts that were refused. A cluster of them is worth understanding: it is either a misconfigured integration retrying, or someone probing for access they do not have. Neither is visible if you only look at what succeeded.

Internal explains changes that appear to have no author. When a role binding materializes on a group member, no person did it — a controller did, in response to something a person did earlier.

Before and after

A resource change log carries the state of the resource before and after the change, which is what makes it possible to answer not just “was this modified” but “what was it previously”. In the dashboard this is the change diff.

This is the fastest route to recovering a configuration someone changed by accident: the previous value is in the record, so it can be put back.

Transactions

Change logs also carry transaction information, including a state, and this affects how you read them.

A change may be recorded as pre-committed before it is known to have succeeded, and is followed by a further record saying whether it was committed or rolled back. If the platform retried the transaction there may be several pre-committed records for one change.

So a pre-committed record is not evidence that a change took effect. Look for the committed record, and where several records share a transaction, the last one describes what actually happened.

Retention

Audit records are not kept forever — retention is governed by policy, alongside metrics and logs. If you have a compliance requirement for a particular retention period, confirm the policy on your project meets it, and export elsewhere if you need to keep records longer than the platform holds them.

Check it before you need it, since the records you wish you had are always the ones that have already aged out.

Practical use

Investigating an unexpected change. Filter to SpecUpdate on the resource in question, read the before and after, then use the request ID to find who made the call.

Reviewing access. Filter to Rejected to see what is being refused, and look at the authentication field to see which principals are trying.

Understanding fleet behavior. Filter by a device’s service account to see what one device has been doing.

Establishing a timeline. Filter by principal and time range to reconstruct a sequence of actions in order.

Next steps

• Logs — application and system logs from devices, which are a different thing from the audit trail.
• Accounts & access — the roles and bindings whose use is being recorded here.

6 - Secrets

Applications need credentials: a token for a private container registry, a password for a database, an API key for a third-party service. Baking these into container images or into a compose file puts them in your source control and in every copy of the image, which is exactly where you do not want them.

Secrets hold those values on the platform instead, and deliver them to workloads at the point of use.

What a secret holds

A secret is a set of key-value pairs, stored encrypted, with the values base64-encoded. One secret can hold several related values — a username and a password, or a certificate and its key — so it maps naturally onto “the credentials for one thing”.

Access to the values is a separate permission from access to the secret. A principal can be allowed to see that a secret exists, and to see its name and description, without being allowed to read what is inside it. This is what makes it safe to give broad read access to a project without handing over every credential in it.

Use that distinction deliberately when granting roles: reading secret values is the permission to be careful with.

Where a secret lives

A secret can be placed at one of three scopes, and the choice matters more than it appears.

Using a secret

The two common uses both come from deploying applications.

Pulling from a private registry. Store the registry credentials in a secret and reference it as the image pull secret for your deployment. See Private container registry for the full walkthrough.

Passing configuration into a container. Reference the secret when deploying, and its values are made available to the container as a mounted volume, without appearing in your compose file.

For configuration that is not sensitive, use a config map instead. Config maps and secrets work the same way from a deployment’s point of view; the difference is that a config map’s contents are not treated as sensitive, so they are simpler to inspect and to reason about. Keep genuinely secret material in secrets and everything else in config maps, instead of putting all configuration in secrets because it is one fewer concept.

Rotating a secret

Updating a secret changes the stored value, but a running workload holds what it was given when it started. Rotation therefore has two steps, and skipping the second is the usual mistake:

1. Update the secret.
2. Restart the workloads that consume it, so they pick up the new value.

Plan for both when rotating a credential under time pressure — a rotated registry password with un-restarted workloads looks like it worked until the next time an image is pulled.

What not to put in a secret

Use the right mechanism for each kind of credential:

Be clear about the distinction between the first two. A secret is something the platform stores for your applications. A service account key is how something authenticates to the platform. Putting a service account key into a secret so that a workload can call the API is reasonable; using a secret as your automation’s own credential store is not.

Good practice

• One secret per credential, named for what it is. A single secret holding everything means every workload that needs one value can read all of them.
• Grant value-read access narrowly. Most people who need to work in a project do not need to read its credentials.
• Create them per region from the start if you are multi-region, instead of discovering the gap when you expand.
• Rotate on a schedule you choose, not on the schedule an incident chooses for you. Knowing the restart step is required makes this much easier to plan.
• Remember the audit trail. Reads of sensitive data are API calls like any other, so audit logs can tell you who has accessed a credential.

Related

• Private container registry — the most common use, end to end.
• Application configuration — config maps and volumes.
• Service accounts — credentials for calling the API.

7 - Accounts & access

Let’s learn how to manage users on SPEKTRA Edge.

SPEKTRA Edge offers the Identity and Access Management (IAM) framework for the user management, which is based on the Role-Based Access Control (RBAC) mechanism. In other words, you apply the certain role or roles to the users or groups, which is called the role binding, to give the certain permissions to the particular individual or group of individuals.

It also has a concept of scope of role binding, which is that the permissions for the particular role only applicable in the certain scope. This means that the role binding happened at the project is only effective under that project, or sub-projects if those available, but not others, like parent projects.

This means that you can create a really powerful and effective user management mechanism with the well-organized projects or organization structure.

Put together, every grant of access on SPEKTRA Edge answers three questions: who, what, and where.

flowchart LR
    WHO["<b>Who</b><br/>a user, a group,<br/>or a service account"] --> RB
    WHAT["<b>What</b><br/>a role, such as<br/>Owner or Viewer"] --> RB
    WHERE["<b>Where</b><br/>a scope: an organization,<br/>a project, or a service"] --> RB
    RB["<b>Role binding</b>"] --> OUT(["This principal has this role's<br/>permissions — but only<br/>inside this scope"])

Scopes inherit downwards only. A role granted on an organization applies to the projects beneath it; a role granted on a project does not grant anything on its parent or on a sibling project.

flowchart TD
    ORG["Organization"] --> P1["Project A"]
    ORG --> P2["Project B"]
    P1 --> SP["Sub-project A1"]

    GRANT(["Grant Viewer<br/>on Project A"]) -.->|"applies"| P1
    GRANT -.->|"applies"| SP
    GRANT -.->|"does <b>not</b> apply"| ORG
    GRANT -.->|"does <b>not</b> apply"| P2

What you need

To grant access to users and groups, you need the following.

• access to the SPEKTRA Edge dashboard
• an active project

Roles

Granting access means choosing a role, so it is worth knowing what the roles mean before you grant anything. These are the pre-existing user roles offered by SPEKTRA Edge.

The owner role has full access to the services offered by SPEKTRA Edge under particular scope.

The admin operator role is similar to the owner role but does not have access to the third-party services, for example the watchdog service offered by Service Experience Insight. This is a good role for someone who manages the entire service, e.g., user management.

The devices and application operator roles are both for the application management. The devices operator role is good for someone who manages both devices and applications but the application operator is for the application management only.

The viewer role has read access to core services but no write access. This is a good role for someone who only monitors or observes core services.

Grant access to users

With a role in mind, you can grant someone access.

Click the Grant access button in the Manage resources and access of this project blue bar on the Project overview page, which will ask you for:

• the E-mail address of the person you want to give access to the project
• the role to be assigned to the person.

Organize users by groups

You can create a group to manage multiple users in one-shot.

One good example of the group usage is to grant access to multiple users in a single operation, as explained in the following section.

To create a group, click the Create group button on the Project overview page and fill in the required information, such as the name and the region, as well as the E-mail addresses of the members managed in the group.

Grant access to groups

You can grant access to the group, which is a great way to grant access to multiple users in the efficient fashion.

To do that, use the group E-mail address to grant access instead of the individual person’s E-mail. The group E-mail address is constructed by SPEKTRA Edge with the following convention.

[Group name] @ [Project name] .groups.iam.edgelq.com

You can also get the group E-mail address on the groups overview page under your project.

Grant access by clicking the Grant access button on the Project overview page. Give the group E-mail address, your-team@your-project.groups.iam.edgelq.com for this example, and the role you want to grant access to the group.

You can check the roles for the group members by going to the Access page under the IAM section. You can see all the group members have the same role of the group’s role.

In this section

• Organizations and projects — how projects and organizations are structured, what descendants inherit, and the choices that are hard to undo.
• User authentication — sign up, sign in, and set up multi-factor authentication.
• Service accounts — identities for automation and devices, and the keys they authenticate with.
• Manage resource limits — the resource quotas that apply to a project, and how to request and approve changes to them.

Next steps

Congratulations on understanding how to manage users on SPEKTRA Edge.

With the power of the scope based role binding, you can conduct the user management with achieving the high security standard.

The role binding is one side of the user management coin. The other side of the user management is the user sign-up and sign-in.

Let’s dive into user authentication to understand the full picture of the user management on SPEKTRA Edge.

7.1 - Organizations and projects

Before you create anything on SPEKTRA Edge you make two structural decisions: how to divide your fleet into projects, and how those projects sit under organizations. Both are cheap to get right at the start and awkward to change later, because a resource’s name — and therefore its identity — includes the project it belongs to.

This page explains the model and flags the choices to make deliberately.

Projects

A project is the unit of ownership and isolation. It holds devices, applications, secrets, metrics, alerting policies, and the role bindings that say who may touch them. Almost every resource on the platform lives inside one.

Two projects share nothing by default. A device in one is invisible to the other, a secret cannot be read across the boundary, and access granted in one grants nothing in the other. That makes the project the natural boundary for anything you want kept genuinely separate — customers, environments, business units.

The trade-off is that separation is not free. Anything you want to see across projects — a fleet-wide view, one alerting policy, a single dashboard — has to be assembled per project, because queries do not span them. Split for isolation you actually need, not for tidiness.

Organizations

An organization groups projects, and organizations can nest inside other organizations to mirror how your business is actually structured.

An organization carries three things its descendants inherit:

• Access. A role binding at organization level applies to every project beneath it. This is how you grant a platform team access once instead of project by project.
• Region policy. Which regions descendants may use, and which is the default.
• Which services descendants may enable, and the default business tier they get.

Inheritance flows downward only. A role granted on a project confers nothing on its parent organization or on a sibling project. When someone can see more than you expected, look upward from the resource, not sideways.

Every project records its full ancestry, so the effective access on a resource is the union of every binding from the root organization down to the project holding it.

Regions

A project’s region policy does two jobs:

• Enabled regions — the complete set of regions in which resources may be created. Creating a resource outside them is refused, not silently redirected.
• Default region — the one that handles resources not tied to a region of their own.

Region is part of a resource’s identity, not a routing hint, so the choice has consequences beyond latency:

• Limits are per region. A project enabled for two regions has two separate allowances for each resource type, not one shared pool. See Resource limits.
• Secrets do not cross regions. A secret in one region is not visible to a device in another; a multi-region fleet needs the secret created in each region it occupies. See Secrets.
• Queries are per region unless you deliberately widen them. The - wildcard reads across every region a project uses.

Enable the regions you need and no more. Adding one later is straightforward; having resources scattered across regions nobody meant to use is not.

Choices that are hard to change

Most of what you set when creating a project can be edited afterwards. These cannot, or not without disruption.