Skip to content

App Platform OCI Registry Baseline v1

As of: March 9, 2026

Purpose

Define the first-class OCI artifact model for app teams building on GPUaaS.

This baseline answers: 1. where app artifacts live, 2. how teams publish them, 3. how the platform tracks lifecycle state, 4. how later Vault, DNS, and trust work attach to the model.

Scope

In scope: 1. platform-owned OCI registry model, 2. repository and namespace ownership rules, 3. publish-intent and artifact-registration contract direction, 4. lifecycle states for publish, promote, deprecate, retire, 5. tenant/project extension path.

Out of scope: 1. non-OCI artifact implementation, 2. final registry product selection and HA deployment, 3. artifact signing enforcement, 4. full secret-delivery implementation.

Core Model

The platform API does not proxy image upload bytes.

Instead: 1. app teams obtain a short-lived publish intent from the control plane, 2. the image is pushed directly to the platform registry, 3. the pushed digest is registered back with the control plane, 4. later lifecycle actions operate on the registered digest metadata.

This keeps the API responsible for: 1. ownership, 2. policy, 3. audit, 4. lifecycle, 5. digest truth.

The registry remains responsible for: 1. blob storage, 2. upload protocol, 3. pull distribution.

This baseline also implies the same division for pull behavior: 1. the control plane should issue pull intents and credentials, 2. the registry should remain the default byte-serving path for artifact pulls, 3. convenience API download proxies should be limited to small platform-owned release artifacts where developer UX outweighs direct-registry requirements.

Ownership and Namespace Baseline

Platform-owned root

The first shipped model is a platform-owned registry root.

Example shape: 1. registry.<env-domain>/gpuaas/apps/...

Repository visibility classes

The contract reserves three visibility classes: 1. platform 2. tenant 3. project

Initial default: 1. platform-owned registry endpoint, 2. project-owned repositories under that registry, 3. future tenant/project private extensions without changing the API shape.

Naming rules

Repository names must be deterministic and safe for policy/audit: 1. gpuaas/apps/<project-slug>/<app-slug> 2. or another platform-owned canonical form with equivalent stability.

The control plane, not the app team, defines the canonical repository path returned in publish intents.

Digest and Lifecycle Rules

Digest is the deployment truth

  1. Tags are convenience labels only.
  2. Every deployable artifact must be referenced by immutable digest.
  3. Runtime consumers must never deploy by mutable tag alone.

Artifact lifecycle states

The control plane tracks metadata states: 1. published 2. promoted 3. deprecated 4. retired

Meaning: 1. published - digest registered and available for use, - no environment promotion claim yet. 2. promoted - digest promoted for a named environment or channel. 3. deprecated - no new use should be created from this artifact. 4. retired - artifact remains auditable but is not eligible for new lifecycle actions.

API Baseline

The public API must expose: 1. registry information for app teams, 2. project artifact inventory, 3. publish intent issuance, 4. artifact registration, 5. lifecycle transitions.

Canonical draft endpoints are reserved in doc/api/openapi.draft.yaml.

Publish intent pattern

Publish intent exists because the actual push happens out-of-band to the registry.

The publish-intent response should provide: 1. canonical repository path, 2. allowed tag hint if tags are used, 3. expected digest requirement, 4. publish credential reference or later credential delivery path, 5. expiry for the intent.

Registration pattern

After push, the app team registers: 1. repository, 2. digest, 3. optional tag, 4. OCI media type, 5. source metadata.

The control plane then records the artifact as a project-owned app artifact.

Pull intent pattern

Pull intent is the missing symmetric primitive for registry-backed distribution.

The pull-intent response should provide: 1. canonical repository path, 2. immutable digest or versioned ref information, 3. credential delivery mode, 4. wrapped credential material or equivalent reference, 5. expiry for the pull authorization, 6. enough metadata for ORAS or equivalent clients to pull without guessing registry paths.

The same pattern should apply to: 1. platform release artifacts, 2. project app artifacts.

This keeps: 1. API = ownership, policy, audit, credential issuance, 2. registry = byte transport.

Platform release catalog and download note

Small developer-facing platform artifacts need an additional control-plane read surface beyond raw registry refs.

The control plane should expose: 1. platform release catalog/discovery metadata, 2. per-version artifact manifests, 3. convenience download endpoints for developer-facing artifacts such as CLI and SDK bundles.

Current implementation status: 1. the platform release catalog/discovery API is implemented, 2. the per-version platform release manifest API is implemented, 3. convenience download endpoints are implemented for platform release artifacts, 4. generalized pull-intent APIs remain follow-on work for registry-native pull flows.

It should not rely on frontend env vars or hardcoded oras pull snippets as the product UX.

IAM Baseline

Human admins

Human project/tenant admins: 1. create repository/publish intents, 2. view project artifacts, 3. deprecate or retire artifacts, 4. manage entitlements and app versions.

Service accounts

Project-scoped operator service accounts may: 1. request publish intents, 2. register published digests, 3. read same-project artifact metadata, 4. promote artifacts only where policy allows.

They must not: 1. write outside the same project, 2. bypass digest-only rules, 3. bypass artifact-source allowlists.

Billing and Audit Baseline

Artifact operations are control-plane actions and must be auditable.

Every privileged artifact mutation should record: 1. actor, 2. project, 3. repository, 4. digest, 5. lifecycle action, 6. correlation_id.

Artifact storage billing is reserved for later; this baseline does not define a final pricing model.

Secret and Trust Dependencies

This registry baseline intentionally depends on later work: 1. Vault-backed credential custody, 2. DNS/TLS/control-plane endpoint stability, 3. artifact signing and promotion trust policy.

The canonical trust and promotion baseline is: - doc/architecture/App_Artifact_Trust_and_Promotion_v1.md

The canonical non-OCI artifact baseline is: - doc/architecture/App_Non_OCI_Artifact_Lifecycle_v1.md

This baseline must not block those tasks by hardcoding: 1. a single registry hostname forever, 2. a single global shared repository path forever, 3. static long-lived robot credentials in app config.

  1. OCI registry baseline
  2. Vault-backed secrets
  3. DNS/TLS/control-plane endpoint automation
  4. artifact trust and promotion
  5. non-OCI artifact lifecycle
  1. doc/architecture/App_Control_Plane_v1.md
  2. doc/architecture/App_Platform_Quickstart_v1.md
  3. doc/architecture/App_Platform_Gap_Tracker_v1.md
  4. doc/architecture/Node_Operations_and_Agent_Lifecycle_v1.md
  5. doc/architecture/App_Artifact_Trust_and_Promotion_v1.md
  6. doc/architecture/App_Non_OCI_Artifact_Lifecycle_v1.md