Deployment Status

While applying a new desired state, the device's management client MUST provide the Workload Fleet Manager service with an indication of the current workload deployment status. This is done by calling the Device API's deployment status endpoint.

Requests to this endpoint MUST be authenticated using the HTTP Message Signature method as defined in the Payload Security section.

Note: This assumes consistent connection to the WFM, we will address intermittent or extended disconnection scenarios in the future.

Route and HTTP Methods

POST /api/v1/clients/{clientId}/deployments/{deploymentId}/status

Route Parameters

Parameter	Type	Required?	Description
{clientId}	string	Y	The unique identifier of the (device) client registered with the WFM during onboarding.
{deploymentId}	string	Y	The UUID of the `ApplicationDeployment` YAML being reported.

Response Codes

Code	Description
200 OK	The deployment status was added, or updated, successfully.
400 Bad Request	Missing or invalid content-digest header. Ensure the SHA256 hash of the base64-encoded payload is included.
401 Unauthorized	Signature verification failed. Ensure you are signing with the correct X.509 private key.
403 Forbidden	Client certificate is not trusted or has been revoked.
422 Unprocessable Content	Request body includes a semantic error.

Request Body Attributes

Fields	Type	Required?	Description
apiVersion	string	Y	Identifier of the version the API resource follows.
kind	string	Y	Must be `DeploymentStatusManifest`.
deploymentId	string	Y	The unique identifier UUID of the deployment specification. Needs to be assigned by the Workload Fleet Management Software.
deviceId	string	N*	Id of the device hosting the deployment. Includes the full device hierarchy if applicable. * This attribute is required when reporting on behalf of a child-device.
status	[]status	Y	Element that defines overall deployment status. See the Status Attributes section below.
components	[]components	Y	Element that defines the individual component's deployment status. See the Component Attributes section below.

Status Attributes

Fields	Type	Required?	Description
state	string	Y	Current state of the overall deployment. The state value MUST be one the following options: pending, installing, installed, removing, removed, failed. The overall deployment status MUST reflect the most severe of the components states, following this precedence: failed > removing > installing > pending > removing > installed.
error	Error	N	Element that defines the overall installation error if one occured. See the Error Attributes section below.

Component Attributes

Attribute	Type	Required?	Description
name	string	Y	Name of the deployment component, inherited via the deployment specification
state	string	Y	The component's current deployment state of the component. MUST be one of the following options: pending, installing, installed, removing, removed, failed
error	Error	N	Element that defines the components installation error if one occured. See the Error Attributes section below.

Note: The components array MUST contain one entry for each "component" defined in the referenced ApplicationDeployment manifest.

Error Attributes

Fields	Type	Required?	Description
code	string	Y	Associated error code following a component failure during installation.
source	string	Y	Identifies the source of the error. It is set to the device id, with its full hierarchy if applicable, of the device generating the error, or to the component name of the component generating the error.
message	string	Y	Associated error message that provides further details to the WFM about the error that was encountered.

When the error is generated by a see-thru gateway, the source attribute of the error structure MUST be set to the gateway device id, with its full hierachy if applicable.

When the error is not generated by a see-thru gateway, the source of the status.error attribute MUST be set to the name of the deployment as defined in the metadata.name attribute of the application deployment manifest.

When the error is not generated by a see-thru gateway, the source of the components.error attribute MUST be set to the name of the component as defined in the components[].name for that component.

Note: Most error codes and messages are implementation-specific. The purpose of the source attribute is to avoid collision between reserved error codes and implementation-specific error codes.

Reserved codes for gateway-generated errors:

Error Code	Message	Source	Description
101	Unknown child device ID	Id of the gateway	The gateway cannot identify the child device with the given ID.
102	Child device unreachable	Id of the gateway	The gateway cannot establish a connection with the child device.
103	Autonomous placement not supported	Id of the gateway	The gateway is not capable of autonomously selecting the child-device for the deployment.

When the error used is a reserved code for a gateway-generated error, the source attribute MUST be set to the id of the gateway, with its full hierachy if applicable.

Example Deployment Status Manifest Request

{
    "apiVersion": "deployment.margo.org/v1alpha1",
    "kind": "DeploymentStatusManifest",
    "deploymentId": "a3e2f5dc-912e-494f-8395-52cf3769bc06",
    "deviceId": "plant-alfa-zone1-edge01",
    "status": {
        "state": "pending",
        "error": {
            "code": "",
            "source": "",
            "message": ""
        }
    },
    "components": [
        {
            "name": "digitron-orchestrator",
            "state": "pending",
            "error": {
                "code":"",
                "source": "",
                "message":""
            }
        },
        {
            "name": "database-services",
            "state": "pending",
            "error": {
                "code": "",
                "source": "",
                "message": ""
            }
        }
    ]
}

On this page