diff --git a/src/specification/margo-management-interface/resources/index.md.jinja2 b/src/specification/margo-management-interface/resources/index.md.jinja2 index ec818c14..a160686d 100644 --- a/src/specification/margo-management-interface/resources/index.md.jinja2 +++ b/src/specification/margo-management-interface/resources/index.md.jinja2 @@ -344,13 +344,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/margo-devices/device-requirements.md b/system-design/specification/margo-devices/device-requirements.md index 607a9fac..1b7bb378 100644 --- a/system-design/specification/margo-devices/device-requirements.md +++ b/system-design/specification/margo-devices/device-requirements.md @@ -1,19 +1,27 @@ # 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. +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: -All devices MUST provide the following components: - - A workload fleet management client -- An OCI container runtime + +> Note: This is not required for a device behind a see-thru gateway. + +All workload hosting devices MUST provide the following capabilities: + +- At least one supported deployment type +- At least one supported workload runtime - An OTEL collector -## Standalone Cluster Role Requirements +> Note: See [device capabilities](../margo-management-interface/device-capabilities.md) for the supported deployment types and runtimes. -Devices filling the standalone cluster role MUST provide the following additional components: +## Helm-enabled Device Requirements + +Devices supporting the Helm deployment type, MUST provide the following additional components: -- Kubernetes orchestration platform - Capabilities for deploying Helm charts +- Kubernetes orchestration platform ### Helm deployment approaches @@ -28,12 +36,12 @@ 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 +- An OCI container runtime, for example Docker or Podman ## 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 e3a7bc3d..ba5bc69f 100644 --- a/system-design/specification/margo-management-interface/device-capabilities.md +++ b/system-design/specification/margo-management-interface/device-capabilities.md @@ -53,28 +53,26 @@ 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.| +| 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.| +| 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 is capable of hosting workloads MUST report at least one entry.| +> 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. | 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.| +| 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 @@ -127,6 +125,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 Compose service deployments locally. | + ## Example Device Capabilities Payload @@ -136,37 +148,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" + "cpus": [ + { + "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" + ] } } ``` @@ -177,19 +191,32 @@ 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 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. 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**. + +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** -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: -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. +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. -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. +**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 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. #### Examples @@ -206,10 +233,7 @@ A WFM client reporting the "Gateway" role MUST report its own capabilities to th "id": "gateway1", "vendor": "Gateway Vendor", "modelNumber": "GW-1000", - "serialNumber": "GW12345678", - "roles": [ - "Gateway" - ] + "serialNumber": "GW12345678" } } ``` @@ -228,26 +252,27 @@ 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" + "cpus": [ + { + "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" + ] } } ``` @@ -266,31 +291,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" + "cpus": [ + { + "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" + ] } } ``` @@ -309,25 +335,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" + "cpus": [ + { + "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-rc.2.yaml b/system-design/specification/margo-management-interface/workload-management-api-1.0.0-rc.2.yaml index f1351c7a..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 @@ -485,7 +485,13 @@ components: enum: [DeviceCapabilitiesManifest] properties: type: object - required: [id, vendor, modelNumber, serialNumber, roles] + required: [id, vendor, modelNumber, serialNumber] + # 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. + # 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' @@ -495,36 +501,43 @@ components: type: string serialNumber: type: string - roles: + cpus: 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] DeviceId: # format: "{id}[/{id}[/{id}...]]" # Top-level id is required and must include only unreserved characters as specified in RFC3986. diff --git a/system-design/specification/observability/collecting-workload-observability-data.md b/system-design/specification/observability/collecting-workload-observability-data.md index cb648217..0e927c07 100644 --- a/system-design/specification/observability/collecting-workload-observability-data.md +++ b/system-design/specification/observability/collecting-workload-observability-data.md @@ -1,16 +1,16 @@ # 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. -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. +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 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 @@ -58,9 +58,9 @@ 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 +### 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. @@ -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. >