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

Note: * A see-thru gateway not hosting workloads itself MUST omit these fields. The WFM infers such a device is non-hosting from the absence of these capabilities, and infers a gateway relationship from the parent/child deviceId hierarchy.

CPU Attributes

CPU element defining the device's CPU characteristics.

Each entry in the cpus array describes one set of cores a single workload can be placed on. A device satisfies an application's requiredResources.cpu only if a single entry provides at least the required number of cores and, when the application specifies one or more architectures, that entry's architecture is one of the listed values. Cores from separate cpus entries MUST NOT be summed together when evaluating the requirement.

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

SupportedRuntime

SupportedDeploymentType

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",
        "cpus": [
            {
                "cores": 24,
                "architecture": "amd64"
            }
        ],
        "memory": "59 Gi",
        "storage": "1862 Gi",
        "peripherals": [
            {
                "type": "gpu",
                "manufacturer": "NVIDIA"
            }
        ],
        "interfaces": [
            {
                "type": "ethernet"
            },
            {
                "type": "wifi"
            }
        ],
        "otelCollector": true,
        "supportedRuntimes": [
            "oci"
        ],
        "supportedDeploymentTypes": [
            "helm",
            "compose"
        ]
    }
}

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 as a single DeviceCapabilitiesManifest. Because the child-devices are not individually visible to the WFM, an opaque gateway is seen as a single device and reports the aggregated resource fields, supportedRuntimes, and supportedDeploymentTypes of the devices behind it.

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. Since the gateway can deploy compose applications on its child-devices it will report supportedDeploymentTypes: ["compose"].

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 client is referred to as a see-thru gateway.

A see-thru gateway uses the same DeviceCapabilitiesManifest schema as any other device — from a payload perspective it is an ordinary device that also reports the devices behind it. Its conformance rules are relaxed, though: unlike non-gateway device, a see-thru gateway is not required to host workloads and need not report workload-hosting capabilities. The WFM infers the gateway relationship from the parent/child deviceId hierarchy, which is typically most evident when the gateway reports no workload-hosting capabilities.

How a see-thru gateway reports capabilities

A see-thru gateway MUST report its own capabilities and the capabilities of each device it connects to the WFM:

1. Call the device capabilities endpoint once for the gateway itself, then once for each device behind it.
2. Encode the hierarchy in the deviceId as a parent/child path. For example, a gateway gateway1 with two child-devices calls the endpoint three times, with deviceIds gateway1, gateway1/deviceA, and gateway1/deviceB.
3. Report the gateway's own manifest before any child manifest. If the WFM receives a child manifest first, it MUST reject the request with a 404 Not Found response code.

What the gateway reports about itself

Hosting is neither required of nor forbidden for a see-thru gateway: it reports the workload-hosting fields when it hosts workloads, and omits them when it does not.

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"
      }
  }

• 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",
          "cpus": [
              {
                  "cores": 4,
                  "architecture": "amd64"
              }
          ],
          "memory": "12 Gi",
          "storage": "200 Gi",
          "peripherals": [],
          "interfaces": [
              {
                  "type": "ethernet"
              }
          ],
          "otelCollector": true,
          "supportedRuntimes": [
              "oci"
          ],
          "supportedDeploymentTypes": [
              "compose"
          ]
      }
  }

• 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",
          "cpus": [
              {
                  "cores": 24,
                  "architecture": "amd64"
              }
          ],
          "memory": "59 Gi",
          "storage": "1862 Gi",
          "peripherals": [
              {
                  "type": "gpu",
                  "manufacturer": "NVIDIA"
              }
          ],
          "interfaces": [
              {
                  "type": "ethernet"
              }
          ],
          "otelCollector": true,
          "supportedRuntimes": [
              "oci"
          ],
          "supportedDeploymentTypes": [
              "helm"
          ]
      }
  }

• 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",
          "cpus": [
              {
                  "cores": 2,
                  "architecture": "arm64"
              }
          ],
          "memory": "6 Gi",
          "storage": "30 Gi",
          "peripherals": [],
          "interfaces": [
              {
                  "type": "ethernet"
              }
          ],
          "otelCollector": true,
          "supportedRuntimes": [
              "oci"
          ],
          "supportedDeploymentTypes": [
              "compose"
          ]
      }
  }

• 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.