Commands & OTA Updates

The Cloud Backend pushes commands to Edge appliances via poll-based long-poll: the device asks for pending commands (also refreshes last_seen_at). Online window: 90 seconds.

Command polling

sequenceDiagram
    participant Edge as Edge Appliance
    participant CloudAPI as Cloud Backend
    participant SQL as Azure SQL

    loop Long-poll
        Edge->>CloudAPI: GET /v1/commands
        Note right of Edge: Backend mount /api/v1/commands
        CloudAPI->>SQL: pending commands for device
        CloudAPI-->>Edge: command list or empty
        Edge->>CloudAPI: POST /v1/commands/:id/ack
    end

Auth: X-Device-Key / api_key from claim-complete (optional mTLS).

OTA: RAUC (current Edge) and snaps (still in Backend)

Path	Who uses it	Backend routes
RAUC bundles	Current Edge image / updater	/api/v1/bundles/latest, /api/v1/bundles/download/:version, publish POST /api/v1/admin/bundles/publish
Snaps	Legacy / still mounted	/api/v1/snaps/:name/latest, download, GET /api/v1/devices/:id/snaps

Edge product direction is RAUC (Updates CA signing — PKI). Backend still exposes both snap and bundle APIs (Backend/internal/domain/updates/routes.go). Do not delete snap docs until the Backend routes and tables are removed.

sequenceDiagram
    participant CI as CI/CD
    participant CloudAPI as Cloud Backend
    participant Edge as Edge Appliance

    CI->>CloudAPI: Publish RAUC bundle metadata
    Edge->>CloudAPI: Poll commands or GET bundles/latest
    CloudAPI-->>Edge: version plus download URL
    Edge->>Edge: Verify signature and rauc install
    Edge->>CloudAPI: Ack / report version

Publish auth for bundles uses a CI bearer token (Edge pipelines: BUNDLE_PUBLISH_TOKEN). Snap publish may still use a separate token — check Key Vault / ADO variable groups.

Database

Area	Notes
Commands	Pending command rows per device
Snap releases	Still present (e.g. V21-era tables)
Bundle releases	Newer migrations (e.g. V47)

Related

• Edge registration
• PKI ceremony
• Edge source: Edge/docs/updates-api.md