From 838a6d9190179b21f264100e1bd584bc3388f420 Mon Sep 17 00:00:00 2001 From: Armand Craig Date: Tue, 14 Jul 2026 16:04:27 -0400 Subject: [PATCH 01/32] Initial edits to move from roles to capabilities Signed-off-by: Armand Craig --- .../margo-devices/device-requirements.md | 24 +- .../device-capabilities.md | 242 ++++++++++-------- .../workload-management-api-1.0.0.yaml | 72 ++++-- 3 files changed, 188 insertions(+), 150 deletions(-) diff --git a/system-design/specification/margo-devices/device-requirements.md b/system-design/specification/margo-devices/device-requirements.md index 607a9fac..c138121e 100644 --- a/system-design/specification/margo-devices/device-requirements.md +++ b/system-design/specification/margo-devices/device-requirements.md @@ -1,19 +1,24 @@ # Device Requirements -All current device roles MUST meet the following requirements to be considered Margo compliant. These requirements ensure devices can effectively host and manage Margo compliant workloads. A device MUST support onboarding and management from only a single workload fleet manager. +All Margo conformant devices MUST meet a baseline set of requirements to be considered Margo compliant. These requirements ensure devices can effectively host and manage Margo compliant workloads. A device MUST support onboarding and management from only a single workload fleet manager. A device reports what it can provide to the ecosystem through its [device capabilities](../margo-management-interface/device-capabilities.md). All devices MUST provide the following components: - + - A workload fleet management client -- An OCI container runtime + +All workload hosting devices MUST provide the following components: + +- at least one supported deployment type (`supportedDeploymentTypes`) +- at least one supported workload runtime (`supportedRuntimes`) - An OTEL collector -## Standalone Cluster Role Requirements +## Kubernetes (Helm) enabled device requirements -Devices filling the standalone cluster role MUST provide the following additional components: +Devices supporting the helm deployment type, MUST provide the following additional components: -- Kubernetes orchestration platform - Capabilities for deploying Helm charts + - described via the `supportedDeploymentTypes`:`helm` +- Kubernetes orchestration platform ### Helm deployment approaches @@ -28,12 +33,13 @@ Margo does not dictate how devices deploy workloads packaged as Helm charts. A d If a device vendor chooses a deployment approach that does not interact with the Kubernetes API, the list of Kuberentes APIs available in the cluster MUST be provided out-of-band. This is supported by a variety of tooling such as the Helm GO SDK, `helm template` command, Kustomization, and ArgoCD. -## Standalone Device Role Details +## Compose enabled device requirements -Devices filling the standalone device role MUST provide the following additional components: +Devices supporting the compose deployment type, MUST provide the following additional components: -- Compose compliant software as the orchestration platform - Capabilities for deploying Compose applications + - described via the `supportedDeploymentTypes`:`compose` +- Compose compliant software as the orchestration platform ## Future Requirements diff --git a/system-design/specification/margo-management-interface/device-capabilities.md b/system-design/specification/margo-management-interface/device-capabilities.md index 7f9cb9db..b6b1358b 100644 --- a/system-design/specification/margo-management-interface/device-capabilities.md +++ b/system-design/specification/margo-management-interface/device-capabilities.md @@ -51,20 +51,17 @@ DELETE /api/v1/clients/{clientId}/capabilities/{deviceId} | vendor | string | Y | Defines the device vendor.| | modelNumber | string | Y | Defines the model number of the device.| | serialNumber | string | Y | Defines the serial number of the device.| -| roles | []string | Y | Element that defines the device role it can provide to the Margo environment. MUST be one of the following: Standalone Cluster, Cluster Leader, Standalone Device, or Gateway | -| resources | Resource | * | Element that defines the device's resources available to the application deployed on the device. See the [Resource Fields](#resources-attributes) section below.
* The element is required if the device has any of the following roles: Standalone Cluster, Cluster Leader, Standalone Device. | - -### Resources Attributes -Resources of the specific device being reported to the WFM. Utilized to match with the required resources defined in the application description - -| Attribute | Type | Required? | Description | -| --- | --- | --- | --- | -| cpu | CPU | Y | CPU element specifying the CPU information of the device. See the [CPU](#cpu-attributes) section below.| -| memory | string | Y | The amount of memory available for applications to utilize on the device. The value is given a binary units (`Ki` = Kibibytes, `Mi` = Mebibytes, `Gi` = Gibibytes). This is defined by the device owner.| -| storage | string | Y | The amount of storage available for applications to utilize on the device. The value is given a binary units (`Ki` = Kibibytes, `Mi` = Mebibytes, `Gi` = Gibibytes, `Ti` Tebibytes, `Pi` = Pebibytes, `Ei` = Exbibytes). This is defined by the device owner.| -| peripherals | []Peripheral | Y | Peripherals element specifying the peripherals available for applications to utilize on the device. See the [Peripheral](#peripheral-attributes) section below.| -| interfaces | []CommunicationInterface | Y | Interfaces element specifying the communication interfaces available for applications to utilize on the device. See the [Communication Interfaces](#communicationinterface-attributes) section below.| - +| cpu | []CPU | Y* | List of CPU entries available on the device. Utilized to match with the required resources defined in the application description. See the [CPU](#cpu-attributes) section below.| +| memory | string | Y* | The amount of memory available for applications to utilize on the device. The value is given in binary units (`Ki` = Kibibytes, `Mi` = Mebibytes, `Gi` = Gibibytes). This is defined by the device owner.| +| storage | string | Y* | The amount of storage available for applications to utilize on the device. The value is given in binary units (`Ki` = Kibibytes, `Mi` = Mebibytes, `Gi` = Gibibytes, `Ti` = Tebibytes, `Pi` = Pebibytes, `Ei` = Exbibytes). This is defined by the device owner.| +| peripherals | []Peripheral | N | Peripherals available for applications to utilize on the device. See the [Peripheral](#peripheral-attributes) section below.| +| interfaces | []CommunicationInterface | N | Communication interfaces available for applications to utilize on the device. See the [Communication Interfaces](#communicationinterface-attributes) section below.| +| otelCollector | boolean | Y* | Reports whether an OpenTelemetry (OTEL) collector is present on the device. | +| supportedRuntimes | []SupportedRuntime | Y* | The standard Margo OCI runtimes available on the device. See the [SupportedRuntime](#supportedruntime) definition for all permissible values. A device that hosts workloads MUST report at least one entry.| +| supportedDeploymentTypes | []SupportedDeploymentType | Y* | The manifest/deployment formats the device can receive and process locally. See the [SupportedDeploymentType](#supporteddeploymenttype) definition for all permissible values. A device that hosts workloads MUST report at least one entry.| +| managesChildDevices | boolean | N | Indicates the device is a see-thru gateway that reports the capabilities of one or more child devices to the WFM as individually visible devices. See the [Gateways considerations](#gateways-considerations) section below. | + +> \* Required for devices that host workloads locally. A device that only manages child devices (a see-thru gateway that hosts nothing itself) reports `managesChildDevices: true` and omits these workload-hosting fields. Every `DeviceCapabilitiesManifest` MUST report at least one capability: the workload-hosting fields (`cpu`, `memory`, `storage`, `otelCollector`, `supportedRuntimes`, `supportedDeploymentTypes`) or `managesChildDevices: true`. ### CPU Attributes CPU element defining the device's CPU characteristics. @@ -72,7 +69,7 @@ CPU element defining the device's CPU characteristics. | Attribute | Type | Required? | Description | | --- | --- | --- | --- | | cores | integer | Y | Defines the cores available within the hosts CPU. Specified as decimal units of CPU cores (e.g., `0.5` is half a core). This is defined by the device owner. After deployment of the application, the device MUST provide this number of CPU cores for the application.| -| architecture | CpuArchitectureType | N | The CPU architecture supported by the device. This can be e.g. amd64, x86_64, arm64, arm. See the [CpuArchitectureType](#cpuarchitecturetype) definition for all permissible values.| +| architecture | CpuArchitectureType | N | The CPU architecture supported by the device. This can be e.g. amd64, arm64, arm. See the [CpuArchitectureType](#cpuarchitecturetype) definition for all permissible values.| ### Peripheral Attributes @@ -125,6 +122,20 @@ These enumerations are used as vocabularies for attribute values of the `DeviceC | microphone | This type stands for a microphone peripheral. | | speaker | This type stands for a speaker peripheral. | +#### SupportedRuntime + +| Permissible Values | Description | +| --- | --- | +| oci | OCI container runtime. | + + +#### SupportedDeploymentType + +| Permissible Values | Description | +| --- | --- | +| helm | Device can receive and process Kubernetes Helm chart deployments locally. | +| compose | Device can receive and process Docker Compose service deployments locally. | + ## Example Device Capabilities Payload @@ -134,37 +145,39 @@ These enumerations are used as vocabularies for attribute values of the `DeviceC "kind": "DeviceCapabilitiesManifest", "properties": { "id": "northstarida.xtapro.k8s.edge", - "vendor": "Northstar Industrial devices", + "vendor": "Northstar Industrial Devices", "modelNumber": "332ANZE1-N1", "serialNumber": "PF45343-AA", - "roles": [ - "standalone cluster", - "cluster leader" + "cpu": [ + { + "cores": 24, + "architecture": "amd64" + } ], - "resources": { - "cpu": [ - { - "cores": 24, - "architecture": "x86_64" - } - ], - "memory": "59 Gi", - "storage": "1862 Gi", - "peripherals": [ - { - "type": "GPU", - "manufacturer": "NVIDIA" - } - ], - "interfaces": [ - { - "type": "ethernet" - }, - { - "type": "wifi" - } - ] - } + "memory": "59 Gi", + "storage": "1862 Gi", + "peripherals": [ + { + "type": "gpu", + "manufacturer": "NVIDIA" + } + ], + "interfaces": [ + { + "type": "ethernet" + }, + { + "type": "wifi" + } + ], + "otelCollector": true, + "supportedRuntimes": [ + "oci" + ], + "supportedDeploymentTypes": [ + "helm", + "compose" + ] } } ``` @@ -175,19 +188,19 @@ These enumerations are used as vocabularies for attribute values of the `DeviceC ### 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. +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 does not set `managesChildDevices`; it 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. In addition since the gateway can deploy compose applications on its child-devices it will report the role of "standalone device". +> 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 clients are referred to as see-thru gateways and report the "Gateway" role. +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 and reports `managesChildDevices: true`. -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 `deviceId`s: "gateway1", "gateway1/deviceA", and "gateway1/deviceB". +A see-thru gateway MUST report its own capabilities and the capabilities of each device it connects 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 `deviceId`s: "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 see-thru gateway that does not host workloads itself reports only `managesChildDevices: true` and omits the workload-hosting fields (`cpu`, `memory`, `storage`, `otelCollector`, `supportedRuntimes`, `supportedDeploymentTypes`). A see-thru gateway that is also capable of hosting workloads reports `managesChildDevices: true` together with the workload-hosting fields, including at least one entry in both `supportedRuntimes` and `supportedDeploymentTypes`. -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. +A see-thru gateway 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 @@ -205,9 +218,7 @@ A WFM client reporting the "Gateway" role MUST report its own capabilities to th "vendor": "Gateway Vendor", "modelNumber": "GW-1000", "serialNumber": "GW12345678", - "roles": [ - "Gateway" - ] + "managesChildDevices": true } } ``` @@ -226,26 +237,28 @@ A WFM client reporting the "Gateway" role MUST report its own capabilities to th "vendor": "Gateway Vendor", "modelNumber": "GW-1000", "serialNumber": "GW12345678", - "roles": [ - "Gateway", - "Standalone Device" + "managesChildDevices": true, + "cpu": [ + { + "cores": 4, + "architecture": "amd64" + } ], - "resources": { - "cpu": [ - { - "cores": 4, - "architecture": "x86_64" - } - ], - "memory": "12 Gi", - "storage": "200 Gi", - "peripherals": [], - "interfaces": [ - { - "type": "ethernet" - } - ] - } + "memory": "12 Gi", + "storage": "200 Gi", + "peripherals": [], + "interfaces": [ + { + "type": "ethernet" + } + ], + "otelCollector": true, + "supportedRuntimes": [ + "oci" + ], + "supportedDeploymentTypes": [ + "compose" + ] } } ``` @@ -264,31 +277,32 @@ A WFM client reporting the "Gateway" role MUST report its own capabilities to th "vendor": "Device A Vendor", "modelNumber": "DA-2000", "serialNumber": "DA12345678", - "roles": [ - "Standalone Cluster", - "Cluster Leader" + "cpu": [ + { + "cores": 24, + "architecture": "amd64" + } ], - "resources": { - "cpu": [ - { - "cores": 24, - "architecture": "x86_64" - } - ], - "memory": "59 Gi", - "storage": "1862 Gi", - "peripherals": [ - { - "type": "GPU", - "manufacturer": "NVIDIA" - } - ], - "interfaces": [ - { - "type": "ethernet" - } - ] - } + "memory": "59 Gi", + "storage": "1862 Gi", + "peripherals": [ + { + "type": "gpu", + "manufacturer": "NVIDIA" + } + ], + "interfaces": [ + { + "type": "ethernet" + } + ], + "otelCollector": true, + "supportedRuntimes": [ + "oci" + ], + "supportedDeploymentTypes": [ + "helm" + ] } } ``` @@ -307,25 +321,27 @@ A WFM client reporting the "Gateway" role MUST report its own capabilities to th "vendor": "Device A Vendor", "modelNumber": "DA-1000", "serialNumber": "DA12345678", - "roles": [ - "Standalone Device" + "cpu": [ + { + "cores": 2, + "architecture": "arm64" + } ], - "resources": { - "cpu": [ - { - "cores": 2, - "architecture": "arm64" - } - ], - "memory": "6 Gi", - "storage": "30 Gi", - "peripherals": [], - "interfaces": [ - { - "type": "ethernet" - } - ] - } + "memory": "6 Gi", + "storage": "30 Gi", + "peripherals": [], + "interfaces": [ + { + "type": "ethernet" + } + ], + "otelCollector": true, + "supportedRuntimes": [ + "oci" + ], + "supportedDeploymentTypes": [ + "compose" + ] } } ``` diff --git a/system-design/specification/margo-management-interface/workload-management-api-1.0.0.yaml b/system-design/specification/margo-management-interface/workload-management-api-1.0.0.yaml index 829889d9..f098dad5 100644 --- a/system-design/specification/margo-management-interface/workload-management-api-1.0.0.yaml +++ b/system-design/specification/margo-management-interface/workload-management-api-1.0.0.yaml @@ -479,7 +479,14 @@ components: enum: [DeviceCapabilitiesManifest] properties: type: object - required: [id, vendor, modelNumber, serialNumber, roles] + required: [id, vendor, modelNumber, serialNumber] + # A device that hosts workloads MUST report cpu, memory, storage, otelCollector, + # supportedRuntimes (>=1), and supportedDeploymentTypes (>=1). A see-thru gateway that + # hosts nothing itself sets managesChildDevices=true and omits those fields. Every + # manifest MUST report at least one capability group, enforced by the anyOf below. + anyOf: + - required: [supportedDeploymentTypes] + - required: [managesChildDevices] properties: id: $ref: '#/components/schemas/DeviceId' @@ -489,36 +496,45 @@ components: type: string serialNumber: type: string - roles: + cpu: type: array + items: + type: object + required: [cores] + properties: + cores: + type: number + architecture: + type: string + enum: [amd64, arm64, arm] + memory: + type: string + storage: + type: string + peripherals: + type: array + items: + $ref: '#/components/schemas/DevicePeripheral' + interfaces: + type: array + items: + $ref: '#/components/schemas/DeviceCommunicationInterface' + otelCollector: + type: boolean + supportedRuntimes: + type: array + minItems: 1 items: type: string - enum: [Standalone Cluster, Cluster Leader, Standalone Device, Gateway] - resources: - type: object - required: [cpu, memory, storage, peripherals, interfaces] - properties: - cpu: - type: object - required: [cores] - properties: - cores: - type: number - architecture: - type: string - enum: [amd64, arm64, arm] - memory: - type: string - storage: - type: string - peripherals: - type: array - items: - $ref: '#/components/schemas/DevicePeripheral' - interfaces: - type: array - items: - $ref: '#/components/schemas/DeviceCommunicationInterface' + enum: [oci] + supportedDeploymentTypes: + type: array + minItems: 1 + items: + type: string + enum: [helm, compose] + managesChildDevices: + type: boolean DeviceId: # format: "{id}[/{id}[/{id}...]]" # Top-level id is required and must include only unreserved characters as specified in RFC3986. From 1799871603822d73a10ee68a41b4e45ad6930dad Mon Sep 17 00:00:00 2001 From: Armand Craig Date: Tue, 21 Jul 2026 15:30:06 -0400 Subject: [PATCH 02/32] Further improvements to device capabilities and requirements markdown files. Signed-off-by: Armand Craig --- .../margo-devices/device-requirements.md | 4 ++- .../device-capabilities.md | 31 +++++++++---------- .../workload-management-api-1.0.0.yaml | 14 +++------ 3 files changed, 22 insertions(+), 27 deletions(-) diff --git a/system-design/specification/margo-devices/device-requirements.md b/system-design/specification/margo-devices/device-requirements.md index c138121e..bdeb3bf6 100644 --- a/system-design/specification/margo-devices/device-requirements.md +++ b/system-design/specification/margo-devices/device-requirements.md @@ -1,11 +1,13 @@ # Device Requirements -All Margo conformant devices MUST meet a baseline set of requirements to be considered Margo compliant. These requirements ensure devices can effectively host and manage Margo compliant workloads. A device MUST support onboarding and management from only a single workload fleet manager. A device reports what it can provide to the ecosystem through its [device capabilities](../margo-management-interface/device-capabilities.md). +All Margo conformant devices MUST meet a baseline set of requirements to be considered Margo compliant. These requirements ensure devices can effectively manage Margo compliant workload and/or host those workloads. A device MUST support onboarding and management from only a single workload fleet manager. A device reports what it can provide to the ecosystem through its [device capabilities](../margo-management-interface/device-capabilities.md). All devices MUST provide the following components: - A workload fleet management client +> Note: This is not required for a device behind a see-thru gateway. + All workload hosting devices MUST provide the following components: - at least one supported deployment type (`supportedDeploymentTypes`) diff --git a/system-design/specification/margo-management-interface/device-capabilities.md b/system-design/specification/margo-management-interface/device-capabilities.md index b6b1358b..19219122 100644 --- a/system-design/specification/margo-management-interface/device-capabilities.md +++ b/system-design/specification/margo-management-interface/device-capabilities.md @@ -51,17 +51,16 @@ DELETE /api/v1/clients/{clientId}/capabilities/{deviceId} | vendor | string | Y | Defines the device vendor.| | modelNumber | string | Y | Defines the model number of the device.| | serialNumber | string | Y | Defines the serial number of the device.| -| cpu | []CPU | Y* | List of CPU entries available on the device. Utilized to match with the required resources defined in the application description. See the [CPU](#cpu-attributes) section below.| -| memory | string | Y* | The amount of memory available for applications to utilize on the device. The value is given in binary units (`Ki` = Kibibytes, `Mi` = Mebibytes, `Gi` = Gibibytes). This is defined by the device owner.| -| storage | string | Y* | The amount of storage available for applications to utilize on the device. The value is given in binary units (`Ki` = Kibibytes, `Mi` = Mebibytes, `Gi` = Gibibytes, `Ti` = Tebibytes, `Pi` = Pebibytes, `Ei` = Exbibytes). This is defined by the device owner.| -| peripherals | []Peripheral | N | Peripherals available for applications to utilize on the device. See the [Peripheral](#peripheral-attributes) section below.| -| interfaces | []CommunicationInterface | N | Communication interfaces available for applications to utilize on the device. See the [Communication Interfaces](#communicationinterface-attributes) section below.| -| otelCollector | boolean | Y* | Reports whether an OpenTelemetry (OTEL) collector is present on the device. | -| supportedRuntimes | []SupportedRuntime | Y* | The standard Margo OCI runtimes available on the device. See the [SupportedRuntime](#supportedruntime) definition for all permissible values. A device that hosts workloads MUST report at least one entry.| -| supportedDeploymentTypes | []SupportedDeploymentType | Y* | The manifest/deployment formats the device can receive and process locally. See the [SupportedDeploymentType](#supporteddeploymenttype) definition for all permissible values. A device that hosts workloads MUST report at least one entry.| -| managesChildDevices | boolean | N | Indicates the device is a see-thru gateway that reports the capabilities of one or more child devices to the WFM as individually visible devices. See the [Gateways considerations](#gateways-considerations) section below. | - -> \* Required for devices that host workloads locally. A device that only manages child devices (a see-thru gateway that hosts nothing itself) reports `managesChildDevices: true` and omits these workload-hosting fields. Every `DeviceCapabilitiesManifest` MUST report at least one capability: the workload-hosting fields (`cpu`, `memory`, `storage`, `otelCollector`, `supportedRuntimes`, `supportedDeploymentTypes`) or `managesChildDevices: true`. +| cpu | []CPU | N* | List of CPU entries available on the device. Utilized to match with the required resources defined in the application description. See the [CPU](#cpu-attributes) section below.| +| memory | string | N* | The amount of memory available for applications to utilize on the device. The value is given in binary units (`Ki` = Kibibytes, `Mi` = Mebibytes, `Gi` = Gibibytes). This is defined by the device owner.| +| storage | string | N* | The amount of storage available for applications to utilize on the device. The value is given in binary units (`Ki` = Kibibytes, `Mi` = Mebibytes, `Gi` = Gibibytes, `Ti` = Tebibytes, `Pi` = Pebibytes, `Ei` = Exbibytes). This is defined by the device owner.| +| peripherals | []Peripheral | N* | Peripherals available for applications to utilize on the device. See the [Peripheral](#peripheral-attributes) section below.| +| interfaces | []CommunicationInterface | N* | Communication interfaces available for applications to utilize on the device. See the [Communication Interfaces](#communicationinterface-attributes) section below.| +| otelCollector | boolean | N* | Reports whether an OpenTelemetry (OTEL) collector is present on the device. | +| supportedRuntimes | []SupportedRuntime | N* | Supported workload runtimes present on the device. See the [SupportedRuntime](#supportedruntime) definition for all permissible values. A device that hosts workloads MUST report at least one entry.| +| supportedDeploymentTypes | []SupportedDeploymentType | N* | The manifest/deployment formats the device can receive and process locally. See the [SupportedDeploymentType](#supporteddeploymenttype) definition for all permissible values. A device that hosts workloads MUST report at least one entry.| + +> Note: \* Required for devices that host workloads locally. A device that does not host workloads itself, for example see-thru gateway, that only relays the devices behind it — omits these fields. The WFM infers that such a device is non-hosting from the absence of these capabilities, and infers a gateway relationship from the parent/child `deviceId` hierarchy. No explicit gateway flag is required. ### CPU Attributes CPU element defining the device's CPU characteristics. @@ -188,17 +187,17 @@ These enumerations are used as vocabularies for attribute values of the `DeviceC ### 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 does not set `managesChildDevices`; it reports the aggregated resource fields, `supportedRuntimes`, and `supportedDeploymentTypes` of the devices behind it. +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 and reports `managesChildDevices: true`. +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 is not a special device type; it is treated as an ordinary device that additionally reports the capabilities of the devices behind it. The WFM infers the gateway relationship from the reported information — the parent/child `deviceId` hierarchy and it is especially evident when the gateway itself reports no workload-hosting capabilities. A see-thru gateway MUST report its own capabilities and the capabilities of each device it connects 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 `deviceId`s: "gateway1", "gateway1/deviceA", and "gateway1/deviceB". -A see-thru gateway that does not host workloads itself reports only `managesChildDevices: true` and omits the workload-hosting fields (`cpu`, `memory`, `storage`, `otelCollector`, `supportedRuntimes`, `supportedDeploymentTypes`). A see-thru gateway that is also capable of hosting workloads reports `managesChildDevices: true` together with the workload-hosting fields, including at least one entry in both `supportedRuntimes` and `supportedDeploymentTypes`. +A see-thru gateway that does not host workloads itself omits the workload-hosting fields (`cpu`, `memory`, `storage`, `otelCollector`, `supportedRuntimes`, `supportedDeploymentTypes`), so its manifest contains only the required identity fields. A see-thru gateway that is also capable of hosting workloads reports the workload-hosting fields, including at least one entry in both `supportedRuntimes` and `supportedDeploymentTypes`. A see-thru gateway 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. @@ -217,8 +216,7 @@ A see-thru gateway MUST report its own capabilities to the WFM before reporting "id": "gateway1", "vendor": "Gateway Vendor", "modelNumber": "GW-1000", - "serialNumber": "GW12345678", - "managesChildDevices": true + "serialNumber": "GW12345678" } } ``` @@ -237,7 +235,6 @@ A see-thru gateway MUST report its own capabilities to the WFM before reporting "vendor": "Gateway Vendor", "modelNumber": "GW-1000", "serialNumber": "GW12345678", - "managesChildDevices": true, "cpu": [ { "cores": 4, diff --git a/system-design/specification/margo-management-interface/workload-management-api-1.0.0.yaml b/system-design/specification/margo-management-interface/workload-management-api-1.0.0.yaml index f098dad5..5e737683 100644 --- a/system-design/specification/margo-management-interface/workload-management-api-1.0.0.yaml +++ b/system-design/specification/margo-management-interface/workload-management-api-1.0.0.yaml @@ -480,13 +480,11 @@ components: properties: type: object required: [id, vendor, modelNumber, serialNumber] - # A device that hosts workloads MUST report cpu, memory, storage, otelCollector, - # supportedRuntimes (>=1), and supportedDeploymentTypes (>=1). A see-thru gateway that - # hosts nothing itself sets managesChildDevices=true and omits those fields. Every - # manifest MUST report at least one capability group, enforced by the anyOf below. - anyOf: - - required: [supportedDeploymentTypes] - - required: [managesChildDevices] + # Only identity fields are required. A device that hosts workloads reports cpu, memory, + # storage, otelCollector, supportedRuntimes (>=1), and supportedDeploymentTypes (>=1). A + # device that does not host workloads (e.g. a see-thru gateway that only relays the + # devices behind it) omits those fields; the WFM infers it is non-hosting from their + # absence and infers a gateway from the parent/child deviceId hierarchy. properties: id: $ref: '#/components/schemas/DeviceId' @@ -533,8 +531,6 @@ components: items: type: string enum: [helm, compose] - managesChildDevices: - type: boolean DeviceId: # format: "{id}[/{id}[/{id}...]]" # Top-level id is required and must include only unreserved characters as specified in RFC3986. From 6cb68d3b741c320c7cd9fd80104c4623e014a7a9 Mon Sep 17 00:00:00 2001 From: Armand Craig Date: Thu, 23 Jul 2026 14:40:11 -0400 Subject: [PATCH 03/32] Further refinement removing content referring to the older device roles. Additional edits are still warranted in the observability content regarding gateway devices(this will be handled outside this PR). Signed-off-by: Armand Craig --- .../margo-management-interface/resources/index.md.jinja2 | 4 ++-- .../observability/collecting-workload-observability-data.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/specification/margo-management-interface/resources/index.md.jinja2 b/src/specification/margo-management-interface/resources/index.md.jinja2 index cc5260d4..74f09dc8 100644 --- a/src/specification/margo-management-interface/resources/index.md.jinja2 +++ b/src/specification/margo-management-interface/resources/index.md.jinja2 @@ -334,13 +334,13 @@ spec: {%- endif %} {%- endfor %} -### Example: Cluster Enabled Application Deployment Specification +### Example: Helm Deployment Specification ```yaml {% include 'examples/valid/DesiredState-001.yaml' %} ``` -### Example: Standalone Device Application Deployment Specification +### Example: Compose Deployment Specification ```yaml {% include 'examples/valid/DesiredState-002.yaml' %} diff --git a/system-design/specification/observability/collecting-workload-observability-data.md b/system-design/specification/observability/collecting-workload-observability-data.md index cb648217..16039c58 100644 --- a/system-design/specification/observability/collecting-workload-observability-data.md +++ b/system-design/specification/observability/collecting-workload-observability-data.md @@ -58,7 +58,7 @@ For devices running Kubernetes the following is a minimum list of observability > **Note:** Please see the [information below](#workload-observability-default-telemetry) for the default attributes added by the Kubernetes Attributes Processor. -### Standalone Device Container Platforms +### Non-Clustered Container Platforms For devices running non-clustered container platforms such as Docker or Podman the following is a minimum list of observability data that MUST be provided. The device owner MAY choose to provide additional observability data if they wish. From 8844848d2fad84d734cd5ad8c6a665bf4888e195 Mon Sep 17 00:00:00 2001 From: Armand Craig Date: Fri, 31 Jul 2026 08:36:07 -0400 Subject: [PATCH 04/32] Update system-design/specification/margo-devices/device-requirements.md Co-authored-by: Philip Presson Signed-off-by: Armand Craig --- .../specification/margo-devices/device-requirements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/system-design/specification/margo-devices/device-requirements.md b/system-design/specification/margo-devices/device-requirements.md index bdeb3bf6..25df7a1e 100644 --- a/system-design/specification/margo-devices/device-requirements.md +++ b/system-design/specification/margo-devices/device-requirements.md @@ -2,7 +2,7 @@ All Margo conformant devices MUST meet a baseline set of requirements to be considered Margo compliant. These requirements ensure devices can effectively manage Margo compliant workload and/or host those workloads. A device MUST support onboarding and management from only a single workload fleet manager. A device reports what it can provide to the ecosystem through its [device capabilities](../margo-management-interface/device-capabilities.md). -All devices MUST provide the following components: +All margo-conformant devices MUST provide the following components: - A workload fleet management client From 443a8c4f3d6293a770daeb07ae580d1abb39cce2 Mon Sep 17 00:00:00 2001 From: Armand Craig Date: Fri, 31 Jul 2026 08:36:44 -0400 Subject: [PATCH 05/32] Update system-design/specification/margo-devices/device-requirements.md Co-authored-by: Philip Presson Signed-off-by: Armand Craig --- .../specification/margo-devices/device-requirements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/system-design/specification/margo-devices/device-requirements.md b/system-design/specification/margo-devices/device-requirements.md index 25df7a1e..c3db92b1 100644 --- a/system-design/specification/margo-devices/device-requirements.md +++ b/system-design/specification/margo-devices/device-requirements.md @@ -1,6 +1,6 @@ # Device Requirements -All Margo conformant devices MUST meet a baseline set of requirements to be considered Margo compliant. These requirements ensure devices can effectively manage Margo compliant workload and/or host those workloads. A device MUST support onboarding and management from only a single workload fleet manager. A device reports what it can provide to the ecosystem through its [device capabilities](../margo-management-interface/device-capabilities.md). +All Margo conformant devices MUST meet a baseline set of requirements to be considered Margo compliant. These requirements ensure devices can effectively manage Margo-compliant workload and/or host those workloads. A device MUST support onboarding and management from only a single workload fleet manager. A device reports what it can provide to the ecosystem through its [device capabilities](../margo-management-interface/device-capabilities.md). All margo-conformant devices MUST provide the following components: From 6522aecd7a7d1cef7fa689744574e8d06b096c41 Mon Sep 17 00:00:00 2001 From: Armand Craig Date: Fri, 31 Jul 2026 08:37:14 -0400 Subject: [PATCH 06/32] Update system-design/specification/margo-management-interface/device-capabilities.md Co-authored-by: Philip Presson Signed-off-by: Armand Craig --- .../margo-management-interface/device-capabilities.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/system-design/specification/margo-management-interface/device-capabilities.md b/system-design/specification/margo-management-interface/device-capabilities.md index 19219122..772e163a 100644 --- a/system-design/specification/margo-management-interface/device-capabilities.md +++ b/system-design/specification/margo-management-interface/device-capabilities.md @@ -58,7 +58,7 @@ DELETE /api/v1/clients/{clientId}/capabilities/{deviceId} | interfaces | []CommunicationInterface | N* | Communication interfaces available for applications to utilize on the device. See the [Communication Interfaces](#communicationinterface-attributes) section below.| | otelCollector | boolean | N* | Reports whether an OpenTelemetry (OTEL) collector is present on the device. | | supportedRuntimes | []SupportedRuntime | N* | Supported workload runtimes present on the device. See the [SupportedRuntime](#supportedruntime) definition for all permissible values. A device that hosts workloads MUST report at least one entry.| -| supportedDeploymentTypes | []SupportedDeploymentType | N* | The manifest/deployment formats the device can receive and process locally. See the [SupportedDeploymentType](#supporteddeploymenttype) definition for all permissible values. A device that hosts workloads MUST report at least one entry.| +| supportedDeploymentTypes | []SupportedDeploymentType | N* | The deployment profile types the device can receive and process locally. See the [SupportedDeploymentType](#supporteddeploymenttype) definition for all permissible values. A device that hosts workloads MUST report at least one entry.| > Note: \* Required for devices that host workloads locally. A device that does not host workloads itself, for example see-thru gateway, that only relays the devices behind it — omits these fields. The WFM infers that such a device is non-hosting from the absence of these capabilities, and infers a gateway relationship from the parent/child `deviceId` hierarchy. No explicit gateway flag is required. From a2517920b3409151100b5abd2ae0c3f8b2d8a91d Mon Sep 17 00:00:00 2001 From: Armand Craig Date: Fri, 31 Jul 2026 08:37:31 -0400 Subject: [PATCH 07/32] Update system-design/specification/observability/collecting-workload-observability-data.md Co-authored-by: Philip Presson Signed-off-by: Armand Craig --- .../observability/collecting-workload-observability-data.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/system-design/specification/observability/collecting-workload-observability-data.md b/system-design/specification/observability/collecting-workload-observability-data.md index 16039c58..8e6c6f73 100644 --- a/system-design/specification/observability/collecting-workload-observability-data.md +++ b/system-design/specification/observability/collecting-workload-observability-data.md @@ -58,7 +58,7 @@ For devices running Kubernetes the following is a minimum list of observability > **Note:** Please see the [information below](#workload-observability-default-telemetry) for the default attributes added by the Kubernetes Attributes Processor. -### Non-Clustered Container Platforms +### Compose-based Devices For devices running non-clustered container platforms such as Docker or Podman the following is a minimum list of observability data that MUST be provided. The device owner MAY choose to provide additional observability data if they wish. From 856d13e893b5453d3bd418f2f580f8519d6ba1b8 Mon Sep 17 00:00:00 2001 From: Armand Craig Date: Fri, 31 Jul 2026 08:37:47 -0400 Subject: [PATCH 08/32] Update system-design/specification/observability/collecting-workload-observability-data.md Co-authored-by: Philip Presson Signed-off-by: Armand Craig --- .../observability/collecting-workload-observability-data.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/system-design/specification/observability/collecting-workload-observability-data.md b/system-design/specification/observability/collecting-workload-observability-data.md index 8e6c6f73..a22a9297 100644 --- a/system-design/specification/observability/collecting-workload-observability-data.md +++ b/system-design/specification/observability/collecting-workload-observability-data.md @@ -60,7 +60,7 @@ For devices running Kubernetes the following is a minimum list of observability ### Compose-based Devices -For devices running non-clustered container platforms such as Docker or Podman the following is a minimum list of observability data that MUST be provided. The device owner MAY choose to provide additional observability data if they wish. +For devices with runtimes supporting compose deployment types, such as Docker or Podman, the following is a minimum list of observability data that MUST be provided. The device owner MAY choose to provide additional observability data if they wish. - Container observability data MUST be collected. - It is recommended the Device Owner use the [Docker Stats Receiver](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/receiver/dockerstatsreceiver/README.md) or [Podman Stats Receiver](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/receiver/podmanreceiver/README.md) with the default configuration to collect this information but using either of these receivers is not required. From 4a5cfeeb9b19ce5039d0a0cef7b5010e9250a24b Mon Sep 17 00:00:00 2001 From: Armand Craig Date: Fri, 31 Jul 2026 08:40:43 -0400 Subject: [PATCH 09/32] Update system-design/specification/margo-management-interface/device-capabilities.md Co-authored-by: Philip Presson Signed-off-by: Armand Craig --- .../margo-management-interface/device-capabilities.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/system-design/specification/margo-management-interface/device-capabilities.md b/system-design/specification/margo-management-interface/device-capabilities.md index 772e163a..2d425940 100644 --- a/system-design/specification/margo-management-interface/device-capabilities.md +++ b/system-design/specification/margo-management-interface/device-capabilities.md @@ -197,7 +197,7 @@ WFM clients may connect one or more child-devices to the WFM while allowing the A see-thru gateway MUST report its own capabilities and the capabilities of each device it connects 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 `deviceId`s: "gateway1", "gateway1/deviceA", and "gateway1/deviceB". -A see-thru gateway that does not host workloads itself omits the workload-hosting fields (`cpu`, `memory`, `storage`, `otelCollector`, `supportedRuntimes`, `supportedDeploymentTypes`), so its manifest contains only the required identity fields. A see-thru gateway that is also capable of hosting workloads reports the workload-hosting fields, including at least one entry in both `supportedRuntimes` and `supportedDeploymentTypes`. +A see-thru gateway that does not host workloads itself MUST omit the workload-hosting fields (`cpu`, `memory`, `storage`, `otelCollector`, `supportedRuntimes`, `supportedDeploymentTypes`), so its manifest contains only the required identity fields. A see-thru gateway that is also capable of hosting workloads reports the workload-hosting fields, including at least one entry in both `supportedRuntimes` and `supportedDeploymentTypes`. A see-thru gateway 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. From 0b1cc562a6de5972cf22d7b3f05d529b08e07009 Mon Sep 17 00:00:00 2001 From: Armand Craig Date: Fri, 31 Jul 2026 08:40:57 -0400 Subject: [PATCH 10/32] Update system-design/specification/margo-management-interface/device-capabilities.md Co-authored-by: Philip Presson Signed-off-by: Armand Craig --- .../margo-management-interface/device-capabilities.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/system-design/specification/margo-management-interface/device-capabilities.md b/system-design/specification/margo-management-interface/device-capabilities.md index 2d425940..60f12bd2 100644 --- a/system-design/specification/margo-management-interface/device-capabilities.md +++ b/system-design/specification/margo-management-interface/device-capabilities.md @@ -133,7 +133,7 @@ These enumerations are used as vocabularies for attribute values of the `DeviceC | Permissible Values | Description | | --- | --- | | helm | Device can receive and process Kubernetes Helm chart deployments locally. | -| compose | Device can receive and process Docker Compose service deployments locally. | +| compose | Device can receive and process Compose service deployments locally. | ## Example Device Capabilities Payload From 18ad80ef7211822009797ebc7bfaadf28573841e Mon Sep 17 00:00:00 2001 From: Armand Craig Date: Fri, 31 Jul 2026 08:41:15 -0400 Subject: [PATCH 11/32] Update system-design/specification/margo-management-interface/device-capabilities.md Co-authored-by: Philip Presson Signed-off-by: Armand Craig --- .../margo-management-interface/device-capabilities.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/system-design/specification/margo-management-interface/device-capabilities.md b/system-design/specification/margo-management-interface/device-capabilities.md index 60f12bd2..163117dc 100644 --- a/system-design/specification/margo-management-interface/device-capabilities.md +++ b/system-design/specification/margo-management-interface/device-capabilities.md @@ -60,7 +60,7 @@ DELETE /api/v1/clients/{clientId}/capabilities/{deviceId} | supportedRuntimes | []SupportedRuntime | N* | Supported workload runtimes present on the device. See the [SupportedRuntime](#supportedruntime) definition for all permissible values. A device that hosts workloads MUST report at least one entry.| | supportedDeploymentTypes | []SupportedDeploymentType | N* | The deployment profile types the device can receive and process locally. See the [SupportedDeploymentType](#supporteddeploymenttype) definition for all permissible values. A device that hosts workloads MUST report at least one entry.| -> Note: \* Required for devices that host workloads locally. A device that does not host workloads itself, for example see-thru gateway, that only relays the devices behind it — omits these fields. The WFM infers that such a device is non-hosting from the absence of these capabilities, and infers a gateway relationship from the parent/child `deviceId` hierarchy. No explicit gateway flag is required. +> Note: \* A see-through gateway not hosting workloads itself MUST omit or provide empty values for 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. From 87881720fa99a22e35ad0284c1d35a33dbaf7af7 Mon Sep 17 00:00:00 2001 From: Armand Craig Date: Fri, 31 Jul 2026 11:51:34 -0400 Subject: [PATCH 12/32] Address feedback on PR. Signed-off-by: Armand Craig --- .../specification/margo-devices/device-requirements.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/system-design/specification/margo-devices/device-requirements.md b/system-design/specification/margo-devices/device-requirements.md index c3db92b1..a3bd3e24 100644 --- a/system-design/specification/margo-devices/device-requirements.md +++ b/system-design/specification/margo-devices/device-requirements.md @@ -14,12 +14,13 @@ All workload hosting devices MUST provide the following components: - at least one supported workload runtime (`supportedRuntimes`) - An OTEL collector -## Kubernetes (Helm) enabled device requirements +> Note: See the `supportedDeploymentTypes` in [device capabilities](../margo-management-interface/device-capabilities.md) for the supported deployment types. + +## Helm enabled device requirements Devices supporting the helm deployment type, MUST provide the following additional components: - Capabilities for deploying Helm charts - - described via the `supportedDeploymentTypes`:`helm` - Kubernetes orchestration platform ### Helm deployment approaches @@ -40,8 +41,7 @@ If a device vendor chooses a deployment approach that does not interact with the Devices supporting the compose deployment type, MUST provide the following additional components: - Capabilities for deploying Compose applications - - described via the `supportedDeploymentTypes`:`compose` -- Compose compliant software as the orchestration platform +- Compose orchestration platform i.e., Docker or Podman ## Future Requirements From 0c20e3c157a284a3367ca37c70b8e7e59ff6f603 Mon Sep 17 00:00:00 2001 From: Armand Craig Date: Fri, 31 Jul 2026 11:55:08 -0400 Subject: [PATCH 13/32] Update to device capabilities regarding required reporting of device properties. Signed-off-by: Armand Craig --- .../device-capabilities.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/system-design/specification/margo-management-interface/device-capabilities.md b/system-design/specification/margo-management-interface/device-capabilities.md index 163117dc..775a0aad 100644 --- a/system-design/specification/margo-management-interface/device-capabilities.md +++ b/system-design/specification/margo-management-interface/device-capabilities.md @@ -51,14 +51,14 @@ DELETE /api/v1/clients/{clientId}/capabilities/{deviceId} | vendor | string | Y | Defines the device vendor.| | modelNumber | string | Y | Defines the model number of the device.| | serialNumber | string | Y | Defines the serial number of the device.| -| cpu | []CPU | N* | List of CPU entries available on the device. Utilized to match with the required resources defined in the application description. See the [CPU](#cpu-attributes) section below.| -| memory | string | N* | The amount of memory available for applications to utilize on the device. The value is given in binary units (`Ki` = Kibibytes, `Mi` = Mebibytes, `Gi` = Gibibytes). This is defined by the device owner.| -| storage | string | N* | The amount of storage available for applications to utilize on the device. The value is given in binary units (`Ki` = Kibibytes, `Mi` = Mebibytes, `Gi` = Gibibytes, `Ti` = Tebibytes, `Pi` = Pebibytes, `Ei` = Exbibytes). This is defined by the device owner.| -| peripherals | []Peripheral | N* | Peripherals available for applications to utilize on the device. See the [Peripheral](#peripheral-attributes) section below.| -| interfaces | []CommunicationInterface | N* | Communication interfaces available for applications to utilize on the device. See the [Communication Interfaces](#communicationinterface-attributes) section below.| -| otelCollector | boolean | N* | Reports whether an OpenTelemetry (OTEL) collector is present on the device. | -| supportedRuntimes | []SupportedRuntime | N* | Supported workload runtimes present on the device. See the [SupportedRuntime](#supportedruntime) definition for all permissible values. A device that hosts workloads MUST report at least one entry.| -| supportedDeploymentTypes | []SupportedDeploymentType | N* | The deployment profile types the device can receive and process locally. See the [SupportedDeploymentType](#supporteddeploymenttype) definition for all permissible values. A device that hosts workloads MUST report at least one entry.| +| cpu | []CPU | Y* | List of CPU entries available on the device. Utilized to match with the required resources defined in the application description. See the [CPU](#cpu-attributes) section below.| +| memory | string | Y* | The amount of memory available for applications to utilize on the device. The value is given in binary units (`Ki` = Kibibytes, `Mi` = Mebibytes, `Gi` = Gibibytes). This is defined by the device owner.| +| storage | string | Y* | The amount of storage available for applications to utilize on the device. The value is given in binary units (`Ki` = Kibibytes, `Mi` = Mebibytes, `Gi` = Gibibytes, `Ti` = Tebibytes, `Pi` = Pebibytes, `Ei` = Exbibytes). This is defined by the device owner.| +| peripherals | []Peripheral | Y* | Peripherals available for applications to utilize on the device. See the [Peripheral](#peripheral-attributes) section below.| +| interfaces | []CommunicationInterface | Y* | Communication interfaces available for applications to utilize on the device. See the [Communication Interfaces](#communicationinterface-attributes) section below.| +| otelCollector | boolean | Y* | Reports whether an OpenTelemetry (OTEL) collector is present on the device. | +| supportedRuntimes | []SupportedRuntime | Y* | Supported workload runtimes present on the device. See the [SupportedRuntime](#supportedruntime) definition for all permissible values. A device that hosts workloads MUST report at least one entry.| +| supportedDeploymentTypes | []SupportedDeploymentType | Y* | The deployment profile types the device can receive and process locally. See the [SupportedDeploymentType](#supporteddeploymenttype) definition for all permissible values. A device that hosts workloads MUST report at least one entry.| > Note: \* A see-through gateway not hosting workloads itself MUST omit or provide empty values for 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. From 7abff0fa65c3acce7af6d63761f61411ac3b23a8 Mon Sep 17 00:00:00 2001 From: Armand Craig Date: Fri, 31 Jul 2026 13:42:50 -0400 Subject: [PATCH 14/32] updated note based on review fb Signed-off-by: Armand Craig --- .../specification/margo-devices/device-requirements.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/system-design/specification/margo-devices/device-requirements.md b/system-design/specification/margo-devices/device-requirements.md index a3bd3e24..832c63d5 100644 --- a/system-design/specification/margo-devices/device-requirements.md +++ b/system-design/specification/margo-devices/device-requirements.md @@ -10,11 +10,11 @@ All margo-conformant devices MUST provide the following components: All workload hosting devices MUST provide the following components: -- at least one supported deployment type (`supportedDeploymentTypes`) -- at least one supported workload runtime (`supportedRuntimes`) +- at least one supported deployment type +- at least one supported workload runtime - An OTEL collector -> Note: See the `supportedDeploymentTypes` in [device capabilities](../margo-management-interface/device-capabilities.md) for the supported deployment types. +> Note: See [device capabilities](../margo-management-interface/device-capabilities.md) for the supported deployment types and runtimes. ## Helm enabled device requirements From e1a0a1f02a36aa53bb54b7d51dfcab2f09ea635b Mon Sep 17 00:00:00 2001 From: Armand Craig Date: Mon, 3 Aug 2026 09:44:27 -0400 Subject: [PATCH 15/32] Update system-design/specification/margo-management-interface/device-capabilities.md Co-authored-by: Matthias Lechner Signed-off-by: Armand Craig --- .../margo-management-interface/device-capabilities.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/system-design/specification/margo-management-interface/device-capabilities.md b/system-design/specification/margo-management-interface/device-capabilities.md index 775a0aad..c923cc75 100644 --- a/system-design/specification/margo-management-interface/device-capabilities.md +++ b/system-design/specification/margo-management-interface/device-capabilities.md @@ -60,7 +60,7 @@ DELETE /api/v1/clients/{clientId}/capabilities/{deviceId} | supportedRuntimes | []SupportedRuntime | Y* | Supported workload runtimes present on the device. See the [SupportedRuntime](#supportedruntime) definition for all permissible values. A device that hosts workloads MUST report at least one entry.| | supportedDeploymentTypes | []SupportedDeploymentType | Y* | The deployment profile types the device can receive and process locally. See the [SupportedDeploymentType](#supporteddeploymenttype) definition for all permissible values. A device that hosts workloads MUST report at least one entry.| -> Note: \* A see-through gateway not hosting workloads itself MUST omit or provide empty values for 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. +> Note: \* A see-thru gateway not hosting workloads itself MUST omit or provide empty values for 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. From fa9cc8d84e760609a214c42cd4ed0038b3667e29 Mon Sep 17 00:00:00 2001 From: Armand Craig Date: Mon, 3 Aug 2026 09:44:35 -0400 Subject: [PATCH 16/32] Update system-design/specification/margo-devices/device-requirements.md Co-authored-by: Matthias Lechner Signed-off-by: Armand Craig --- .../specification/margo-devices/device-requirements.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/system-design/specification/margo-devices/device-requirements.md b/system-design/specification/margo-devices/device-requirements.md index 832c63d5..528e94f6 100644 --- a/system-design/specification/margo-devices/device-requirements.md +++ b/system-design/specification/margo-devices/device-requirements.md @@ -10,8 +10,8 @@ All margo-conformant devices MUST provide the following components: All workload hosting devices MUST provide the following components: -- at least one supported deployment type -- at least one supported workload runtime +- At least one supported deployment type +- At least one supported workload runtime - An OTEL collector > Note: See [device capabilities](../margo-management-interface/device-capabilities.md) for the supported deployment types and runtimes. From 65f3b7e8d047aaba3c09acb6a4b9937ec41972ce Mon Sep 17 00:00:00 2001 From: Armand Craig Date: Mon, 3 Aug 2026 09:44:43 -0400 Subject: [PATCH 17/32] Update system-design/specification/margo-devices/device-requirements.md Co-authored-by: Matthias Lechner Signed-off-by: Armand Craig --- .../specification/margo-devices/device-requirements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/system-design/specification/margo-devices/device-requirements.md b/system-design/specification/margo-devices/device-requirements.md index 528e94f6..ed6bf874 100644 --- a/system-design/specification/margo-devices/device-requirements.md +++ b/system-design/specification/margo-devices/device-requirements.md @@ -8,7 +8,7 @@ All margo-conformant devices MUST provide the following components: > Note: This is not required for a device behind a see-thru gateway. -All workload hosting devices MUST provide the following components: +All workload hosting devices MUST provide the following capabilities: - At least one supported deployment type - At least one supported workload runtime From 4170e66cf6a7f879a2b64edd0bbba74b2765d8a8 Mon Sep 17 00:00:00 2001 From: Armand Craig Date: Mon, 3 Aug 2026 09:44:51 -0400 Subject: [PATCH 18/32] Update system-design/specification/margo-devices/device-requirements.md Co-authored-by: Matthias Lechner Signed-off-by: Armand Craig --- .../specification/margo-devices/device-requirements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/system-design/specification/margo-devices/device-requirements.md b/system-design/specification/margo-devices/device-requirements.md index ed6bf874..d6851a2e 100644 --- a/system-design/specification/margo-devices/device-requirements.md +++ b/system-design/specification/margo-devices/device-requirements.md @@ -2,7 +2,7 @@ All Margo conformant devices MUST meet a baseline set of requirements to be considered Margo compliant. These requirements ensure devices can effectively manage Margo-compliant workload and/or host those workloads. A device MUST support onboarding and management from only a single workload fleet manager. A device reports what it can provide to the ecosystem through its [device capabilities](../margo-management-interface/device-capabilities.md). -All margo-conformant devices MUST provide the following components: +All Margo-conformant devices MUST provide the following components: - A workload fleet management client From 544c56e9b8c8961dc62c0eddb4914b5f77b80e60 Mon Sep 17 00:00:00 2001 From: Armand Craig Date: Mon, 3 Aug 2026 09:45:32 -0400 Subject: [PATCH 19/32] Update system-design/specification/margo-devices/device-requirements.md Co-authored-by: Matthias Lechner Signed-off-by: Armand Craig --- .../specification/margo-devices/device-requirements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/system-design/specification/margo-devices/device-requirements.md b/system-design/specification/margo-devices/device-requirements.md index d6851a2e..4efd5449 100644 --- a/system-design/specification/margo-devices/device-requirements.md +++ b/system-design/specification/margo-devices/device-requirements.md @@ -16,7 +16,7 @@ All workload hosting devices MUST provide the following capabilities: > Note: See [device capabilities](../margo-management-interface/device-capabilities.md) for the supported deployment types and runtimes. -## Helm enabled device requirements +## Helm-enabled Device Requirements Devices supporting the helm deployment type, MUST provide the following additional components: From 074078641a94e328cca42e7adb77bdd60257df01 Mon Sep 17 00:00:00 2001 From: Armand Craig Date: Mon, 3 Aug 2026 09:47:41 -0400 Subject: [PATCH 20/32] Update system-design/specification/margo-devices/device-requirements.md Co-authored-by: Matthias Lechner Signed-off-by: Armand Craig --- .../specification/margo-devices/device-requirements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/system-design/specification/margo-devices/device-requirements.md b/system-design/specification/margo-devices/device-requirements.md index 4efd5449..eebb74a4 100644 --- a/system-design/specification/margo-devices/device-requirements.md +++ b/system-design/specification/margo-devices/device-requirements.md @@ -36,7 +36,7 @@ Margo does not dictate how devices deploy workloads packaged as Helm charts. A d If a device vendor chooses a deployment approach that does not interact with the Kubernetes API, the list of Kuberentes APIs available in the cluster MUST be provided out-of-band. This is supported by a variety of tooling such as the Helm GO SDK, `helm template` command, Kustomization, and ArgoCD. -## Compose enabled device requirements +## Compose-enabled Device Requirements Devices supporting the compose deployment type, MUST provide the following additional components: From abfc313c109e6b5e67cf919ef1dfbc78b6da6190 Mon Sep 17 00:00:00 2001 From: Armand Craig Date: Mon, 3 Aug 2026 09:48:15 -0400 Subject: [PATCH 21/32] Update system-design/specification/margo-devices/device-requirements.md Co-authored-by: Matthias Lechner Signed-off-by: Armand Craig --- .../specification/margo-devices/device-requirements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/system-design/specification/margo-devices/device-requirements.md b/system-design/specification/margo-devices/device-requirements.md index eebb74a4..3ebb06c9 100644 --- a/system-design/specification/margo-devices/device-requirements.md +++ b/system-design/specification/margo-devices/device-requirements.md @@ -38,7 +38,7 @@ If a device vendor chooses a deployment approach that does not interact with the ## Compose-enabled Device Requirements -Devices supporting the compose deployment type, MUST provide the following additional components: +Devices supporting the Compose deployment type, MUST provide the following additional components: - Capabilities for deploying Compose applications - Compose orchestration platform i.e., Docker or Podman From f3abecf703ff1eb67974692816dff75d154917e8 Mon Sep 17 00:00:00 2001 From: Armand Craig Date: Mon, 3 Aug 2026 09:48:43 -0400 Subject: [PATCH 22/32] Update system-design/specification/margo-devices/device-requirements.md Co-authored-by: Matthias Lechner Signed-off-by: Armand Craig --- .../specification/margo-devices/device-requirements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/system-design/specification/margo-devices/device-requirements.md b/system-design/specification/margo-devices/device-requirements.md index 3ebb06c9..cbd56666 100644 --- a/system-design/specification/margo-devices/device-requirements.md +++ b/system-design/specification/margo-devices/device-requirements.md @@ -18,7 +18,7 @@ All workload hosting devices MUST provide the following capabilities: ## Helm-enabled Device Requirements -Devices supporting the helm deployment type, MUST provide the following additional components: +Devices supporting the Helm deployment type, MUST provide the following additional components: - Capabilities for deploying Helm charts - Kubernetes orchestration platform From e442dd679831aee09129f4a47121f2a841b05f38 Mon Sep 17 00:00:00 2001 From: Armand Craig Date: Mon, 3 Aug 2026 09:56:36 -0400 Subject: [PATCH 23/32] Update system-design/specification/margo-management-interface/device-capabilities.md Co-authored-by: Matthias Lechner Signed-off-by: Armand Craig --- .../margo-management-interface/device-capabilities.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/system-design/specification/margo-management-interface/device-capabilities.md b/system-design/specification/margo-management-interface/device-capabilities.md index c923cc75..74167ada 100644 --- a/system-design/specification/margo-management-interface/device-capabilities.md +++ b/system-design/specification/margo-management-interface/device-capabilities.md @@ -57,7 +57,7 @@ DELETE /api/v1/clients/{clientId}/capabilities/{deviceId} | peripherals | []Peripheral | Y* | Peripherals available for applications to utilize on the device. See the [Peripheral](#peripheral-attributes) section below.| | interfaces | []CommunicationInterface | Y* | Communication interfaces available for applications to utilize on the device. See the [Communication Interfaces](#communicationinterface-attributes) section below.| | otelCollector | boolean | Y* | Reports whether an OpenTelemetry (OTEL) collector is present on the device. | -| supportedRuntimes | []SupportedRuntime | Y* | Supported workload runtimes present on the device. See the [SupportedRuntime](#supportedruntime) definition for all permissible values. A device that hosts workloads MUST report at least one entry.| +| supportedRuntimes | []SupportedRuntime | Y* | Supported workload runtimes present on the device. See the [SupportedRuntime](#supportedruntime) definition for all permissible values. A device that is capable of hosting workloads MUST report at least one entry.| | supportedDeploymentTypes | []SupportedDeploymentType | Y* | The deployment profile types the device can receive and process locally. See the [SupportedDeploymentType](#supporteddeploymenttype) definition for all permissible values. A device that hosts workloads MUST report at least one entry.| > Note: \* A see-thru gateway not hosting workloads itself MUST omit or provide empty values for 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. From 8c179bb0fbef67ef57fb1e602a8427792ddb1176 Mon Sep 17 00:00:00 2001 From: Armand Craig Date: Mon, 3 Aug 2026 09:57:19 -0400 Subject: [PATCH 24/32] Update system-design/specification/margo-management-interface/device-capabilities.md Co-authored-by: Matthias Lechner Signed-off-by: Armand Craig --- .../margo-management-interface/device-capabilities.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/system-design/specification/margo-management-interface/device-capabilities.md b/system-design/specification/margo-management-interface/device-capabilities.md index 74167ada..8aa2a575 100644 --- a/system-design/specification/margo-management-interface/device-capabilities.md +++ b/system-design/specification/margo-management-interface/device-capabilities.md @@ -56,7 +56,7 @@ DELETE /api/v1/clients/{clientId}/capabilities/{deviceId} | storage | string | Y* | The amount of storage available for applications to utilize on the device. The value is given in binary units (`Ki` = Kibibytes, `Mi` = Mebibytes, `Gi` = Gibibytes, `Ti` = Tebibytes, `Pi` = Pebibytes, `Ei` = Exbibytes). This is defined by the device owner.| | peripherals | []Peripheral | Y* | Peripherals available for applications to utilize on the device. See the [Peripheral](#peripheral-attributes) section below.| | interfaces | []CommunicationInterface | Y* | Communication interfaces available for applications to utilize on the device. See the [Communication Interfaces](#communicationinterface-attributes) section below.| -| otelCollector | boolean | Y* | Reports whether an OpenTelemetry (OTEL) collector is present on the device. | +| otelCollector | boolean | Y* | Reports whether an OpenTelemetry (OTEL) collector is present on the device. A device that is capable of hosting workloads MUST report `true`. | | supportedRuntimes | []SupportedRuntime | Y* | Supported workload runtimes present on the device. See the [SupportedRuntime](#supportedruntime) definition for all permissible values. A device that is capable of hosting workloads MUST report at least one entry.| | supportedDeploymentTypes | []SupportedDeploymentType | Y* | The deployment profile types the device can receive and process locally. See the [SupportedDeploymentType](#supporteddeploymenttype) definition for all permissible values. A device that hosts workloads MUST report at least one entry.| From be1bfdcf10ca7b1d5d4205d0c3846f9da6b602ca Mon Sep 17 00:00:00 2001 From: Armand Craig Date: Mon, 3 Aug 2026 10:02:00 -0400 Subject: [PATCH 25/32] Update system-design/specification/margo-management-interface/device-capabilities.md Co-authored-by: Matthias Lechner Signed-off-by: Armand Craig --- .../margo-management-interface/device-capabilities.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/system-design/specification/margo-management-interface/device-capabilities.md b/system-design/specification/margo-management-interface/device-capabilities.md index 8aa2a575..8c7838c9 100644 --- a/system-design/specification/margo-management-interface/device-capabilities.md +++ b/system-design/specification/margo-management-interface/device-capabilities.md @@ -58,7 +58,7 @@ DELETE /api/v1/clients/{clientId}/capabilities/{deviceId} | interfaces | []CommunicationInterface | Y* | Communication interfaces available for applications to utilize on the device. See the [Communication Interfaces](#communicationinterface-attributes) section below.| | otelCollector | boolean | Y* | Reports whether an OpenTelemetry (OTEL) collector is present on the device. A device that is capable of hosting workloads MUST report `true`. | | supportedRuntimes | []SupportedRuntime | Y* | Supported workload runtimes present on the device. See the [SupportedRuntime](#supportedruntime) definition for all permissible values. A device that is capable of hosting workloads MUST report at least one entry.| -| supportedDeploymentTypes | []SupportedDeploymentType | Y* | The deployment profile types the device can receive and process locally. See the [SupportedDeploymentType](#supporteddeploymenttype) definition for all permissible values. A device that hosts workloads MUST report at least one entry.| +| supportedDeploymentTypes | []SupportedDeploymentType | Y* | The deployment profile types the device can receive and process locally. See the [SupportedDeploymentType](#supporteddeploymenttype) definition for all permissible values. A device that is capable of hosting workloads MUST report at least one entry.| > Note: \* A see-thru gateway not hosting workloads itself MUST omit or provide empty values for 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. From 36ab42871c38e81eaf3f0ae5ed3dc813c7cff7da Mon Sep 17 00:00:00 2001 From: Armand Craig Date: Mon, 3 Aug 2026 15:06:18 -0400 Subject: [PATCH 26/32] Address feedback from Matthias' review. Signed-off-by: Armand Craig --- .../margo-devices/device-requirements.md | 2 +- .../device-capabilities.md | 37 +++++++++++++------ .../workload-management-api-1.0.0-rc.2.yaml | 11 +++--- .../collecting-workload-observability-data.md | 16 ++++---- .../consuming-workload-observability-data.md | 2 +- .../publishing-workload-observability-data.md | 4 +- 6 files changed, 44 insertions(+), 28 deletions(-) diff --git a/system-design/specification/margo-devices/device-requirements.md b/system-design/specification/margo-devices/device-requirements.md index cbd56666..a7782496 100644 --- a/system-design/specification/margo-devices/device-requirements.md +++ b/system-design/specification/margo-devices/device-requirements.md @@ -1,6 +1,6 @@ # Device Requirements -All Margo conformant devices MUST meet a baseline set of requirements to be considered Margo compliant. These requirements ensure devices can effectively manage Margo-compliant workload and/or host those workloads. A device MUST support onboarding and management from only a single workload fleet manager. A device reports what it can provide to the ecosystem through its [device capabilities](../margo-management-interface/device-capabilities.md). +A device MUST meet a baseline set of requirements to be considered Margo-conformant. These requirements ensure devices can effectively manage Margo-conformant workload and/or host those workloads. A device MUST support onboarding and management from only a single workload fleet manager. A device reports what it can provide to the ecosystem through its [device capabilities](../margo-management-interface/device-capabilities.md). All Margo-conformant devices MUST provide the following components: diff --git a/system-design/specification/margo-management-interface/device-capabilities.md b/system-design/specification/margo-management-interface/device-capabilities.md index b690a1fe..47889c83 100644 --- a/system-design/specification/margo-management-interface/device-capabilities.md +++ b/system-design/specification/margo-management-interface/device-capabilities.md @@ -53,7 +53,7 @@ DELETE /api/v1/clients/{clientId}/capabilities/{deviceId} | vendor | string | Y | Defines the device vendor.| | modelNumber | string | Y | Defines the model number of the device.| | serialNumber | string | Y | Defines the serial number of the device.| -| cpu | []CPU | Y* | List of CPU entries available on the device. Utilized to match with the required resources defined in the application description. See the [CPU](#cpu-attributes) section below.| +| cpus | []CPU | Y* | List of CPU entries available on the device. Utilized to match with the required resources defined in the application description. See the [CPU](#cpu-attributes) section below.| | memory | string | Y* | The amount of memory available for applications to utilize on the device. The value is given in binary units (`Ki` = Kibibytes, `Mi` = Mebibytes, `Gi` = Gibibytes). This is defined by the device owner.| | storage | string | Y* | The amount of storage available for applications to utilize on the device. The value is given in binary units (`Ki` = Kibibytes, `Mi` = Mebibytes, `Gi` = Gibibytes, `Ti` = Tebibytes, `Pi` = Pebibytes, `Ei` = Exbibytes). This is defined by the device owner.| | peripherals | []Peripheral | Y* | Peripherals available for applications to utilize on the device. See the [Peripheral](#peripheral-attributes) section below.| @@ -62,16 +62,18 @@ DELETE /api/v1/clients/{clientId}/capabilities/{deviceId} | supportedRuntimes | []SupportedRuntime | Y* | Supported workload runtimes present on the device. See the [SupportedRuntime](#supportedruntime) definition for all permissible values. A device that is capable of hosting workloads MUST report at least one entry.| | supportedDeploymentTypes | []SupportedDeploymentType | Y* | The deployment profile types the device can receive and process locally. See the [SupportedDeploymentType](#supporteddeploymenttype) definition for all permissible values. A device that is capable of hosting workloads MUST report at least one entry.| -> Note: \* A see-thru gateway not hosting workloads itself MUST omit or provide empty values for 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. +> Note: \* A see-thru gateway not hosting workloads itself MUST omit these fields or provide empty values for them, reporting `otelCollector` as `false`. 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. | Attribute | Type | Required? | Description | | --- | --- | --- | --- | -| cores | integer | Y | Defines the cores available within the hosts CPU. Specified as decimal units of CPU cores (e.g., `0.5` is half a core). This is defined by the device owner. After deployment of the application, the device MUST provide this number of CPU cores for the application.| +| cores | number | Y | Defines the cores available within the hosts CPU. Specified as decimal units of CPU cores (e.g., `0.5` is half a core). This is defined by the device owner. After deployment of the application, the device MUST provide this number of CPU cores for the application.| | architecture | CpuArchitectureType | N | The CPU architecture supported by the device. This can be e.g. amd64, arm64, arm. See the [CpuArchitectureType](#cpuarchitecturetype) definition for all permissible values.| +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. @@ -149,7 +151,7 @@ These enumerations are used as vocabularies for attribute values of the `DeviceC "vendor": "Northstar Industrial Devices", "modelNumber": "332ANZE1-N1", "serialNumber": "PF45343-AA", - "cpu": [ + "cpus": [ { "cores": 24, "architecture": "amd64" @@ -195,13 +197,26 @@ A device may represent, and aggregate the capabilities of, multiple child-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 client is referred to as a **see-thru gateway**. A see-thru gateway is not a special device type; it is treated as an ordinary device that additionally reports the capabilities of the devices behind it. The WFM infers the gateway relationship from the reported information — the parent/child `deviceId` hierarchy and it is especially evident when the gateway itself reports no workload-hosting capabilities. +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 a standalone hosting 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. 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 `deviceId`s: "gateway1", "gateway1/deviceA", and "gateway1/deviceB". +A see-thru gateway MUST report its own capabilities and the capabilities of each device it connects to the WFM: -A see-thru gateway that does not host workloads itself MUST omit the workload-hosting fields (`cpu`, `memory`, `storage`, `otelCollector`, `supportedRuntimes`, `supportedDeploymentTypes`), so its manifest contains only the required identity fields. A see-thru gateway that is also capable of hosting workloads reports the workload-hosting fields, including at least one entry in both `supportedRuntimes` and `supportedDeploymentTypes`. +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 `deviceId`s `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** + +| If the gateway... | Then its own manifest MUST... | +| --- | --- | +| does **not** host workloads | contain only the required identity fields — omit or provide empty values for the workload-hosting fields (`cpus`, `memory`, `storage`, `peripherals`, `interfaces`, `supportedRuntimes`, `supportedDeploymentTypes`), and omit `otelCollector` or report it as `false` | +| **also** hosts workloads | report the workload-hosting fields like any hosting device, including at least one entry in both `supportedRuntimes` and `supportedDeploymentTypes` | -A see-thru gateway 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. +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 @@ -237,7 +252,7 @@ A see-thru gateway MUST report its own capabilities to the WFM before reporting "vendor": "Gateway Vendor", "modelNumber": "GW-1000", "serialNumber": "GW12345678", - "cpu": [ + "cpus": [ { "cores": 4, "architecture": "amd64" @@ -276,7 +291,7 @@ A see-thru gateway MUST report its own capabilities to the WFM before reporting "vendor": "Device A Vendor", "modelNumber": "DA-2000", "serialNumber": "DA12345678", - "cpu": [ + "cpus": [ { "cores": 24, "architecture": "amd64" @@ -320,7 +335,7 @@ A see-thru gateway MUST report its own capabilities to the WFM before reporting "vendor": "Device A Vendor", "modelNumber": "DA-1000", "serialNumber": "DA12345678", - "cpu": [ + "cpus": [ { "cores": 2, "architecture": "arm64" diff --git a/system-design/specification/margo-management-interface/workload-management-api-1.0.0-rc.2.yaml b/system-design/specification/margo-management-interface/workload-management-api-1.0.0-rc.2.yaml index 942f4023..c1f1edfd 100644 --- a/system-design/specification/margo-management-interface/workload-management-api-1.0.0-rc.2.yaml +++ b/system-design/specification/margo-management-interface/workload-management-api-1.0.0-rc.2.yaml @@ -486,10 +486,11 @@ components: properties: type: object required: [id, vendor, modelNumber, serialNumber] - # Only identity fields are required. A device that hosts workloads reports cpu, memory, - # storage, otelCollector, supportedRuntimes (>=1), and supportedDeploymentTypes (>=1). A - # device that does not host workloads (e.g. a see-thru gateway that only relays the - # devices behind it) omits those fields; the WFM infers it is non-hosting from their + # Only identity fields are required. A device that hosts workloads reports cpus, memory, + # storage, peripherals, interfaces, otelCollector (true), supportedRuntimes (>=1), and + # supportedDeploymentTypes (>=1). A device that does not host workloads (e.g. a see-thru + # gateway that only relays the devices behind it) omits those fields or reports them + # empty, reporting otelCollector as false; the WFM infers it is non-hosting from their # absence and infers a gateway from the parent/child deviceId hierarchy. properties: id: @@ -500,7 +501,7 @@ components: type: string serialNumber: type: string - cpu: + cpus: type: array items: type: object diff --git a/system-design/specification/observability/collecting-workload-observability-data.md b/system-design/specification/observability/collecting-workload-observability-data.md index a22a9297..798b48d3 100644 --- a/system-design/specification/observability/collecting-workload-observability-data.md +++ b/system-design/specification/observability/collecting-workload-observability-data.md @@ -2,15 +2,15 @@ The device owner MUST deploy, and configure, an OpenTelemetry collector on their device. The device owner MAY choose the deployment model they wish to follow but MUST use one of the following approaches. -For standalone and clustered devices there MUST be at least one OpenTelemetry collector deployed to collect the observability data required below. The Device owner MAY choose to deploy multiple OpenTelemetry collectors with each collector receiving different parts of the observability data required below as long as all required observability data is collected. +For workload hosting devices there MUST be at least one OpenTelemetry collector deployed to collect the observability data required below. The Device owner MAY choose to deploy multiple OpenTelemetry collectors with each collector receiving different parts of the observability data required below as long as all required observability data is collected. ![Deployment Model - Multi-Node Deployment](../../figures/System-design-observability-deployment1.drawio.svg) -For multi-node capable clusters the device owner MAY chose to use the DaemonSet deployment model to ensure there is an OpenTelemetry collector running on each node. +For multi-node capable devices the device owner MAY chose to use the DaemonSet deployment model to ensure there is an OpenTelemetry collector running on each node. ![Deployment Model - DaemonSet](../../figures/System-design-observability-deployment2.drawio.svg) -For multi-node capable clusters the device owner MUST ensure the communication between workloads, and collector, from one node to a collector on a different node is secure. +For multi-node capable devices the device owner MUST ensure the communication between workloads, and collector, from one node to a collector on a different node is secure. The device owner MUST NOT require the use of the sidecar deployment model at this time since this requires the pods/containers to have foreknowledge of this deployment model. @@ -18,7 +18,7 @@ The device owner MUST NOT require the use of the sidecar deployment model at thi The device owner MUST NOT pre-configure exporters to send observability data from the device because the end user must control what observability data is exported. -The device owner MUST NOT attempt to inject auto-instrumentation (by using the [OpenTelemetry operator](https://github.com/open-telemetry/opentelemetry-operator#opentelemetry-auto-instrumentation-injection) for example) into any compliant workloads running on the device that are not owned by the device owner. +The device owner MUST NOT attempt to inject auto-instrumentation (by using the [OpenTelemetry operator](https://github.com/open-telemetry/opentelemetry-operator#opentelemetry-auto-instrumentation-injection) for example) into any Margo-conformant workloads running on the device that are not owned by the device owner. Device owners are NOT required to provide backends for consuming observability data on their devices. @@ -26,7 +26,7 @@ Device owners are NOT required to provide backends for consuming observability d ## Container Platform Observability Requirements -In order to allow for monitoring the chosen container platform's state the device owner MUST ensure the following observability data is being collected and made available for export from the OpenTelemetry collector(s) on the standalone device or cluster +In order to allow for monitoring the chosen container platform's state the device owner MUST ensure the following observability data is being collected and made available for export from the OpenTelemetry collector(s) on the workload hosting device ### Kubernetes @@ -90,13 +90,13 @@ If the device owner chooses not to deploy the Workload Fleet Management Client a > **Action:** Need to do research to determine if this makes sense, or not, when the client is not running as a containerized workload. We may have to leave it up to what is covered through device observability for this case. If it is possible, and makes sense, we need to define what should be provided. -In addition to the resource utilization data the Workload Fleet Management Client MUST also send the following minimum set of workload observability data to the open telemetry collector on the standalone device or cluster. The device owner MAY choose to provided additional observability data if they wish. +In addition to the resource utilization data the Workload Fleet Management Client MUST also send the following minimum set of workload observability data to the open telemetry collector on the workload hosting device. The device owner MAY choose to provided additional observability data if they wish. > **Action:** We need to understand what the WOS/a is going to be doing to determine what this is. ### Connecting to the OpenTelemetry Collector -In order for a workload to publish its observability data to the collector on the standalone device or cluster the device own MUST inject the following environment variables into each container. +In order for a workload to publish its observability data to the collector on the workload hosting device the device owner MUST inject the following environment variables into each container. |Environment Variable|Description| |---|---| @@ -109,7 +109,7 @@ In order for a workload to publish its observability data to the collector on th ## Exporting Observability Data -End users MUST be able to export observability data from a standalone device or cluster to collectors, or backends, onsite or in the cloud if they wish to make the information available to enable remote monitoring and diagnostics. +End users MUST be able to export observability data from a workload hosting device to collectors, or backends, onsite or in the cloud if they wish to make the information available to enable remote monitoring and diagnostics. > **Decision Needed:** There is a dependency on the decisions about using OpenTelemetry instead of the management API approach. If OpenTelemetry is chosen then there would be some subset of data that MUST be exported to the workload fleet manager supplier. > diff --git a/system-design/specification/observability/consuming-workload-observability-data.md b/system-design/specification/observability/consuming-workload-observability-data.md index e6f85931..5e711015 100644 --- a/system-design/specification/observability/consuming-workload-observability-data.md +++ b/system-design/specification/observability/consuming-workload-observability-data.md @@ -2,6 +2,6 @@ Workload Fleet Management or observability platform suppliers MAY choose to consume workload observability data exported from the end user's devices to provide valuable services to the end user. -The end user MAY choose to export observability data from Margo compliant devices to other OpenTelemetry collectors or backends within their environment that is not on the device. +The end user MAY choose to export observability data from Margo-conformant devices to other OpenTelemetry collectors or backends within their environment that is not on the device. > **Note**: See the [workload observability overview](../../overview/workload-observability.md) page for more information about workload observability. diff --git a/system-design/specification/observability/publishing-workload-observability-data.md b/system-design/specification/observability/publishing-workload-observability-data.md index f83c4be4..5831d37b 100644 --- a/system-design/specification/observability/publishing-workload-observability-data.md +++ b/system-design/specification/observability/publishing-workload-observability-data.md @@ -1,6 +1,6 @@ # Publishing Workload Observability Data -Compliant workloads MAY choose to expose workload specific observability data by sending their observability data to the Open Telemetry collector on the standalone device or cluster. While this is optional, it is highly recommended in order to support distributed diagnostics. +Margo-conformant workloads MAY choose to expose workload specific observability data by sending their observability data to the Open Telemetry collector on the workload hosting device. While this is optional, it is highly recommended in order to support distributed diagnostics. Workload suppliers choosing to expose metrics, traces or logs for consumption with OpenTelemetry MUST send the data to the OpenTelemetry collector using OTLP. @@ -8,7 +8,7 @@ The information required to communicate with the device's OTEL Collector is inje Workload suppliers SHOULD NOT expect their workloads to be auto-instrumented by anything outside of their control (by the [OpenTelemetry operator](https://github.com/open-telemetry/opentelemetry-operator#opentelemetry-auto-instrumentation-injection) for example). -A workload supplier MAY choose an observability framework other than OpenTelemetry but it MUST be self-contained within the deployment of their workload. If an alternative approach is taken, it is NOT recommended workload suppliers publish their observability data outside the device/cluster by using any other means other than the Open Telemetry collector. If the workload supplier chooses to export data without using the OpenTelemetry collector they MUST NOT do this without the end user's approval. +A workload supplier MAY choose an observability framework other than OpenTelemetry but it MUST be self-contained within the deployment of their workload. If an alternative approach is taken, it is NOT recommended workload suppliers publish their observability data outside the device by using any other means other than the Open Telemetry collector. If the workload supplier chooses to export data without using the OpenTelemetry collector they MUST NOT do this without the end user's approval. > **Note:** See the [workload observability overview](../../overview/workload-observability.md) page for more information about workload observablity. > From dd179daa40c716fa2727444b032319c68679044b Mon Sep 17 00:00:00 2001 From: Armand Craig Date: Tue, 4 Aug 2026 09:46:23 -0400 Subject: [PATCH 27/32] Update system-design/specification/margo-devices/device-requirements.md Co-authored-by: Matthias Lechner Signed-off-by: Armand Craig --- .../specification/margo-devices/device-requirements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/system-design/specification/margo-devices/device-requirements.md b/system-design/specification/margo-devices/device-requirements.md index a7782496..1b7bb378 100644 --- a/system-design/specification/margo-devices/device-requirements.md +++ b/system-design/specification/margo-devices/device-requirements.md @@ -41,7 +41,7 @@ If a device vendor chooses a deployment approach that does not interact with the Devices supporting the Compose deployment type, MUST provide the following additional components: - Capabilities for deploying Compose applications -- Compose orchestration platform i.e., Docker or Podman +- An OCI container runtime, for example Docker or Podman ## Future Requirements From 42fdee25e6e01ff95bb1106ea33403dc1881d089 Mon Sep 17 00:00:00 2001 From: Armand Craig Date: Tue, 4 Aug 2026 09:46:42 -0400 Subject: [PATCH 28/32] Update system-design/specification/margo-management-interface/device-capabilities.md Co-authored-by: Matthias Lechner Signed-off-by: Armand Craig --- .../margo-management-interface/device-capabilities.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/system-design/specification/margo-management-interface/device-capabilities.md b/system-design/specification/margo-management-interface/device-capabilities.md index 47889c83..7730a409 100644 --- a/system-design/specification/margo-management-interface/device-capabilities.md +++ b/system-design/specification/margo-management-interface/device-capabilities.md @@ -62,7 +62,7 @@ DELETE /api/v1/clients/{clientId}/capabilities/{deviceId} | supportedRuntimes | []SupportedRuntime | Y* | Supported workload runtimes present on the device. See the [SupportedRuntime](#supportedruntime) definition for all permissible values. A device that is capable of hosting workloads MUST report at least one entry.| | supportedDeploymentTypes | []SupportedDeploymentType | Y* | The deployment profile types the device can receive and process locally. See the [SupportedDeploymentType](#supporteddeploymenttype) definition for all permissible values. A device that is capable of hosting workloads MUST report at least one entry.| -> Note: \* A see-thru gateway not hosting workloads itself MUST omit these fields or provide empty values for them, reporting `otelCollector` as `false`. 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. +> 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. From ae30f4ce0e6ef4b83ddc1206590d60cd1dbb20c3 Mon Sep 17 00:00:00 2001 From: Armand Craig Date: Tue, 4 Aug 2026 09:46:55 -0400 Subject: [PATCH 29/32] Update system-design/specification/margo-management-interface/device-capabilities.md Co-authored-by: Matthias Lechner Signed-off-by: Armand Craig --- .../margo-management-interface/device-capabilities.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/system-design/specification/margo-management-interface/device-capabilities.md b/system-design/specification/margo-management-interface/device-capabilities.md index 7730a409..093d74df 100644 --- a/system-design/specification/margo-management-interface/device-capabilities.md +++ b/system-design/specification/margo-management-interface/device-capabilities.md @@ -213,7 +213,7 @@ A see-thru gateway MUST report its own capabilities and the capabilities of each | If the gateway... | Then its own manifest MUST... | | --- | --- | -| does **not** host workloads | contain only the required identity fields — omit or provide empty values for the workload-hosting fields (`cpus`, `memory`, `storage`, `peripherals`, `interfaces`, `supportedRuntimes`, `supportedDeploymentTypes`), and omit `otelCollector` or report it as `false` | +| does **not** host workloads | contain only the required identity fields — omit the workload-hosting fields (`cpus`, `memory`, `storage`, `peripherals`, `interfaces`, `supportedRuntimes`, `supportedDeploymentTypes`), and omit `otelCollector` | | **also** hosts workloads | report the workload-hosting fields like any hosting device, including at least one entry in both `supportedRuntimes` and `supportedDeploymentTypes` | 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. From c3a7e3d38c207eb4ac41aba201020b959fdfa601 Mon Sep 17 00:00:00 2001 From: Armand Craig Date: Tue, 4 Aug 2026 09:47:12 -0400 Subject: [PATCH 30/32] Update system-design/specification/margo-management-interface/workload-management-api-1.0.0-rc.2.yaml Co-authored-by: Matthias Lechner Signed-off-by: Armand Craig --- .../workload-management-api-1.0.0-rc.2.yaml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/system-design/specification/margo-management-interface/workload-management-api-1.0.0-rc.2.yaml b/system-design/specification/margo-management-interface/workload-management-api-1.0.0-rc.2.yaml index c1f1edfd..a3a0057e 100644 --- a/system-design/specification/margo-management-interface/workload-management-api-1.0.0-rc.2.yaml +++ b/system-design/specification/margo-management-interface/workload-management-api-1.0.0-rc.2.yaml @@ -489,9 +489,9 @@ components: # Only identity fields are required. A device that hosts workloads reports cpus, memory, # storage, peripherals, interfaces, otelCollector (true), supportedRuntimes (>=1), and # supportedDeploymentTypes (>=1). A device that does not host workloads (e.g. a see-thru - # gateway that only relays the devices behind it) omits those fields or reports them - # empty, reporting otelCollector as false; the WFM infers it is non-hosting from their - # absence and infers a gateway from the parent/child deviceId hierarchy. + # gateway that only relays the devices behind it) omits those fields. + # The WFM infers it is non-hosting from their absence and infers a + # gateway from the parent/child deviceId hierarchy. properties: id: $ref: '#/components/schemas/DeviceId' From 17b1a4fb7b56dce3a2b57d9e492250b758d115ba Mon Sep 17 00:00:00 2001 From: Armand Craig Date: Tue, 4 Aug 2026 11:51:32 -0400 Subject: [PATCH 31/32] Clear up hard requirement requiring all devices to host collectors. Signed-off-by: Armand Craig --- .../observability/collecting-workload-observability-data.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/system-design/specification/observability/collecting-workload-observability-data.md b/system-design/specification/observability/collecting-workload-observability-data.md index 798b48d3..0e927c07 100644 --- a/system-design/specification/observability/collecting-workload-observability-data.md +++ b/system-design/specification/observability/collecting-workload-observability-data.md @@ -1,9 +1,9 @@ # Collecting Workload Observability Data -The device owner MUST deploy, and configure, an OpenTelemetry collector on their device. The device owner MAY choose the deployment model they wish to follow but MUST use one of the following approaches. - For workload hosting devices there MUST be at least one OpenTelemetry collector deployed to collect the observability data required below. The Device owner MAY choose to deploy multiple OpenTelemetry collectors with each collector receiving different parts of the observability data required below as long as all required observability data is collected. +The device owner MAY choose the deployment model they wish to follow but MUST use one of the following approaches. + ![Deployment Model - Multi-Node Deployment](../../figures/System-design-observability-deployment1.drawio.svg) For multi-node capable devices the device owner MAY chose to use the DaemonSet deployment model to ensure there is an OpenTelemetry collector running on each node. From 8e972a9be3496ca5d1c32449536136b0027482ee Mon Sep 17 00:00:00 2001 From: Armand Craig Date: Tue, 4 Aug 2026 12:05:13 -0400 Subject: [PATCH 32/32] Update system-design/specification/margo-management-interface/device-capabilities.md Co-authored-by: Matthias Lechner Signed-off-by: Armand Craig --- .../margo-management-interface/device-capabilities.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/system-design/specification/margo-management-interface/device-capabilities.md b/system-design/specification/margo-management-interface/device-capabilities.md index 093d74df..ba5bc69f 100644 --- a/system-design/specification/margo-management-interface/device-capabilities.md +++ b/system-design/specification/margo-management-interface/device-capabilities.md @@ -199,7 +199,7 @@ A device may represent, and aggregate the capabilities of, multiple child-device 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 a standalone hosting 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. +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**