Cloud Communication

Introduction

This section documents how AosEdge Units communicate with the AosCloud backend. The cloud communication channel is the primary control plane for fleet management — it carries desired-state instructions from cloud to Unit, and status reports from Unit to cloud.

All cloud communication flows through the Communication Manager (CM) component on the Unit side, using a WebSocket-based JSON protocol over mTLS. The protocol is versioned independently of the AosCore software version, with the current version being protocol v7.

Communication Architecture

The cloud communication path involves three stages:

1. Service Discovery — the Unit contacts the service discovery endpoint (/sd/v7/) to obtain the WebSocket URL for its assigned cloud region
2. Connection Establishment — the Unit opens a persistent WebSocket connection to the cloud (/ws/v7/) using mutual TLS (mTLS) for authentication
3. Message Exchange — the Unit and cloud exchange JSON messages over the WebSocket, with each message acknowledged by the receiver

On the cloud side, incoming messages are validated, then routed internally via a message broker (RabbitMQ) to the appropriate handler service. This internal routing is transparent to the Unit — from the Unit's perspective, it communicates with a single WebSocket endpoint.

WebSocket JSON Protocol

The protocol uses a structured JSON envelope for all messages:

{
  "header": {
    "version": 7,
    "systemId": "<unit-system-id>",
    "createdAt": "<ISO-8601 timestamp>",
    "txn": "<transaction-id>"
  },
  "data": {
    "messageType": "<type>",
    ...
  }
}

Key protocol characteristics:

• Binary WebSocket frames — messages are serialized as JSON and sent as binary frames
• Transaction tracking — every message carries a txn field used for acknowledgment correlation
• Discriminated union — the messageType field in data determines the message schema
• Versioned — the header.version field identifies the protocol version (currently 7)

Message Types Overview

The protocol defines 15 Unit→Cloud message types and 12 Cloud→Unit message types:

Unit → Cloud (15 types)

Message Type	Purpose
unitStatus	Reports current state of services, layers, components, and nodes
monitoringData	Sends resource usage metrics (CPU, RAM, disk, network)
alerts	Reports system and service alerts
newState	Uploads new service state data
stateAcceptance	Confirms or rejects a state update
pushLog	Sends requested service log data
overrideEnvVarsStatus	Reports result of environment variable override
issueUnitCertificates	Requests new certificates from cloud CA
installUnitCertificatesConfirmation	Confirms certificate installation
startProvisioningResponse	Responds to provisioning initiation
finishProvisioningResponse	Responds to provisioning completion
deprovisioningResponse	Responds to deprovisioning request
requestBlobUrls	Requests download URLs for large binary objects
renewCertificatesNotification	Notifies cloud that certificates need renewal
ack	Acknowledges receipt of a cloud→unit message

Cloud → Unit (12 types)

Message Type	Purpose
desiredStatus	Declares the target state for services, layers, and components
requestLog	Requests service log data from the Unit
overrideEnvVars	Sets environment variable overrides for services
updateState	Sends updated service state to the Unit
stateRequest	Requests current service state from the Unit
issuedUnitCertificates	Delivers newly issued certificates
startProvisioningRequest	Initiates Unit provisioning
finishProvisioningRequest	Completes Unit provisioning
deprovisioningRequest	Initiates Unit deprovisioning
blobUrls	Provides requested download URLs
ack	Acknowledges receipt of a unit→cloud message
nack	Negative acknowledgment with retry-after hint

Acknowledgment Mechanism

Every message sent over the WebSocket receives an explicit acknowledgment:

• ack — confirms the message was received and accepted for processing
• nack — indicates the message could not be processed; includes a retryAfter field (in milliseconds) suggesting when the sender should retry

The txn field from the original message header is echoed in the acknowledgment, allowing the sender to correlate responses. If no acknowledgment is received within a timeout period, the sender assumes the connection is broken and initiates reconnection.

Service Discovery

Before establishing a WebSocket connection, the Unit must discover the cloud endpoint:

1. The Unit sends an HTTP POST to the service discovery endpoint (/sd/v7/) with its systemId
2. The cloud responds with a list of WebSocket URLs (e.g., wss://cloud.example.com/ws/v7/)
3. The Unit connects to the provided URL using its mTLS client certificate

Service discovery is a lightweight REST call — it does not use the WebSocket protocol. The discovered URL is cached and reused across reconnections until a new discovery is triggered (e.g., after repeated connection failures).

Security

All cloud communication is secured with mutual TLS (mTLS):

• The Unit authenticates to the cloud using its online certificate (issued during provisioning)
• The cloud validates the certificate against its CA chain and extracts the Unit identity from the certificate subject
• Connections without valid mTLS certificates are rejected before the WebSocket handshake completes

Message payloads for sensitive operations (desired status responses containing encryption keys) are additionally encrypted using the Unit's offline certificate public key.

In This Section

• Cloud Protocol Reference — detailed message schemas, field definitions, and protocol behavior
• Connection Management — reconnection logic, keepalive, and error handling

Related Pages

• Communication Manager — the CM component that implements cloud communication on the Unit side
• Architecture Overview — high-level view of all AosCore components and their interactions
• Security Model — certificate architecture and mTLS infrastructure

• Service Lifecycle — how desired-state messages drive service deployment