Production setup

The previous chapters have covered a lot about how to work with edges. Here we will go through the steps for a typical production setup where an edge is prepared for running in a production scenario.

Most of the information in this chapter will be known from other chapters in the documentation, but here we connect the previous chapters and put them in a context by illustrating a typical production setup.

The steps we will cover are as follows.

1. Write models and publish to central repository
2. Set up the edge on the server
3. Install SA Engine on the edge
4. Write a connection script in OSQL
5. Write a startup shell script
6. Configure the edge device to run on boot
7. Reboot edge

1. Write models and publish to central repository

In the work leading up to a successful production scenario there is first a development phase in which the models containing the analytics pipelines are produced. During the development phase, code gets deployed to the edge devices regularly to test, verify, and validate functionality. This kind of interactive development on real edge devices is vital for developing and building confidence that the models will achieve the desired result.

When the analytics pipelines have been properly tested and it is time to deploy them to production, the models needs to be prepared to run in a production environment. This includes structuring the model code to run autonomously on the edge device, packaging the model, and putting it in a central model repository to enable access.

Structuring the model code

A model consists of one or more OSQL files and potentially some other files (like data files), and how to work with models is covered in depth in the Model management documentation.

For a model to run in production it has to use edge queries (EdgeQuery) that starts the model when it is loaded and runs autonomously. Edge queries are described in the Persistent edge queries documentation.

The figure below shows the typical contents of a model that is set up to run autonomously in production.

Contents of a typical production model.

A typical production model has the following contents.

1. Imports that load any dependencies.
2. A "body" with functions making up the analytics pipeline.
3. An EdgeQuery table with one entry for each pipeline to trigger when the model starts.
4. Calls to each edge query at the end of the model to start the analytics pipelines.

Packaging and publishing the model

When the model code is structured correctly for a production scenario, the model needs to be packages and published to a central model repository from which it can be loaded by the edge devices. How to package and publish models is described in the Model releases documentation.

Package model and publish to a central model repository.

2. Set up the edge on the server

Before SA Engine is configured on the edge device, the server needs to be configured for communicating with the edge.

This includes the following steps.

1. Creating a connection blob for the edge so the edge can connect to the server.
2. Add the edge to an edge group on the server.
3. (optional) Configure edge to run in ONLINE mode.
4. Specify which model(s) to run on the edge.

How to create a connection blob is described in the Connecting edges to a federation documentation.

How to add an edge to an edge group is described in the Managing deployment to fleets of edges using groups documentation.

How to configure the edge to run in ONLINE mode is described in the Edge modes documentation.

How to specify which model(s) to run ton the edge is described in the Assigning models to edge groups documentation.

Setting up the edge on the server side.

3. Install SA Engine on the edge

Once the edge has been set up on the server it is time to prepare the edge device itself. The first step in this is to install SA Engine on the edge device. How this is done varies between different hardwares and also depends on any existing software infrastructure on the device (such as containers or web-based software deployment tools). But typically this is done by copying and unpacking the SA Engine release package on the device and adding the path to SA Engine executable to the default path environment variable.

How to install SA Engine on various devices is described in the Installing SA Engine documentation.

Install SA Engine on the edge device.

4. Write a connection script in OSQL

When SA Engine starts on the edge it just sits idle. To get it to connect to the server it needs to run an OSQL "connection script" on startup with code instructing it to connect to the server. A connection script typically contains two things.

1. Some configuration code that is needed for setting up the edge instance properly and connecting.
2. Code for establishing the connection to the server.

The first is not always needed; it depends on the infrastructure setup and custom configuration needs (for example updating the connection blob with local port information).

The code for establishing the connection to the server is simply a call to reconnect_using_config_blob() that uses the connection blob produced earlier to connect to the server.

The connection script will be fed to SA Engine on startup by using the -O flag when running the SA Engine binary.

sa.engine -O connect.osql

OSQL connection script.

5. Write a startup shell script

To be able to start SA Engine on the edge without having to run it manually through an interactive shell, there needs to be a startup script that can run SA Engine every time the device reboots. How this is done varies between operating systems. But for a typical Linux environment this is simply a shell script that sets up some environment variables and then starts the SA Engine process by calling the SA Engine binary with the connection script as input.

Shell startup script for SA Engine.

6. Configure the edge device to run on boot

To get the edge device to connect and run its models on startup, there needs to be some mechanism in place to execute the startup shell script whenever the device boots. How this is done varies between operating systems. But for a typical Linux environment this is preferably done by setting up a systemd service to run the startup script. How to run SA Engine as a systemd service is described in the Run an edge as a service documentation.

In short this means copy the startup scripts to the edge device, write a systemd service file for SA Engine, install the service file in systemd, and reload the systemd daemon. Once that is done there should be a systemd service that takes care of starting SA Engine on the edge whenever the edge device is restarted.

Setup start script as service on edge device.

7. Reboot edge

When a service that manages SA Engine is in place on the edge device SA Engine will start whenever the device is rebooted (or when the service is started manually).

If all the previous steps have been completed and SA Engine starts on the edge device, a number of things will happen in sequence.

1. The edge runs the setup scripts which starts SA Engine and establishes a connection to the server.

Connect to server.

2. The server tells the edge to run in ONLINE mode (if that was configured on the server), and the server tells the edge which models it should run.

Get instructions from server about ONLINE mode and which models to run.

3. The edge downloads the model(s) from the central model repository (if not previously downloaded) and runs the models.

Download and run models.

4. The edge is now running the model(s), which process data streams and send results to various receivers depending on how the model(s) were implemented.

Run analysis and feed results to specified receivers.

That is it. The model(s) will now be running on the edge device until it is turned off or until the edge group on the server is assigned new models to run.