Skip to content

Commit c914a93

Browse files
ajcraigphil-abbarne-broering
authored
Specification Navigation Restructure (#78)
* Initial commit for restructuring Signed-off-by: Armand Craig <ajcraig@ra.rockwell.com> * Additional general updates towards the branch. - enrolled persona updates following Josh Swansons branch - closed some feedback via reviewers Signed-off-by: Armand Craig <ajcraig@ra.rockwell.com> * Various additions/fixes Signed-off-by: Armand Craig <ajcraig@ra.rockwell.com> * Updated content on the Introduction page to add more 200-level content. Signed-off-by: Philip <philip.presson@us.abb.com> * Updates to the workload observability pages to account for persona changes Signed-off-by: Philip <philip.presson@us.abb.com> * Fixed a couple of type-os Signed-off-by: Philip <philip.presson@us.abb.com> * more restructuring Signed-off-by: Arne Broering <arne.broering@siemens.com> * Updated headings to make the navigation a little cleaner Signed-off-by: Philip <philip.presson@us.abb.com> * Updated navigation titles to use our lexicon terms Signed-off-by: Philip <philip.presson@us.abb.com> * restructured the App Package Definition - 2 Signed-off-by: Arne Broering <arne.broering@siemens.com> * polishing the restructuring of App Definition Package Signed-off-by: Arne Broering <arne.broering@siemens.com> * added additional "why" information to the workloads overview page. Signed-off-by: Philip <philip.presson@us.abb.com> * Updates to the system design page to add more context and links to the overview pages. Signed-off-by: Philip <philip.presson@us.abb.com> * Fixed some wording on the intro page Signed-off-by: Philip <philip.presson@us.abb.com> * Fixed some spelling errors Signed-off-by: Philip <philip.presson@us.abb.com> * added some initial definitions for orchestration and interoperability Signed-off-by: Philip <philip.presson@us.abb.com> * Additional cleanup within management interface / technical lexicon / device requirements Signed-off-by: Armand Craig <ajcraig@rockwellautomation.com> * small restructuring Signed-off-by: Arne Broering <arne.broering@siemens.com> * small restructuring Signed-off-by: Arne Broering <arne.broering@siemens.com> * Switch lexicon terms back to headers so they can be linked to Signed-off-by: Philip <philip.presson@us.abb.com> * aligned section titles in overview and made some formatting/spelling updates. Signed-off-by: Philip <philip.presson@us.abb.com> * Fixed type-o Signed-off-by: Philip <philip.presson@us.abb.com> * added missing main header to page Signed-off-by: Philip <philip.presson@us.abb.com> * Final commit with few changes before PR creation Signed-off-by: Armand Craig <ajcraig@rockwellautomation.com> * Fixed a few spelling and md formatting issues I noticed. Signed-off-by: Philip <philip.presson@us.abb.com> * Updated System Design based on new technical lexicon Signed-off-by: Armand Craig <ajcraig@rockwellautomation.com> --------- Signed-off-by: Philip <philip.presson@us.abb.com> Signed-off-by: Arne Broering <arne.broering@siemens.com> Co-authored-by: Philip <philip.presson@us.abb.com> Co-authored-by: Arne Broering <arne.broering@siemens.com>
1 parent f8b82c8 commit c914a93

File tree

40 files changed

+4171
-352
lines changed

40 files changed

+4171
-352
lines changed

‎doc-generation/configurations/application-description.json‎

Lines changed: 0 additions & 6 deletions
This file was deleted.

‎doc-generation/configurations/application-package-api.json‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
{
2+
"root": "src/margo-api-reference/workload-api/application-package-api",
3+
"targetclass": "ApplicationDescription",
4+
"schemafile": "application-description.linkml.yaml",
5+
"markdowndoc": "application-description.md"
6+
}

‎mkdocs.yml‎

Lines changed: 42 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,49 +1,55 @@
1-
site_name: System Design
1+
site_name: Specification (pre-draft)
22
docs_dir: system-design
33

44
nav:
5-
- index.md
6-
- margo-overview/introduction-system-design.md
7-
- margo-overview/personas.md
8-
- Concepts and Terms:
9-
- margo-overview/technical-lexicon.md
10-
- margo-overview/application-observability-overview.md
11-
- Application Distribution:
12-
- app-interoperability/application-package-definition.md
13-
- app-interoperability/workload-orch-to-app-reg-interaction.md
14-
- app-interoperability/publishing-application-observability-data.md
15-
- app-interoperability/local-registries.md
16-
- Device Interoperability:
17-
- device-interoperability/device-requirements.md
18-
- device-interoperability/collecting-application-observability-data.md
19-
- Orchestration:
20-
- Workload:
21-
- orchestration/workload/workload-management-interface-breakdown.md
22-
- orchestration/workload/workload-orchestration-edge-onboarding.md
23-
- orchestration/workload/device-capability-reporting.md
24-
- orchestration/workload/workload-deployment.md
25-
- orchestration/workload/consuming-application-observability-data.md
26-
## - Device:
27-
## - Appendix:
28-
## - Management API Definition: margo-overview/personas.md
29-
- Management API Reference:
30-
- margo-api-reference/margo-api-specification.md
31-
- Workload API:
32-
- Desired State API:
33-
- margo-api-reference/workload-api/desired-state-api/desired-state.md
34-
- Device API:
35-
- margo-api-reference/workload-api/device-api/device-capabilities.md
36-
- margo-api-reference/workload-api/device-api/deployment-status.md
37-
- Onboarding API:
38-
- margo-api-reference/workload-api/onboarding-api/device-onboarding.md
39-
- margo-api-reference/workload-api/onboarding-api/rootca-download.md
5+
- What is Margo?: index.md
6+
- Personas & Definitions:
7+
- margo-overview/personas.md
8+
- margo-overview/personas-extended.md
9+
- margo-overview/technical-lexicon.md
10+
- Overview:
11+
- margo-overview/introduction-system-design.md
12+
- margo-overview/application-package-overview.md
13+
- margo-overview/workload-management-interface-overview.md
14+
- margo-overview/devices-overview.md
15+
- margo-overview/workload-observability-overview.md
16+
- Components:
17+
- Workloads:
18+
- app-interoperability/application-package-definition.md
19+
- app-interoperability/workload-orch-to-app-reg-interaction.md # = Application Registry
20+
- app-interoperability/publishing-workload-observability-data.md
21+
- app-interoperability/local-registries.md
22+
- Workload Fleet Managers:
23+
- fleet-management/workload/management-interface-requirements.md
24+
- fleet-management/workload/workload-fleet-management-edge-onboarding.md
25+
- fleet-management/workload/device-capability-reporting.md
26+
- fleet-management/workload/workload-deployment.md
27+
- fleet-management/workload/consuming-workload-observability-data.md
28+
- Edge Compute Devices:
29+
- device-interoperability/device-requirements.md
30+
- device-interoperability/collecting-workload-observability-data.md
31+
- Technical References:
32+
- Margo Management Interface:
33+
- margo-api-reference/margo-api-specification.md
34+
- margo-api-reference/workload-api/desired-state-api/desired-state.md
35+
- margo-api-reference/workload-api/device-api/device-capabilities.md
36+
- margo-api-reference/workload-api/device-api/deployment-status.md
37+
- margo-api-reference/workload-api/onboarding-api/device-onboarding.md
38+
- margo-api-reference/workload-api/onboarding-api/rootca-download.md
39+
- Application Package Definition:
40+
- margo-api-reference/workload-api/application-package-api/application-description.md
41+
#- Observability:
42+
- Make a Contribution:
43+
- how-to-contribute/contribution-tutorial.md
44+
- how-to-contribute/contribution-navigation.md
4045

4146
theme:
4247
name: material
4348
features:
4449
#- navigation.tabs
4550
#- navigation.settings
4651
#- navigation.top
52+
#- navigation.sections
4753
- navigation.tracking
4854
- navigation.footer
4955
- toc.integrate

src/app-interoperability/application-package-definition.linkml.yaml renamed to src/margo-api-reference/workload-api/application-package-api/application-description.linkml.yaml

File renamed without changes.

src/app-interoperability/resources/class.md.jinja2 renamed to src/margo-api-reference/workload-api/application-package-api/resources/class.md.jinja2

File renamed without changes.

src/app-interoperability/resources/examples/valid/ApplicationDescription-001.yaml renamed to src/margo-api-reference/workload-api/application-package-api/resources/examples/valid/ApplicationDescription-001.yaml

File renamed without changes.

src/app-interoperability/resources/examples/valid/ApplicationDescription-002.yaml renamed to src/margo-api-reference/workload-api/application-package-api/resources/examples/valid/ApplicationDescription-002.yaml

File renamed without changes.

src/app-interoperability/resources/index.md.jinja2 renamed to src/margo-api-reference/workload-api/application-package-api/resources/index.md.jinja2

Lines changed: 17 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -1,59 +1,4 @@
1-
# Application Package Definition
2-
3-
This section defines the application package provided by an “Application Developer” who has implemented the application and aims to provide it to Margo-conformant systems. The application package comprises:
4-
5-
- The **application description**: a YAML document with the element `kind` defined as `ApplicationDescription`, which is stored in a file (e.g., `margo.yaml`) and contains information about the application's [metadata](#metadata-attributes) (e.g., description, icon, release notes, license file, etc.), application supported [deployment configurations](#deploymentprofile-attributes) (e.g, Helm charts, Docker Compose package), and [configurable application parameters](#defining-configurable-application-parameters). There SHALL be only one YAML file in the package root of kind `ApplicationDescription`.
6-
- The **resources**, which are additional information about the application (e.g., manual, icon, release notes, license file, etc.) that can be provided in an [application catalog](../../margo-overview/technical-lexicon) or [marketplace](../../margo-overview/technical-lexicon).
7-
8-
The application package has the following file/folder structure:
9-
10-
```yaml
11-
/ # REQUIRED top-level directory
12-
└── application description # REQUIRED a YAML document with element 'kind' as 'ApplicationDescription' stored in a file (e.g., 'margo.yaml')
13-
└── resources # OPTIONAL folder with application resources (e.g., icon, license file, release notes) that can be displayed in an application catalog
14-
```
15-
16-
An application aggregates one or more [OCI Containers](https://github.com/opencontainers). While the application package is made available in an [application registry](./workload-orch-to-app-reg-interaction.md), the referenced OCI artifacts are stored in a remote or [local registry](../local-registries).
17-
18-
> **Note**
19-
> Application catalogs or marketplaces are out of scope for Margo. The exact requirements of the marketing material shall be defined by the application marketplace beyond outlined mandatory content.
20-
21-
The [deployment profiles](#deploymentprofile-attributes) specified in the application description SHALL be defined as Helm Charts AND/OR Docker Compose components.
22-
23-
- To target devices, which run Kubernetes, applications must be packaged as Helm charts using [Helm V3](https://helm.sh/).
24-
- To target devices, which deploy applications using Docker Compose, applications must be packaged as a tarball file containing the *docker-compose.yml* file and any additional artifacts referenced by the docker compose file (e.g., configuration files, environment variable files, etc.). It is highly recommend to digitally sign this package. When digitally signing the package PGP MUST be used.
25-
26-
> **Investigation Needed**: We plan to do a security review of this package definition later.
27-
> During this review we will revisit the way the Docker Compose tarball file should be signed.
28-
> We will also discuss how we should handle secure container registries that require a username and password.
29-
>
30-
> **Investigation Needed**: We need to determine what impact, if any, using 3rd party helm charts has on being Margo compliant.
31-
>
32-
> **Investigation Needed**: Missing in the current specification are ways to define the compatibility information (resources required to run, application dependencies) as well as required infrastructure services such as storage, message queues/bus, reverse proxy, or authentication/authorization/accounting.
33-
34-
If either one cannot be implemented it MAY be omitted but Margo RECOMMENDS defining [deployment profiles](#deploymentprofile-attributes) as both Helm chart **AND** Docker Compose components to strengthen interoperability and applicability.
35-
36-
> **Note**
37-
> A device running the application will only install the application using either Docker Compose files or Helm Charts but not both.
38-
39-
40-
## Application Description
41-
42-
The application description has the purpose of presenting the application, e.g., on an application catalog or marketplace from where an end user selects an application to be installed. The end user defines an `ApplicationDeployment` by specifying [configuration parameters](#defining-configurable-application-parameters) for an `ApplicationDescription`. An `ApplicationDeployment` defines the [desired state](../../margo-api-reference/workload-api/desired-state-api/desired-state/) for an application.
43-
44-
### Application Description Example
45-
46-
A simple hello-world example of an `ApplicationDescription` is shown below:
47-
48-
```yaml
49-
{% include 'examples/valid/ApplicationDescription-001.yaml' %}
50-
```
51-
52-
An example of an `ApplicationDescription` defining [deployment profiles](#deploymentprofile-attributes) for both cases, Helm chart as well as Docker Compose, is shown below.
53-
54-
```yaml
55-
{% include 'examples/valid/ApplicationDescription-002.yaml' %}
56-
```
1+
The application description has the purpose of presenting the application, e.g., on an application catalog or marketplace from where an end user selects an application to be installed. The end user defines an `ApplicationDeployment` by specifying [configuration parameters](#defining-configurable-application-parameters) for an `ApplicationDescription`. An `ApplicationDeployment` defines the [desired state](../desired-state-api/desired-state.md) for an application.
572

583
### Top-level Attributes
594

@@ -150,3 +95,19 @@ To allow customizable configuration values when installing an application, the *
15095

15196
{%- endif %}
15297
{%- endfor %}
98+
99+
## Application Description Examples
100+
101+
### Example 1: Simple Application Description
102+
A simple hello-world example of an `ApplicationDescription` is shown below:
103+
104+
```yaml
105+
{% include 'examples/valid/ApplicationDescription-001.yaml' %}
106+
```
107+
108+
### Example 2: Application Description with Deployment Profiles for Helm and Compose
109+
An example of an `ApplicationDescription` defining [deployment profiles](#deploymentprofile-attributes) for both cases, Helm chart as well as Compose, is shown below.
110+
111+
```yaml
112+
{% include 'examples/valid/ApplicationDescription-002.yaml' %}
113+
```

‎system-design/app-interoperability/.gitignore‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,2 @@
11
docs
2-
application-package-definition.md
32

‎system-design/app-interoperability/application-package-definition.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# Application Package Definition
2+
3+
The application package, which is used to [distribute an application](../margo-overview/application-package-overview.md), comprises the following elements:
4+
5+
- The **application description**: a YAML document with the element `kind` defined as `ApplicationDescription`, which is stored in a file (for example named `margo.yaml`) and contains information about the application's [metadata](../margo-api-reference/workload-api/application-package-api/application-description.md#metadata-attributes) (e.g., description, icon, release notes, license file, etc.), application supported [deployment configurations](../margo-api-reference/workload-api/application-package-api/application-description.md#deploymentprofile-attributes) (e.g, Helm charts, Compose package), and [configurable application parameters](../margo-api-reference/workload-api/application-package-api/application-description.md#defining-configurable-application-parameters). There SHALL be only one YAML file in the package root of kind `ApplicationDescription`.
6+
- The **resources**, which are additional information about the application (e.g., manual, icon, release notes, license file, etc.) that can be provided in an [application catalog](../margo-overview/technical-lexicon.md) or [marketplace](../margo-overview/technical-lexicon.md).
7+
8+
The application package has the following file/folder structure:
9+
10+
```yaml
11+
/ # REQUIRED top-level directory
12+
└── application description # REQUIRED a YAML document with element 'kind' as 'ApplicationDescription' stored in a file (e.g., 'margo.yaml')
13+
└── resources # OPTIONAL folder with application resources (e.g., icon, license file, release notes) that can be displayed in an application catalog
14+
```
15+
16+
An application aggregates one or more [OCI Containers](https://github.com/opencontainers). While the application package is made available in an [application registry](./workload-orch-to-app-reg-interaction.md), the referenced OCI artifacts are stored in a remote or [local registry](../app-interoperability/local-registries.md).
17+
18+
> **Note**
19+
> Application catalogs or marketplaces are out of scope for Margo. The exact requirements of the marketing material shall be defined by the application marketplace beyond outlined mandatory content.
20+
21+
The [deployment profiles](../margo-api-reference/workload-api/application-package-api/application-description.md#deploymentprofile-attributes) specified in the application description SHALL be defined as Helm Charts AND/OR Compose components.
22+
23+
- To target devices, which run Kubernetes, applications must be packaged as Helm charts using [Helm (version 3)](https://helm.sh/docs/topics/charts/).
24+
- To target devices, which deploy applications using [Compose](https://www.compose-spec.io/), applications must be packaged as a tarball file containing the *compose.yml* file and any additional artifacts referenced by the Compose file (e.g., configuration files, environment variable files, etc.). It is highly recommend to digitally sign this package. When digitally signing the package PGP encryption MUST be used.
25+
26+
> **Investigation Needed**: We plan to do a security review of this package definition later.
27+
> During this review we will revisit the way the Compose tarball file should be signed.
28+
> We will also discuss how we should handle secure container registries that require a username and password.
29+
>
30+
> **Investigation Needed**: We need to determine what impact, if any, using 3rd party helm charts has on being Margo compliant.
31+
>
32+
> **Investigation Needed**: Missing in the current specification are ways to define the compatibility information (resources required to run, application dependencies) as well as required infrastructure services such as storage, message queues/bus, reverse proxy, or authentication/authorization/accounting.
33+
34+
If either one cannot be implemented it MAY be omitted but Margo RECOMMENDS defining [deployment profiles](../margo-api-reference/workload-api/application-package-api/application-description.md#deploymentprofile-attributes) as both Helm chart **AND** Compose components to strengthen interoperability and applicability.
35+
36+
> **Note**
37+
> A device running the application will only install the application using either Compose files or Helm Charts but not both.
38+
39+
## Relevant Links
40+
Please follow the subsuquent link to view the technical reference:
41+
42+
- [Application Description](../margo-api-reference/workload-api/application-package-api/application-description.md)

0 commit comments

Comments
 (0)
⚡