Communications

This document describes the components in EVE that are responsible for communications between an EVE instance and a Controller. Read about the API for Device to Controller Communications here

All of these are components of pkg/pillar, which is the set of process, commands and services responsible for managing an EVE device.

Overview

An EVE instance is controlled via a Controller. EVE is responsible for:

  • Opening a communications channel with its Controller
  • Requesting its configuration on a regular basis
  • Updating any of its components that require updating based on the updated configuration
  • Communicating any events, such as logs or metrics, that need to be sent to the Controller

Architecture

Within pillar, each process, command or service that needs to communicate with the Controller does so directly; there is no local proxy or buffering engine process that stands between these processes and the Controller.

However, common logic for communications is extracted out to the package pkg/pillar/controllerconn. Each service that needs to communicate with the Controller imports the controllerconn package and uses its functions to communicate with the Controller.

The overall architecture is as follows.

+--------------------------+
|        Controller        |
++---+---+---+---------+---+
 ^   ^   ^   ^         ^
 |   |   |   |         |
 |   |   |   |         |
 |   |   |   |         |
 v   v   v   v         v
+++ +++ +++ +++      +-+--+
|c| |c| |c| |c|      | cc |  *cc = controllerconn package
|c| |c| |c| |c|      |    |
| | | | | | | |      |    |
| | | | | | | |      |    |
| | | | | | | |      |    |
|l| |n| |d| |c|      | z  |
|o| |i| |i| |l|      | e  |
|g| |m| |a| |i|      | d  |
|m| | | |g| |e|      | a  |
|a| | | | | |n|      | g  |
|n| | | | | |t|      | e  |
|a| | | | | | |      | n  |
|g| | | | | | |      | t  |
|e| | | | | | |      |    |
|r| | | | | | |      |    |
+++ +++ +++ +++      +--+-+
 ^   ^   ^   ^          |
 |   |   |   |          v
 +---+---+---+----------+
 |        pubsub        |
 +----------------------+

controllerconn - communications

In EVE, the shared functionality for communications with the Controller is encapsulated in the controllerconn package. All services communicate with the Controller using functions provided via the controllerconn package.

controllerconn is responsible for:

  • Creating SSL channels
  • mutual TLS (mTLS) and client authentication
  • Handling http logic, including status codes
  • Retries in case of loss of communication
  • Using multiple management ports to communicate with the controller

controllerconn does not handle protobuf analysis. It is blissfully unaware of the contents of most messages in both directions. It simply makes the request on behalf of, and passes the response back to, the requesting functions.

The logic in the services themselves do the following:

  • Create an instance of controllerconn.Client using the controllerconn.NewClient method
  • Package up any messages to be sent in protobuf
  • Pass the message to Send* methods of controllerconn.Client
  • Receive the response from controller
  • Unpack the received protobufs

services

The following are a few of the key services that communicate with the Controller via controllerconn.Client.

zedagent

zedconfig is the service responsible for retrieving configuration from the Controller and updating locally running services on EVE. Like all other services communicating with the Controller, it does so through the methods provided by controllerconn.Client.

zedagent is responsible for the following:

  • Maintaining a regular cycle for retrieving configuration or updates from Controller.
  • Requesting the configuration from the Controller via methods provided by controllerconn.Client.
  • Receiving the latest correct configuration in response to its request.
  • Saving the latest correct configuration locally.
  • Loading the initial (aka bootstrap) device configuration if present (see CONFIG.md)
  • Informing any services of changes to their relevant configurations via pubsub, which allows those services to restart or make changes in response to the updated configuration.

loguploader

Loguploader is the service responsible for uploading device and application gzip logs to controller. It does so through the methods provided by controllerconn.Client.

client

client is the service responsible for registering the EVE device with the Controller, as well as retrieving the initial configuration, as part of onboarding a new device to the Controller.

nim

Network interface manager is responsible for managing local network interfaces on the device, as well as checking connectivity to the Controller and retrieving the config for testing communications purposes. All communications with the Controller are performed via the methods provided by controllerconn.Client.

diag

Diagnostics is responsible for managing diagnostic services on the device, and reporting to console for debugging if there are issues. It does not send information to the Controller. However, among its diagnostic tests, it does test the ability to reach both the ping and config endpoints of the Controller. To connect and test these endpoints, it uses the methods provided by controllerconn.Client.