Skip to content

App Tenant-Shared Runtime API Direction v1

Purpose

Define the first additive API direction for tenant-owned shared app runtimes and their attached consumer projects before changing openapi.draft.yaml.

This document sits between: - the product model in doc/architecture/App_Tenant_Shared_Attachment_Model_v1.md, - and the future contract/code implementation work tracked in A-TENANT-SHARED-RUNTIME-ATTACHMENT-CONTRACT-001.

Current State

The current public app control plane is still intentionally project-owned:

  1. app instances live under /api/v1/projects/{project_id}/...,
  2. service accounts are project-scoped,
  3. app controller placement and credentials are project-scoped,
  4. this is the correct baseline for project-scoped mode.

That means tenant-owned shared mode is not yet an API contract, even though the product language now exists.

Decision Summary

Tenant-owned shared mode should be added as a new additive control-plane layer.

Do not: 1. overload one project-owned app_instance to mean tenant ownership, 2. pretend one project path can describe multi-project attachment state, 3. reuse project-scoped machine identity as if it were tenant-scoped.

Do: 1. keep project-scoped app-instance APIs intact, 2. add a tenant-owned shared-runtime resource family, 3. add explicit attachment resources for consumer projects, 4. preserve project attribution for workload usage and audit.

Resource Model Direction

1. Shared runtime

New tenant-scoped control-plane resource representing the shared runtime owner.

Directionally: - one per tenant environment for the first narrow product shape, - tenant-owned lifecycle, - app-specific runtime config and status, - runtime control-plane metadata.

Suggested logical fields: 1. id 2. resource_name 3. org_id 4. app_slug 5. app_version 6. display_name 7. operating_mode = tenant_dedicated 8. control_plane_scope = tenant 9. runtime_backend 10. status 11. operator_service_account_id or successor tenant-scoped machine identity 12. placement_intent 13. config 14. created_at 15. updated_at

2. Shared runtime attachment

New tenant-scoped resource describing one attached consumer project.

Suggested logical fields: 1. id 2. shared_runtime_id 3. org_id 4. project_id 5. status 6. contribution_policy 7. submission_policy 8. billing_policy_ref 9. created_at 10. updated_at

3. Optional project-local consumer view

This is optional and should only exist if UX really needs a project-local object for discovery or delegation.

If added later, it must be explicitly modeled as a consumer projection, not as the owner object.

Path Direction

The likely path family should be tenant-scoped.

Directionally: 1. GET /api/v1/orgs/{org_id}/shared-app-runtimes 2. POST /api/v1/orgs/{org_id}/shared-app-runtimes 3. GET /api/v1/orgs/{org_id}/shared-app-runtimes/{shared_runtime_id} 4. DELETE /api/v1/orgs/{org_id}/shared-app-runtimes/{shared_runtime_id} 5. GET /api/v1/orgs/{org_id}/shared-app-runtimes/{shared_runtime_id}/attachments 6. POST /api/v1/orgs/{org_id}/shared-app-runtimes/{shared_runtime_id}/attachments 7. GET /api/v1/orgs/{org_id}/shared-app-runtimes/{shared_runtime_id}/attachments/{attachment_id} 8. DELETE /api/v1/orgs/{org_id}/shared-app-runtimes/{shared_runtime_id}/attachments/{attachment_id}

These names are directional, not final.

The key requirement is: - tenant-owned resources should live at a tenant-scoped path, - consumer attachment should not be tunneled through one project path.

Request Direction

Create shared runtime

Should include: 1. app_slug 2. app_version 3. display_name 4. operator_identity_ref 5. placement_intent 6. config 7. optional initial attached_project_ids

Attach project

Should include: 1. project_id 2. contribution policy for worker allocations 3. submission policy 4. optional project-specific app-owned policy metadata

Authorization Direction

Shared runtime owner actions

Tenant-scoped permissions should govern: 1. create/delete shared runtime 2. view shared runtime 3. attach/detach projects 4. modify tenant-shared placement and policy

Consumer project actions

Project-scoped permissions should still govern: 1. view project-local access to the runtime 2. submit project-owned work where policy allows 3. contribute project-owned allocations where policy allows

App controller actions

The controller must authenticate with delegated shared-runtime operator identity for the tenant-owned runtime.

This is intentionally blocked on the follow-on identity contract.

Placement Direction

Shared-runtime placement should not blur controller and worker sources.

The contract should be able to express: 1. tenant-owned controller placement, 2. project-contributed worker allocations, 3. policy about whether attached projects may contribute worker capacity, 4. visibility of source project for each worker contribution.

That implies tenant-aware allocation read surfaces and attachment-aware policy checks.

Billing Direction

The contract should preserve two separate anchors:

  1. shared runtime ownership
  2. project workload attribution

The API does not need to solve pricing in this slice, but it must make later billing reconstruction possible.

Minimum expectation: 1. shared runtime has tenant ownership context, 2. attachments identify consumer projects, 3. workload and capacity usage can still resolve to project attribution.

Event Direction

The first event family should likely include: 1. apps.shared_runtime.requested 2. apps.shared_runtime.running 3. apps.shared_runtime.failed 4. apps.shared_runtime.deleting 5. apps.shared_runtime.deleted 6. apps.shared_runtime.attachment.requested 7. apps.shared_runtime.attachment.attached 8. apps.shared_runtime.attachment.failed 9. apps.shared_runtime.attachment.detached

This is directional only; event additions should follow the normal AsyncAPI process once the REST contract is chosen.

Migration Rule

When this work moves into openapi.draft.yaml, keep the change additive:

  1. do not break project-scoped app-instance endpoints,
  2. do not retroactively reinterpret one project-owned app instance as tenant-owned,
  3. do not require apps that only support project scope to adopt the new model,
  4. do not force scheduler-specific semantics into generic app control-plane paths.

Current contract progress: 1. shared-runtime and attachment schemas are now reserved in doc/api/openapi.draft.yaml 2. tenant-scoped path family is now reserved in doc/api/openapi.draft.yaml 3. delegated shared-runtime operator auth model is now implemented 4. shared worker and worker-operation resource family is the next additive contract slice

  1. finalize the shared-runtime and attachment resource naming,
  2. define the delegated shared-runtime operator identity model,
  3. add the OpenAPI resource family,
  4. add schema/ERD direction,
  5. then implement service/handler/runtime code.
  1. doc/architecture/App_Tenant_Shared_Attachment_Model_v1.md
  2. doc/architecture/Shared_Runtime_Worker_Topology_v1.md
  3. doc/architecture/App_Control_Plane_v1.md
  4. doc/architecture/App_Runtime_Operating_Modes_v1.md
  5. doc/architecture/App_Runtime_Billing_Model_v1.md
  6. doc/architecture/Slurm_Tenant_Scope_Semantics_v1.md
  7. doc/architecture/Tenant_Scoped_App_Machine_Identity_v1.md