Overview

Command Execution Extension service (CEX) extends the communication capability of Kaa Protocol (1/KP) by implementing Command Execution Protocol (11/CEP). CEX supports this extension protocol to deliver commands to endpoint and consume endpoint command execution result. As with other Kaa extension services, CEX uses Extension Service Protocol (4/ESP) for integration with a communication service.

Commands can be submitted from a command invocation caller over NATS or by invoking CEX REST API.

CEX supports two modes of command invocation via REST API:

  • synchronous mode requires the REST API client to wait for the response while the command is being executed. The maximum allowed response timeout is specified by the client in a request query parameter. This mode is useful in cases when the command execution is expected to be completed relatively fast (e.g. turning on an air conditioner).
  • asynchronous mode allows the REST API caller not to wait for the command execution to complete. Rather, immediately following the API call the client would receive a URL to the created command resource. The result will be retained by CEX for the duration specified by the caller via a query parameter. This command resource URL can be further used for checking the command execution result. This mode is useful in cases when the command execution takes relatively long (e.g. updating the firmware). CEX implements a proactive command push—commands are sent to an endpoint as soon as possible, and an explicit endpoint subscription is not required. Note that explicit subscription is still recommended.

Interfaces

CEX supports a number of interfaces to perform its functional role. The key supported interfaces are summarized in the following diagram.

CEX interfaces diagram

For inter-service communication, Kaa services mainly use REST APIs and messaging protocols that run over NATS messaging system.

Command invocation protocol

CEX acts as a command invocation agent according to 12/CIP. This protocol is used to accept command invocation request and return command invocation result back to command invocation caller.

Extension service protocol

CEX uses 4/ESP over NATS to exchange 11/CEP messages with endpoints through a communication service.

Command store

In some scenarios, endpoint can be inaccessible during command invocation request emission, thus it will not get a message with a command.

CEX persists commands for a configurable amount of time. So endpoint has an ability to request already scheduled commands.

The command store is maintained in [Postgres][postgres].

Commands history list

List of pending and executed commands by endpoint ID available via REST API.

Command execution flow

The overall command invocation and execution sequence diagram can be illustrated as follows:

CEX sequence diagram

Tekton integration

CEX is integrated with the Kaa Tekton for centralized application configuration management. It receives configuration update messages from Tekton over 17/SCMP and uses Tekton REST API to retrieve current configs.

See configuration for more information.

Kaa Tenant Manager integration

CEX supports multi-tenancy with each tenant using a separate OAuth 2.0 issuer for authentication, authorization, and resource management. The list of the existing tenants is managed by [the Kaa Tenant Manager][Tenant Manager], which provides REST API for retrieving tenant security configs.

See the security configuration for more details on how to enable multi-tenancy in CEX.