diff --git a/src/specification/applications/application-description.linkml.yaml b/src/specification/applications/application-description.linkml.yaml index 84567be0..c9ca9c3f 100644 --- a/src/specification/applications/application-description.linkml.yaml +++ b/src/specification/applications/application-description.linkml.yaml @@ -337,7 +337,7 @@ classes: #rank: 63 slot_usage: type: - equals_string: "helm.v3" + equals_string: "helm" rank: 10 components: range: HelmComponent @@ -687,16 +687,16 @@ slots: type: description: >- Defines the type of this deployment configuration for the application. - The allowed values are `helm.v3`, to indicate the deployment profile's format is Helm version 3, + The allowed values are `helm`, to indicate the deployment profile's format is Helm version 3 or Version 4 using Chart APIVersion v2 (see [special exceptions below](#helm-exceptions)), and `compose` to indicate the deployment profile's format is a Compose file. - When installing the application on a device supporting the Kubernetes platform, all `helm.v3` components, - and only `helm.v3` components, will be provided to the device in same order they are listed in the application description file. + When installing the application on a device supporting the Kubernetes platform, all `helm` components, + and only `helm` components, will be provided to the device in same order they are listed in the application description file. When installing the application on a device supporting Compose, all `compose` components, and only `compose` components, will be provided to the device in the same order they are listed in the application description file. The device will install the components in the same order they are listed in the application description file. range: string required: true - pattern: ^(helm\.v3|compose)$ + pattern: ^(helm|compose)$ rank: 10 components: diff --git a/src/specification/applications/resources/examples/valid/ApplicationDescription-001.yaml b/src/specification/applications/resources/examples/valid/ApplicationDescription-001.yaml index 5eef610d..ec9d8395 100644 --- a/src/specification/applications/resources/examples/valid/ApplicationDescription-001.yaml +++ b/src/specification/applications/resources/examples/valid/ApplicationDescription-001.yaml @@ -21,8 +21,8 @@ metadata: - name: Northstar Industrial Applications site: http://northstar-ida.com deploymentProfiles: - - type: helm.v3 - id: com-northstartida-hello-world-helm.v3-a + - type: helm + id: com-northstartida-hello-world-helm-a components: - name: hello-world properties: diff --git a/src/specification/applications/resources/examples/valid/ApplicationDescription-002.yaml b/src/specification/applications/resources/examples/valid/ApplicationDescription-002.yaml index c21c8d9e..583d36a0 100644 --- a/src/specification/applications/resources/examples/valid/ApplicationDescription-002.yaml +++ b/src/specification/applications/resources/examples/valid/ApplicationDescription-002.yaml @@ -21,8 +21,8 @@ metadata: - name: Northstar Industrial Applications site: http://northstar-ida.com deploymentProfiles: - - type: helm.v3 - id: com-northstartida-digitron-orchestrator-helm.v3-a + - type: helm + id: com-northstartida-digitron-orchestrator-helm-a description: This allows to install / run the application as a Helm chart deployment. The device where this application is installed needs to have a screen and a keyboard (as indicated in the required peripherals). components: diff --git a/src/specification/applications/resources/index.md.jinja2 b/src/specification/applications/resources/index.md.jinja2 index 7e4e1b3c..6dd13526 100644 --- a/src/specification/applications/resources/index.md.jinja2 +++ b/src/specification/applications/resources/index.md.jinja2 @@ -67,20 +67,34 @@ which defines the [desired state](../margo-management-interface/desired-state.md {%- endif %} +{%- if c.name.startswith("DeploymentProfile") %} +#### Helm Exceptions +Applications can be deployed as Helm charts using either Helm [version 3](https://helm.sh/docs/v3/topics/charts) or [version 4](https://helm.sh/docs/topics/charts) using Chart APIVersion v2 only. + +In order to facility the require deployment options for Helm charts, Margo does not support Helm functions requiring direct communication with the Kubernetes API. + +Your Helm based application MUST NOT rely on the following Helm functions: +- [Lookup](https://helm.sh/docs/chart_template_guide/functions_and_pipelines#using-the-lookup-function): The `lookup` template function queries live resources in the target Kubernetes cluster at render time, for example to fetch ConfigMaps, Secrets, or other objects. This requires direct API access and cluster credentials during rendering. +- [Hooks](https://helm.sh/docs/topics/charts_hooks/): Hooks (pre/post install, upgrade, delete, rollback, test, etc.) execute additional Kubernetes resources or jobs at specific points in the release lifecycle. Helm waits for these resources to reach a ready state by monitoring them via the Kubernetes API, and the hooks themselves may perform privileged or arbitrary operations in the cluster. +- [CRD management via helm](https://helm.sh/docs/chart_best_practices/custom_resource_definitions/): Installing or managing Custom Resource Definitions (CRDs) with Helm requires checking for the presence of CRDs and registering new APIs with the cluster, which involves API calls and may require elevated permissions. + +**Note:** This function list is based on the current Helm v3 and v4 implementations. Additional functions may be added later if Helm introduced new functions requiring communication with the Kuberentes API to work. + +{%- endif %} {%- if c.name.startswith("ComponentProperties") %} ### ComponentProperties Attributes The expected properties for the suppported deployment types are indicated below. -- Properties for `helm.v3` components +- Properties for `helm` components | Attribute | Type | Required? | Description | | --- | --- | --- | --- | | repository | string | Y | The URL indicating the helm chart's location.| | revision | string | Y | The helm chart's full version.| -| wait | bool | N | If `True`, indicates the device MUST wait until the helm chart has finished installing before installing the next helm chart. The default is `True`. The Workload Fleet Management Client MUST support `True` and MAY support `False`. Only applies if multiple `helm.v3` components are provided.| +| wait | bool | N | If `True`, indicates the device MUST wait until the helm chart has finished installing before installing the next helm chart. The default is `True`. The Workload Fleet Management Client MUST support `True` and MAY support `False`. Only applies if multiple `helm` components are provided.| | timeout | string | N | The time to wait for the component's installation to complete. If the installation does not completed before the timeout occurs the installation process fails. The format is "##m##s" indicating the total number of minutes and seconds to wait. | - Properties for `compose` components diff --git a/src/specification/margo-management-interface/desired-state.linkml.yaml b/src/specification/margo-management-interface/desired-state.linkml.yaml index 105e6b80..d6f8e991 100644 --- a/src/specification/margo-management-interface/desired-state.linkml.yaml +++ b/src/specification/margo-management-interface/desired-state.linkml.yaml @@ -121,7 +121,7 @@ classes: rank: 40 slot_usage: type: - equals_string: "helm.v3" + equals_string: "helm" rank: 10 components: range: HelmComponent @@ -212,7 +212,7 @@ classes: slots: type: - description: The type of deployment profile (e.g., helm.v3, compose). + description: The type of deployment profile (e.g., helm, compose). range: string required: true rank: 10 diff --git a/src/specification/margo-management-interface/resources/examples/invalid/DesiredState-001.yaml b/src/specification/margo-management-interface/resources/examples/invalid/DesiredState-001.yaml index 08580061..95560b44 100644 --- a/src/specification/margo-management-interface/resources/examples/invalid/DesiredState-001.yaml +++ b/src/specification/margo-management-interface/resources/examples/invalid/DesiredState-001.yaml @@ -11,7 +11,7 @@ metadata: namespace: margo-poc spec: deploymentProfile: - type: helm.v3 + type: helm components: - name: database-services properties: diff --git a/src/specification/margo-management-interface/resources/examples/invalid/DesiredState-002.yaml b/src/specification/margo-management-interface/resources/examples/invalid/DesiredState-002.yaml index 59a37d58..d80e0edc 100644 --- a/src/specification/margo-management-interface/resources/examples/invalid/DesiredState-002.yaml +++ b/src/specification/margo-management-interface/resources/examples/invalid/DesiredState-002.yaml @@ -11,7 +11,7 @@ metadata: namespace: margo-poc spec: deploymentProfile: - type: helm.v3 + type: helm components: - name: database-services properties: diff --git a/src/specification/margo-management-interface/resources/examples/invalid/DesiredState-003.yaml b/src/specification/margo-management-interface/resources/examples/invalid/DesiredState-003.yaml index 237b232d..47b10d7b 100644 --- a/src/specification/margo-management-interface/resources/examples/invalid/DesiredState-003.yaml +++ b/src/specification/margo-management-interface/resources/examples/invalid/DesiredState-003.yaml @@ -11,7 +11,7 @@ metadata: namespace: margo-poc spec: deploymentProfile: - type: helm.v3 + type: helm components: - name: database-services properties: diff --git a/src/specification/margo-management-interface/resources/examples/invalid/DesiredState-004.yaml b/src/specification/margo-management-interface/resources/examples/invalid/DesiredState-004.yaml index e39e153c..4d07f923 100644 --- a/src/specification/margo-management-interface/resources/examples/invalid/DesiredState-004.yaml +++ b/src/specification/margo-management-interface/resources/examples/invalid/DesiredState-004.yaml @@ -11,7 +11,7 @@ metadata: namespace: margo-poc spec: deploymentProfile: - type: helm.v3 + type: helm components: - name: database-services properties: diff --git a/src/specification/margo-management-interface/resources/examples/valid/DesiredState-001.yaml b/src/specification/margo-management-interface/resources/examples/valid/DesiredState-001.yaml index d99ec03a..b72ca632 100644 --- a/src/specification/margo-management-interface/resources/examples/valid/DesiredState-001.yaml +++ b/src/specification/margo-management-interface/resources/examples/valid/DesiredState-001.yaml @@ -8,7 +8,7 @@ metadata: namespace: margo-poc spec: deploymentProfile: - type: helm.v3 + type: helm components: - name: database-services properties: diff --git a/system-design/specification/margo-devices/device-requirements.md b/system-design/specification/margo-devices/device-requirements.md index e17d6c25..dd564a3d 100644 --- a/system-design/specification/margo-devices/device-requirements.md +++ b/system-design/specification/margo-devices/device-requirements.md @@ -14,7 +14,19 @@ Devices filling the standalone cluster role MUST provide the following additiona - Kubernetes orchestration platform - Capabilities for deploying Helm charts - + +### Helm deployment approaches + +Applications can be deployed as Helm charts using either Helm [version 3](https://helm.sh/docs/v3/topics/charts) or [version 4](https://helm.sh/docs/topics/charts) using Chart APIVersion v2 only. + +Margo does not dictate how devices deploy workloads packaged as Helm charts. A device vendor may choose a deployment approach that either interacts with the Kubernetes API (such as `helm install`) or an approach that renders the helm templates and applies the templates (such as `helm template` or Kustomization). In order to facility this choice, certain Helm functions are not support. See the [Helm exceptions](../applications/application-description#helm-exceptions) for more details. + +#### Probationary support for `.Capabilities.APIVersions.Has` function + +**Feedback Wanted:** We are looking for feedback on supporting this function. If you are using a deployment method that does not support passing the list of Kubernetes APIs out of band, please let us know. + +If a device vendor chooses a deployment approach that does not interact with the Kubernetes API, the list of Kuberentes APIs available in the cluster MUST be provided out-of-band. This is supported by a variety of tooling such as the Helm GO SDK, `helm template` command, Kustomization, and ArgoCD. + ## Standalone Device Role Details diff --git a/system-design/specification/margo-management-interface/workload-management-api-1.0.0.yaml b/system-design/specification/margo-management-interface/workload-management-api-1.0.0.yaml index 28b3debc..72181588 100644 --- a/system-design/specification/margo-management-interface/workload-management-api-1.0.0.yaml +++ b/system-design/specification/margo-management-interface/workload-management-api-1.0.0.yaml @@ -643,7 +643,7 @@ components: properties: type: type: string - enum: ["helm.v3", "compose"] + enum: ["helm", "compose"] description: Type of deployment profile components: type: array