Add a New App designed
This is the practical onboarding path for a new app team. It answers two questions directly:
- how the App SDK path is structured;
- what must exist before a new app is real in GPUaaS.
The App SDK Structure
The App SDK is not one library. It is the combined developer contract:
| Layer | What it contains |
|---|---|
| API and event contracts | OpenAPI, AsyncAPI, generated clients, auth and error shapes |
| App manifest contract | App metadata, version metadata, launch/connect/decommission intent |
| Artifact contract | Trusted runtime images and promoted artifacts |
| Control-plane resources | Catalog, entitlement, app instance, shared runtime, operation records |
| Validation and smoke | Manifest validation, launch/connect/decommission smoke, evidence capture |
| Portal and examples | Developer onboarding, quickstart, reference examples, lifecycle explanations |
What GPUaaS Owns vs What The App Team Owns
| GPUaaS owns | App team owns |
|---|---|
| Identity, tenancy, project hierarchy, service-account path | Runtime-specific controller logic |
| Catalog, entitlement, app instance lifecycle | Runtime bootstrap, reconcile, health, and recovery behavior |
| Artifact trust, audit, billing attribution, evidence shape | App-specific operational semantics |
| Shared shell, public contracts, route and access model | App manifest quality and release discipline |
Add-a-New-App Sequence
Step-by-Step
1. Decide the runtime shape
Answer these first:
- single-image workload or curated multi-service runtime;
- project-scoped, tenant-shared, or future platform-managed control plane;
- browser app, API app, or both;
- whether the app needs a long-running external worker.
2. Define the manifest
The manifest is the app contract. It should describe:
- app and version identity;
- launch parameters and validation;
- endpoint types and connect actions;
- runtime backend and profile shape;
- artifact references;
- health and lifecycle expectations.
3. Build and register the artifact
An app is not launchable until its artifact path is explicit:
- immutable OCI image or approved artifact type;
- digest or equivalent immutable identity;
- trust and promotion metadata;
- release notes and expected runtime profile.
4. Set up machine identity
If the app needs automation or runtime control-plane calls:
- create a scoped service account;
- grant only required scopes;
- make the credential rotation and audit path explicit;
- do not use human credentials for runtime automation.
5. Register the app and version
At this point the app must be visible as platform data:
- catalog entry exists;
- version entry exists;
- manifest is attached;
- artifact references are valid;
- ownership and support fields are known.
6. Grant entitlement
The app still should not appear to arbitrary users.
- project or tenant entitlement decides visibility;
- this is the product access boundary;
- launch should fail closed if entitlement is absent.
7. Launch, connect, and decommission
The first complete proof is not “the manifest looks good.” It is:
- launch succeeds through public contracts;
- connect or open action works through the intended route family;
- decommission cleans up correctly;
- status, audit, and billing attribution surfaces update correctly.
New-App Readiness Checklist
| Area | Ready when |
|---|---|
| Manifest | Runtime intent, parameters, endpoints, and lifecycle are explicit |
| Artifact | Immutable artifact exists and trust path is recorded |
| Identity | Service account and scopes are minimal and auditable |
| Catalog | App/version records are registered |
| Entitlement | Intended project or tenant can see and launch the app |
| Runtime | Launch and decommission work through supported contracts |
| Access | Browser/API/terminal path matches intended user flow |
| Evidence | Smoke and promotion evidence are attached |
Where This Usually Fails
Most onboarding failures are not deep runtime bugs. They are missing contract joins:
- manifest does not match runtime assumptions;
- artifact exists but is not trusted or promoted correctly;
- service account scopes are unclear;
- app appears in catalog but cannot actually launch;
- connect action exists but route family or endpoint model is wrong;
- docs explain the architecture but not the operator/developer sequence.
This page exists to keep that failure class out of UAT.
Canonical sources