Proposal/Discussion: Describe the deployment specification

[ajcraig]

Below I have outlined proposals for an interoperable deployment specification utilized when defining a new desired state within the Workload Orchestration Software.
The associated workflow / use case for this is detailed below.

1. User selects application from the catalog within the WOS
2. User configured the instance of the app for a particular Edge
3. User answers any configuration prompts
4. User selects deploy.
5. WOS creates this deployment specification and places it within a git repository.
6. WOA pulls from the git repository and hands off to the deployment service.

Included in this issue are 3 different example deployment specifications:

• Cluster Simple
• Cluster Complex
• Standalone Simple

Once this discussion has matured, I will create a pull request towards the workload orchestration agent markdown.

Deployment specification example for Cluster with a single component.

kind: Margo Deployment Specification
metadata:
    deploymentName: name: hello-world-deployment
    deploymentUniqueId: #######
spec:
    target:
      device_id: UUID of device from WOA registration
    components:
      - name: hello-world
        type: helm.v3
        properties:
          namespacePrefix: hello.world
          version: 0.0.1
          repo:
          wait: false
    parameters:
      - name: 
        value:
      - name:
        value:

Top-level Attributes

Attribute	Type	Required?	Description
apiVersion	string	Y	Identifier of the version of the API the object definition follows.
kind	string	Y	Must be application.
metadata	Metadata	Y	Metadata element specifying characteristics about the application. See the Metadata section below.
spec	Spec	Y	Spec element that defines target, components, and parameters of the deployment. See the Spec section below.

Metadata Attributes

Attribute	Type	Required?	Description
name	string	Y	The name of the deployment specification.
uniqueID	string	Y	Workload Orchestration Software Unique ID.

Spec Attributes

Attribute	Type	Required?	Description
target	Target	Y	Section that defines which edge device the deployment specification is designed for
components	Components	Y	Components defines the applications associated with the deployment specification
parameters	Parameters	Y	Describes the configured parameters applied via the end-user.

** Target Attributes**

Attribute	Type	Required?	Description
deviceId	string	Y	Unique Identifier assigned to the WOA via the WOS during enrollment.

** Components Attributes**

Attribute	Type	Required?	Description
name	string	Y	Defines the name of the component.
type	string	Y	Describes the type of component.
properties	Properties	Y	Describes the properties of the component.
namespacePrefix	string	Y	Utilized when deploying to the Kubernetes distribution.
version	integer	Y	Describes the version of the component.
repo	string	Y	Provides link to the component location. This can be either a local repository or a remote.
wait	string	N	Describes the configured parameters applied via the end-user.

** Parameter Attributes**

Attribute	Type	Required?	Description
name	string	N	Unique name of the parameter.
value	string	N	Value pair matched to the name of the parameter.

Deployment specification example for Cluster with multiple components.

kind: Margo Deployment Specification
metadata:
    deploymentName: name: hello-world-deployment
    deploymentUniqueId: #######
spec:
    target:
      deviceId: UUID of device from WOA registration
    components:
      - name: hello-world
        type: helm.v3
        properties:
          namespacePrefix: hello.world
          version: 0.0.1
          repo:
          wait: true
          waitTime: 15 seconds
      - name: database
        type: helm.v3
        properties:
          namespacePrefix: 
          version:
          repo:
          wait:
          waitTime:
    parameters:
      - name: 
        value:
      - name:
        value:

Deployment specification example for Standalone Device with a single component.

kind: Margo Deployment Specification
metadata:
    deploymentName: name: hello-world-deployment
    deploymentUniqueId: #######
spec:
    target:
      deviceId: UUID of device from WOA registration
    components:
      standalone:
        - name: 
          type: docker-compose
          properties:
            packageLocation:
            keyLocation:
    parameters:
      - name: 
        value:
      - name:
        value:

[ajcraig]

@margo/technical-wg @phil-abb @Haishi2016 @arne-broering
I have updated this to include my proposal shown during the call today.

Let me know your thoughts!

[phil-abb]

Since the apiVersion will have Margo in the name I don't think the kind needs to have "Margo" in it. Also, the convention is to use Pascal casing for the kind with CRDs so it should be DeploymentSpecification instead.

What do you think about ApplicationDeployment instead?

In the table, it says it should be application

Also, your examples are omitting the apiVersion

[phil-abb]

• deploymentName: name: hello-world-deployment isn't valid. In the table, you have just name and uniqueID but the examples have deploymentXYZ so I'm not sure which direction you were intending. my preference it to create groups instead of repeating prefixes if you wanted to keep the deployment prefix but I don't think it's needed.

• The example has a waitTime but the table doesn't. If this is something we intend to have here then we'd also need to include it in the application description. I'm not sure if it's necessary.

• For the namespacePrefix we should consider passing in the id from the application definition instead because that was the idea behind it. Maybe that was the intention but it's not clear. I guess this opens up another question when dealing with multiple helm charts. Would an application need to install them in different namespaces or should we always install them in the same namespace? It seems like putting them all in the same namespace would be ideal.

• The first example has device_id instead of deviceId- we should decide on ID vs Id since it is also used with uniqueID. The two should be consistent. I'd vote for deviceId and uniqueId

• With the parameters we should align with what is agreed to from the proposal to update them in the application definition

[phil-abb]

@ajcraig Here's an example that aligns with the latest changes to the application definition and the parameter changes proposal.

I removed the name from the metadata because it didn't seem like this was something that was needed but there might be a good use case for it. I just figured the process was going to be mostly automated so inventing a name, or requiring a customer to give it a name, didn't feel like it would be needed.

I also added the applicationId to be a replacement for the namespacePrefix since one of the ideas for the applicationId is to be able to use it for a namespace prefix.

apiVersion: margo.deployment/v1
kind: ApplicationDeployment
metadata:
    id: 0f83e682-a35b-4533-ae93-ff3810095f31
    applicationId: com-northstarida-digitron-orchestrator
spec:
    deploymentProfile:
      type: helm.v3
      components:
        - name: digitron-orchestrator
          properties:
            repository: oci://northstarida.azurecr.io/charts/northstarida-digitron-orchestrator
            revision: 1.0.9
            wait: true
            timeout: 8m0s
        - name: database-services
           properties:
             repository: oci://quay.io/charts/realtime-database-services
             revision: 2.3.7
    parameters:
      hostname:
        value: edge.host.local
        targets:
          - pointer: edge_host_name
            components: ["digitron-orchestrator"]
          - pointer: global.ingress.host
            components: ["digitron-orchestrator", "database-services"]
      pollFrequency:
        value: 30
        targets: 
          - pointer: settings.pollFrequency
            components: ["digitron-orchestrator"]
      siteId:
        value: d8b64e67-3bc4-4d0b-a3b8-da94b8f36315
        targets:
          - pointer: settings.siteId
            components: ["digitron-orchestrator"]
          - pointer: globals.site.id
            components: ["database-services"]
      cpuLimit:
        value: 3
        targets:
          - pointer: settings.limits.cpu
            components: ["digitron-orchestrator"]
      memoryLimit:
        value: 16384
        targets:
          - pointer: settings.limits.memory
            components: ["digitron-orchestrator"]

[ajcraig]

This Issue is now tied to the following pull request:
#13

[ajcraig]

All work associated to this is now within the linked PR above. Closing issue.