- Introduction
- Sandbox Feedback / Issue Reporting
- Quick Start Guide
- Structure of the Repository
- 3rd Party Components
- Design and Mapping to Margo Architecture
- Margo Identity and Authorization Framework (MIAF)
- Identity Lifecycle and Operator Playbooks
- Release Notes
Welcome to the Margo project's Code-first Sandbox! The Margo initiative defines mechanisms for interoperable fleet management of edge applications/workloads and devices. It will deliver on the interoperability promise through an open standard, a reference implementation, and a comprehensive compliance testing toolkit. Margo unlocks barriers to innovation in complex multi-vendor environments and accelerates digital transformation for organizations of all sizes.
This project provides an open-source, sandbox implementation of the Margo specified interfaces and workflows. The objective is to allow interested users to experiment with the interfaces and APIs and provide feedback to improve the Margo specifications. This project is by no means intended for "commercial adoption". The Specification Enhancements process relies on the Code-first sandbox to enable fully specified contributions to the specification.
Before you get started, please spend some time to understand the Structure of the Repository first.
The project follows a Release schedule tied with the Margo specification releases. Please look at the Release Notes sections for specific release specific content. If you want to read more on the design aspects and understand how various components map to the Margo Architecture, please read the Design and Mapping to Margo Architecture section.
However, if you want to try out things first read the section Quick Start Guide below to get your Sandbox Environment setup quickly.
We welcome your thoughts and feedback towards the Code First Sandbox!
Please navigate to the Issues tab of the repository and create a new Issue using the Feedback template.
This section allows you to set up the 'Sandbox' environment for experimenting with the Margo specifications and APIs. This includes instructions on the prerequisites for your setup, how to set up a build environment, creating a deployment on a set of virtual machines and running scenarios between the WFM and the Workload Fleet Management Client using a simple CLI.
Here is Setup Guide to get you started quickly.
Once your environment is set up, refer to the Operations Guide to manage workloads, deploy applications, and monitor your environment using the EasyCLI and observability dashboards.
The repository is divided into three main parts. You can find more details here on Repository Structure:
shared-lib: Reusable libraries and utilities (Open Source Components)standard: Implementation of the components as per Margo specification, a snapshot of the implemented spec is copied from the official sources in this directory for traceability, in case the original source gets changed later on.non-standard: Enabling components, which are not defined by Margo, but required for an overall implementation
| Component Type | Component Name | Version |
|---|---|---|
| Container Registry | Harbor | v2.13.2 |
| Container Runtime | containerd | v1.7.27-1 |
| OCI Client | ORAS | 1.1.0 |
| Database | Redis | 7.0.15 |
| Plugin | docker-buildx | v0.23.0-1 |
| Observability Stack | Prometheus | prometheus-27.49.0 |
| Observability Stack | Grafana | grafana-10.3.0 |
| Observability Stack | Prometheus | prometheus-27.49.0 |
| Observability Stack | Grafana | grafana-10.3.0 |
| Observability Stack | Jaeger | jaeger-3.4.1 |
| Observability Stack | Loki | loki-6.46.0 |
| Observability Stack | OpenTelemetry Collector | 0.140.0 |
| Observability Stack | Promtail | 6.17.1 (helm chart for k3s device), grafana/promtail:2.9.10 (docker-image for docker device) |
| Security & Authentication | OpenSSL | System default |
| Supporting Infrastructure | Helm | 3.15.1 |
| Supporting Infrastructure | Go | 1.25.10 |
| Supporting Infrastructure | Docker | 29.1.2 |
| Supporting Infrastructure | Docker Compose | v5.0.0 |
| Supporting Infrastructure | K3s | v1.31.4+k3s1 |
| Supporting Infrastructure | Node.js/NPM | System default |
| System Utilities | curl | System default |
| System Utilities | jq | System default |
| System Utilities | yq | System default |
| System Utilities | git | System default |
| System Utilities | wget | System default |
| System Utilities | build-essential | System default |
| System Utilities | gcc | System default |
| System Utilities | libc6-dev | System default |
| System Utilities | dos2unix | System default |
Margo envisions a Distributed system design for Industry 4.0 applications, which chiefly includes Application Supplier infrastructure, Fleet Manager and Devices which run Applications. The Fleet Manager responsible for deploying Applications as running Workloads is referred to as a 'Workload Fleet Manager' or WFM.
Other Margo definitions are available in Margo Technical Lexicon
This Code First Sandbox replicates the Margo system design using a set of open-source components, as well as an implementation of the 'standard' and 'non-standard' or enabling components. You can see a view of the Margo system design, with an overlay of the components available in the Code First Sandbox in this diagram of the distributed system design.
This includes the following elements -
- This Code First Sandbox uses Eclipse Symphony as Workload Fleet Manager.
- As mentioned in Margo architecture and overlay architecture WFM connects through Margo envisioned communication mechanisms.
- In case you want to contribute to its repo, then a developer's guide has been can be found here.
- Harbor provides application registry and images/helm-charts repository functionalities.
- Application suppliers' packages, images/helm-charts (related to the before mentioned packages or not) are stored in Harbor.
- Application packages are pulled/pushed/deleted from the Harbor registry.
- WFM stores application packages in its database and are used during LCM (Life Cycle Management) operation.
- The Workload Fleet Management Client pulls docker images/helm artifacts from Harbor whenever workloads are getting deployed corresponding to the application packages during instance deployment.
- Sandbox deploys OpenTelemetry Collector on the WFM client for instrumentation as per Margo observability specification.
- OpenTelemetry Collector sends telemetry data to observability backends from WFM client. Promtail is also deployed on WFM client for log aggregation. Promtail agent fetches and pushes logs to Loki on WFM.
- Observability backends should be external to WFM client. In Sandbox implementation, these backends are deployed on WFM. These include Prometheus, Jaeger, Loki and Grafana.
- Loki is deployed for log aggregation and Grafana dashboard for visualization.
- Jaeger is deployed for tracing.
- Prometheus is deployed for Metrics collection.
- The Sandbox implements MIAF for the Workload Fleet Management interface between the WFM and WFM Clients.
- Components authenticate using mutual TLS (mTLS) with X.509-SVIDs containing SPIFFE IDs. Each peer validates the other peer's SVID against the Trust Bundle for the shared Trust Domain.
- The Margo Identity Service (MIS) issues SVIDs and publishes the Trust Domain discovery document and Trust Bundle over HTTPS. The Sandbox provisions these identities as part of its setup and onboarding workflows.
- Authorization is performed locally by each verifier using the peer's validated SPIFFE ID and the applicable Margo policy; no central authorization server is used.
- See the Margo WFM Identity Profile and Transport Layer Security Requirements for the normative identity and transport requirements.
The Margo Identity Service issues X.509-SVIDs and publishes the Trust Domain discovery document and Trust Bundle over HTTPS. It is deployed on the WFM VM as part of the sandbox setup.
- Issues SVIDs for WFM and WFM Clients using SPIFFE IDs
- Publishes the Trust Bundle via a normative HTTPS API secured by a self-signed CA
- Lifecycle operations (SVID renewal, revocation, Root CA replacement) are operator-driven
See the MIS README for deployment details, PKI setup, and trust model documentation.
The sandbox's choices for MIS SVID minting, HTTP connection reuse, and client-side authorization reflect the current specification and operator-driven lifecycle. See MIAF Design Rationale and Current Trade-offs for the reasoning, security and performance trade-offs, and areas that may evolve with MIAF.
All development and deployment of MIS within this sandbox is performed using self-signed Root Certificate Authorities (CAs). This includes both the Minter CA used to issue X.509-SVIDs and the HTTPS CA used to secure the normative Trust Bundle API. This approach is intentional for sandbox and proof-of-concept use — it keeps the environment fully self-contained without requiring an external PKI infrastructure. Operators bringing their own PKI are responsible for supplying the correct certificate material and ensuring its correctness and trustworthiness.
For a detailed explanation of the PKI trust model, the certificates involved, and guidance on supplying your own PKI infrastructure, see the MIS PKI Setup and Trust Model documentation.
The sandbox follows the operator-driven identity lifecycle described by Margo. Initial SVIDs are generated by MIS, renewal requires replacing the certificate and key followed by a device-agent restart, and device access is revoked by removing its SPIFFE ID from the authorization list. Trust-bundle reset and Root CA replacement require an MIS restart and new identities.
See the Identity Lifecycle and Operator Playbooks for the supported procedures and limitations.
If you want to quickly try the device-agent without setting up the full sandbox environment, you can run the prebuilt binary directly from the release package.
Running the binary requires identity material from a Margo Identity Service (MIS), unless your operator provides equivalent overrides.
👉 Follow the Binary Quick Start Guide here:
Device Agent - Binary Setup Guide
This method is useful for:
- Quick validation and testing
- Lightweight setups without Docker/K3s
- Direct execution on supported systems