tools: instances live in OpenStack, so that is where the create goes

[traviswu-bigstack]

What

create_instance now posts to nova's /servers instead of a cube-cos-api path that does not exist. Tools name a Backend; the executor holds one write client per backend; OpenStack is reached with a per-cluster application credential through the Keystone catalog.

Why

#33 established that POST /api/v1/datacenters/{dc}/instances names nothing: cube-cos-api serves the appliance — nodes, health, events, images, volumes — across 102 paths, and VM lifecycle is not among its resource families. The tool's level gate, approval statement, write ledger and readable refusal were all correct and destination-independent. What was missing was somewhere to send the request.

Instances are nova's, so that is where it goes.

Reviewer notes

Ground truth, and what is citable. POST /servers is confirmed from nova's own router as CubeCOS vendors it — core/nova/caracal_patch/api/openstack/compute/routes.py.orig, cubecos 5a0e4640. Caracal is confirmed from the tree, not assumed: every core/*/*.mk names it and the patch directory is caracal_patch. The request body schema is not vendored anywhere in this environment — nova's api/openstack/compute/schemas/ is not in the tree, since only patched files are vendored — so the body shape is pinned by tests rather than by conformance. That is a weaker guarantee than the path has, and it is stated rather than implied.

Backend is an enum, not an interface. Two destinations today, a third foreseen (k8s clusters are Rancher's). An abstraction designed against one real case and two imagined ones is worse than a second concrete case later. The field is named for the role so nothing bakes in "a write means nova", and the zero value is cube-cos-api so no existing tool restates its destination.

The allowlist stays inexpressive. It can say: a literal path, a flat body of declared fields, finite value sets, and one shaped free parameter. It still cannot say a wildcard, a nested object, or a host. nova wants the body nested under server with flavorRef/imageRef and networks as a list — teaching Body to express that would widen what this file can say for no gain, so the backend translates and the translation is testable without a nova.

There is no project field, and that is the control. A server is created in whatever project the credential is scoped to. Nothing to name, so nothing to name wrongly. internal/openstack refuses outright if Keystone reports a scope other than the one the operator's configuration names, rather than creating somewhere nobody chose.

Credentials — the decision that generalises, and the one worth ratifying. A per-cluster OpenStack application credential in openstack-credential.json, beside the enrollment identity and the action level: same directory, same custody, no new distribution mechanism. Scoped to one project at creation, carrying only the roles the operator granted, revocable on its own, issued by the operator in their own Keystone — nothing about it depends on Bigstack, which is what makes it work air-gapped. This sets the pattern for Rancher and everything after, which is part of why it was chosen rather than a service user.

The file is refused if group- or world-readable, unlike the action level, which is policy anyone may inspect. Absent is not an error: it is the ordinary state of every cluster that has not opted in.

A missing credential does not look like a level refusal. They are different problems with different owners — one is policy the operator chose, the other is configuration they have not finished — and the refusal says so in as many words. A level refusal still comes first, so a cluster at observe is never told to go and configure a credential for a tool its level does not serve.

Keystone and secrets. The auth URL is configuration; the compute endpoint comes from the catalog, which is why /servers is the whole of what the allowlist writes down. Tokens are cached and renewed five minutes before expiry. Neither the token nor the secret reaches a log, an error, an audit row or the model: Credential.String/GoString redact so a later %+v cannot leak, a Keystone refusal deliberately does not echo the request, and a malformed credential file is reported without quoting its contents.

Idempotency is unchanged, including its residue. The ledger keys on the fully resolved path and body; a failed or timed-out write stays retryable. nova offers nothing better — it permits duplicate server names and has no create-once semantics here — so the Idempotency-Key header is sent in case a proxy honours it, and the ledger is what actually holds. Stated rather than implied to be stronger.

Name shape errs strict, deliberately. ShapeDNSLabel is narrower than nova's server-name rule. A shape looser than the API is a failed write the model cannot interpret; a stricter one is a usability limit an operator can see and complain about. Kept.

Conformance is per backend. nova's paths are vendored from its router as cube-cos-api's are from its OpenAPI document, with the same truncation floor and the same refusal to skip when input is missing. notInTheSpec is now empty — create_instance was its only entry, and giving the tool a destination paid the debt rather than excusing it. The two honesty guards iterate that map, so an empty map exercises nothing; they earn their keep when someone next adds an entry, and the comment says so.

A weak test found by breaking it. TestACallerCannotChooseWhatTheProfileDecides asserted only ErrBadArgument — which both the executor-context guard and the unknown-argument fallback return — so it passed with the guard deleted. It now pins the reason and covers all four profile fields. That is the third time this exercise has found untested behaviour rather than confirming a belief.

Breaks proved, each watched to fail a named test and then restored: credential refusal removed (TestACreateWithoutACredentialIsRefusedAndSaysSoDistinctly); executor-context guard disabled (TestACallerCannotChooseWhatTheProfileDecides, four subcases, after strengthening); ledger suppression disabled (TestARetriedWriteDoesNotCreateASecondInstance).

Wired but inert. run.go loads the credential when one exists and refuses cleanly when it does not. Nothing can act until an operator writes that file and raises the cluster's level, so this ships without changing any deployment's behaviour.

No SaaS PR. pkg/toolcatalog is doing its job: cube-ai-advisor holds no copy of the path — only the tool's name, in two eval cases, which is unchanged.

Docs

Handbook: the slice-3 as-built and #33's correction both describe a destination that has now changed.