Files
ilkerandClaude Opus 5 379cac5007 hpcod: let the portal allocate a cluster, instead of me typing it into tfvars
The planner has been able to pick the right hypervisor and the right card
for a while. Nothing acted on it: /v1/plan printed the decision and threw it
away, and the cluster was then created from a tfvars whose cluster_id I read
off the running estate and typed in by hand.

POST /v1/clusters closes that. It takes exactly the path a dry run takes -
applications folded in, reservations subtracted, then planned - and writes
the result. Sharing the path is the point: if the two diverged, a dry run
would stop being worth running. What it does not do is provision. It settles
what the cluster is and leaves it in state "requested", because building
takes minutes and an HTTP request should not be holding the decision in
memory while it happens.

Also GET to list, DELETE to release, and adoption.

Adoption is not a convenience. c002 was built by hand and holds subnet and
MAC octet 2; the database knew nothing about it, so the allocator would
eventually have handed 2 to someone else and put two live clusters on the
same addresses. It is now recorded, and allocation measurably steps over it:
three requests in a row took 1, 3 and 4.

The store became an interface here so the handlers could be tested without a
PostgreSQL. What is worth checking at this layer is status codes and what
gets dropped in translation, and neither is a database question. An
infeasible request is 409 with the reasons attached, not 400: it is well
formed and may succeed tomorrow.

Verified against the live database and hv01, end to end:

  POST                    201, c001-5, compute1 holds 0000:01:00.0
  POST again              409 "gpu: none present" - the card is promised to
                          a cluster that does not physically exist yet, so
                          only the reservation can say so
  dry-run                 the same answer, which is the point
  DELETE, POST again      201, address 1 recycled, name c001-6 - never c001-5

Three things the run found. The role had no privileges on the two tables
added in the last commit, because the first two were granted by hand and
nobody granted the rest - that is now a migration with default privileges,
so the next table cannot repeat it. A store failure was reported as 400,
which would have sent a caller rewriting a request that was never wrong.
And parseVMs split its input on every colon, cutting 0000:01:00.0 into
pieces and recording a card that does not exist; the test that caught it was
written for exactly that reason.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-20 23:30:52 +02:00

183 lines
5.7 KiB
Go

// Package spec is the tenant request: what someone asks the portal for.
//
// It is provider-neutral by construction. A request names capabilities from
// model's vocabulary, never a PCI id, a flavor name or an aggregate.
package spec
import (
"fmt"
"strings"
"time"
"gopkg.in/yaml.v3"
"github.com/ilkermanap/hpcod/internal/model"
)
// Constraint is one hardware requirement.
//
// Requirements are expressed per compute node, not per cluster: "2 GPUs each"
// is what users mean and what placement can actually pack.
type Constraint struct {
Capability model.Capability `yaml:"capability"`
Count int `yaml:"count"`
Vendor string `yaml:"vendor,omitempty"`
MinSpeedGb int `yaml:"min_speed_gbps,omitempty"`
}
func (c Constraint) String() string {
s := string(c.Capability)
if c.Count > 1 {
s = fmt.Sprintf("%s x%d", s, c.Count)
}
if c.Vendor != "" {
s += " (" + c.Vendor + ")"
}
if c.MinSpeedGb > 0 {
s += fmt.Sprintf(" >=%dGb", c.MinSpeedGb)
}
return s
}
// NodeSpec sizes a single VM.
type NodeSpec struct {
Cores int `yaml:"cores"`
MemoryGB int `yaml:"memory_gb"`
DiskGB int `yaml:"disk_gb,omitempty"`
}
// ComputeSpec sizes the compute pool.
type ComputeSpec struct {
Count int `yaml:"count"`
Cores int `yaml:"cores"`
MemoryGB int `yaml:"memory_gb"`
Require []Constraint `yaml:"require,omitempty"`
Prefer []Constraint `yaml:"prefer,omitempty"`
}
// StackSpec selects the software to install. Consumed in phase 4, carried now
// so requests do not have to change shape later.
type StackSpec struct {
OS string `yaml:"os,omitempty"`
Scheduler string `yaml:"scheduler,omitempty"`
Identity string `yaml:"identity,omitempty"`
// Apps names catalog entries - "openfoam", or "openfoam:12" to pin a
// version. They are the reason someone wants a cluster at all, and
// naming them is how a user avoids having to restate the hardware:
// the catalog knows that gromacs-gpu needs a GPU, so placement does
// too, without the box being ticked twice (see internal/catalog).
Apps []string `yaml:"apps,omitempty"`
}
// Request is one tenant cluster someone wants.
type Request struct {
Name string `yaml:"name"`
// Tenant is who the cluster is for. Required to create one, ignored
// when planning: a dry run asks whether the hardware exists, which is
// not a question about ownership, and demanding a tenant to ask it
// would make the cheap question as awkward as the expensive one.
Tenant string `yaml:"tenant,omitempty"`
// Owner is the contact recorded the first time a tenant is seen.
// Defaults to whoever is signed in.
Owner string `yaml:"owner,omitempty"`
Lease string `yaml:"lease,omitempty"`
Head NodeSpec `yaml:"head"`
Compute ComputeSpec `yaml:"compute"`
Stack StackSpec `yaml:"stack,omitempty"`
}
// The Warewulf model unpacks the node's root filesystem into RAM, so a compute
// node needs this much before any user workload runs. Requests state usable
// memory; placement adds this. Getting it wrong means tenants are handed nodes
// that OOM under their own job.
const RootfsReserveGB = 2
// MemoryPerComputeGB is what must actually be allocated per compute VM.
func (r Request) MemoryPerComputeGB() int {
return r.Compute.MemoryGB + RootfsReserveGB
}
func (r Request) LeaseDuration() (time.Duration, error) {
if r.Lease == "" {
return 0, nil
}
// Accept plain day counts as well as Go durations: "14d" is what people write.
if d, found := strings.CutSuffix(strings.TrimSpace(r.Lease), "d"); found {
var days int
if _, err := fmt.Sscanf(d, "%d", &days); err != nil || days <= 0 {
return 0, fmt.Errorf("bad lease %q", r.Lease)
}
return time.Duration(days) * 24 * time.Hour, nil
}
return time.ParseDuration(r.Lease)
}
// Validate rejects requests that cannot be satisfied by any site, so the error
// is about the request rather than about capacity.
func (r Request) Validate() error {
var errs []string
if strings.TrimSpace(r.Name) == "" {
errs = append(errs, "name is required")
}
if r.Compute.Count < 1 {
errs = append(errs, "compute.count must be at least 1")
}
if r.Compute.Cores < 1 {
errs = append(errs, "compute.cores must be at least 1")
}
if r.Compute.MemoryGB < 1 {
errs = append(errs, "compute.memory_gb must be at least 1")
}
if r.Head.Cores < 1 {
errs = append(errs, "head.cores must be at least 1")
}
if r.Head.MemoryGB < 1 {
errs = append(errs, "head.memory_gb must be at least 1")
}
if _, err := r.LeaseDuration(); err != nil {
// Name the field: "invalid duration" alone leaves the user guessing
// which of several time-valued settings is wrong.
errs = append(errs, fmt.Sprintf("lease %q is not a duration (try 14d, 336h): %v", r.Lease, err))
}
for _, c := range append(append([]Constraint{}, r.Compute.Require...), r.Compute.Prefer...) {
if c.Capability == "" {
errs = append(errs, "a constraint is missing its capability")
continue
}
switch c.Capability {
case model.CapGPU, model.CapInfiniBand, model.CapRoCE, model.CapNVMe:
default:
errs = append(errs, fmt.Sprintf("unknown capability %q", c.Capability))
}
if c.Count < 0 {
errs = append(errs, fmt.Sprintf("%s: count cannot be negative", c.Capability))
}
}
if len(errs) > 0 {
return fmt.Errorf("invalid request:\n - %s", strings.Join(errs, "\n - "))
}
return nil
}
// Parse reads a YAML request and normalises defaults.
func Parse(raw []byte) (Request, error) {
var r Request
if err := yaml.Unmarshal(raw, &r); err != nil {
return r, err
}
for i := range r.Compute.Require {
if r.Compute.Require[i].Count == 0 {
r.Compute.Require[i].Count = 1
}
}
for i := range r.Compute.Prefer {
if r.Compute.Prefer[i].Count == 0 {
r.Compute.Prefer[i].Count = 1
}
}
return r, r.Validate()
}