Skip to main content
Version: Next

Service Control

A control command acts on one service of a device: starting it, stopping it, restarting it, or any other action that service supports.

  • A service declares the actions it supports in the metadata of its control command.
  • An action is triggered as a control command naming that action.
  • tedge-agent executes the commands of the services registered with its own device as their @parent.
  • The shipped control workflow delegates every action to tedge service, which runs the action through one of two backends, the init system or a service plugin.

The restart operation restarts a device; the restart action of a service restarts one service of that device.

Control actions​

A control command action name matches [A-Za-z][A-Za-z0-9_-]*: letters, digits, _ and -, starting with a letter. Action names are case-sensitive, so requestLog and requestlog are two actions.

MQTT API​

The service control API follows the generic thin-edge.io rules for operations, applied to a service topic identifier such as device/main/service/nodered and to the control operation.

Declaring the control actions​

A service declares its control actions by publishing a retained message on te/<service-topic-id>/cmd/control, with the action names in an actions array.

tedge mqtt pub -r 'te/device/main/service/nodered/cmd/control' '{
  "actions": [
    "restart",
    "pause"
  ]
}'

To remove one action, the service publishes the message again without that action.

Clearing the control actions​

A service removes all its actions by publishing a retained empty message on the same topic.

tedge mqtt pub -r 'te/device/main/service/nodered/cmd/control' ''

Triggering a control action​

A control command is published on te/<service-topic-id>/cmd/control/<cmd_id>, with the action, starting in the init state and ending in successful or failed.

tedge mqtt pub -r 'te/device/main/service/nodered/cmd/control/c8y-mapper-123' '{
  "status": "init",
  "action": "restart",
  "serviceName": "nodered",
  "serviceType": "service"
}'
FieldDescription
statusThe state of the command, as for every thin-edge.io command
actionThe action to run, one of the actions the service declares
serviceNameThe name of the service, as the backend running the action knows it
serviceTypeThe type of the service, which selects the backend that runs the action

Progress is published on the same topic by whoever executes the command, and the command is cleared by the requester.

tedge mqtt pub -r 'te/device/main/service/nodered/cmd/control/c8y-mapper-123' '{
  "status": "failed",
  "action": "restart",
  "serviceName": "nodered",
  "serviceType": "service",
  "reason": "The action failed, see the operation log for the reason"
}'

Shipped workflow​

A thin-edge.io service managed by an init unit of its own declares restart when it starts.

tedge-agent installs the workflow of the control command in /etc/tedge/operations/service_control.toml. It declares type = "service", so it applies to service entities. See scoping a workflow by entity type.

The workflow runs every action through tedge service, custom actions included, so a custom action only has to be supported by the init system or by the service plugin.

From the cloud​

A Cumulocity operator triggers these actions from the service itself. See service commands with Cumulocity.