Initial backup/commit. More cleanup to accomplish!

Signed-off-by: Armand Craig <ajcraig@ra.rockwell.com>

Author: ajcraig

mkdocs.yml

@@ -31,11 +31,11 @@ nav:
           - device-interoperability/collecting-workload-observability-data.md
   - Technical References:
       - Margo Management Interface:
-          - margo-api-reference/margo-api-specification.md
+          - margo-api-reference/workload-api/api-security-details.md
           - margo-api-reference/workload-api/desired-state-api/desired-state.md
           - margo-api-reference/workload-api/device-api/device-capabilities.md
           - margo-api-reference/workload-api/device-api/deployment-status.md
-          - margo-api-reference/workload-api/onboarding-api/device-onboarding.md
+          - margo-api-reference/workload-api/onboarding-api/client-onboarding.md
           - margo-api-reference/workload-api/onboarding-api/rootca-download.md
       - Application Package Definition:
           - margo-api-reference/workload-api/application-package-api/application-description.md

system-design/fleet-management/workload/device-capability-reporting.md

@@ -1,12 +1,10 @@
 # Device Capabilities
 
-The purpose of device capabilities reporting is to ensure the Workload Fleet Management solution has the information needed to pair workloads with compatible edge devices. The [device's capabilities](../../margo-api-reference/workload-api/device-api/device-capabilities.md) are reported to the workload orchestration web service using [Margo management API](../../margo-api-reference/margo-api-specification.md).
+The purpose of device capabilities reporting is to ensure the Workload Fleet Management solution has the information needed to pair workloads with compatible edge devices. The device's capabilities are reported to the WFM web service using the Margo Management API.
 
 ### Device Capability Reporting
 
-The device owner MUST report their device's capabilities and characteristics via the [Device API](../../margo-api-reference/workload-api/device-api/device-capabilities.md) when onboarding the device with the workload orchestration solution. Additionally, during the lifecycle of the Edge device, if there is a change that impacts the reported characteristics, the device's interface shall send an update to the Workload Fleet Manager. 
-
-> Action: The device capabilities details are still being discussed
+The device owner MUST report their device's capabilities and characteristics, via the device API, when onboarding the device with the Workload Fleet Management solution. Additionally, during the lifecycle of the edge device, if there is a change that impacts the reported characteristics, the device MUST update the Workload Fleet Manager with the latest information via the management API. 
 
 The following information MUST be provided:
 
@@ -16,10 +14,14 @@ The following information MUST be provided:
 - Serial Number
 - Margo Device Role Designation(Cluster Leader/Worker / Standalone Device)
 - Resources available for workloads to utilize on the Device:
-  - Memory Capacity
+    - Memory Capacity
     - Storage Capacity
-  - CPU information
+    - CPU information
 - Device peripherals(i.e. Graphics card)
 - Network interfaces(wifi/eth/cellular)
 
-For more information see the [device capabilties API](../../margo-api-reference/workload-api/device-api/device-capabilities.md).
+## Relevant Links
+
+Please follow the subsequent links to view more technical information on device capability reporting:
+
+- [Device Capabilities API](../../margo-api-reference/workload-api/device-api/device-capabilities.md)

system-design/fleet-management/workload/management-interface-requirements.md

@@ -1,25 +1,37 @@
 # Management Interface Requirements
 
-Provided below are a set of requirements that the Management Interface participants must follow to become Margo compliant.
+Provided below are a set of requirements that the Management Interface participants must follow to become Margo compliant. 
+
 
-- Additional technical details can be found in the following location: [Margo Management API specification](../../margo-api-reference/margo-api-specification.md)
 
 ## Requirements
 
-- The Management Interface MUST provide the following functionality:
-	- device onboarding with the workload orchestration solution
+- The Management Interface MUST provide the following functionality outlined within this specification:
+	- onboarding of the management client
    	- device capabilities reporting
-	- identifying desired state changes
-	- deployment status reporting
-- The Workload Fleet Management vendors MUST implement the server side of the API specification.
-- The device vendor MUST implement a client following the API specification.
-- The Workload Fleet Management vendors solution MUST maintain a storage repository to store the managed edge device's associated set of desired state files.
-    - Margo does not dictate how the desired state files are stored, other than ensuring they are available upon request. 
+	- defining the workload(s) desired state
+	- workload deployment status reporting
+- The Workload Fleet Management supplier MUST implement the server side of the API specification contract.
+- The Device Owner MUST implement the client side of the API specification contract.
+- The Workload Fleet Management supplier's solution MUST maintain a storage repository to store the managed edge device's associated set of desired state files.
+    - Margo does not dictate how the desired state files are stored, other than ensuring they are available upon request via API definition.
 - The device's management client MUST retrieve the device's set of desired state files from the Workload Fleet Manager.
+    - Following the retrieval of the desired state(s), the device MUST orchestrate the changes locally via the provider. 
+- Following the initial upload of device capabilities from client to server, the device MUST update the WFM with an updated list of capabilities if any workload related changes occur.
 - Interface patterns MUST support extended device communication downtime. 
-- The Management Interface MUST MUST reference industry security protocols and port assignments for both client and server interactions.
-- Running the device's management client as containerized services is preferred to enable easier lifecycle management but not required.
 - The Management Interface MUST allow an end user to configure the following:
 	- Downtime configuration - ensures the device's management client is not retrying communication when operating under a known downtime. Additionally, communication errors MUST be ignored during this configurable period. 
 	- Polling Interval Period - describes a configurable time period indicating the hours in which the device's management client checks for updates to the device's desired state.
-	- Polling Interval Rate - describes the rate for how frequently the device's management client checks for updates to the device's desire state.
+	- Polling Interval Rate - describes the rate for how frequently the device's management client checks for updates to the device's desire state.
+
+
+## Suggestions
+
+- Running the device's management client as containerized services is preferred. By following Margo application packaging guidelines, it makes the management interface easier to lifecycle manage, however this is not required.
+
+
+## Relevant Links
+
+Please follow the subsequent links to view more technical information regarding Margo's management interface:
+
+- [Margo API Technical Reference](../../margo-api-reference/workload-api/api-security-details.md)

system-design/fleet-management/workload/workload-deployment.md

@@ -40,4 +40,6 @@ The deployment status uses the following rules:
 - The state is `Failure` if at any point the desired state fails to be applied. When reporting a `Failure` state the error message and error code MUST be reported
 - The state is `Success` once the desired state has been applied completely 
 
+
+> Note: Drawing to be replaced with mermaid sequence diagram. 
 ![Workload Install Sequence Diagram (svg)](../../figures/workload-install-sequence.drawio.svg)

system-design/fleet-management/workload/workload-fleet-management-edge-onboarding.md

@@ -6,58 +6,20 @@ In order for the Workload Fleet Management software to manage the edge device's
 **The onboarding process includes:**
 
 - The end user provides the the Workload Fleet Management web service's root URL to the device's management client
-- The device's management client downloads the workload orchestration solution vendor's public root CA certificate using the [Onboarding API](../../margo-api-reference/workload-api/onboarding-api/rootca-download.md)
+- The device's management client downloads the Workload Fleet Manager's public root CA certificate using the [Onboarding API](../../margo-api-reference/workload-api/onboarding-api/rootca-download.md)
 - Context and trust is established between the device's management client and the Workload Fleet Management web service
-- The device's management client uses the [Onboarding API](../../margo-api-reference/workload-api/onboarding-api/device-onboarding.md) to onboard with the workload orchestration service.
+- The device's management client uses the [Onboarding API](../../margo-api-reference/workload-api/onboarding-api/client-onboarding.md) to onboard with the Workload Fleet Management service.
 - The device's management client receives the client Id, client secret and token endpoint URL used to generate a bearer token.
 - The device's management client receives the URL for the Git repository containing its desired state and an associated access token for authentication
-- The [device capabilities](./device-capability-reporting.md) information is sent from the device to the workload orchestration web service using the [Device API](../../margo-api-reference/workload-api/device-api/device-capabilities.md)
+> Action: The Margo TWG is currently reviewing alternatives to GitOps. This page will be updated upon a finalization of a new strategy. 
+- The [device capabilities](./device-capability-reporting.md) information is sent from the device to the WFM service using the [Device API](../../margo-api-reference/workload-api/device-api/device-capabilities.md)
 
-![Margo Management Interface Operational Flow Diagram (svg)](../../figures/margo-interface-generic.drawio.svg)
-> Action: FIDO Device onboarding has not been finalized as the standard onboarding solution. Further discussion/investigations are needed. 
 
 ### Configuring the Workload Fleet Management Web Service URL
 
 > Action: Ideally this URL is discoverable instead of having to manually enter it but we still need to determine if there is a good way to make this discoverable by using something like the FDO Rendezvous service or multicast DNS. Also, once we determine how the Margo compliant device onboarding and fleet management is going to work it will probably impact this.
 
-To ensure the management client is configured to communicate with the correct Workload Fleet Management web service, the device's management client needs to be configured with the expected URL. The device vendor MUST provide a way for the end user to manually set the URL the device's management client uses to communicate with the workload orchestration solution chosen by the end user.
-
-### Margo Web API Authentication Method
-
-The Margo Web API communication pattern between the device's management client and the workload orchestration web service must use a secure communication channel. In order to facilitate this secure communication Margo requires the use of oAuth 2.0 for authentication.
-
-#### API Authorization Strategy
-
-- During the [onboarding process](../../margo-api-reference/workload-api/onboarding-api/device-onboarding.md) the Workload Fleet Management's web service provides the management client with a client Id, client secret and token endpoint URL
-- The management client uses this information to [create a bearer token ](../../margo-api-reference/margo-api-specification.md#authorization-header)for each request
-- The bearer token is set in the `Authorization` header for each web request sent to the Workload Fleet Management's web service requiring authorization.
-
-#### Payload Security Method
-
-> Action: Certificate Rotation / Unique Identifier for device are still research areas needed.
-
-Because of limitations using mTLS with common OT infrastructure such as TLS terminating HTTPS load-balancer or a HTTPS proxy doing lawful inspection Margo has adopted a certificate-based payload signing approach to protect payloads from being tampered with. By utilizing the certificates to create payload envelopes, the device's management client can ensure secure transport between the device's management client and the Workload Fleet Management's web service.
-
-- During the onboarding process the end user uploads the device's x.509 certificate to the workload orchestration solution 
-- The device's management client downloads the root CA certificate using the [Onboarding API](../../margo-api-reference/workload-api/onboarding-api/rootca-download.md)
-- Once this is complete, both parties are able to [secure their payloads](../../margo-api-reference/margo-api-specification.md#signing-payloads). 
-
-##### Details pertaining to the message Envelope:
-
-Once the edge device has a message prepared for the Workload Fleet Management's web service, it completes the following to secure the message.
-
-- The device's management client calculates a digest and signature of the payload
-- The device's management client adds an envelope around it that has:
-    - actual payload
-    - SHA of the payload, signed by the device certificate
-    - Identifier for the certificate that corresponds to the private key used to sign it. 
-        - This identifier MUST be the GUID provided by the device manufacturer. Typically the hardware serial number. 
-- The envelope is sent as the payload to the Workload Fleet Management's web service. 
-- The Workload Fleet Management's web service treats the request's payload as envelope structure, and receives the certificate identifier.
-> Note: This certificate is the device certificate that was manually uploaded to the workload orchestration solution during onboarding. 
-- The Workload Fleet Management's web service computes digest from the payload, and verifies the signature using the device certification.
-- The payload is then processed by the Workload Fleet Management's web service. 
-
+To ensure the management client is configured to communicate with the correct Workload Fleet Management web service, the device's management client needs to be configured with the expected URL. The device vendor MUST provide a way for the end user to manually set the URL the device's management client uses to communicate with the Workload FLeet Management solution chosen by the end user. 
 
 ### GitOps Service Enrollment
 
@@ -67,3 +29,10 @@ Once the edge device has a message prepared for the Workload Fleet Management's
 
 - Git access tokens shall be provided to the device's management client. These access tokens MUST be tied to a dedicated non-user account for access where credentials are frequently rotated and short lived.
 - Need to support accessing rotations of tokens
+
+## Relevant Links
+
+Please follow the subsequent links to view more technical information regarding the management API:
+
+- [Margo API Security Details(../margo-api-reference/workload-api/api-security-details.md)
+- [Margo API Onboarding](../margo-api-reference/workload-api/api-security-details.md)