Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
347 lines (201 sloc) 18.8 KB

API

This document defines the API for Device to Controller communications.

This document is version 1, and all endpoints will begin with /api/v1.

Definitions

  1. API: This API for Device-to-Controller communications.
  2. Device: an independent computation Device that runs an engine and is controlled via a centralized control system. Normally, it runs EVE.
  3. Controller: A centralized unit that can control one or more Devices. It can be in the cloud, on a laptop, on a Device itself, or anywhere.
  4. UUID: A universally unique identifier for a Device within the realm of a Controller.

Responsibilities

Device

A Device MUST be able to boot independently of a Controller, as defined in this document. The independent boot mechanism MAY be a local flash or disk, an attached storage Device like a media card or CD/DVD, network boot, or any other method. A Controller MAY also provide boot services such as iPXE, but that is NOT part of the Controller's responsibilities according to this document.

A Device MUST register with a Controller in an agreed and secure fashion, to be detailed below. It is NOT the responsibility of the Controller to seek out and find Devices.

A Device MUST retrieve its configuration from its Controller.

A Device MUST check for updated configuration on a periodic basis. The period for refresh is implementation-dependent and is NOT defined in this document.

A Device MUST use the communications, authentication and authorization channels described in this document.

A Device MUST NOT generate its own UUID. Rather, it MUST receive its UUID from its Controller via its first config API call. A Device MUST submit its UUID with each request other than register and ping, and it MUST check its current UUID against the returned UUID with each request from the config endpoint.

A Device MUST generate its own unique Device certificate and key. This specification does NOT define the mechanism by which a Device is to do so, as it is implementation-dependent. It is RECOMMENDED that a Device use hardware security, where possible, such as TPM or TEE, to protect the Device private key.

A Device MUST have a method of knowing or discovering its Controller URL. This specification does NOT define the mechanism by which a Device is to do so, as it is implementation-dependent.

A Device MUST maintain and persist its own current state such that it survives reboots and process restarts. This includes UUID and configuration parameters. This specification does NOT define the mechanism by which each Device is to do so.

Controller

A Controller MUST be available for response to Device requests.

A Controller MUST be accessible to all Devices that need to reach it. If it cannot be accessed due to network limitations, the necessary proxies and other network traversal solutions should be made available. Those solutions are implementation-dependent and are not defined in this specification.

A Controller MUST listen for https on a port. The specific port is not specified in this document, however, it is RECOMMENDED to use the well-known https port of 443 where possible. A Controller MUST expose all of the endpoints listed in this document. A Controller MAY additionally listen on other ports, and MAY expose additional endpoints defined in this document, provided those endpoints do NOT conflict with those defined in this document, and use the "Extensions" provision listed herein.

A Controller MUST generate a UUID for each Device. The UUID MUST be unique across all Devices managed by the Controller. The Controller SHOULD use an approach to generating UUIDs which minimizes the probability of UUID collisions with UUIDs generated by all Controllers everywhere.

Messages

All messages are defined in subdirectories to the proto directory. In general, there is one directory for each API endpoint:

  • register: The register message sent as part of onboarding a device
  • config: The EdgeDevConfig message sent from Controller to Device in response to requests for configuration
  • info: The ZInfoMsg message sent from Device to Controller when there is a state change for an object (device, app instance, etc )
  • metrics: The ZMetricMsg message sent from Device to Controller periodically to report on resource usage etc.
  • logs: The LogBundle message sent from Device to Controller containing internal device logs.

Authentication

All communication messages MUST be encrypted with TLS v1.2 or higher, and MUST authenticate all message with mutual TLS (mTLS). It is RECOMMENDED to use TLS v1.3 or higher to provider better privacy for the Device certificate and faster communication initialization.

There are two types of certificates to use for client authentication via mTLS:

  • Onboarding: These MUST be used only for initial Device registration via the /register endpoint or for the /ping endpoint prior to registration, and MUST NOT be used again thereafter.
  • Device: These MUST be used for all communications after the initial Device registration.

A Controller MUST NOT expose any endpoints that do not offer TLS encryption. A Controller MUST NOT offer any endpoints in the edge device path /api/v1/edgedevice/ that do not use mTLS authentication.

The ping endpoint may be useful for a Device to check connectivity before registering. Since the device has not yet registered, it MUST use its onboarding certificate to authenticate to the ping endpoint. The Controller SHOULD rate limit the endpoint when authenticated via onboarding certificate. A Device MUST expect that its Controller may rate limit the ping endpoint, and have an appropriate backoff scheme for retrying.

The common return codes for failed authentication or authorization are:

  • In the case of a missing or invalid client certificate, a Controller MUST return a 401 http error code.
  • In the case of a valid client certificate but an endpoint to which the certificate does NOT have access, whether an endpoint listed in this specification or a custom endpoint, a Controller MUST return a 403 http error code.

Additional return codes are defined in this specification for each endpoint as necessary.

Extensions

A Controller MAY offer additional API endpoints under the path /ext after the /api and version prefix. This is to ensure no conflict with existing or future official endpoints.

For example, an endpoint called "custom" would be:

GET /api/v1/ext/custom

An endpoint specific called "check" specific to edge devices would be:

GET /api/v1/edgedevice/ext/check

Because the endpoint is under the /edgedevice/ path, it MUST be encrypted and mTLS authenticated.

Mime Types

All GET requests MUST have no mime type set. All POST requests MUST have the mime type set of application/x-proto-binary. All responses with a body MUST have the mime type set of application/x-proto-binary.

Endpoints

The following are the API endpoints that MUST be implemented by a Controller. All of these endpoints MUST be encrypted and authenticated.

Register

Register a new Device for the first time.

POST /api/v1/edgeDevice/register

Return codes:

  • Unauthenticated or invalid credentials: 401
  • Valid credentials without authorization: 403
  • Valid registration: 201
  • Repeat valid registration for Device: 200
  • Duplicate Device: 409
  • Missing or unprocessable body: 422

Request:

The request MUST use the onboarding certificate for mTLS authentication. The Controller MAY retain the onboarding certificate or information within it for further purposes.

The request MUST have the body of a single protobuf message of type register.ZRegisterMsg. The message MUST include the Device certificate. In the case where the Device certificate is the same as the onboarding certificate, the Device MUST NOT assume that the Controller will extract the Device certificate from the mTLS authentication, and instead it MUST include the certificate in the message.

The message SHOULD include a serial string or other unique identifier for the Device.

The combination of onboard certificate and serial MUST be unique to each Device. Each item on its own, serial or onboard certificate, MAY be duplicated. In the case of an attempt to register a combination of onboard certificate+serial that already has been registered:

  • If the proposed device certificate is identical to the one already registered, then the Controller MUST return a "OK 200" status code.
  • If the proposed device certificate is different from the one already registered, then the Controller MUST return a "Conflict 409" status code.

A Controller MAY require pre-registration of onboarding certificates, Device certificates, serial or any combination thereof prior to accepting a Device register request. In the case where a Controller requires pre-registration, yet a Device attempts to use the register endpoint prior to pre-registration, a Controller MUST return an "Unauthorized 403".

This specification recognizes two use cases for device registration:

  • Onboarding: A Device with an appropriate onboarding certificate and serial string can register. The Device calls the /register endpoint to register its unique device certificate.
  • Registered: A Device with a unique device certificate has already had its certificate registered with the Controller. The Device does not call the /register endpoint, as it already is registered. Instead, it moves directly to the /config endpoint to retrieve its configuration.

Additional registration flows, including a unique Device certificate signed by a CA recognized by the Controller, and a CSR-based flow, are under consideration for future versions of this specification.

Response:

The response MUST NOT contain any body content.

Ping

Check connectivity between Device and Controller.

GET /api/v1/edgeDevice/ping

Return codes:

  • Unauthenticated or invalid credentials: 401
  • Valid credentials without authorization: 403
  • Success: 200

Request:

The request MUST use the Device certificate for mTLS authentication.

The request MUST NOT contain any body content.

Response:

The response MUST NOT contain any body content.

Configuration

Retrieve configuration for a specific Device.

GET /api/v1/edgeDevice/config

Return codes:

  • Unauthenticated or invalid credentials: 401
  • Valid credentials without authorization: 403
  • Success: 200
  • Unknown Device: 400

Request:

The request MUST use the Device certificate for mTLS authentication.

The request MUST NOT contain any body content.

Response:

The response mime type MUST be "application/x-proto-binary". The response MUST contain a message with the entire configuration for the given Device. The body MUST be a protobuf message of type config.EdgeDevConfig. The body MUST contain the entire configuration for the Device. The body MUST contain the UUID for the Device on each and every request. The Controller MUST NOT assume that the Device already has the UUID.

Arbitrary Config Variables

The config endpoint, specifically the EdgeDevConfig message, supports arbitrary key/value pairs. These are intended to send implementation-specific configuration to a Device. For example, it might control the frequency of downloading configs, enable debug logging or enable a USB port.

The EdgeDevConfig message can contain zero, one or more ConfigItem entries, each of which is an arbitrary key/value pair. These SHOULD be used to send implementation-specific configuration to a Device, other than configuration already defined in this API or the messages. The items are defined in global-config-variables

Info

Send Device status information to Controller

POST /api/v1/edgeDevice/info

Return codes:

  • Unauthenticated or invalid credentials: 401
  • Valid credentials without authorization: 403
  • Success: 201
  • Unknown Device: 400
  • Missing or unprocessable body: 422

Request:

The request MUST use the Device certificate for mTLS authentication.

The request MUST be of mime type "application/x-proto-binary".

The request body MUST be a protobuf message of type info.ZInfoMsg. The message itself MUST be one of the types defined as info.ZInfoTypes.

The request body MUST indicate the type of information it is sending, and the content thereof. It MUST be one of:

  • Device via ZInfoDevice: information about the Device itself, including baseos version, update of baseos, etc.
  • Application via ZInfoApp: information about an application running on the Device, including running, started, stopped, downloaded, version, etc.
  • Network via ZInfoNetworkInstance: information about networking on the Device, including ports, connectivity, assignment, etc.

An information message is expected to be reliable. A Device MUST retry until it successfully delivers information messages. How often information messages are sent, retries and other caching mechanisms on the Device are NOT specified here, as they are implementation questions.

Response:

The response MUST contain no body content.

metrics

Send Device and Application metrics to Controller

POST /api/v1/edgeDevice/metrics

Return codes:

  • Unauthenticated or invalid credentials: 401
  • Valid credentials without authorization: 403
  • Success: 201
  • Unknown Device: 400
  • Missing or unprocessable body: 422

Request:

The request MUST use the Device certificate for mTLS authentication.

The request MUST be of mime type "application/x-proto-binary".

The request body MUST be a protobuf message of type metrics.ZMetricMsg. The message itself contains metrics of the following combinations:

  • zero or one Device metrics DeviceMetric
  • zero, one or many application metrics appMetric
  • zero, one or many network metrics ZMetricNetworkInstance

A metrics message is NOT expected to be reliable. A Device SHOULD expect that some metrics messages will be lost. A Controller MUST NOT expect that it has received all of the metrics from a Device. Metric values in a metrics message SHOULD be cumulative, such that the loss of one or more metrics messages results in the loss of precision in the time domain alone, and not in the loss of any other information.

A Device SHOULD bundle many metrics together into a single ZMetricMsg. The choice of how many to bundle together, and how often to send them, is implementation-dependent.

Response:

The response MUST contain no body content.

logs

Send Device and Application logs to Controller

POST /api/v1/edgeDevice/logs

Return codes:

  • Unauthenticated or invalid credentials: 401
  • Valid credentials without authorization: 403
  • Success: 201
  • Unknown Device: 400
  • Missing or unprocessable body: 422

Request:

The request MUST use the Device certificate for mTLS authentication.

The request MUST be of mime type "application/x-proto-binary".

The request body MUST be a protobuf message of type log.LogBundle. The message itself contains zero, one or more entries of type log.LogEntry.

Each LogEntry is a single log message indicating its timestamp, source, severity, message ID, application or process ID, and arbitrary message content. In addition, it can content an unlimited number of key/value pairs.

A Device SHOULD bundle many log messages together into a single LogBundle.

A LogBundle MUST NOT be larger than the maximum size specified by the Controller for the Device, but MAY be smaller than that, if insufficient messages are available or the Device network or endpoints cannot handle the maximum size. The Device MUST retrieve the maximum LogBundle message size from the appropriate field of the configuration.

A log message is expected to be reliable. A Device MUST retry until it successfully delivers log messages. How often log messages are sent, retries, the number of messages and which types to bundle together into a single LogBundle, and other caching mechanisms on the Device are NOT specified here, as they are implementation questions.

Response:

The response MUST contain no body content.

flowlog

The flowlog API is used by the device to send network flow statistics (TCP and UDP flows with IP addresses, port numbers, counters, whether dropped or accepted), and also the hostname to IP address mapping as seen by the device.

POST /api/v1/edgeDevice/flowlog

Return codes:

  • Unauthenticated or invalid credentials: 401
  • Valid credentials without authorization: 403
  • Success: 201
  • Unknown Device: 400
  • Missing or unprocessable body: 422

Request:

The request MUST use the Device certificate for mTLS authentication.

The request MUST be of mime type "application/x-proto-binary".

The request body MUST be a protobuf message of type flowlog.FlowMessage. The message itself contains zero or more entries of type flowlog.FlowRecord and/or zero or more entries of type flowlog.DnsRequest.

A FlowMessage MUST NOT be larger than the maximum size specified by the Controller for the Device, but MAY be smaller than that, if insufficient messages are available or the Device network or endpoints cannot handle the maximum size. The Device MUST retrieve the maximum FlowMessage message size from the appropriate field of the configuration.

A flowlog message is expected to be reliable. A Device MUST retry until it successfully delivers log messages. However, if there is more recent information for flows, e.g., updated counters, that information can be sent instead of retransmitting old information as long as no flows are omitted. How often log messages are sent, retries, the number of entries to bundle together into a single FlowMessage, and other caching mechanisms on the Device are NOT specified here, as they are implementation questions.

Response:

The response MUST contain no body content.

Caching Policy

Edge Devices are expected to have intermittent connectivity, with limited bandwidth, memory and storage. It is likely that, at some point, a Device will run out of local memory or storage to cache information, logs or metrics messages that need to be sent to a Controller.

The choice of which messages to keep, how long to keep them, which to discard, and how to handle these overflows are implementation-dependent and are NOT specified in this document.

HTTP MetaData

Edge Devices may send some MetaData in HTTP header to the controller. This will help the controller side troubleshooting at the HTTP level. The Device UUID can be included in the HTTP header 'X-Request-ID'. Since the UUID on Device is obtained from the controller, when the UUID is not available yet, the Device Serial-Number and Soft-Serial-Number can be included in the HTTP header fields 'X-Serial-Number' and 'X-Soft-Serial' respectively.

You can’t perform that action at this time.