Skip to content

feat(lifecycle): expose confirmed pool allocation summary #1479

Description

@cwj2001

Problem

The lifecycle API accepts extensions.poolRef, but GET /sandboxes/{id} currently does not expose whether the Kubernetes Pool controller actually confirmed a Pool allocation. The request value is intent rather than proof, especially for poolRef: "*" auto-assignment.

This prevents HTTP-only control planes and platform operators from distinguishing a confirmed Pool allocation from an unconfirmed or pending state without Kubernetes RBAC or parsing controller-internal annotations.

Proposal

Add an optional, additive allocation summary to the existing lifecycle Sandbox response:

{
  "allocation": {
    "mode": "pool",
    "poolRef": "example-pool",
    "state": "allocated"
  }
}

The Server should emit it only when its Kubernetes runtime can confirm the current Pool allocation from its internal workload/controller state. Omit it for direct sandboxes, unsupported providers, pending or inconsistent allocation, release/deletion, or otherwise unconfirmed state. Absence must not be interpreted as cold-create, pending, or unsupported.

The summary intentionally excludes Pod names, namespace, node/IP/UID, raw annotations/finalizers, allocation history, and requested Pool reference. It is not a new endpoint, does not change CreateSandbox response, CRDs, or controller behavior.

Reusable users

  • HTTP-only Gateways/control planes that deliberately have no Kubernetes RBAC.
  • poolRef: "*" callers that need the effective Pool once allocation is confirmed.
  • Self-hosted platform operators diagnosing capacity/allocation failures.
  • Performance/regression tooling that must distinguish confirmed warm-pool allocation from non-evidence.

Compatibility

Optional response-only field; existing clients can ignore it. The implementation should update the lifecycle OpenAPI source, Server mapper/tests, and affected generated SDKs.

I plan to submit a minimal implementation PR if maintainers agree this belongs in the lifecycle resource contract.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions