Topics and Messages

As part of the installation, the following configuration variables have been set, in addition to the MQTT broker’s connection details:

ASE_CORE_MINIMUM_LOG_LEVEL (optional, defaults to “error”, recommended setting is “warning”)
ASE_CORE_ERROR_LOG_LEVEL (optional, defaults to “error”, recommended setting is “critical”)
EDGE_COMPUTE_PLATFORM_IDENTIFIER (required, should be cloud-side “thing-id” for cluster)
EDGE_COMPUTE_PLATFORM_ACCOUNT_ID (required, should be cloud-side account)
MQTT_CONNECTION_URL (required)
MQTT_PEM (optional, but required for ssl connections)
MQTT_QOS (optional, defaults to 2)
MQTT_USERNAME (optional, defaults to empty string)
MQTT_PASSWORD (optional, defaults to empty string

Send a Message to the Management Service

The MQTT topic the Management Service subscribes to is:

status/<account>/collections/cluster/things/<thing-id>/actions/send-kubectl

The message format for publishing is as follows:

{
  "send-kubectl": {
    "input": {
      "correlationId": "{create-a-unique-id-for-each-message}",
      "command": "kubectl",
      "arguments": [
        "{each}",
        "{new}",
        "{argument}",
        "{needs}",
        "{its}",
        "{own}",
        "{array}",
        "{entry}"
      ]
    },
    "status": "pending",
    "timeRequested": "<datetime>",
    "href": "<account>/collections/cluster/things/<thing-id>/actions/send-kubectl/<action-id>"
  }
}

For example:

{
  "send-kubectl": {
    "input": {
      "correlationId": "666",
      "command": "kubectl",
      "arguments": [
        "get",
        "nodes",
        "-o",
        "wide"
      ]
    },
    "status": "pending",
    "timeRequested": "2020-05-26 15:37:46+0000",
    "href": "martin/things/ag150/actions/send-kubectl/1234"
  }
}

Note: It is important that each argument is put in a new array entry. If there is a space in the complete command, then that means a new argument.

Status Update After Receiving Action Request

MQTT topic the message is sent to:

set/<account>/collections/cluster/things/<thing-id>/actions/send-kubectl/<action-id>

Message:

{
  "send-kubectl": {
    "status": "received"
  }
}

Event Publish After Running Action

MQTT topic the message is sent to:

set/<account>/collections/cluster/things/<thing-id>/events/kubectl-logs

Message:

{
	"kubectl-logs": {
		"data": {
 		    "correlationId": "{the-unique-id-from-the-request}",
    		"statusCode": "{an-http-status-code}",
    		"statusMessage": "{optional descriptive message}",
    		"response": "{the output in plain text format}"
		}
	}
}

Example:

{
	"kubectl-logs": {
		"data": {
  			"correlationId": "666",
  			"statusCode": 200,
  			"statusMessage": "Command executed successfully",
  			"response": "NAME           STATUS   ROLES    AGE   VERSION        INTERNAL-IP    EXTERNAL-IP   OS-IMAGE           KERNEL-VERSION     CONTAINER-RUNTIME\nmartin-ag150   Ready    master   50d   v1.18.2+k3s1   10.10.10.100   \u003cnone\u003e        Ubuntu 20.04 LTS   5.4.0-40-generic   containerd://1.3.3-k3s2\n"
		}
	}
}

You need to use the correlationId to match the response to the request.

Status Update After Completing Action

MQTT topic the message is sent to:

set/<account>/collections/cluster/things/<thing-id>/actions/send-kubectl/<action-id>

Message:

{
  "send-kubectl": {
    "status": "completed"
  }
}