From 254b6973c0332a6893d66f302fb55d3c8a59161f Mon Sep 17 00:00:00 2001 From: Philip Date: Mon, 27 Apr 2026 12:39:58 -0400 Subject: [PATCH 1/2] Updates for approved Helm SUPs Signed-off-by: Philip --- .../concepts/applications/application-package.md | 2 +- system-design/overview/applications.md | 2 +- .../personas-and-definitions/software-composition.md | 12 ++++++------ 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/system-design/concepts/applications/application-package.md b/system-design/concepts/applications/application-package.md index 1e31821..2f9ea39 100644 --- a/system-design/concepts/applications/application-package.md +++ b/system-design/concepts/applications/application-package.md @@ -45,7 +45,7 @@ Registries can be remote (i.e., Internet-accessible) or [local](../../concepts/a The components are being deployed as workloads on the edge devices: -- To target devices, which deploy workloads using Kubernetes, components need to be defined as Helm charts using [Helm (version 3)](https://helm.sh/docs/topics/charts/). +- To target devices, which deploy workloads using Kubernetes, components need to be defined as Helm charts using either Helm [version 3](https://helm.sh/docs/v3/topics/charts) or [version 4](https://helm.sh/docs/topics/charts) with Chart APIVersion V2 only (see [specification for restrictions](../../specification/applications/application-description#helm-restrictions)). - To target devices, which deploy workloads using [Compose](https://www.compose-spec.io/), components need to be packaged as [Compose Archives](../../personas-and-definitions/technical-lexicon.md#compose-archive), i.e., a tarball file containing the `compose.yaml` file and any additional artifacts referenced by the Compose file (e.g., configuration files, environment variable files, etc.). Margo recommends to digitally sign this package and to specify the location of the public key in the `ApplicationDescription` (see `keyLocation` [here](../../specification/applications/application-description.md#componentproperties-attributes)). When digitally signing the package PGP encryption MUST be used. If either one cannot be implemented it MAY be omitted but Margo RECOMMENDS defining [deployment profiles](../../specification/applications/application-description.md#deploymentprofile-attributes) as both Helm chart **AND** Compose components to strengthen interoperability and applicability. diff --git a/system-design/overview/applications.md b/system-design/overview/applications.md index 47f8ace..8d0fada 100644 --- a/system-design/overview/applications.md +++ b/system-design/overview/applications.md @@ -2,7 +2,7 @@ An application is defined as an [Application Package](../concepts/applications/application-package.md) described through an [Application Description](../specification/applications/application-description.md) and consists of deployable [components](../personas-and-definitions/technical-lexicon.md#component). A running [component](../personas-and-definitions/technical-lexicon.md#component) is called a [workload](../personas-and-definitions/technical-lexicon.md#workload). A workload runs on a Margo compliant [edge compute device](../personas-and-definitions/technical-lexicon.md#edge-compute-device). -In order to help achieve Margo's interoperability [mission statement](../what-is-margo#mission-statement) we are initially targeting [containerized](https://github.com/opencontainers) components/workloads capable of running on platforms like Kubernetes, Docker and Podman. The flexibility these platforms provide enables [workload suppliers](../personas-and-definitions/personas.md#workload-supplier) to define and package their components in a common way using [Helm](https://helm.sh/docs/) or the [Compose specification](https://github.com/compose-spec/compose-spec/blob/main/spec.md) so they can more easily be deployed to multiple compatible edge compute devices as workloads. +In order to help achieve Margo's interoperability [mission statement](../what-is-margo#mission-statement) we are initially targeting [containerized](https://github.com/opencontainers) components/workloads capable of running on platforms like Kubernetes, Docker and Podman. The flexibility these platforms provide enables [workload suppliers](../personas-and-definitions/personas.md#workload-supplier) to define and package their components in a common way using Helm [version 3](https://helm.sh/docs/v3/) or [version 4](https://helm.sh/docs/) with Chart APIVersion v2 only (see [specification for restrictions](../../specification/applications/application-description#helm-restrictions)), or the [Compose specification](https://github.com/compose-spec/compose-spec/blob/main/spec.md) so they can more easily be deployed to multiple compatible edge compute devices as workloads. While Margo is initially targeting deployments using Helm or Compose, we plan to support other deployment types in the future. One of our design goals is to make it easier for [workload fleet managers](../personas-and-definitions/technical-lexicon.md#workload-fleet-manager) to support the current and future deployment types without having to implement special logic for each type. In order to achieve this, Margo defines an [application description model](../concepts/applications/application-package.md) to abstract away some of the details to make it easier for workload fleet managers to support the different deployment types. diff --git a/system-design/personas-and-definitions/software-composition.md b/system-design/personas-and-definitions/software-composition.md index 8c55270..18bb486 100644 --- a/system-design/personas-and-definitions/software-composition.md +++ b/system-design/personas-and-definitions/software-composition.md @@ -35,8 +35,8 @@ Some [providers][provider-model] might support that multiple [Workload][workload [Components][component] might have different shapes depending on their type and on which stage is being considered: -1. Helm v3 as [Component][component]: a [Helm Chart](https://helm.sh/docs/topics/charts/) -2. Helm v3 as [Workload][workload]: all container images required by the to-be-started pods. +1. Helm as [Component][component]: a [Helm Chart](https://helm.sh/docs/topics/charts/) +2. Helm as [Workload][workload]: all container images required by the to-be-started pods. 3. Compose as [Component][component]: a [Compose Archive][application-package] 4. Compose as [Workload][workload]: a so-called [Compose file](https://github.com/compose-spec/compose-spec/blob/main/spec.md#compose-file) and all the container images required by the to-be-started [services](https://github.com/compose-spec/compose-spec/blob/main/05-services.md). @@ -87,7 +87,7 @@ C4Component System_Boundary(c1, "Application Description") { Component(ad, "Application Description", "ApplicationDescription", "YAML document") System_Boundary(c2, "deploymentProfiles") { - System_Boundary(c3, "helm.v3") { + System_Boundary(c3, "helm") { Component(wldh1, "Helm WorkloadArtifact 1", "Section in YAML document") } System_Boundary(c4, "compose") { @@ -200,15 +200,15 @@ C4Context In this stage the [providers][provider-model] are responsible for managing the individual [Workloads][workload]. -On a Helm v3 [Deployment Profiles][deployment-profile], a [Workload Fleet Management Client][wfmc] implementation could utilize the Helm API to start the individual Helm Charts. +On a Helm [Deployment Profiles][deployment-profile], a [Workload Fleet Management Client][wfmc] implementation could utilize the Helm API to start the individual Helm Charts. On a Compose [Deployment Profiles][deployment-profile], a [Workload Fleet Management Client][wfmc] implementation could utilize the Compose CLI to start the individual [Workloads][workload]. -The following diagram shows the result of reaching the desired state for an [Application][application] with a Helm v3 [Deployment Profile][deployment-profile] (the result of `helm install`). +The following diagram shows the result of reaching the desired state for an [Application][application] with a Helm [Deployment Profile][deployment-profile] (the result of `helm install`). ```mermaid C4Component - title Application Deployment: Helm v3 deployment profile + title Application Deployment: Helm deployment profile UpdateLayoutConfig($c4BoundaryInRow="3", $c4ShapeInRow="1") From 6144d252fc59aa169f5b7c29b48a3f13aca87c97 Mon Sep 17 00:00:00 2001 From: Philip Date: Mon, 27 Apr 2026 12:56:36 -0400 Subject: [PATCH 2/2] Missed file with commit Signed-off-by: Philip --- system-design/concepts/applications/application-package.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/system-design/concepts/applications/application-package.md b/system-design/concepts/applications/application-package.md index 2f9ea39..770e58b 100644 --- a/system-design/concepts/applications/application-package.md +++ b/system-design/concepts/applications/application-package.md @@ -45,7 +45,7 @@ Registries can be remote (i.e., Internet-accessible) or [local](../../concepts/a The components are being deployed as workloads on the edge devices: -- To target devices, which deploy workloads using Kubernetes, components need to be defined as Helm charts using either Helm [version 3](https://helm.sh/docs/v3/topics/charts) or [version 4](https://helm.sh/docs/topics/charts) with Chart APIVersion V2 only (see [specification for restrictions](../../specification/applications/application-description#helm-restrictions)). +- To target devices, which deploy workloads using Kubernetes, components need to be defined as Helm charts using either Helm [version 3](https://helm.sh/docs/v3/topics/charts) or [version 4](https://helm.sh/docs/topics/charts) with Chart APIVersion v2 only (see [specification for restrictions](../../specification/applications/application-description#helm-restrictions)). - To target devices, which deploy workloads using [Compose](https://www.compose-spec.io/), components need to be packaged as [Compose Archives](../../personas-and-definitions/technical-lexicon.md#compose-archive), i.e., a tarball file containing the `compose.yaml` file and any additional artifacts referenced by the Compose file (e.g., configuration files, environment variable files, etc.). Margo recommends to digitally sign this package and to specify the location of the public key in the `ApplicationDescription` (see `keyLocation` [here](../../specification/applications/application-description.md#componentproperties-attributes)). When digitally signing the package PGP encryption MUST be used. If either one cannot be implemented it MAY be omitted but Margo RECOMMENDS defining [deployment profiles](../../specification/applications/application-description.md#deploymentprofile-attributes) as both Helm chart **AND** Compose components to strengthen interoperability and applicability.