Device Capabilities

Devices MUST provide the Workload Fleet Management service with their capabilities and characteristics. This is done by calling the Device API's device capabilities endpoint. Reporting the device capabilities is the final step in the onboarding of the device's client.

The reported capabilities represent only the subset of device resources delegated exclusively to Margo for workload placement and reconciliation, and do not necessarily reflect the device's total physical capacity. The mechanisms used to isolate, reserve, and preserve these resources for exclusive Margo use are implementation-specific and outside the scope of this specification.

To ensure the WFM is kept up to date, the device's client MUST send updated capabilities information if any changes occur to the information originally provided (i.e., additional memory is added to the device).

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

Route and HTTP Methods

POST /api/v1/clients/{clientId}/capabilities/{deviceId}
PUT /api/v1/clients/{clientId}/capabilities/{deviceId}
DELETE /api/v1/clients/{clientId}/capabilities/{deviceId}

Route Parameters

Response Codes

Request Body Attributes

Properties Attributes

Resources Attributes

Resources of the specific device being reported to the WFM. Utilized to match with the required resources defined in the application description

CPU Attributes

CPU element defining the device's CPU characteristics.

Peripheral Attributes

Peripheral hardware of a device.

CommunicationInterface Attributes

Communication interface of a device.

Enumerations

These enumerations are used as vocabularies for attribute values of the DeviceCapabilities.

CpuArchitectureType

CommunicationInterfaceType

PeripheralType

Example Device Capabilities Payload

{
    "apiVersion": "device.margo.org/v1alpha1",
    "kind": "DeviceCapabilitiesManifest",
    "properties": {
        "id": "northstarida.xtapro.k8s.edge",
        "vendor": "Northstar Industrial devices",
        "modelNumber": "332ANZE1-N1",
        "serialNumber": "PF45343-AA",
        "roles": [
            "standalone cluster",
            "cluster leader"
        ],
        "resources": {
            "cpu": [
                {
                    "cores": 24,
                    "architecture": "x86_64"
                }
            ],
            "memory": "59 Gi",
            "storage": "1862 Gi",
            "peripherals": [
                {
                    "type": "GPU",
                    "manufacturer": "NVIDIA"
                }
            ],
            "interfaces": [
                {
                    "type": "ethernet"
                },
                {
                    "type": "wifi"
                }
            ]
        }
    }
}

Gateways considerations

Note: See Gateways page in the concepts section for more information about gateways.

Opaque gateways

A device may represent, and aggregate the capabilities of, multiple child-devices behind it and report itself as a single Margo device to the WFM. This type of device is referred to as an opaque gateway. Opaque gateways report the combined capabilities of all the devices they connect to the WFM.

Example: An opaque gateway has two child-devices. Each child-device has an ARM64 processor with 2 cores, 5 GB of memory, 32 GB of storage, and 1 ethernet interface. The gateway will report capabilities of 2 CPUs (arm64) with 2 cores each, 10 GB of memory, 64 GB of storage, and 2 ethernet interfaces. In addition since the gateway can deploy compose applications on its child-devices it will report the role of "standalone device".

See-thru gateways

WFM clients may connect one or more child-devices to the WFM while allowing the WFM to see each device behind it as an individual device with its own capabilities. This type of clients are referred to as see-thru gateways and report the "Gateway" role.

WFM clients reporting the "Gateway" role MUST report their capabilities and the capabilities of each device they connect to the WFM. This is done by calling the device capabilities endpoint for the gateway itself and for each device behind the gateway. The deviceId in the endpoint is used to indicate the hierarchy of devices, with a parent/child relationship. For example, if a see-thru gateway with deviceId "gateway1" connects two devices with deviceId "deviceA" and "deviceB", the gateway would call the device capabilities endpoint three times with the following deviceIds: "gateway1", "gateway1/deviceA", and "gateway1/deviceB".

If a WFM client reporting the "Gateway" role is capable of hosting edge applications it MUST report the corresponding role(s) (i.e., "Standalone Device", "Standalone Cluster, and/or "Cluster Leader") and the resources available for these deployments.

A WFM client reporting the "Gateway" role MUST report its own capabilities to the WFM before reporting the capabilities of any child devices. If a WFM receives a DeviceCapabilitiesManifest for a child-device before it has received the DeviceCapabilitiesManifest of the parent WFM client, the WFM MUST reject the request with a 404 Not Found response code.

Examples

• See-thru gateway, without hosting capabilities, reporting its capabilities to the WFM:

  POST /api/v1/clients/{clientId}/capabilities/gateway1

  {
      "apiVersion": "device.margo.org/v1alpha1",
      "kind": "DeviceCapabilitiesManifest",
      "properties": {
          "id": "gateway1",
          "vendor": "Gateway Vendor",
          "modelNumber": "GW-1000",
          "serialNumber": "GW12345678",
          "roles": [
              "Gateway"
          ]
      }
  }

• See-thru gateway, with hosting capabilities, reporting its capabilities to the WFM:

  POST /api/v1/clients/{clientId}/capabilities/gateway1

  {
      "apiVersion": "device.margo.org/v1alpha1",
      "kind": "DeviceCapabilitiesManifest",
      "properties": {
          "id": "gateway1",
          "vendor": "Gateway Vendor",
          "modelNumber": "GW-1000",
          "serialNumber": "GW12345678",
          "roles": [
              "Gateway",
              "Standalone Device"
          ],
          "resources": {
              "cpu": [
                  {
                      "cores": 4,
                      "architecture": "x86_64"
                  }
              ],
              "memory": "12 Gi",
              "storage": "200 Gi",
              "peripherals": [],
              "interfaces": [
                  {
                      "type": "ethernet"
                  }
              ]
          }
      }
  }

• See-thru gateway reporting the capabilities of a child device to the WFM:

  POST /api/v1/clients/{clientId}/capabilities/gateway1/deviceA

  {
      "apiVersion": "device.margo.org/v1alpha1",
      "kind": "DeviceCapabilitiesManifest",
      "properties": {
          "id": "gateway1/deviceA",
          "vendor": "Device A Vendor",
          "modelNumber": "DA-2000",
          "serialNumber": "DA12345678",
          "roles": [
              "Standalone Cluster",
              "Cluster Leader"
          ],
          "resources": {
              "cpu": [
                  {
                      "cores": 24,
                      "architecture": "x86_64"
                  }
              ],
              "memory": "59 Gi",
              "storage": "1862 Gi",
              "peripherals": [
                  {
                      "type": "GPU",
                      "manufacturer": "NVIDIA"
                  }
              ],
              "interfaces": [
                  {
                      "type": "ethernet"
                  }
              ]
          }
      }
  }

• See-thru gateway reporting the capabilities of a child device with deeper hierarchy to the WFM:

  POST /api/v1/clients/{clientId}/capabilities/gateway1/path1/deviceA

  {
      "apiVersion": "device.margo.org/v1alpha1",
      "kind": "DeviceCapabilitiesManifest",
      "properties": {
          "id": "gateway1/path1/deviceA",
          "vendor": "Device A Vendor",
          "modelNumber": "DA-1000",
          "serialNumber": "DA12345678",
          "roles": [
              "Standalone Device"
          ],
          "resources": {
              "cpu": [
                  {
                      "cores": 2,
                      "architecture": "arm64"
                  }
              ],
              "memory": "6 Gi",
              "storage": "30 Gi",
              "peripherals": [],
              "interfaces": [
                  {
                      "type": "ethernet"
                  }
              ]
          }
      }
  }

• See-thru gateway informing the WFM that a child device is no longer available:

  DELETE /api/v1/clients/{clientId}/capabilities/gateway1/deviceA

Specification Extensions

Note: See the specification extensions page for additional details.

The Device Capabilities document supports the following specification extension scenarios:

Collaboration between device and workload fleet manager suppliers

For the device workload fleet manager clients to make use of specification extensions defined by a workload fleet manager supplier, the extension property MUST be added to the device capabilities JSON document's root.

Workload fleet manager service implementations MUST ignore any unknown specification extensions targeting a device supplier. Importing a device capabilities document with unknown specification extensions MUST NOT result in a failure because of the included specification extensions.