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.

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/deployments/{deploymentId}/status

Route Parameters

Response Codes

Request Body Attributes

Status Attributes

Component Attributes

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

Error Attributes

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 hierarchy 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:

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 hierarchy if applicable.

Adopted Manifest Version

A state manifest defines a revision of each deployment it carries. A WFM client has adopted that revision when it holds it and has begun applying it. Adoption is independent of the outcome. The status.state attribute carries the outcome.

The WFM client MUST populate the adoptedManifestVersion attribute with the manifestVersion of the most recent state manifest it has adopted for the reported deployment. A reported version N means the client has taken up the deployment as manifest N defined it. The reported version MUST match the revision of the deployment the client holds. A client still on an older revision reports that older version.

Fetching a newer state manifest does not by itself advance the reported version for a deployment. Until the client begins applying the deployment's newer revision, it keeps reporting the version of the revision it still holds. The reported version need not be the version at which the deployment last changed. A client that has lost its local state and resynchronized reports the version it resynchronized against, which can be later.

The attribute is present in every status report. A client learns of a deployment from a versioned state manifest, so it always has a version to report for a deployment it has taken up. On a first install the client reports the version of the manifest it adopted the deployment from, even if applying it fails. There is no reserved value for "no previous version".

Note: Manifest versions increase monotonically and never repeat, so the WFM can order any reported version against the versions it has published, even when a deployment's content reverts to an earlier revision.

Example Deployment Status Manifest Request

{
    "deploymentId": "a3e2f5dc-912e-494f-8395-52cf3769bc06",
    "deviceId": "plant-alfa-zone1-edge01",
    "adoptedManifestVersion": 7,
    "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": ""
            }
        }
    ]
}