talaria

(pronounced "tuh-laa-ree-uh")

Summary

Talaria's primary function is to interact with the devices: forwarding device events and sending requests to the device then forwarding the response. The communication with the device happens over a websocket using WRP Messages.

Table of Contents

• Code of Conduct
• Details
• Build
• Deploy
• Contributing

Code of Conduct

This project and everyone participating in it are governed by the XMiDT Code Of Conduct. By participating, you agree to this Code.

Details

Device Interaction

Talaria's primary function is to interact with the devices. The communication with the device happens over a websocket using WRP Messages.

Talaria can send events originating from the device as well as emit its own events. When this occurs, the event is sent to Caduceus.

Talaria has three API endpoints to interact with the devices connected to itself. A XMiDT cloud client should not directly query against a talaria. Instead, they should send a request through scytale.

Device Statistics - /device/{deviceID}/stat endpoint

This will return the statistics of the connected device, including information such as uptime and bytes sent. This request does not communicate with the device, instead the request returns stored statistics.

Get Devices - /devices endpoint

This will return a list of all the actively connected devices and their statistics, just like the stat command.

⚠️ Warning: this is an expensive request. Use with caution. This is not recommended to be used in production.

Send WRP to Device - /device/send endpoint

This will send a WRP message to the device. Talaria will accept a WRP message encoded in a valid WRP representation - generally msgpack or json. If the message is json encoded, talaria will encode the payload as msgpack. Talaria will then forward the message to the device. If the device returns a message, it will be encoded as the HTTP accept header. msgpack is the default encoding of the wrp message.

Control Devices

A secondary function of talaria is to control the connected devices. This allows for the flow of devices to go towards specific talarias. In other words, where the websockets are made can be controlled. For more information refer to Control Server Docs.

Gate Devices - /device/gate endpoint

This will allow or deny devices to connect to the talaria instance.

Drain Devices - /device/drain endpoint

This will remove the connected devices from the talaria instance.

Open Fail

Talaria's default functionality is to allow for devices without authorization to connect. There is an optional failOpen property that can be added to the talaria configuration and set to false in order to disable this feature. This should be it's own property and not nested under any other properties. In order to enable the open fail feature either set the property to true or remove it from the configuration file if previously added.

Build

Source

In order to build from the source, you need a working Go environment with version 1.11 or greater. Find more information on the Go website.

You can directly use go get to put the Talaria binary into your GOPATH:

GO111MODULE=on go get github.com/xmidt-org/talaria

You can also clone the repository yourself and build using make:

mkdir -p $GOPATH/src/github.com/xmidt-org
cd $GOPATH/src/github.com/xmidt-org
git clone [email protected]:xmidt-org/talaria.git
cd talaria
make build

Makefile

The Makefile has the following options you may find helpful:

• make build: builds the Talaria binary
• make docker: fetches all dependencies from source and builds a Talaria docker image
• make local-docker: vendors dependencies and builds a Talaria docker image (recommended for local testing)
• make test: runs unit tests with coverage for Talaria
• make clean: deletes previously-built binaries and object files

RPM

First have a local clone of the source and go into the root directory of the repository. Then use rpkg to build the rpm:

rpkg srpm --spec <repo location>/<spec file location in repo>
rpkg -C <repo location>/.config/rpkg.conf sources --outdir <repo location>'

Docker

The docker image can be built either with the Makefile or by running a docker command. Either option requires first getting the source code.

See Makefile on specifics of how to build the image that way.

If you'd like to build it without make, follow these instructions based on your use case:

• Local testing

go mod vendor
docker build -t talaria:local -f deploy/Dockerfile .

This allows you to test local changes to a dependency. For example, you can build a Talaria image with the changes to an upcoming changes to webpa-common by using the replace directive in your go.mod file like so:

replace github.com/xmidt-org/webpa-common v1.10.8 => ../webpa-common

Note: if you omit go mod vendor, your build will fail as the path ../webpa-common does not exist on the builder container.

• Building a specific version

git checkout v0.5.7 
docker build -t talaria:v0.5.7 -f deploy/Dockerfile .

Additional Info: If you'd like to stand up a XMiDT docker-compose cluster, read this.

Kubernetes

A helm chart can be used to deploy talaria to kubernetes

helm install xmidt-talaria deploy/helm/talaria/

Deploy

For deploying a XMiDT cluster refer to getting started.

For running locally, ensure you have the binary built. If it's in your GOPATH, run:

talaria

If the binary is in your current folder, run:

./talaria

Contributing

Refer to CONTRIBUTING.md.