RFC: A package format for Helm media functions

[znerol2]

Summary

dmfdeploy is an independent, open prototype of a Dynamic Media Facility. It proves its claims with conformance checks against published specifications and shares what it learns upstream as evidence. It does not call itself a reference.

This RFC proposes the Helm Media Function Package v1. It is one ordinary Helm chart plus one adjacent descriptor file, dmf-function.yaml. A conformance tool checks both with JSON Schema and a set of deliberately broken fixtures. The proposal is a scoped implementation of ADR-0047. It adds no actuator, no operator and no new control plane.

Tracking issues: #634 (schema and tool), #635 (MXL port binding), #636 (wrapping step), #637 (existing charts).

The problem

Today a Helm chart, a catalog YAML file and a launcher are joined by a key string. Versions, image references and MXL facts can drift apart. The console rejects only a malformed EBU classification. CI checks that demand matches for one chart.

ADR-0047 already defines the unit of contribution: catalog metadata, a Helm chart and an image closure. The IS-05 work (see the companion RFC) also needs NMOS and MXL facts in a machine-readable form. Today those facts live in prose and in launcher code.

The closest public manifest is AMWA's IN-003, which is still a draft: its repository has no release or tag. Its manifest schema describes resources and media inputs and outputs. It has no field for an image digest, a publisher, a source commit or a signature, so it can't carry artifact identity or trust on its own.

Proposed decision

A package is a directory packages/<key>/ with one Helm chart (Chart.yaml apiVersion: v2) and one dmf-function.yaml. The package version equals Chart.yaml version. The package holds no launcher code.

Trust comes first

• The project-controlled, versioned catalog-source index is the first deliverable, as ADR-0047 requires.
• An ingestion record keyed by publisher, package key, version and artifact digest points to the descriptor. The descriptor is a signed member of the release closure.
• Source class, launcher privilege, promotion state and revocation come from the index and the record. A package cannot assert them. The conformance tool rejects a descriptor that tries.
• Every release is an ADR-0047 closure: the OCI chart digest, every rendered workload image pinned by digest, signatures, and revocation state. Charts supply values.schema.json. Values may not turn digest-pinned images or declared resources into free-form overrides.

What the descriptor holds

• Identity and origin. apiVersion: dmf.io/v1, kind: MediaFunction, key, version, display name, summary, publisher, source commit, provenance URI, and a licence field. The licence may say "declared, not enforced" but is never absent.
• Classification. EBU layer and lifecycle owner, plus exactly one of vertical or media_function_type, using the ADR-0046 enums.
• Artifacts. The chart name, version and digest, and each image's name, digest and architectures.
• Resources. CPU and memory requests for each named render fixture. Every workload container has them.
• Ports. One list of {name, direction, control, transport, format}. Formats and transports use NMOS Parameter Register URNs. For MXL that is urn:x-nmos:transport:mxl from BCP-007-03. A receiver may carry BCP-004-01 style constraint sets.
• NMOS nodes. A list, possibly empty, with roles and the IS-04 and IS-05 endpoints it exposes.
• MXL binding policy. Each MXL port declares a role and one policy: runtime-assigned, topology-supplied or fixed-singleton. A concrete flow UUID appears only under fixed-singleton. Resolved IDs belong to the instance overlay (ADR-0046), not the package.
• Lifecycle and dependencies. Provision, health, monitoring, finalise, and typed provides and consumes references.
• Optional. Ingress, topology reference, placement, clock quality, documentation links, and a namespaced extension block. An extension cannot weaken generic policy.
• Generated, not written. Chart annotations for chart indexes come from the descriptor, so there is one source. An optional IN-003 resourceManifest is also generated from the descriptor and checked by the conformance run. The Helm requests that fixtures verify stay authoritative.

Package keys are unique per publisher. The names dmf-* and project-* are reserved for the project source.

Validation

dmf-function-conform packages/<key> does the following:

• Checks the descriptor and the chart values against JSON Schema.
• Runs helm lint --strict.
• Renders the named fixtures and compares identity, labels, digest-pinned images, ports and NMOS and MXL declarations.
• Sums resources across init containers and pod overhead.

The resolved instance overlay is validated separately, including that MXL bindings resolve to distinct IDs. One required fixture deploys two instances of a function into one MXL domain, checks that they get distinct flow IDs, and then runs a receiver A/B IS-05 switch.

Bad fixtures fail on purpose:

• a self-asserted source class or launcher mode
• missing provenance
• stale or missing revocation
• a bespoke launcher from a non-project source
• an extension block that weakens generic policy
• a package-key collision

CI in dmf-media runs the tool for every package. It generalises the existing check-catalog-demand.py.

Order of work

Write the JSON Schemas, the conformance tool and the bad fixtures first. Code for #634 to #637 follows. The chart hygiene of the public mxl-k8s project is a model for the validation target only: values.schema.json, digest-pinned images and native multi-arch builds.

Contribution and migration

Likely third-party packages arrive as an image plus a manifest, not as a chart. So conformance needs a wrapping step (#636): a contributor wraps the image and manifest into a chart plus a descriptor, then submits it through an ADR-0047 catalog source. The package is browse-only until promotion and generic-launcher policy allow deployment. No contributor receives AWX code authority.

The existing dmf-media charts move first: mxl-fabrics-demo (high effort: split topology, resource gate, MXL ports), nmos-cpp and nmos-crosspoint (medium effort each) (#637).

Alternatives considered

• Chart annotations as the catalog. Annotations are strings. Structured NMOS and MXL validation and references become awkward.
• The Open Application Model (OAM). Its implementations add a CUE and controller control plane beside the committed AWX actuator.
• The Score specification. Its abstraction leaves out placement, host networking, devices and lifecycle, which media functions need.
• Telecom network-function packages. They duplicate Helm descriptors and bring orchestration machinery that does not fit a small AWX and NetBox stack.
• A CRD or operator. It adds cluster machinery, which ADR-0047 forbids on the generic path.

Consequences

• A function's definition and chart travel together. The privileged execution seam stays separate.
• The format builds on Helm, OCI and JSON Schema, which many people already know, and on the ADR-0047 trust model.
• The cost is a catalog assembly and conformance tool, full schema validation in the console, stricter release discipline and more fixtures to maintain.
• The format does not solve runtime truth, scheduling of specialised hardware, or automatic NMOS registration.
• Mapping to IN-003 carries risk: the draft is early and may change, so we map to it now and revisit adopting it when AMWA publishes a release. We do not fork it.

What would prove this wrong

• A real third-party image-plus-manifest repository cannot be wrapped into a conformant package without custom code.
• The descriptor and the chart drift anyway, because the conformance tool does not catch the drift that matters. We test this by changing a chart and checking that a bad fixture fails.
• Two instances of one function cannot get distinct flow IDs from the binding policy.
• The signed-closure requirement blocks legitimate contributors more than it blocks bad packages.
• AMWA publishes a release of IN-003 that covers artifacts and trust. Then we would adopt it and wrap it, not extend our own.

Questions for discussion

1. Which NMOS declarations are contract only, and which are assertions the tool verifies against observed IS-04 and IS-05 state?
2. How should the generic chart policy grow to allow justified host networking, hugepages, RDMA and clock devices without weakening isolation for third-party packages?
3. Should the package version always equal the chart version, or should a signed metadata revision be possible without a new chart release?
4. Who owns the shared status-sidecar contract, and how does a function with two charts map to one package?
5. Is mapping to the IN-003 draft the right level of alignment today, or should we wait for a release?
6. Are there public media-function packages we should test the wrapping step against?

How this gets decided

Discussion here shapes the format. When it converges, an ADR records it as a scoped implementation of ADR-0047, following the RFC to ADR path. Related: ADR-0045, ADR-0046.

[znerol2]

Decision recorded for the first deliverable of this RFC, dmfdeploy/dmf-media#38 (the descriptor schema and conformance tool):

• The descriptor's apiVersion is dmfdeploy.io/v1alpha1. The project controls dmfdeploy.io, and v1alpha1 keeps the format free to change while AMWA IN-003 is a draft.
• The descriptor stays dmfdeploy's own format. It aligns with IN-003 by field name and through a generated, validated export. It never copies IN-003 text or schema. The plan for staying compatible as IN-003 evolves is Keep the media function descriptor compatible with AMWA IN-003 as it evolves #746.
• feat: backlog-hygiene drift detector + weekly schedule (WP6) #38 leaves hold and goes through normal review.

Further comments on the package format stay welcome here; anything that changes the schema lands as a follow-up PR.

[znerol2]

Decision update for the package descriptor, tracked in #746. This changes the earlier note that the descriptor stays dmfdeploy's own format.

• AMWA IN-003 field names are authoritative. The descriptor is a superset of IN-003. Where a descriptor field means the same as an IN-003 field, the descriptor uses the IN-003 name and shape.
• Fields that only dmfdeploy needs, such as artefact identity, provenance and revocation, are additions. They are never renamed IN-003 fields.
• The optional IN-003 manifest export stays. A test checks the export against a pinned IN-003 commit. dmfdeploy never copies or adapts IN-003 text or schema.

This answers question 5 for now: align by name and shape today, and keep checking the draft as it changes. Renames of existing descriptor fields are a schema change, so we plan to batch them in one change before any package exists (#637).