Skip to content

App Manifest Registration Guide v1

As of: March 31, 2026

Purpose

Define how app onboarding and version registration should work for GPUaaS platform apps, while clearly separating: - what is implemented now, - what is still directional, - and what an app team should prepare in its manifest package today.

This document exists because app developers need more than runtime APIs. They also need a clear answer to: 1. how a new app becomes known to the platform, 2. how a new app version is described, 3. how artifacts and version metadata are linked, 4. which parts are self-service today versus platform-admin-assisted, 5. how this should evolve toward a cleaner third-party onboarding model.

Use this with: - doc/architecture/App_Developer_Starter_Pack_v1.md - doc/architecture/Build_an_App_for_GPUaaS_v1.md - doc/architecture/App_Runtime_External_Worker_Contract_v1.md - doc/architecture/App_Control_Plane_v1.md - doc/architecture/App_Artifact_Trust_and_Promotion_v1.md - doc/architecture/App_Non_OCI_Artifact_Lifecycle_v1.md - doc/api/openapi.draft.yaml

Decision Summary

  1. The long-term onboarding model should be manifest-driven.
  2. The public contract for runtime operation and the public contract for app registration are related but distinct.
  3. Today the platform has real app/version metadata and artifact APIs, but not a fully productized third-party manifest registration workflow yet.
  4. App teams should still prepare their app and version metadata as if manifest registration is the target contract.
  5. First-party seed data and internal reference apps should converge toward the same manifest shape over time rather than remain one-off rows forever.

Current State vs Target State

Current implemented state

Today the platform has: - app catalog records - app version records with a manifest jsonb field - published version listing - project entitlement APIs - app artifact publish/register/promote/verify/revoke/deprecate/retire APIs

Today the platform does not yet have a fully productized public flow for: - register app by manifest - register app version by manifest - schema-backed third-party app onboarding without platform-admin or seed assistance

Target state

The target onboarding model should be:

  1. app team prepares an app manifest package
  2. platform validates it
  3. platform registers app metadata and one or more versions
  4. platform links artifact references and runtime metadata
  5. platform admin publishes/approves the version
  6. tenant/project admins grant entitlements

Why Manifest-Driven Registration

The platform already stores version metadata in a manifest-shaped field.

Moving to an explicit manifest model would: - reduce ad hoc seed-only app registration - let app teams describe input schemas without platform-core code changes - make app version review and approval auditable - create a stable packaging story for internal and external apps - align runtime docs, UI metadata, artifact metadata, and SDK generation around one source package

What A Manifest Package Should Describe

At minimum, an app manifest package should cover two layers.

1. App-level metadata

This is stable across versions.

Examples: - slug - display_name - description - category - runtime_backend - supported operating modes - supported control-plane scopes - whether the app can run in project-scoped, tenant-shared, or future platform-managed mode - whether the app uses metadata-only UI or custom UI extension behavior

2. Version-level metadata

This is version-specific.

Examples: - version - runtime backend - version status - manifest body - expected artifact set - runtime bootstrap expectations - placement/config schema references - required credential classes - supported topology notes

The exact final schema is still design work, but an app team should think in terms like:

app:
  slug: slurm-reference
  display_name: Slurm Reference
  runtime_backend: slurm
  supported_modes:
    operating_modes: [tenant_dedicated]
    control_plane_scopes: [project, tenant]

version:
  version: 24.05.0
  runtime_backend: slurm
  placement_schema:
    type: object
    properties:
      controller_allocation_ids:
        type: array
        items: { type: string }
  config_schema:
    type: object
  runtime_requirements:
    bootstrap_access_credential: ssh_key
    operator_identity: service_account
  external_worker_contract:
    delivery: polling
    root:
      component_key: controller
      allocation_id_key: controller_allocation_id
      requested_phase: controller_requested
      bound_phase: controller_allocation_bound
    child_operation:
      component_key: worker
      allocation_ids_key: worker_allocation_ids
  artifacts:
    - name: runtime
      artifact_kind: oci
      source_type: oci_registry
      repository: apps/slurm-reference/runtime

This is an example direction, not a final enforced schema.

How This Maps To Current Platform Objects

Even before full manifest registration exists, the conceptual mapping is already visible in the current model:

  • app catalog entry -> app-level metadata
  • app version row -> version metadata + manifest
  • project app artifact records -> artifact registration and trust lifecycle
  • app UI extension metadata -> deploy/runtime UI behavior

That means the platform is not missing all the pieces. It is missing the consolidated onboarding workflow.

Current App-Team Path

If an app team needs to onboard today, the realistic path is:

  1. define app and version metadata in a manifest document under source control
  2. define the runtime contract and placement/config expectations in that document
  3. publish and register artifacts through the existing app-artifact APIs where appropriate
  4. coordinate initial app/version registration through current platform-admin or reference-app paths
  5. use entitlement and app-instance/shared-runtime APIs as the runtime-facing public surface

This is not yet a perfect self-service story, but it is the cleanest current operating model.

Artifact Registration Relationship

Manifest registration and artifact registration are related but not the same thing.

Manifest registration answers:

  • what is this app
  • what is this version
  • what backend does it use
  • what placement/config/credential model does it expect

Artifact registration answers:

  • where is the versioned runtime artifact stored
  • what digest is trusted
  • what lifecycle state and trust state apply

App teams should not treat artifact registration alone as complete app onboarding.

UI And Schema Relationship

The app manifest direction should eventually feed: - deploy-form validation - metadata-driven UI rendering - CLI and SDK validation help - runtime worker packaging guidance

This is especially important because the platform already stores: - placement_intent - config - version manifest

The missing layer is declaring and validating the schemas in a reusable onboarding contract.

What Is Implemented Enough To Use Now

An app team can rely on these today: - app catalog listing and version listing - project entitlements - app instance lifecycle APIs - tenant-shared runtime APIs - app artifact APIs - SDK and CLI support for runtime control-plane operations

An app team should not assume these are finished self-service products yet: - manifest registration API - schema-driven external app onboarding workflow - app package upload and publish from one manifest file

Review Checklist For An App Manifest Package

Before onboarding an app, the package should answer:

  1. What is the app slug and runtime backend?
  2. Which operating modes and scopes are supported?
  3. What is the placement input shape?
  4. What is the config input shape?
  5. Which credentials are required?
  6. Which artifacts are expected and how are they delivered?
  7. Does the runtime use project-scoped instances, tenant-shared runtimes, or both?
  8. Does the UI rely on metadata-only shell behavior or a custom UI extension?
  9. What should be considered published versus only available for internal testing?
  10. If the app uses an external worker, what root component and child operation contract should the worker poll and report through?

Current Recommendation

For now, every app team should keep a versioned app manifest document in source control even before the full registration API exists.

That gives the platform a clean migration path: - current admin-assisted onboarding can consume the same manifest package - later self-service onboarding can validate the same package

What Still Needs To Be Built

The next real product steps are:

  1. define the canonical manifest schema
  2. define the app and version registration endpoints or import workflow
  3. define schema validation rules for placement/config sections
  4. link manifest registration cleanly with artifact registration and version publish flow
  5. decide how first-party seed data converges toward the same package format

Until those are complete, this guide should be read as: - the expected onboarding contract direction, - plus the cleanest current operating model, not: - a claim that third-party self-service app registration is fully shipped already.