SpecificationMargo Management Interface

Desired State

In order for the Workload Fleet Manager (WFM) to manage workloads on an Edge Compute Device, the device's Workload Fleet Management Client must periodically retrieve its desired workload configuration - referred to as the Desired State - from the WFM.

The Desired State defines what workloads (applications) should run on the device and how they should be configured. It is distributed using a lightweight, pull-based HTTP API that allows devices to stay synchronized with the WFM.

At the center of this process is the State Manifest, a JSON document that lists all workloads assigned to the authenticated client. The manifest is scoped to the client, not to a single device: a client that fronts several devices, such as a see-thru gateway with child devices, retrieves one manifest covering all of them. Each workload is represented by an ApplicationDeployment YAML - a self-contained object defining configuration, components, and parameters for that workload - and names its target device in its metadata.deviceId attribute.

The manifest includes two complementary ways for the client to obtain the same ApplicationDeployment YAMLs:

  • Individual YAMLs - each ApplicationDeployment YAML fetched separately using its own URL.
  • A bundle archive - a single compressed archive containing multiple ApplicationDeployment YAMLs.

Both references describe the same content. The bundle is simply a packaging optimization. This design allows the Workload Fleet Management Client to choose the optimal retrieval strategy depending on network conditions or update size.

Retrieval MethodTypical UseAdvantages
BundleInitial onboarding, large updates, high-latency or high-round-trip networksSingle request with minimal overhead
Individual YAMLsIncremental updates, bandwidth-limited or metered linksOnly changed workloads are downloaded

The Workload Fleet Management Client compares the manifest with its current state and reconciles any differences by deploying, updating, or removing workloads. For every change in deployment state - including installation, updates, removals, and failures - the client MUST report the corresponding status to the WFM using the Deployment Status API.

Endpoints: State Manifest

This section defines the API endpoint used by a client to retrieve the State Manifest from the Workload Fleet Manager, representing the complete desired workload configuration assigned to the client and the devices it is responsible for.

Route and HTTP Methods

GET /api/v1/deployments

Request Headers

HeaderDescription
If-None-Match (optional)The ETag value from the last successfully retrieved manifest.
Accept (optional)The client SHOULD request the manifest in the application/vnd.margo.manifest.v1+json format. If the Accept header lists only unsupported types, the server MUST return 406 Not Acceptable. If omitted, the server MUST return this format by default.

Response Codes

CodeDescription
200 OKThe response body contains the manifest. The server MUST include a valid ETag and Content-Type: application/vnd.margo.manifest.v1+json.
304 Not ModifiedThe response body is empty. Returned if the If-None-Match ETag matches, i.e. the cached response body has not changed since the last retrieved version.
403 ForbiddenThe request is not authorized by the WFM's local policy (for example, the client relationship has been retired; see Authorization).
406 Not AcceptableThe server cannot return a representation matching the Accept header.

Example State Manifest Response

{
  "manifestVersion": 101,
  "bundle": {
    "mediaType": "application/vnd.margo.bundle.v1+tar+gzip",
    "digest": "sha256:b5c6d7e8f9...",
    "url": "/api/v1/bundles/sha256:b5c6d7e8f9..."
  },
  "deployments": [
    {
      "deploymentId": "a3e2f5dc-912e-494f-8395-52cf3769bc06",
      "digest": "sha256:a4e01b2c3d...",
      "url": "/api/v1/deployments/a3e2f5dc-912e-494f-8395-52cf3769bc06/sha256:a4e01b2c3d..."
    }
  ]
}

Response Body Attributes

FieldTypeRequired?Description
manifestVersionnumberYMonotonically increasing unsigned 64-bit integer in the inclusive range [1, 2^64-1]. Each new manifest for the same client MUST have a strictly greater value than the previous, forming a single sequence per client that spans all devices the client is responsible for. The first manifest for a given client MUST use the value 1.
bundleobjectYDescribes an archive containing all referenced ApplicationDeployment YAMLs. If there are zero deployments (i.e., the deployments array is empty), this field MUST be present with the value null. An empty archive MUST NOT be served.
bundle.mediaTypestringYMUST be application/vnd.margo.bundle.v1+tar+gzip, which denotes a gzip-compressed tar archive (commonly delivered as a .tar.gz) whose root contains one or more ApplicationDeployment YAML files. Servers MUST set the HTTP Content-Type to this media type. The archive MUST contain exactly the set of YAML files referenced by deployments.
bundle.digeststringYDigest of the bundle archive. MUST equal the digest computed over the exact sequence of bytes in the bundle endpoint's HTTP 200 OK response body. See Protocol: Digest for further details.
bundle.sizeBytesnumberNOptional unsigned 64-bit advisory estimate of the decoded payload length in bytes for the bundle archive. Provided for bandwidth estimation and update planning. MUST NOT be used for integrity verification.
bundle.urlstringYContent-addressable retrieval endpoint for the bundle of the form /api/v1/bundles/{digest} where {digest} equals bundle.digest.
deploymentsarrayYList of deployment objects describing each workload.
deployments[].deploymentIdstringYThe UUID of the deployment. MUST equal top-level id attribute in the ApplicationDeployment.
deployments[].digeststringYDigest of the corresponding ApplicationDeployment YAML file. MUST equal the digest computed over the exact sequence of bytes in the individual deployment endpoint's HTTP 200 OK response body. See Protocol: Digest for further details.
deployments[].sizeBytesnumberNOptional unsigned 64-bit advisory estimate of the decoded payload length in bytes for the ApplicationDeployment YAML. Provided for bandwidth estimation and update planning. MUST NOT be used for integrity verification.
deployments[].urlstringYContent-addressable retrieval endpoint for the ApplicationDeployment YAML of the form /api/v1/deployments/{deploymentId}/{digest} where {digest} equals deployments[].digest.

Note: The ETag returned from this endpoint is a digest of the entire JSON response body (after serialization). It is independent of bundle.digest and individual deployment digests (deployments[].digest). See ETag and Caching for details.

Client Validation Rules

  • The client MUST verify the digest of every fetched artifact before use.
  • If any digest validation fails, the client MUST abort the update and retain the previous state.
  • The client MUST persist both the last accepted manifestVersion and ETag to prevent rollback across restarts.

Endpoints: Individual Deployment YAML

This section defines the API endpoint used by a client to retrieve a single ApplicationDeployment YAML for incremental synchronization and targeted updates.

Route and HTTP Methods

GET /api/v1/deployments/{deploymentId}/{digest}

Route Parameters

ParameterTypeRequired?Description
{deploymentId}stringYThe UUID of the served ApplicationDeployment YAML. This MUST equal to top-level id attribute in the ApplicationDeployment.
{digest}stringYContent-addressable digest of the served ApplicationDeployment YAML. See Protocol: Digest for further details.

Response Codes

CodeDescription
200 OKThe response body contains the raw ApplicationDeployment YAML (Content-Type: application/yaml). Server MUST set ETag to the quoted digest and MUST return Cache-Control: private, max-age=31536000, immutable (see Protocol: ETag and Caching).
403 ForbiddenThe request is not authorized by the WFM's local policy (for example, the client relationship has been retired; see Authorization).
404 Not FoundThe referenced digest does not exist on the server. 404 Not Found indicates only that this specific digest is unavailable. It MUST NOT be interpreted as a deletion signal by a client; deletion of workloads is determined solely by absence from the state manifest.

Note: Servers MAY apply HTTP Content-Encoding (e.g., gzip, br). The client advertises support via Accept-Encoding. Digests and ETags always refer to the decoded representation (i.e., the exact bytes of the response body after decompressing any HTTP Content-Encoding such as gzip). Servers SHOULD include Vary: Accept-Encoding if compression is used.

Endpoints: Deployment Bundle

This section defines the API endpoint used by a client to retrieve a compressed bundle containing all ApplicationDeployment YAMLs for efficient bulk synchronization.

Route and HTTP Methods

GET /api/v1/bundles/{digest}

Route Parameters

ParameterTypeRequired?Description
{digest}stringYContent-addressable digest of the served bundle archive. See Protocol: Digest for further details.

Response Codes

CodeDescription
200 OKThe bundle was successfully retrieved. The server MUST set Content-Type to the manifest-declared bundle.mediaType, ETag to the quoted digest, and MUST return Cache-Control: private, max-age=31536000, immutable (see Protocol: ETag and Caching).
403 ForbiddenThe request is not authorized by the WFM's local policy (for example, the client relationship has been retired; see Authorization).
404 Not FoundThe referenced digest does not exist on the server. 404 Not Found indicates only that this specific digest is unavailable. It MUST NOT be interpreted as a deletion signal by a client; deletion of workloads is determined solely by absence from the state manifest.

Note: Servers MAY apply Content-Encoding (e.g., gzip, br) and SHOULD include Vary: Accept-Encoding if they do.

Protocol: Digest

All Desired State artifacts - including the manifest, bundle archives, and individual ApplicationDeployment YAMLs - use a canonical digest to ensure content integrity and consistency across client and server implementations.

A digest has the form algorithm:encoded, where both parts are lowercase. Clients and servers MUST NOT add prefixes, suffixes, or whitespace. The required algorithm is sha256, and the encoded portion is a 64-character lowercase hexadecimal string.

  • The digest MUST be computed over the exact bytes of the decoded HTTP response body - that is, after decompressing any HTTP Content-Encoding (for example, gzip or br).
  • No reformatting, re-serialization, or newline normalization is permitted during digest computation.

The resulting digest value is used consistently across all API representations:

  • In JSON responses: "digest": "sha256:a4e01b2c3d..."
  • In URLs: /api/v1/deployments/{deploymentId}/sha256:a4e01b2c3d...
  • In HTTP headers: ETag: "sha256:a4e01b2c3d..."

Clients MUST verify that the digest they compute for every retrieved artifact matches the value provided in the manifest. Any mismatch MUST cause the client to abort the update and preserve the previous state. If a manifest references a digest using an unsupported algorithm, the client MUST treat the manifest as invalid and abort processing.

Example:

sha256:a1b2c3d4e5f67890123456789abcdef0123456789abcdef0123456789abcdef

Note: This API defines the digest format sha256:<hex> (lowercase) for JSON fields, URLs, and ETags. This digest represents content identity, ensuring that each artifact (manifest, bundle, or ApplicationDeployment YAML) can be uniquely verified and referenced within the Desired State API.

By contrast, transport-level authenticity and integrity are provided by mutual TLS as described in the API Requirements and Security Details document. The two operate at different layers of the protocol:

  • The digest in this API defines immutable content identity for artifacts, verifiable independently of how they were transported.
  • Mutual TLS authenticates both parties and protects the messages that carry those artifacts in transit.

Protocol: ETag and Caching

All Desired State endpoints implement standard HTTP caching semantics to optimize synchronization between the Workload Fleet Manager (WFM) and the Workload Fleet Management Client. ETags are used to detect content changes and avoid redundant data transfers. Two caching models are defined: one for the mutable State Manifest, and one for immutable, content-addressable resources such as individual deployments and bundles.

Every response is scoped to the authenticated client, so all Desired State responses are marked Cache-Control: private, which keeps a response in that client's own cache rather than a shared one. Because mTLS carries no Authorization header (whose presence would normally keep a response out of shared caches per RFC 9111 §3.5), servers set this explicitly rather than rely on default cache behavior. Under end-to-end mTLS no shared cache sees these responses at all; the marking matters only where an operator terminates mTLS at a TLS-offloading proxy and cleartext reaches an internal hop (see the MIAF traffic-inspecting proxies rules), where private keeps a cache on that hop from serving one client's response to another.

State Manifest Endpoint

For the State Manifest endpoint, servers use strong ETags as defined in RFC 9110 § 8.8.3.

  • The ETag MUST be a strong validator computed as a digest of the exact serialized JSON response body. The format MUST follow the digest grammar defined in Protocol: Digest: "<algorithm>:<hex-encoded-hash>", for example: "sha256:a4e01b2c3d...".
  • Servers SHOULD serialize JSON deterministically (for example, per RFC 8785) so that logically identical manifests yield identical bytes and therefore identical ETags.
  • Manifest responses MUST be marked Cache-Control: private and MUST NOT be marked immutable (no Cache-Control: immutable or excessively long max-age). Freshness is controlled through periodic polling using If-None-Match revalidation requests.
  • When a client presents an ETag that matches the current manifest, the server MUST respond with 304 Not Modified, omitting the response body.

Content-Addressable Endpoints

For Individual Deployment YAML and Deployment Bundle endpoints, the resources are immutable and uniquely identified by their digest.

  • The ETag MUST equal the quoted digest embedded in the resource’s URL (e.g., ETag: "sha256:a4e01b2c3d..."). This constitutes a strong validator per RFC 9110 § 8.8.3.
  • Servers MUST include Cache-Control: private, max-age=31536000, immutable, enabling long-term caching of immutable artifacts in the client's own cache.
  • If compression is applied, servers SHOULD include Vary: Accept-Encoding to ensure cache correctness across encodings.
  • Clients MAY send If-None-Match when revalidating cached resources; servers MAY return 304 Not Modified if the artifact has not changed.

Deployment Workflow

This section defines the end-to-end workflow followed by a client to retrieve, validate, and reconcile its Desired State with the Workload Fleet Manager.

  • The client polls the WFM for the latest manifest using the last known ETag (if any):

    GET /api/v1/deployments
    • If the manifest is unchanged, the WFM responds with 304 Not Modified.
    • If the manifest has changed (200 OK), the client:
      • Verifies the manifestVersion is strictly greater than the stored version. If not, the update MUST be rejected and SHOULD be logged as a security event. The specific requirements for logging security events are not currently defined and will be addressed in a future version of the specification.
      • Parses the manifest and decides whether to fetch the bundle or individual deployments.
      • Downloads and verifies digests for all referenced ApplicationDeployment YAMLs.
    • The client reconciles its local workloads:
      • Adds or updates workloads that appear in the new manifest.
      • Removes workloads no longer present in the new manifest.
    • For each change in workload state, the client reports progress and results to the WFM using the Deployment Status API.
    • Once reconciliation succeeds, the client MUST durably persist the new manifestVersion and associated ETag for use in the next poll cycle.

Sequence Diagram

ApplicationDeployment YAML Definition

This section defines the structure and YAML schema of an ApplicationDeployment, providing a normative reference for Desired State configuration objects.

Each workload is represented as an ApplicationDeployment YAML file that specifies its components, configuration, and parameters. This resource is delivered via the Desired State API and referenced by id in the Deployment Status API.

id: 
metadata: 
  name: 
  namespace: 
  deviceId: 
spec:
    applicationId:
    deploymentProfile:
        type: 
        components:
            - name: 
              properties:
        deviceConstraints:
          capacityRequirements:
            cpu:
              cores:
              architectures:
            memory:
            storage:
          eligibilityRules:
          - propertySelector:
            matchExpressions:
            - key: 
              operator:
              value:
          - labelSelector:
            matchExpression:
            - key:
              operator:
              value:  
    parameters:
        param:
            value: 
            targets:
                - pointer: 
                  components:[]
AttributeTypeRequired?Description
idstringYThe unique identifier UUID of the deployment specification. Needs to be assigned by the Workload Fleet Manager. When the Workload Fleet Manager changes the content of an existing deployment, the id stays the same and the digest changes. A different id identifies a different deployment.
metadataMetadataYMetadata element specifying characteristics about the application deployment. See the Metadata Attributes section below.
specSpecYSpec element that defines deployment profile and parameters associated with the application deployment. See the Spec Attributes section below.

Metadata Attributes

AttributeTypeRequired?Description
namestringYWhen deploying to Kubernetes, the manifests name. The name is chosen by the Workload Fleet Management vendor and is not displayed anywhere.
namespacestringYWhen deploying to Kubernetes, the namespace the manifest is added under. The namespace is chosen by the Workload Fleet Management vendor.
deviceIdstringYThe id of the device, with hierarchy if applicable, to which the deployment is assigned. To reference a child-device the format is {device-id}[/{device-id}[/...]]. To request the gateway to choose the child-device, use * for the last segment in the hierarchy (i.e. {device-id}[/{device-id}/...]/*). If the gateway is not capable of autonomously selecting a child-device, it MUST send back a deployment status with error 103 - Autonomous placement not supported when * is used.

Spec Attributes

AttributeTypeRequired?Description
applicationIdstringYIt MUST match the associated application description's top-level "id" attribute. It can be used to help create unique identifiers where required, such as namespaces.
deploymentProfileDeploymentProfileYSection that defines deployment details including type and components.
parametersmap[string][Parameter]YDescribes the configured parameters applied via the end-user. Defined as a map where each key is the parameter name matching a parameter defined in the ApplicationDescription (e.g., mysqlDatabase:, greeting:, idpName:, myAppEndpoint:); unrecognized keys are ignored.
x-<unique-name>-extensionsmap[string]interface{}NAllows addition of an arbitrary object (mapping) whose contents suppliers use to provide vendor-specific functionality beyond what is defined in the Margo specification. See the Specification Extensions section below for more details.

DeploymentProfile Attributes

AttributeTypeRequired?Description
typestringYThe type of deployment profile (e.g., helm, compose).
componentsComponentYComponents of the application
deviceConstraintsDeviceConstraintsNDevice constraints specifying the minimum device capabilities and eligibility rules required for the deployment. See the Device Constraints section below.
x-<unique-name>-extensionsmap[string]interface{}NAllows addition of an arbitrary object (mapping) whose contents suppliers use to provide vendor-specific functionality beyond what is defined in the Margo specification. See the Specification Extensions section below for more details.

ComposeDeploymentProfile Attributes

AttributeTypeRequired?Description

DeviceConstraints Attributes

AttributeTypeRequired?Description
capacityRequirementsCapacityRequirementsNMinimum CPU, memory, and storage requirements for the deployment profile. See the Capacity Requirements section below.
eligibilityRules[]EligibilityRuleNOptional rules used to match the deployment with device properties and supplier-defined labels reported in the device capabilities. See the Eligibility Rules section below.

Note: Please see the device constraints section on the Application Description page for details about how to apply device constraint rules.

Device constraints contain a set of rules application suppliers can use to describe device compatibility requirements for their workloads. The device constraints are taken directly from the Application Description and MUST be provided without modification in the Application Deployment if defined in the Application Description.

Device suppliers MAY choose to evaluate the capacity constraints before deploying the workload as a preliminary check or leave it up to their chosen runtime to determine if the device has the required capacity.

Device suppliers MUST evaluate the eligibility rules before deploying the workload.

CapacityRequirements Attributes

AttributeTypeRequired?Description
cpuCPUNCPU element specifying the CPU requirements for the deployment. See the CPU section below.
memorystringNThe minimum amount of memory required. The value is given in binary units (Ki = Kibibytes, Mi = Mebibytes, Gi = Gibibytes).
storagestringNThe minimum amount of storage required. The value is given in binary units (Ki = Kibibytes, Mi = Mebibytes, Gi = Gibibytes, Ti = Tebibytes, Pi = Pebibytes, Ei = Exbibytes).

CPU Attributes

AttributeTypeRequired?Description
coresdoubleYThe required amount of CPU cores. Specified as decimal units of CPU cores (e.g., 0.5 is half a core).
architectures[]CpuArchitectureTypeNThe CPU architectures supported by the deployment. See the CpuArchitectureType definition for all permissible values.

EligibilityRule Attributes

AttributeTypeRequired?Description
propertySelectorSelectorNSelector evaluated against the properties reported in the device capabilities.
labelSelectorSelectorNSelector evaluated against the labels reported in the device capabilities.

Selector Attributes

AttributeTypeRequired?Description
matchExpressions[]MatchExpressionYMatch expressions evaluated against the device's reported capabilities.

MatchExpression Attributes

AttributeTypeRequired?Description
keystringYThe key used to match the device's reported capabilities. For property selectors, this MUST be a JSON Pointer, as defined by RFC 6901, mapping to a specific property. For label selectors, this MUST be the exact label key.
operatorSelectorOperatorYOperator used to evaluate the referenced value. See SelectorOperator for all permissible values.
values[]AnyNValues used by the operator when required for matching expressions. Required for the In, NotIn, Gt, or Lt operator.
itemSelectorSelectorNSelector evaluated against array elements. Required for the ContainsAll or ContainsAny operator.

Component Attributes

AttributeTypeRequired?Description
namestringYThe name of the component.
propertiesComponentPropertiesYComponent deployment properties providing OCI coordinates and behavior settings. See the ComponentProperties section below.
x-<unique-name>-extensionsmap[string]interface{}NAllows addition of an arbitrary object (mapping) whose contents suppliers use to provide vendor-specific functionality beyond what is defined in the Margo specification. See the Specification Extensions section below for more details.

ComposeComponent Attributes

AttributeTypeRequired?Description

Parameter Attributes

AttributeTypeRequired?Description
valuestringYThe value of the parameter.
targetsTargetYThe targets associated with the parameter.

Target Attributes

AttributeTypeRequired?Description
pointerstringYThe pointer indicating the location of the target.
componentsstringYThe components associated with the target.

ComponentProperties Attributes

AttributeTypeRequired?Description
repositorystringYOCI repository URI for the component package (e.g., oci://registry.example.com/org/component-name). MUST be a valid OCI reference using the oci:// scheme.
revisionstringYOCI tag identifying the component version within the repository (e.g., "1.0.0", "2.3.1", "1.0.0-rc1", "1.0.0_build.123"). MUST be a valid SemVer 2.0 string without a leading v. SemVer build metadata separator + MUST be stored as _ because + is not a valid OCI tag character. Implementations comparing this value against a SemVer string MUST convert _ back to + before comparison.
waitbooleanNWhether to wait for component installation to complete before proceeding. For Helm: waits until the release is deployed. For Compose: waits until all containers reach running state. Default is true. Only applies when multiple components are provided.
timeoutstringNMaximum time to wait for component installation to complete. Format is "##m##s" (e.g., "5m0s", "8m30s"). If installation does not complete before timeout, deployment fails.

Enumerations

These enumerations are used as vocabularies for attribute values of the ApplicationDeployment.

CpuArchitectureType

Permissible ValuesDescription
amd64AMD 64-bit architecture.
arm64ARM 64-bit architecture.
armARM 32-bit architecture.

SelectorOperator

Permissible ValuesDescription
InIndicates matching should find a match with at least one specified value.
NotInIndicates matching should not find a match with any specified values.
ExistsIndicates matching should find a match on the specified key.
DoesNotExistIndicates matching should not find a match on the specified key.
GtIndicates matching should find a match if the target value is greater than the specified value.
LtIndicates matching should find a match if the target value is less than the specified value.
ContainsAllIndicates matching should find a match against all itemSelectors.
ContainersAnyIndicates matching should find a match against at least one itemSelector.

Example: Helm Deployment Specification

id: a3e2f5dc-912e-494f-8395-52cf3769bc06
metadata:
    name: com-northstartida-digitron-orchestrator-deployment
    namespace: margo-poc
    deviceId: edge-01
spec:
    applicationId: com-northstartida-digitron-orchestrator
    deploymentProfile:
        type: helm
        components:
            - name: database-services
              properties:
                repository: oci://quay.io/charts/realtime-database-services
                revision: 2.3.7
                timeout: 8m30s
                wait: true
            - name: digitron-orchestrator
              properties:
                repository: oci://northstarida.azurecr.io/charts/northstarida-digitron-orchestrator
                revision: 1.0.9
                wait: true
        deviceConstraints:
          capacityRequirements:
            cpu:
              cores: 1.5
              architectures:
                - amd64
            memory: 1024Mi
            storage: 10Gi
          eligibilityRules:
            - propertySelector:
                matchExpressions:
                  - key: /peripherals
                    operator: ContainsAll
                    itemSelector:
                      matchExpressions:
                        - key: /type
                          operator: In
                          values: ["gpu"]
                        - key: /manufacturer
                          operator: In
                          values: ["NVIDIA"]
                  - key: /interfaces
                    operator: ContainsAll
                    itemSelector:
                      matchExpressions:
                        - key: /type
                          operator: In
                          values: ["ethernet", "bluetooth"]
    parameters:
        adminName:
            value: Some One
            targets:
                - pointer: administrator.name
                  components:
                    - digitron-orchestrator
        adminPrincipalName:
            value: someone@somewhere.com
            targets:
                - pointer: administrator.userPrincipalName
                  components:
                    - digitron-orchestrator
        cpuLimit:
            value: "4"
            targets:
                - pointer: settings.limits.cpu
                  components:
                    - digitron-orchestrator
        idpClientId:
            value: 123-ABC
            targets:
                - pointer: idp.clientId
                  components:
                    - digitron-orchestrator
        idpName:
            value: Azure AD
            targets:
                - pointer: idp.name
                  components:
                    - digitron-orchestrator
        idpProvider:
            value: aad
            targets:
                - pointer: idp.provider
                  components:
                    - digitron-orchestrator
        idpUrl:
            value: https://123-abc.com
            targets:
                - pointer: idp.providerUrl
                  components:
                    - digitron-orchestrator
                - pointer: idp.providerMetadata
                  components:
                    - digitron-orchestrator
        memoryLimit:
            value: "16384"
            targets:
                - pointer: settings.limits.memory
                  components:
                    - digitron-orchestrator
        pollFrequency:
            value: "120"
            targets:
                - pointer: settings.pollFrequency
                  components:
                    - digitron-orchestrator
                    - database-services
        siteId:
            value: SID-123-ABC
            targets:
                - pointer: settings.siteId
                  components:
                    - digitron-orchestrator
                    - database-services

Example: Compose Deployment Specification

id: ad9b614e-8912-45f4-a523-372358765def
metadata:
    name: com-northstartida-digitron-orchestrator-deployment
    namespace: margo-poc
    deviceId: edge-01
spec:
    applicationId: com-northstartida-digitron-orchestrator
    deploymentProfile:
        type: compose
        components:
            - name: digitron-orchestrator-docker
              properties:
                repository: oci://northstarida.azurecr.io/compose/digitron-orchestrator
                revision: "1.0.9"
                wait: true
                timeout: "5m0s"
    parameters:
        adminName:
            value: Some One
            targets:
                - pointer: ADMIN_NAME
                  components:
                    - digitron-orchestrator-docker
        adminPrincipalName:
            value: someone@somewhere.com
            targets:
                - pointer: ADMIN_PRINCIPALNAME
                  components:
                    - digitron-orchestrator-docker
        idpClientId:
            value: 123-ABC
            targets:
                - pointer: IDP_CLIENT_ID
                  components:
                    - digitron-orchestrator-docker
        idpName:
            value: Azure AD
            targets:
                - pointer: IDP_NAME
                  components:
                    - digitron-orchestrator-docker
        idpProvider:
            value: aad
            targets:
                - pointer: IDP_PROVIDER
                  components:
                    - digitron-orchestrator-docker
        idpUrl:
            value: https://123-abc.com
            targets:
                - pointer: IDP_URL
                  components:
                    - digitron-orchestrator-docker
        pollFrequency:
            value: "120"
            targets:
                - pointer: POLL_FREQUENCY
                  components:
                    - digitron-orchestrator-docker
        siteId:
            value: SID-123-ABC
            targets:
                - pointer: SITE_ID
                  components:
                    - digitron-orchestrator-docker

Example: Gateway Directed Deployment Specification

In this example, an application is deployed to a specific child device through a see-thru gateway. The gateway determines the target device for deployment from the value of the deviceId attribute of the ApplicationDeployment specification.

id: ad9b614e-8912-45f4-a523-372358765def
metadata:
    name: com-northstartida-digitron-orchestrator-deployment
    namespace: margo-poc
    deviceId: gateway-01/edge-01
spec:
    applicationId: com-northstartida-digitron-orchestrator
    deploymentProfile:
        type: compose
        components:
            - name: digitron-orchestrator-docker
              properties:
                repository: oci://northstarida.azurecr.io/compose/digitron-orchestrator
                revision: 1.0.9
    parameters:
        adminName:
            value: Some One
            targets:
                - pointer: ADMIN_NAME
                  components:
                    - digitron-orchestrator-docker
        adminPrincipalName:
            value: someone@somewhere.com
            targets:
                - pointer: ADMIN_PRINCIPALNAME
                  components:
                    - digitron-orchestrator-docker
        idpClientId:
            value: 123-ABC
            targets:
                - pointer: IDP_CLIENT_ID
                  components:
                    - digitron-orchestrator-docker
        idpName:
            value: Azure AD
            targets:
                - pointer: IDP_NAME
                  components:
                    - digitron-orchestrator-docker
        idpProvider:
            value: aad
            targets:
                - pointer: IDP_PROVIDER
                  components:
                    - digitron-orchestrator-docker
        idpUrl:
            value: https://123-abc.com
            targets:
                - pointer: IDP_URL
                  components:
                    - digitron-orchestrator-docker
        pollFrequency:
            value: "120"
            targets:
                - pointer: POLL_FREQUENCY
                  components:
                    - digitron-orchestrator-docker
        siteId:
            value: SID-123-ABC
            targets:
                - pointer: SITE_ID
                  components:
                    - digitron-orchestrator-docker

Example: Gateway Autonomous Deployment Specification

In this example, an application is deployed to a child device with the see-thru gateway deciding which device to use. The gateway is told to choose the device by using * in the deviceId attribute of the ApplicationDeployment specification.

id: ad9b614e-8912-45f4-a523-372358765def
metadata:
    name: com-northstartida-digitron-orchestrator-deployment
    namespace: margo-poc
    deviceId: gateway-01/*
spec:
    applicationId: com-northstartida-digitron-orchestrator
    deploymentProfile:
        type: compose
        components:
            - name: digitron-orchestrator-docker
              properties:
                repository: oci://northstarida.azurecr.io/compose/digitron-orchestrator
                revision: 1.0.9
    parameters:
        adminName:
            value: Some One
            targets:
                - pointer: ADMIN_NAME
                  components:
                    - digitron-orchestrator-docker
        adminPrincipalName:
            value: someone@somewhere.com
            targets:
                - pointer: ADMIN_PRINCIPALNAME
                  components:
                    - digitron-orchestrator-docker
        idpClientId:
            value: 123-ABC
            targets:
                - pointer: IDP_CLIENT_ID
                  components:
                    - digitron-orchestrator-docker
        idpName:
            value: Azure AD
            targets:
                - pointer: IDP_NAME
                  components:
                    - digitron-orchestrator-docker
        idpProvider:
            value: aad
            targets:
                - pointer: IDP_PROVIDER
                  components:
                    - digitron-orchestrator-docker
        idpUrl:
            value: https://123-abc.com
            targets:
                - pointer: IDP_URL
                  components:
                    - digitron-orchestrator-docker
        pollFrequency:
            value: "120"
            targets:
                - pointer: POLL_FREQUENCY
                  components:
                    - digitron-orchestrator-docker
        siteId:
            value: SID-123-ABC
            targets:
                - pointer: SITE_ID
                  components:
                    - digitron-orchestrator-docker

Specification Extensions

Note: See the specification extensions page for additional details.

The Application Deployment document supports the following specification extension scenarios:

Collaboration between application and device suppliers

Application suppliers targeting device supplier specification extensions include the required specification extension properties in the application description document. Workload fleet manager service implementations MUST include the specification extension properties defined in the application description in the application deployment document. The specification extensions defined in the application description's deploymentProfile or component objects must be included in the comparable deploymentProfile or component objects in the application deployment document exactly as they are in the application description document.

The device client implementations MUST ignore any unknown specification extensions targeting a device supplier. Importing an application deployment with unknown specification extensions MUST NOT result in a failure because of the included specification extensions.

Collaboration between workload fleet manager and device suppliers

For the workload fleet manager to make use of specification extensions defined by a device supplier, the extension property MUST be added to the Application Deployment yaml document's spec object.

The device client implementations MUST ignore any unknown specification extensions targeting a device supplier. Importing an application deployment with unknown specification extensions MUST NOT result in a failure because of the included specification extensions.

Device Capabilities

Previous Page

Deployment Status

Next Page

On this page

Endpoints: State ManifestRoute and HTTP MethodsRequest HeadersResponse CodesExample State Manifest ResponseResponse Body AttributesClient Validation RulesEndpoints: Individual Deployment YAMLRoute and HTTP MethodsRoute ParametersResponse CodesEndpoints: Deployment BundleRoute and HTTP MethodsRoute ParametersResponse CodesProtocol: DigestProtocol: ETag and CachingState Manifest EndpointContent-Addressable EndpointsDeployment WorkflowSequence DiagramApplicationDeployment YAML DefinitionMetadata AttributesSpec AttributesDeploymentProfile AttributesComposeDeploymentProfile AttributesDeviceConstraints AttributesCapacityRequirements AttributesCPU AttributesEligibilityRule AttributesSelector AttributesMatchExpression AttributesComponent AttributesComposeComponent AttributesParameter AttributesTarget AttributesComponentProperties AttributesEnumerationsCpuArchitectureTypeSelectorOperatorExample: Helm Deployment SpecificationExample: Compose Deployment SpecificationExample: Gateway Directed Deployment SpecificationExample: Gateway Autonomous Deployment SpecificationSpecification ExtensionsCollaboration between application and device suppliersCollaboration between workload fleet manager and device suppliers