POOLS capacity management

Outcome. You can reason about the seller-side capacity layer: what a resource pool is, what the site authority owns instead, how listings reference capacity without leaking infrastructure, and what pool disablement actually does — and validate, apply, inspect, and safely disable a pool definition through the provisioning service's operator API.

Prerequisites

• A seller provisioning service from the Seller quickstart, running at the inspected revision.
• Its X-Admin-Key value when storefront_admin_key is configured.
• curl and jq on the operator host.
• An Ansible playbook path that exists inside the provisioning container.

Environment and authority

The commands on this page target the seller-internal provisioning service at http://<PROVISIONING_HOST>:8081. They mutate seller infrastructure only when you call the explicit import or disable endpoints. Buyers never call this API, and a pool does not participate in Discovery or Negotiation.

The commands are derived from the pool controller and request models at the exact documentation pin — an inspected development API. The pinned repository does not ship a separate released public operator guide for it, and this page is not evidence that a hosted deployment exposes it. Run these commands only against an SCM provisioning service you operate at the documented revision.

POOLS are capacity abstraction, not participation

Resource pools are a seller-side grouping of physical settlement candidates: each pool identifies the provider and the provider-specific configuration used after scheduling selects a resource. Pools route provisioning; they do not participate in the market, express demand, or negotiate. Buyers never see them directly — commercial listings reference a trusted projected pool_id or resource_id, never a vm_host.

Three authorities, kept separate

State	Authority
Capacity offerings and projections used to publish and negotiate	Storefront
Capacity admission, reservation, expiry, versions, and the event feed	Site authority
Pool metadata and provider routing configuration	Resource-pool service

The storefront's projection may be stale; authoritative admission happens at the site authority, which is the serialization point for competing reservations. Storefront capacity pools and provisioning resource pools are distinct concepts — mapping between them is explicit configuration or attributes, never a cross-service foreign key.

Fungible by default, specific by opt-in

The ordinary path is fungible: a seller advertises capacity, admission reserves it, and fulfillment scheduling selects the concrete settlement resource. Exposing one specific resource is a valid opt-in — the seller lists a concrete resource and permits the buyer to constrain placement. Rows use attribute.pool_id (fungible routing) or a projected resource_id (specific), as the seller quickstart shows.

Define pools declaratively

Create pools.yaml. The document is authoritative: it must include the system default pool, and applying it disables enabled pools that are omitted. Provider configuration is validated by the selected provider; the Ansible adapter at this revision accepts playbook_path and optional extra_vars.

pools.yaml

pools:
  - id: default
    label: Default pool
    provider: ansible
    enabled: true
    provider_config:
      playbook_path: /opt/domains/vms/provisioning/iac/ansible/playbooks/single-tenant/vm-operations.yaml
      extra_vars: {}
  - id: gpu-east
    label: GPU east
    provider: ansible
    enabled: true
    policy_tags:
      region: us-east
    provider_config:
      playbook_path: /opt/domains/vms/provisioning/iac/ansible/playbooks/single-tenant/vm-operations.yaml
      extra_vars: {}

Validate before applying

Convert the file into the API's yaml_text request and call the no-write validation endpoint first:

jq -Rs '{yaml_text: .}' pools.yaml > /tmp/arkhai-pools-request.json

curl -sS -X POST \
  -H "X-Admin-Key: <admin_api_key>" \
  -H "Content-Type: application/json" \
  --data-binary @/tmp/arkhai-pools-request.json \
  http://<PROVISIONING_HOST>:8081/api/v1/pools/validate | jq

Expected shape for a valid document that introduces gpu-east:

{
  "valid": true,
  "problems": [],
  "diff": {
    "created": ["gpu-east"],
    "updated": [],
    "disabled": [],
    "unchanged": ["default"]
  }
}

The exact diff depends on existing state. Review created, updated, and especially disabled before continuing.

Apply and verify

Apply the already-reviewed document, then inspect the canonical export:

Warning

Importing mutates seller provisioning state, and the applied document is authoritative: enabled pools omitted from it are disabled for new assignment. Review the validation diff — especially disabled — before running the import.

curl -sS -X POST \
  -H "X-Admin-Key: <admin_api_key>" \
  -H "Content-Type: application/json" \
  --data-binary @/tmp/arkhai-pools-request.json \
  http://<PROVISIONING_HOST>:8081/api/v1/pools/import | jq

curl -sS -H "X-Admin-Key: <admin_api_key>" \
  http://<PROVISIONING_HOST>:8081/api/v1/pools/ | jq

curl -sS -H "X-Admin-Key: <admin_api_key>" \
  http://<PROVISIONING_HOST>:8081/api/v1/pools/export

A successful import returns "applied": true plus the reviewed diff. The list response includes gpu-east with "enabled": true; canonical export must validate back to the same semantic state.

Cross-domain host accounting

When VM slices and whole-host bare-metal listings share physical hosts, one stable attribute.physical_host_id per host — identical in both storefront inventories — lets the site ledger prevent cross-mode double selling. Keep it stable across CSV edits; changing it breaks accounting for existing rows.

Disablement and lifecycle

Pool disablement prevents new assignment; it does not erase existing host membership or lifecycle records, and disabled pools remain resolvable for in-flight work. Pool administration is deliberately distinct from scheduling policy. Capacity release remains proof-driven (Fulfillment and seller delivery) — a pool change never silently frees held capacity.

Disable a non-default pool without erasing it:

Warning

Disabling mutates live routing state: the pool immediately stops receiving new assignments. Existing membership, lifecycle records, and in-flight work are preserved, and held capacity is not freed.

curl -sS -X DELETE \
  -H "X-Admin-Key: <admin_api_key>" \
  http://<PROVISIONING_HOST>:8081/api/v1/pools/gpu-east | jq

The response carries "enabled": false; a subsequent GET for gpu-east still resolves the pool and its history.

Scheduling behavior at the pin

The current scheduling policy is round-robin and deterministic for the same candidate order and state. Multidimensional fit checks every requested dimension; a candidate missing a requested dimension has zero availability for it.

Troubleshoot

• 401 Missing or invalid admin key — the provisioning service has an admin key configured and X-Admin-Key is absent or wrong.
• unknown_provider — no provider-specific configuration handler is registered for the named provider.
• missing_default_pool — an authoritative document omitted the required default definition.
• Unexpected IDs under disabled — stop before import; omitted pools are intentionally drained, not ignored.
• A disabled pool still appears in GET /pools/ — expected. Listing defaults include disabled pools so operators can audit them.

Next steps

• Reference the pool through a storefront listing: Storefront and listing management.
• Follow assignment and provider execution: Fulfillment and seller delivery.

Source and revision

Normative contracts: resource-pool management, site capacity, and fulfillment. The concrete operator API and request models are in the pool controller and the pool wire models. These describe the inspected development revision; the site-capacity contract itself notes it is not a distributed-consensus ledger for active-active replicas, and this documentation claims nothing beyond it.