- Command execution flow
- Batch command execution
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.
CEX supports a number of interfaces to perform its functional role. The key supported interfaces are summarized in the following 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.
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.
Command execution history
List of pending and executed commands by endpoint ID available via REST API.
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, which provides REST API for retrieving tenant security configs.
See the security configuration for more details on how to enable multi-tenancy in CEX.
Command execution flow
The overall command invocation and execution sequence diagram can be illustrated as follows:
Batch command execution
CEX allows to execute a command on a group of endpoints that match a specific endpoint filter using REST API.
Batch command execution is represented by a task that can be queried to get information on the execution state. For that use batch REST API.
The batch command execution sequence diagram can be illustrated as follows:
When CEX receives a batch command execution request, it resolves a list of endpoints that match the specified filter from the Endpoint Register service and, in case there is at least one matching endpoint, asynchronously distributes commands via 11/CEP protocol to the resolved endpoint(s).