Elias Groot

Software Lead, Project Administrator

Service

A service is a self-contained software package that is meant to run in a pipeline. It can be any normal Linux program, such as a binary, a python file or a bash script. Any service is defined by a service.yaml file which describes how the service should be built and run, and how it can communicate with other services.

Service Folder and service.yaml

A service should be self-contained: all files must be contained in one root folder that can be ported across Linux installations. At the root of each service folder should be a service.yaml file. The following is an example of a valid service.yaml

service.yaml

# Service identity
name: example-service
author: vu-ase
source: https://github.com/vu-ase/example-service
version: 1.0.0

# Optional alias to change the name of the service in a pipeline
as: controller

# The rover will execute these commands to build and start the service
# NB: they will be executed with cwd set to the service folder, where the service.yaml file is located
commands:
  build: make build # this can be any shell command, or a file to execute in the current working directory
  run: ./bin/example-service  # this can be any shell command, or a file to execute in the current working directory

# From each service, describe which stream we are interested in
inputs:
  - service: imaging
    streams:
      - track
      - debug
  - service: controller
    streams:
      - decision

# The names of the streams that this service will produce
outputs:
  - trajectory

# Here you define options values that can be accessed during runtime, by the roverlib
configuration:
  - name: speed
    value: 1.0
    type: number # this is represented as a float/double value
  - name: ki
    value: 123
    type: number
    tunable: true # do you want to be able to change this value during runtime?
  - name: kp
    value: 456
    tunable: true
    type: string 

The example is also available here. Contents of a service.yaml file are validated according to the formal specification JSON schema that can be found here. roverd validates a service.yaml file using the rovervalidate library.

Fully Qualified Name (FQN)

A service is uniquely and fully qualified by the tuple of author, name and version. A service alias (the as field) is not considered in the FQN.

Alias

Service communication is name-bound and all services operate in the same namespace when enabled in a pipeline. To differentiate between services, an alias can be specified using the as field. roverd will validate the service as if it has the name of this alias.

Effective Name (EN)

The effective name is the name by which other services can find and communicate with a service.

• If no as field is specified, a service's effective name is defined by the name field in its service.yaml
• If an as field is specified, a service's effective name is defined by the as field in its service.yaml

Thus, the as field takes precedence to define the effective name of a service.

Rover Installation Directory

On the Rover, services are stored using their FQN using the following directory structure:

/home/debix/.rover/<AUTHOR>/<NAME>/<VERSION>

Build-time and Runtime

Both commands.build and commands.run will be executed in a sub-shell by roverd. The working directory will be set to the service directory (the directory with the service.yaml at the root). The commands are executed with the debix user login shell, which means that you have access to the same environment variables and installations as the debix user when SSH'ed (including the $PATH and $HOME environment variables).

In addition, roverd will statically verify the chain of inputs and outputs in the pipeline and will inject a bootspec environment variable when executing the commands.run command.

global dependencies

If your service depends on global dependencies (such as pip packages or global header files), you need to make sure that these are available to the debix user.

Logs

If commands.build fails, an error will be reported and the build logs (STDOUT and STDERR) will be returned by roverd. Only the logs for the last build are saved.

For commands.run, all output on STDOUT and STDERR is captured and saved to a log file that can be queried through roverd. Logs for multiple runs are persisted and can be queried until the Rover is restarted.

Exit Codes

If commands.run exits, the entire pipeline will be terminated. The exit code will be saved and can be queried through roverd.