|
1 | 1 | # Workload Deployment |
2 | 2 |
|
3 | | -Margo uses an [OpenGitOps](https://opengitops.dev/) approach for managing the edge device's desired state. The workload orchestration solution vendor maintains Git repositories, under their control, to push updates to the desired state for each device being managed. The device's management client is responsible for monitoring the device's assigned Git repository for any changes to the desired state that MUST be applied. |
4 | | -> Action: The use of GitOps patterns for pulling desired state is still being discussed/investigated. |
| 3 | +This page describes how Margo manages the deployment and reconciliation of workloads on Edge Compute Devices. |
5 | 4 |
|
| 5 | +Workload deployment in Margo is based on a declarative Desired State model. |
| 6 | +A Workload Fleet Manager (WFM) defines the desired workloads for each Edge Compute Device, including what should run, how each workload should be configured, and the parameters needed for deployment and lifecycle management. |
| 7 | +Each device runs a Workload Fleet Management Client (WFM Client) that retrieves and applies this Desired State, while reporting progress and results back to the WFM. |
| 8 | +This model provides a consistent and observable way to manage workloads across distributed environments. |
6 | 9 |
|
7 | | -### Desired State Requirements: |
| 10 | +## How it works |
8 | 11 |
|
9 | | -> Note: Need to investigate best way to construct the Git Repository. Folder structure / Multiple applications per Edge Device/Cluster |
10 | | -> Note: this is the recommendation from FluxCD <https://fluxcd.io/flux/guides/repository-structure/> |
| 12 | +The Workload Fleet Manager coordinates workloads across Edge Compute Devices. |
| 13 | +Operators use the WFM to define workloads, update deployments, and view rollout progress across devices. |
| 14 | +The WFM Client continuously reconciles the Desired State provided by the WFM with the workloads actually running on the device. |
11 | 15 |
|
12 | | -- The workload orchestration solution MUST store the device's [desired state documents](../../specification/margo-management-interface/desired-state.md) within a Git repository the device's management client can access. |
13 | | -> Note: Git repository storage was selected to ensure secure storage and traceability pertaining to the workload's desire state(s). |
14 | | -- The device's management client MUST monitor the device's Git repository for updates to the desired state using the URL and access token provided by the workload orchestration solution during onboarding. |
| 16 | +The WFM and WFM Clients communicate through two key interfaces: |
15 | 17 |
|
16 | | -### Workload Management Sequence of Operations |
| 18 | +- The [Desired State API](../../specification/margo-management-interface/desired-state.md), which distributes workload definitions to devices |
| 19 | +- The [Deployment Status API](../../specification/margo-management-interface/deployment-status.md), which collects deployment updates from devices |
17 | 20 |
|
18 | | -#### Desired State lifecycle: |
| 21 | +Together, these interfaces establish a feedback loop between the centralized manager and the distributed devices, ensuring workload consistency and visibility at scale. |
19 | 22 |
|
20 | | -1. The workload orchestration solution creates the [desired state documents](../../specification/margo-management-interface/desired-state.md) based on the end user's inputs when installing, updating or deleting an application. |
21 | | -2. The workload orchestration solution pushes updates to the device's Git repository reflecting the changes to the desired state. |
22 | | -3. The device's management client monitors its assigned Git repository for changes. |
23 | | -4. When the device's management client notices a difference between the current (running) state and the desired state, it MUST pull down and attempt to apply the new desired state. |
| 23 | +## Desired State |
24 | 24 |
|
25 | | -#### Applying the Desired State: |
| 25 | +The Desired State defines the workloads that should run on each Edge Compute Device and the details of how they are deployed. |
| 26 | +It is represented by a [State Manifest](../../specification/margo-management-interface/desired-state.md#endpoints-state-manifest) that lists all workloads assigned to a device. |
| 27 | +The WFM exposes this manifest through the Desired State API. |
26 | 28 |
|
27 | | -1. The device attempts to apply the desired state to become new current state |
28 | | -2. While the new desired state is being applied, the device's management client MUST report progress on state changes (see the [deployment state](#deployment-status) section below) using the [Device API](../../specification/margo-management-interface/deployment-status.md) |
| 29 | +Each workload is defined by an [ApplicationDeployment](../../specification/margo-management-interface/desired-state.md#applicationdeployment-yaml-definition), which describes: |
29 | 30 |
|
30 | | -#### Deployment Status |
| 31 | +- The Components that make up the workload, such as Helm charts or Compose-based container bundles |
| 32 | +- Configuration parameters and deployment profiles that control workload behavior |
| 33 | +- Target information identifying which devices or groups of devices the deployment applies to |
31 | 34 |
|
32 | | -The deployment status is sent to the workload orchestration web service using the [Device API](../../specification/margo-management-interface/deployment-status.md) when there is a change in the deployment state. This informs the workload orchestration web service of the current state as the new desired state is applied. |
| 35 | +The WFM can provide ApplicationDeployments in two formats: |
33 | 36 |
|
34 | | -The deployment status uses the following rules: |
| 37 | +- Individual YAML files, allowing incremental synchronization |
| 38 | +- A bundle archive that contains multiple ApplicationDeployments for bulk distribution |
35 | 39 |
|
36 | | -- The state is `Pending` once the device management client has received the updated desired state but has not started applying it. When reporting this state indicate the reason. |
37 | | - - Such as waiting on Policy agent |
38 | | - - Waiting on other applications in the 'Order of operations' to be completed. |
39 | | -- The state is `Installing` once the device management client has started the process of applying the desired state. |
40 | | -- 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 |
41 | | -- The state is `Success` once the desired state has been applied completely |
| 40 | +All files retrieved as part of the Desired State—manifests, ApplicationDeployment YAMLs, and bundle archives—are treated as immutable artifacts. |
| 41 | +Each artifact is referenced by a SHA-256 digest. The WFM Client validates these digests before applying updates to ensure authenticity and consistency. |
42 | 42 |
|
| 43 | +## Reconciliation process |
43 | 44 |
|
44 | | -> Note: Drawing to be replaced with mermaid sequence diagram. |
45 | | - |
| 45 | +Each WFM Client maintains the Desired State on its Edge Compute Device by running a continuous reconciliation loop. |
| 46 | + |
| 47 | +1. **Retrieve the manifest:** |
| 48 | + The WFM Client periodically checks the WFM for updates to its State Manifest. |
| 49 | + When a new manifest version is available, the client initiates synchronization. |
| 50 | + |
| 51 | +2. **Retrieve artifacts:** |
| 52 | + The WFM Client downloads the referenced ApplicationDeployment YAMLs or bundle archive. |
| 53 | + |
| 54 | +3. **Verify integrity:** |
| 55 | + The WFM Client verifies that each artifact matches the digest declared in the manifest. |
| 56 | + If verification fails, the update is halted and the current workloads remain unchanged. |
| 57 | + |
| 58 | +4. **Apply the Desired State:** |
| 59 | + The WFM Client compares the current workloads with those defined in the Desired State: |
| 60 | + |
| 61 | + - Adds or updates workloads that have changed |
| 62 | + - Removes workloads that are no longer listed |
| 63 | + - Keeps workloads that remain valid and current |
| 64 | + |
| 65 | +5. **Report status:** |
| 66 | + As the synchronization proceeds, the WFM Client reports its deployment status to the WFM through the Deployment Status API. |
| 67 | + |
| 68 | +This continuous process allows the WFM to maintain awareness of workload rollout progress and ensures devices converge toward the Desired State. |
| 69 | + |
| 70 | +## Deployment status |
| 71 | + |
| 72 | +The Deployment Status API provides feedback from devices to the Workload Fleet Manager. |
| 73 | +The WFM Client reports progress, success, or failure during installation, update, and removal operations. |
| 74 | +This feedback allows the WFM to present an aggregated view of deployment health and state across the managed fleet. |
| 75 | + |
| 76 | +A deployment status report includes: |
| 77 | + |
| 78 | +- The identifier of the ApplicationDeployment |
| 79 | +- The current deployment state, which may be: |
| 80 | + |
| 81 | + - Pending - the Desired State has been received but not yet applied |
| 82 | + - Installing - the workload is being deployed |
| 83 | + - Installed - the workload has been successfully applied |
| 84 | + - Removing or Removed - the workload is being or has been uninstalled |
| 85 | + - Failed - an error occurred during deployment |
| 86 | + |
| 87 | +- Optional component-level progress information |
| 88 | +- Error codes and messages, when applicable |
| 89 | + |
| 90 | +This information enables real-time monitoring and supports troubleshooting and auditing of workload operations. |
| 91 | + |
| 92 | +## Sequence diagram |
| 93 | + |
| 94 | +```mermaid |
| 95 | +sequenceDiagram |
| 96 | + participant WFM as Workload Fleet Manager |
| 97 | + participant Client as WFM Client (running on Edge Compute Device) |
| 98 | +
|
| 99 | + loop Periodic synchronization |
| 100 | + Client->>WFM: Retrieve Desired State (Desired State API) |
| 101 | + alt Desired State unchanged |
| 102 | + WFM-->>Client: No update available |
| 103 | + else Desired State updated |
| 104 | + WFM-->>Client: Provide new State Manifest |
| 105 | + Client->>WFM: Retrieve ApplicationDeployments or bundle |
| 106 | + Client->>Client: Apply workloads from Desired State |
| 107 | + Client->>WFM: Report deployment status (Deployment Status API) |
| 108 | + end |
| 109 | + end |
| 110 | +
|
| 111 | +``` |
0 commit comments