Merge C19 OpenAPI for the admin API and a Terraform provider
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
commit
9dc82f73d4
37 files changed
+11095
-62
No files matched your search
@@ -75,13 +75,26 @@ func (a *API) SetRevoker(f func(ctx context.Context, nodeID string, at time.Time
|
||||
a.revoke = f
|
||||
}
|
||||
|
||||
// Mux is where the endpoints are mounted. An *http.ServeMux is one; a test
|
||||
// that records the patterns is another, and is how the route table is checked
|
||||
// against what is actually served.
|
||||
type Mux interface {
|
||||
HandleFunc(pattern string, handler func(http.ResponseWriter, *http.Request))
|
||||
}
|
||||
|
||||
// Register mounts the endpoints on a mux under /api/v1.
|
||||
func (a *API) Register(mux *http.ServeMux) {
|
||||
//
|
||||
// Every pattern registered here, or by the register helpers it calls, must
|
||||
// also be in Routes: that table is what the OpenAPI document is generated
|
||||
// from, and a test fails when the two disagree.
|
||||
func (a *API) Register(mux Mux) {
|
||||
mux.HandleFunc("GET /api/v1/summary", a.summary)
|
||||
// Adding a model is a write, and the only one this API has. It lives here
|
||||
// rather than on the client-facing listener for the same reason the rest of
|
||||
// it does: reaching this port already means holding the control plane.
|
||||
mux.HandleFunc("GET /api/v1/openapi.json", serveOpenAPI)
|
||||
// Changes to the catalog live here rather than on the client-facing
|
||||
// listener for the same reason the rest of this does: reaching this port
|
||||
// already means holding the control plane.
|
||||
mux.HandleFunc("POST /api/v1/models", a.addModel)
|
||||
mux.HandleFunc("GET /api/v1/models/{name}", a.getModel)
|
||||
mux.HandleFunc("DELETE /api/v1/models/{name}", a.removeModel)
|
||||
mux.HandleFunc("POST /api/v1/models/{name}/scale", a.scaleModel)
|
||||
mux.HandleFunc("POST /api/v1/models/{name}/resources", a.setResources)
|
||||
@@ -97,9 +110,7 @@ func (a *API) Register(mux *http.ServeMux) {
|
||||
writeError(w, http.StatusNotImplemented, "this control plane has no store")
|
||||
return
|
||||
}
|
||||
var req struct {
|
||||
Class string `json:"class"`
|
||||
}
|
||||
var req ClassRequest
|
||||
if err := json.NewDecoder(io.LimitReader(r.Body, 1<<12)).Decode(&req); err != nil {
|
||||
writeError(w, http.StatusBadRequest, "the request is not valid JSON: "+err.Error())
|
||||
return
|
||||
@@ -109,7 +120,7 @@ func (a *API) Register(mux *http.ServeMux) {
|
||||
writeError(w, http.StatusBadRequest, err.Error())
|
||||
return
|
||||
}
|
||||
writeJSON(w, http.StatusOK, map[string]string{"model": m.Name, "class": m.EffectiveClass()})
|
||||
writeJSON(w, http.StatusOK, ClassView{Model: m.Name, Class: m.EffectiveClass()})
|
||||
})
|
||||
mux.HandleFunc("PUT /api/v1/models/{name}/capacity", a.putCapacity)
|
||||
mux.HandleFunc("GET /api/v1/capacity", a.listCapacity)
|
||||
@@ -997,7 +1008,25 @@ func (a *API) addModel(w http.ResponseWriter, r *http.Request) {
|
||||
writeError(w, http.StatusBadRequest, err.Error())
|
||||
return
|
||||
}
|
||||
writeJSON(w, http.StatusOK, map[string]string{"added": m.Name})
|
||||
writeJSON(w, http.StatusOK, ModelAdded{Added: m.Name})
|
||||
}
|
||||
|
||||
// getModel answers with one model's whole definition as it is in force: what
|
||||
// was added, with the defaults the catalog filled in. The listing shows a
|
||||
// model's state and only the names of its profiles; this is what a tool
|
||||
// managing the definition — Terraform, say — compares against what it wants.
|
||||
//
|
||||
// By its name only, not an alias: an alias answering would let a tool believe
|
||||
// a model it manages exists when it is another one.
|
||||
func (a *API) getModel(w http.ResponseWriter, r *http.Request) {
|
||||
name := r.PathValue("name")
|
||||
for _, m := range a.ctl.Catalog().Models() {
|
||||
if m.Name == name {
|
||||
writeJSON(w, http.StatusOK, m)
|
||||
return
|
||||
}
|
||||
}
|
||||
writeError(w, http.StatusNotFound, "no model named "+name+" is in the catalog")
|
||||
}
|
||||
|
||||
// ScaleRequest is how many replicas a model should run.
|
||||
@@ -1083,7 +1112,7 @@ func (a *API) removeModel(w http.ResponseWriter, r *http.Request) {
|
||||
writeError(w, http.StatusBadRequest, err.Error())
|
||||
return
|
||||
}
|
||||
writeJSON(w, http.StatusOK, map[string]string{"removed": name})
|
||||
writeJSON(w, http.StatusOK, Removed{Removed: name})
|
||||
}
|
||||
|
||||
func (a *API) summary(w http.ResponseWriter, _ *http.Request) {
|
||||
@@ -1181,15 +1210,13 @@ func (a *API) removeNode(w http.ResponseWriter, r *http.Request) {
|
||||
}
|
||||
inv.Remove(id)
|
||||
a.ctl.Reconciler().Notify()
|
||||
writeJSON(w, http.StatusOK, map[string]string{"id": id, "removed": "true"})
|
||||
writeJSON(w, http.StatusOK, NodeRemoved{ID: id, Removed: "true"})
|
||||
}
|
||||
|
||||
func (a *API) setNodeState(w http.ResponseWriter, r *http.Request) {
|
||||
id := r.PathValue("id")
|
||||
|
||||
var body struct {
|
||||
State string `json:"state"`
|
||||
}
|
||||
var body NodeStateRequest
|
||||
if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
|
||||
writeError(w, http.StatusBadRequest, err.Error())
|
||||
return
|
||||
@@ -1217,7 +1244,7 @@ func (a *API) setNodeState(w http.ResponseWriter, r *http.Request) {
|
||||
// is usually about to do something to it.
|
||||
a.ctl.Reconciler().Notify()
|
||||
|
||||
writeJSON(w, http.StatusOK, map[string]string{"id": id, "state": st.String()})
|
||||
writeJSON(w, http.StatusOK, NodeStateView{ID: id, State: st.String()})
|
||||
}
|
||||
|
||||
func writeJSON(w http.ResponseWriter, code int, v any) {
|
||||
@@ -1227,7 +1254,7 @@ func writeJSON(w http.ResponseWriter, code int, v any) {
|
||||
}
|
||||
|
||||
func writeError(w http.ResponseWriter, code int, msg string) {
|
||||
writeJSON(w, code, map[string]string{"error": msg})
|
||||
writeJSON(w, code, ErrorView{Error: msg})
|
||||
}
|
||||
|
||||
// profileChanged reports whether a replica is running a profile the catalog no
|
||||
@@ -1428,7 +1455,7 @@ func (a *API) retryModel(w http.ResponseWriter, r *http.Request) {
|
||||
return
|
||||
}
|
||||
was := a.ctl.Reconciler().Retry(name)
|
||||
writeJSON(w, http.StatusOK, map[string]bool{"was_parked": was})
|
||||
writeJSON(w, http.StatusOK, RetryView{WasParked: was})
|
||||
}
|
||||
|
||||
// requestFinder looks a request up by the id it was given. Asked of the usage
|
||||
@@ -1523,7 +1550,7 @@ func (a *API) upgradeNode(w http.ResponseWriter, r *http.Request) {
|
||||
writeError(w, http.StatusBadGateway, err.Error())
|
||||
return
|
||||
}
|
||||
writeJSON(w, http.StatusOK, map[string]string{"node": r.PathValue("id"), "version": req.Version})
|
||||
writeJSON(w, http.StatusOK, UpgradeView{Node: r.PathValue("id"), Version: req.Version})
|
||||
}
|
||||
|
||||
// SetServe supplies what serves a model from the registry.
|
||||
@@ -1623,7 +1650,7 @@ func (a *API) rollbackModel(w http.ResponseWriter, r *http.Request) {
|
||||
writeError(w, http.StatusBadRequest, err.Error())
|
||||
return
|
||||
}
|
||||
writeJSON(w, http.StatusOK, map[string]string{"result": msg})
|
||||
writeJSON(w, http.StatusOK, Result{Result: msg})
|
||||
}
|
||||
|
||||
// OriginRequest names the repository a model's weights came from.
|
||||
|
||||
@@ -8,7 +8,13 @@ import (
|
||||
"gitea.mynodes.xyz/ilker/llmgw/internal/control/catalog"
|
||||
)
|
||||
|
||||
func (a *API) registerCanary(mux *http.ServeMux) {
|
||||
// CanaryPercentRequest changes the share of a model's requests its canary
|
||||
// takes.
|
||||
type CanaryPercentRequest struct {
|
||||
Percent int `json:"percent"`
|
||||
}
|
||||
|
||||
func (a *API) registerCanary(mux Mux) {
|
||||
need := func(w http.ResponseWriter) bool {
|
||||
if a.serve == nil {
|
||||
writeError(w, http.StatusNotImplemented, "a canary needs a mirror and a store, and this control plane lacks one")
|
||||
@@ -45,9 +51,7 @@ func (a *API) registerCanary(mux *http.ServeMux) {
|
||||
if !need(w) {
|
||||
return
|
||||
}
|
||||
var req struct {
|
||||
Percent int `json:"percent"`
|
||||
}
|
||||
var req CanaryPercentRequest
|
||||
if err := json.NewDecoder(io.LimitReader(r.Body, 1<<12)).Decode(&req); err != nil {
|
||||
writeError(w, http.StatusBadRequest, "the request is not valid JSON: "+err.Error())
|
||||
return
|
||||
@@ -57,7 +61,7 @@ func (a *API) registerCanary(mux *http.ServeMux) {
|
||||
writeError(w, http.StatusBadRequest, err.Error())
|
||||
return
|
||||
}
|
||||
writeJSON(w, http.StatusOK, map[string]string{"result": msg})
|
||||
writeJSON(w, http.StatusOK, Result{Result: msg})
|
||||
})
|
||||
mux.HandleFunc("DELETE /api/v1/models/{name}/canary", func(w http.ResponseWriter, r *http.Request) {
|
||||
if !need(w) {
|
||||
@@ -68,7 +72,7 @@ func (a *API) registerCanary(mux *http.ServeMux) {
|
||||
writeError(w, http.StatusBadRequest, err.Error())
|
||||
return
|
||||
}
|
||||
writeJSON(w, http.StatusOK, map[string]string{"result": msg})
|
||||
writeJSON(w, http.StatusOK, Result{Result: msg})
|
||||
})
|
||||
mux.HandleFunc("POST /api/v1/models/{name}/promote", func(w http.ResponseWriter, r *http.Request) {
|
||||
if !need(w) {
|
||||
|
||||
@@ -34,10 +34,7 @@ type RailView struct {
|
||||
// sends traffic over the fabric for seconds a rail, so it is a POST and only
|
||||
// ever run when asked.
|
||||
func (a *API) fabricTest(w http.ResponseWriter, r *http.Request) {
|
||||
var body struct {
|
||||
A, B, Fabric string
|
||||
Seconds int
|
||||
}
|
||||
var body FabricTestRequest
|
||||
if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
|
||||
writeError(w, http.StatusBadRequest, err.Error())
|
||||
return
|
||||
|
||||
@@ -66,7 +66,17 @@ func (a *API) guardTarget(ctx context.Context, target string) (guard.Attachment,
|
||||
return guard.Attachment{}, fmt.Errorf("%q: attach to org, team, project, key or user", kind)
|
||||
}
|
||||
|
||||
func (a *API) registerGuard(mux *http.ServeMux) {
|
||||
// GuardAttachmentRequest attaches a policy to a part of the tenancy tree, a
|
||||
// key or a person, or with DELETE takes it off again.
|
||||
type GuardAttachmentRequest struct {
|
||||
// Target is org:NAME, team:ORG/TEAM, project:ORG/TEAM/PROJECT (or the ID
|
||||
// after the colon), key:KEY-ID or user:USER-ID.
|
||||
Target string `json:"target"`
|
||||
// Policy is a policy's name in server.yaml's guard.policies.
|
||||
Policy string `json:"policy"`
|
||||
}
|
||||
|
||||
func (a *API) registerGuard(mux Mux) {
|
||||
mux.HandleFunc("GET /api/v1/guard", func(w http.ResponseWriter, r *http.Request) {
|
||||
if a.guard == nil {
|
||||
writeError(w, http.StatusNotImplemented, "no guard policies: define them under guard: in server.yaml")
|
||||
@@ -97,12 +107,7 @@ func (a *API) registerGuard(mux *http.ServeMux) {
|
||||
writeError(w, http.StatusNotImplemented, "no guard policies: define them under guard: in server.yaml")
|
||||
return
|
||||
}
|
||||
var at struct {
|
||||
// Target is org:NAME, team:ORG/TEAM, project:ORG/TEAM/PROJECT
|
||||
// (or the ID after the colon), key:KEY-ID or user:USER-ID.
|
||||
Target string `json:"target"`
|
||||
Policy string `json:"policy"`
|
||||
}
|
||||
var at GuardAttachmentRequest
|
||||
if err := json.NewDecoder(r.Body).Decode(&at); err != nil {
|
||||
writeError(w, http.StatusBadRequest, err.Error())
|
||||
return
|
||||
|
||||
@@ -50,7 +50,26 @@ type QuotaRequest struct {
|
||||
Limit store.Resources `json:"limit"`
|
||||
}
|
||||
|
||||
func (a *API) registerQuotas(mux *http.ServeMux) {
|
||||
// QuotaSet is the scope a quota was set on, as org:ID, team:ID or
|
||||
// project:ID whatever name it was asked by.
|
||||
type QuotaSet struct {
|
||||
Scope string `json:"scope"`
|
||||
}
|
||||
|
||||
// OwnerRequest sets the part of the tenancy tree a model's capacity counts
|
||||
// against: org:NAME, team:ORG/TEAM or project:ORG/TEAM/PROJECT, or their IDs.
|
||||
// Empty makes the model shared.
|
||||
type OwnerRequest struct {
|
||||
Owner string `json:"owner"`
|
||||
}
|
||||
|
||||
// OwnerView is a model's owner now, as scope:ID.
|
||||
type OwnerView struct {
|
||||
Model string `json:"model"`
|
||||
Owner string `json:"owner"`
|
||||
}
|
||||
|
||||
func (a *API) registerQuotas(mux Mux) {
|
||||
mux.HandleFunc("GET /api/v1/quotas", func(w http.ResponseWriter, r *http.Request) {
|
||||
if a.quotas == nil {
|
||||
writeError(w, http.StatusNotImplemented, "this control plane has no store")
|
||||
@@ -78,7 +97,7 @@ func (a *API) registerQuotas(mux *http.ServeMux) {
|
||||
writeError(w, http.StatusBadRequest, err.Error())
|
||||
return
|
||||
}
|
||||
writeJSON(w, http.StatusOK, map[string]string{"scope": key})
|
||||
writeJSON(w, http.StatusOK, QuotaSet{Scope: key})
|
||||
})
|
||||
mux.HandleFunc("DELETE /api/v1/quotas/{scope}", func(w http.ResponseWriter, r *http.Request) {
|
||||
if a.quotas == nil {
|
||||
@@ -90,16 +109,14 @@ func (a *API) registerQuotas(mux *http.ServeMux) {
|
||||
writeError(w, http.StatusBadRequest, err.Error())
|
||||
return
|
||||
}
|
||||
writeJSON(w, http.StatusOK, map[string]string{"removed": key})
|
||||
writeJSON(w, http.StatusOK, Removed{Removed: key})
|
||||
})
|
||||
mux.HandleFunc("POST /api/v1/models/{name}/owner", func(w http.ResponseWriter, r *http.Request) {
|
||||
if a.models == nil || a.quotas == nil {
|
||||
writeError(w, http.StatusNotImplemented, "this control plane has no store")
|
||||
return
|
||||
}
|
||||
var req struct {
|
||||
Owner string `json:"owner"`
|
||||
}
|
||||
var req OwnerRequest
|
||||
if err := json.NewDecoder(io.LimitReader(r.Body, 1<<12)).Decode(&req); err != nil {
|
||||
writeError(w, http.StatusBadRequest, "the request is not valid JSON: "+err.Error())
|
||||
return
|
||||
@@ -118,7 +135,7 @@ func (a *API) registerQuotas(mux *http.ServeMux) {
|
||||
writeError(w, http.StatusBadRequest, err.Error())
|
||||
return
|
||||
}
|
||||
writeJSON(w, http.StatusOK, map[string]string{"model": m.Name, "owner": m.Owner})
|
||||
writeJSON(w, http.StatusOK, OwnerView{Model: m.Name, Owner: m.Owner})
|
||||
})
|
||||
}
|
||||
|
||||
|
||||
@@ -0,0 +1,84 @@
|
||||
package adminapi
|
||||
|
||||
// The small bodies the endpoints read and answer with. Named types rather
|
||||
// than maps and anonymous structs, so the OpenAPI document generated from
|
||||
// Routes describes exactly what a handler decodes and writes: a map literal
|
||||
// in a handler is a shape no generator can see.
|
||||
|
||||
// ErrorView is every refusal: a 4xx or 5xx status with what went wrong.
|
||||
type ErrorView struct {
|
||||
Error string `json:"error"`
|
||||
}
|
||||
|
||||
// Result is what a change that has no other answer says it did.
|
||||
type Result struct {
|
||||
Result string `json:"result"`
|
||||
}
|
||||
|
||||
// ModelAdded names the model added to the catalog.
|
||||
type ModelAdded struct {
|
||||
Added string `json:"added"`
|
||||
}
|
||||
|
||||
// Removed names what was taken away: a model, or a quota's scope.
|
||||
type Removed struct {
|
||||
Removed string `json:"removed"`
|
||||
}
|
||||
|
||||
// ClassRequest sets a model's capacity class: critical, standard or
|
||||
// opportunistic, or empty to go back to what its scaling implies.
|
||||
type ClassRequest struct {
|
||||
Class string `json:"class"`
|
||||
}
|
||||
|
||||
// ClassView is a model's capacity class now.
|
||||
type ClassView struct {
|
||||
Model string `json:"model"`
|
||||
Class string `json:"class"`
|
||||
}
|
||||
|
||||
// RetryView says whether the model had been parked, given up on after
|
||||
// failing to start, before it was retried.
|
||||
type RetryView struct {
|
||||
WasParked bool `json:"was_parked"`
|
||||
}
|
||||
|
||||
// NodeStateRequest cordons, drains or readies a node: ready (or uncordon),
|
||||
// cordoned (or cordon), draining (or drain).
|
||||
type NodeStateRequest struct {
|
||||
State string `json:"state"`
|
||||
}
|
||||
|
||||
// NodeStateView is a node's state after the change.
|
||||
type NodeStateView struct {
|
||||
ID string `json:"id"`
|
||||
State string `json:"state"`
|
||||
}
|
||||
|
||||
// NodeRemoved names the node forgotten. Removed is the string "true".
|
||||
type NodeRemoved struct {
|
||||
ID string `json:"id"`
|
||||
Removed string `json:"removed"`
|
||||
}
|
||||
|
||||
// UpgradeView is the release a node was told to run.
|
||||
type UpgradeView struct {
|
||||
Node string `json:"node"`
|
||||
Version string `json:"version"`
|
||||
}
|
||||
|
||||
// FabricTestRequest is a bandwidth test between two nodes.
|
||||
type FabricTestRequest struct {
|
||||
A string `json:"a"`
|
||||
B string `json:"b"`
|
||||
// Fabric is the declared fabric to test over; empty is the one the two
|
||||
// nodes share.
|
||||
Fabric string `json:"fabric,omitempty"`
|
||||
// Seconds each rail is measured for, from 1 to 30.
|
||||
Seconds int `json:"seconds,omitempty"`
|
||||
}
|
||||
|
||||
// ReplayRequest names the model a kept request is sent to again.
|
||||
type ReplayRequest struct {
|
||||
Model string `json:"model"`
|
||||
}
|
||||
@@ -60,9 +60,7 @@ func (a *API) replayRequest(w http.ResponseWriter, r *http.Request) {
|
||||
writeError(w, http.StatusNotImplemented, "this control plane does not route requests")
|
||||
return
|
||||
}
|
||||
var req struct {
|
||||
Model string `json:"model"`
|
||||
}
|
||||
var req ReplayRequest
|
||||
if err := json.NewDecoder(io.LimitReader(r.Body, 1<<12)).Decode(&req); err != nil || req.Model == "" {
|
||||
writeError(w, http.StatusBadRequest, "say which model: {\"model\": \"...\"}")
|
||||
return
|
||||
|
||||
@@ -0,0 +1,249 @@
|
||||
package adminapi
|
||||
|
||||
import (
|
||||
"net/http"
|
||||
|
||||
llmgw "gitea.mynodes.xyz/ilker/llmgw"
|
||||
"gitea.mynodes.xyz/ilker/llmgw/internal/bench"
|
||||
"gitea.mynodes.xyz/ilker/llmgw/internal/control/catalog"
|
||||
"gitea.mynodes.xyz/ilker/llmgw/internal/control/fabrics"
|
||||
"gitea.mynodes.xyz/ilker/llmgw/internal/control/modelserve"
|
||||
"gitea.mynodes.xyz/ilker/llmgw/internal/control/nvlink"
|
||||
"gitea.mynodes.xyz/ilker/llmgw/internal/guard"
|
||||
"gitea.mynodes.xyz/ilker/llmgw/internal/notify"
|
||||
"gitea.mynodes.xyz/ilker/llmgw/internal/store"
|
||||
)
|
||||
|
||||
// Route is one endpoint as the OpenAPI document describes it.
|
||||
//
|
||||
// A table written by hand beside Register rather than read out of the
|
||||
// handlers, because what a handler decodes and answers is not visible from
|
||||
// outside it. The table is checked against Register by a test, so an endpoint
|
||||
// cannot be added without being described; the bodies are Go values whose
|
||||
// types the generator reads, so a field added to one is in the document the
|
||||
// next time it is generated.
|
||||
type Route struct {
|
||||
Method string
|
||||
Path string
|
||||
// Summary is one line; Description, when there is more to say, the rest.
|
||||
Summary string
|
||||
Description string
|
||||
// Query is the query parameters the handler reads.
|
||||
Query []Param
|
||||
// Request is a value of the body's type; nil reads none.
|
||||
Request any
|
||||
// OptionalBody is set when the body may be left out.
|
||||
OptionalBody bool
|
||||
// Response is a value of the type a success answers with.
|
||||
Response any
|
||||
// Status is the success status; zero is 200.
|
||||
Status int
|
||||
// CSV is set when the answer is CSV unless JSON is asked for.
|
||||
CSV bool
|
||||
}
|
||||
|
||||
// Param is a query parameter.
|
||||
type Param struct {
|
||||
Name string
|
||||
Description string
|
||||
// Type is a JSON Schema type: string when empty, or integer, number,
|
||||
// boolean.
|
||||
Type string
|
||||
Required bool
|
||||
}
|
||||
|
||||
// PathParams describes the parameters in Routes' paths, by the segment
|
||||
// before them and their name.
|
||||
var PathParams = map[string]string{
|
||||
"models/{name}": "The model's name in the catalog.",
|
||||
"nodes/{id}": "The node's ID, as `llmgw ctl nodes` lists it.",
|
||||
"jobs/{id}": "The job's ID, as starting it answered.",
|
||||
"requests/{id}": "The request's ID: the x-request-id a client was answered with.",
|
||||
"fabrics/{id}": "The physical fabric's ID, as GET /api/v1/fabrics lists it.",
|
||||
"quotas/{scope}": "The scope: org:NAME, team:ORG/TEAM, project:ORG/TEAM/PROJECT, or their IDs after the colon.",
|
||||
}
|
||||
|
||||
// Routes is every endpoint Register mounts.
|
||||
var Routes = []Route{
|
||||
// The document itself.
|
||||
{Method: "GET", Path: "/api/v1/openapi.json", Summary: "This document",
|
||||
Description: "The admin API in OpenAPI 3.1, generated from the route table and built into the binary.",
|
||||
Response: map[string]any{}},
|
||||
|
||||
// The fleet.
|
||||
{Method: "GET", Path: "/api/v1/summary", Summary: "The whole fleet in one answer",
|
||||
Response: Summary{}},
|
||||
{Method: "GET", Path: "/api/v1/nodes", Summary: "Every node, with its cards, load and fabrics",
|
||||
Response: []NodeView{}},
|
||||
{Method: "POST", Path: "/api/v1/nodes/{id}/state", Summary: "Cordon, drain or ready a node",
|
||||
Request: NodeStateRequest{}, Response: NodeStateView{}},
|
||||
{Method: "POST", Path: "/api/v1/nodes/{id}/upgrade", Summary: "Have a node run a release",
|
||||
Request: UpgradeRequest{}, Response: UpgradeView{}},
|
||||
{Method: "POST", Path: "/api/v1/nodes/{id}/engines", Summary: "Choose an engine's build for a node",
|
||||
Description: "The node installs the build chosen. Build is auto, a build such as cu129, or none.",
|
||||
Request: NodeEngineRequest{}, Response: NodeEngineRequest{}},
|
||||
{Method: "DELETE", Path: "/api/v1/nodes/{id}", Summary: "Forget a node that has gone",
|
||||
Description: "Only a node that is lost, or unreachable with nothing on it; its certificate is revoked.",
|
||||
Response: NodeRemoved{}},
|
||||
{Method: "GET", Path: "/api/v1/nodes/{id}/logs", Summary: "The last lines of a node's logs",
|
||||
Query: []Param{
|
||||
{Name: "lines", Type: "integer", Description: "How many lines; 300 when absent, at most 2000."},
|
||||
{Name: "source", Description: "Which log: agent when absent, or an engine the node lists in sources."},
|
||||
},
|
||||
Response: LogsView{}},
|
||||
{Method: "GET", Path: "/api/v1/fabrics", Summary: "The physical fabrics and the names nodes give them",
|
||||
Response: fabrics.Report{}},
|
||||
{Method: "GET", Path: "/api/v1/fabrics/{id}/topology", Summary: "One fabric's map, with the cluster's adapters live on it",
|
||||
Response: TopologyView{}},
|
||||
{Method: "GET", Path: "/api/v1/nvlink", Summary: "The multi-node NVLink domains and what keeps nodes out of them",
|
||||
Response: nvlink.Report{}},
|
||||
{Method: "POST", Path: "/api/v1/fabric-test", Summary: "Measure bandwidth between two nodes, rail by rail",
|
||||
Request: FabricTestRequest{}, Response: FabricTestView{}},
|
||||
{Method: "GET", Path: "/api/v1/weights/orphans", Summary: "Weights on nodes that no model uses",
|
||||
Response: []OrphanView{}},
|
||||
{Method: "POST", Path: "/api/v1/weights/collect", Summary: "Delete weights that no model uses",
|
||||
Request: CollectRequest{}, OptionalBody: true, Response: []CollectResult{}},
|
||||
|
||||
// The catalog.
|
||||
{Method: "GET", Path: "/api/v1/models", Summary: "Every model, with its replicas and state",
|
||||
Response: []ModelView{}},
|
||||
{Method: "POST", Path: "/api/v1/models", Summary: "Add a model to the catalog",
|
||||
Description: "Kept in the store across restarts. Refused when the name is taken, a model in " +
|
||||
"configuration has it, or the definition would make the catalog invalid.",
|
||||
Request: catalog.Model{}, Response: ModelAdded{}},
|
||||
{Method: "GET", Path: "/api/v1/models/{name}", Summary: "One model's definition, as it is in force",
|
||||
Description: "With the defaults the catalog filled in. By its name only, not an alias.",
|
||||
Response: catalog.Model{}},
|
||||
{Method: "DELETE", Path: "/api/v1/models/{name}", Summary: "Remove a model added at runtime",
|
||||
Description: "A model declared in configuration is refused: it would come back on the next restart.",
|
||||
Response: Removed{}},
|
||||
{Method: "POST", Path: "/api/v1/models/{name}/scale", Summary: "Set how many replicas a model runs",
|
||||
Request: ScaleRequest{}, Response: ScaleResponse{}},
|
||||
{Method: "POST", Path: "/api/v1/models/{name}/resources", Summary: "Set what a model's profiles reserve of a node",
|
||||
Request: ResourcesRequest{}, Response: catalog.Model{}},
|
||||
{Method: "POST", Path: "/api/v1/models/{name}/class", Summary: "Set a model's capacity class",
|
||||
Request: ClassRequest{}, Response: ClassView{}},
|
||||
{Method: "POST", Path: "/api/v1/models/{name}/owner", Summary: "Set the part of the tenancy tree a model's capacity counts against",
|
||||
Request: OwnerRequest{}, Response: OwnerView{}},
|
||||
{Method: "POST", Path: "/api/v1/models/{name}/adapters", Summary: "Replace a model's LoRA adapters",
|
||||
Description: "Each new file is read first, to check it is an adapter for the model's architecture.",
|
||||
Request: AdaptersRequest{}, Response: AdaptersRequest{}},
|
||||
{Method: "POST", Path: "/api/v1/models/{name}/retry", Summary: "Try a parked model again",
|
||||
Response: RetryView{}},
|
||||
{Method: "GET", Path: "/api/v1/models/{name}/target", Summary: "How many replicas a throughput needs, and whether they fit",
|
||||
Query: []Param{{Name: "tokens_per_sec", Type: "number", Required: true,
|
||||
Description: "The output tokens a second wanted of the model."}},
|
||||
Response: TargetView{}},
|
||||
{Method: "GET", Path: "/api/v1/models/{name}/headroom", Summary: "How many more replicas of a model fit now, and where",
|
||||
Query: []Param{{Name: "limit", Type: "integer",
|
||||
Description: "The most to try placing; 16 when absent or past 64."}},
|
||||
Response: HeadroomView{}},
|
||||
{Method: "PUT", Path: "/api/v1/models/{name}/capacity", Summary: "Record what a replica was measured to serve",
|
||||
Description: "Replaces an earlier measurement of the same model on the same profile.",
|
||||
Request: bench.Capacity{}, Response: bench.Capacity{}},
|
||||
{Method: "GET", Path: "/api/v1/capacity", Summary: "Every recorded measurement",
|
||||
Response: []CapacityView{}},
|
||||
{Method: "GET", Path: "/api/v1/replicas", Summary: "Every replica, with its shards",
|
||||
Query: []Param{{Name: "model", Description: "Only this model's replicas."}},
|
||||
Response: []ReplicaView{}},
|
||||
{Method: "GET", Path: "/api/v1/explain-placement", Summary: "Why a model could not be placed",
|
||||
Query: []Param{{Name: "model", Required: true, Description: "The model's name or an alias."}},
|
||||
Response: ExplainView{}},
|
||||
{Method: "POST", Path: "/api/v1/restart", Summary: "Restart replicas, every replica of some models, or all",
|
||||
Request: RestartRequest{}, Response: RestartResult{}, Status: http.StatusAccepted},
|
||||
|
||||
// Serving from the registry, and newer weights.
|
||||
{Method: "GET", Path: "/api/v1/plan", Summary: "How a registry repository would be served here",
|
||||
Query: []Param{
|
||||
{Name: "repo", Required: true, Description: "The repository, owner/name."},
|
||||
{Name: "format", Description: "gguf or safetensors; gguf when absent."},
|
||||
{Name: "context", Type: "integer", Description: "The context length to plan for, in tokens."},
|
||||
},
|
||||
Response: modelserve.Plan{}},
|
||||
{Method: "POST", Path: "/api/v1/models/serve", Summary: "Fetch a registry repository and serve it",
|
||||
Request: modelserve.Request{}, Response: modelserve.Job{}, Status: http.StatusAccepted},
|
||||
{Method: "GET", Path: "/api/v1/jobs", Summary: "Every job since the control plane started",
|
||||
Response: []modelserve.Job{}},
|
||||
{Method: "GET", Path: "/api/v1/jobs/{id}", Summary: "One job",
|
||||
Response: modelserve.Job{}},
|
||||
{Method: "GET", Path: "/api/v1/updates", Summary: "Newer weights the registry has for models",
|
||||
Response: []modelserve.UpdateInfo{}},
|
||||
{Method: "POST", Path: "/api/v1/updates/check", Summary: "Ask the registry now, about one model or every one",
|
||||
Request: CheckRequest{}, OptionalBody: true, Response: []modelserve.UpdateInfo{}},
|
||||
{Method: "POST", Path: "/api/v1/models/{name}/update", Summary: "Move a model to its repository's newer weights",
|
||||
Response: modelserve.Job{}, Status: http.StatusAccepted},
|
||||
{Method: "POST", Path: "/api/v1/models/{name}/rollback", Summary: "Go back to the weights the last update replaced",
|
||||
Response: Result{}},
|
||||
{Method: "POST", Path: "/api/v1/models/{name}/origin", Summary: "Record the repository a model's weights came from",
|
||||
Request: OriginRequest{}, Response: OriginView{}},
|
||||
{Method: "GET", Path: "/api/v1/canaries", Summary: "Every canary, and how its two sides serve",
|
||||
Response: []modelserve.CanaryView{}},
|
||||
{Method: "POST", Path: "/api/v1/models/{name}/canary", Summary: "Start a canary of a model's newer weights",
|
||||
Request: catalog.Canary{}, Response: modelserve.Job{}, Status: http.StatusAccepted},
|
||||
{Method: "PUT", Path: "/api/v1/models/{name}/canary", Summary: "Change the share of requests a canary takes",
|
||||
Request: CanaryPercentRequest{}, Response: Result{}},
|
||||
{Method: "DELETE", Path: "/api/v1/models/{name}/canary", Summary: "Take a canary out: its share first, then the candidate",
|
||||
Response: Result{}},
|
||||
{Method: "POST", Path: "/api/v1/models/{name}/promote", Summary: "Make a canary's weights the model's",
|
||||
Response: modelserve.Job{}, Status: http.StatusAccepted},
|
||||
|
||||
// Tenancy: quotas and guardrails.
|
||||
{Method: "GET", Path: "/api/v1/quotas", Summary: "Every capacity quota, with what its scope holds now",
|
||||
Response: []QuotaView{}},
|
||||
{Method: "PUT", Path: "/api/v1/quotas", Summary: "Set a scope's capacity quota",
|
||||
Description: "Replaces the scope's quota whole. The scope may be named by path or by ID; the answer names it by ID.",
|
||||
Request: QuotaRequest{}, Response: QuotaSet{}},
|
||||
{Method: "DELETE", Path: "/api/v1/quotas/{scope}", Summary: "Remove a scope's capacity quota",
|
||||
Response: Removed{}},
|
||||
{Method: "GET", Path: "/api/v1/guard", Summary: "The guardrail policies and where they are attached",
|
||||
Response: GuardView{}},
|
||||
{Method: "POST", Path: "/api/v1/guard/attachments", Summary: "Attach a guardrail policy",
|
||||
Request: GuardAttachmentRequest{}, Response: guard.Attachment{}},
|
||||
{Method: "DELETE", Path: "/api/v1/guard/attachments", Summary: "Detach a guardrail policy",
|
||||
Request: GuardAttachmentRequest{}, Response: guard.Attachment{}},
|
||||
|
||||
// Usage, requests and the record of changes.
|
||||
{Method: "GET", Path: "/api/v1/usage", Summary: "What each group of the tenancy tree spent",
|
||||
Query: []Param{
|
||||
{Name: "by", Description: "org, team or project; team when absent."},
|
||||
{Name: "since", Description: "A duration back from now, like 24h; 24h when absent."},
|
||||
},
|
||||
Response: []ScopeUsageView{}},
|
||||
{Method: "GET", Path: "/api/v1/usage/export", Summary: "Usage totals by period and dimension, as CSV or JSON",
|
||||
Query: []Param{
|
||||
{Name: "from", Description: "A date (2026-09-01) or an RFC 3339 time; the first of this month when absent."},
|
||||
{Name: "to", Description: "A date or an RFC 3339 time; now when absent."},
|
||||
{Name: "period", Description: "hour, day or month; day when absent."},
|
||||
{Name: "by", Description: "Dimensions, comma-separated: org, team, project, user, key, model."},
|
||||
{Name: "format", Description: "json for JSON; CSV otherwise."},
|
||||
},
|
||||
Response: []store.ExportRow{}, CSV: true},
|
||||
{Method: "GET", Path: "/api/v1/requests/{id}", Summary: "What one request went through",
|
||||
Response: RequestView{}},
|
||||
{Method: "GET", Path: "/api/v1/requests/{id}/body", Summary: "A kept request and its answer",
|
||||
Response: store.RequestBody{}},
|
||||
{Method: "POST", Path: "/api/v1/requests/{id}/replay", Summary: "Send a kept request again, to any model",
|
||||
Request: ReplayRequest{}, Response: ReplayView{}},
|
||||
{Method: "GET", Path: "/api/v1/audit", Summary: "Changes made, newest first",
|
||||
Query: []Param{
|
||||
{Name: "since", Description: "How far back: 90m, 24h, 7d; 7d when absent."},
|
||||
{Name: "limit", Type: "integer", Description: "The most events to answer with."},
|
||||
{Name: "actor", Description: "Only changes by this actor."},
|
||||
{Name: "contains", Description: "Only events whose action or target contains this."},
|
||||
},
|
||||
Response: []store.AuditEvent{}},
|
||||
|
||||
// Operations.
|
||||
{Method: "POST", Path: "/api/v1/notify/test", Summary: "Send a test notification to every webhook",
|
||||
Response: []notify.Result{}},
|
||||
{Method: "POST", Path: "/api/v1/metrics/range", Summary: "Several Prometheus range queries at once",
|
||||
Description: "Read from the Prometheus monitoring.prometheus names; configured is false without one.",
|
||||
Request: MetricsRequest{}, Response: MetricsResult{}},
|
||||
}
|
||||
|
||||
// serveOpenAPI answers with the document generated from Routes, as it was
|
||||
// when this binary was built.
|
||||
func serveOpenAPI(w http.ResponseWriter, _ *http.Request) {
|
||||
w.Header().Set("Content-Type", "application/json")
|
||||
_, _ = w.Write(llmgw.AdminOpenAPI)
|
||||
}
|
||||
@@ -0,0 +1,119 @@
|
||||
package adminapi
|
||||
|
||||
import (
|
||||
"net/http"
|
||||
"slices"
|
||||
"strings"
|
||||
"testing"
|
||||
|
||||
"gitea.mynodes.xyz/ilker/llmgw/internal/control/catalog"
|
||||
)
|
||||
|
||||
// patterns records what Register mounts.
|
||||
type patterns []string
|
||||
|
||||
func (p *patterns) HandleFunc(pattern string, _ func(http.ResponseWriter, *http.Request)) {
|
||||
*p = append(*p, pattern)
|
||||
}
|
||||
|
||||
func TestEveryRegisteredEndpointIsInTheRouteTable(t *testing.T) {
|
||||
// The OpenAPI document is generated from Routes, so an endpoint missing
|
||||
// from it is one no client generated from the document can call, and one
|
||||
// in it that is not served is a promise the server breaks.
|
||||
a, _ := setup(t, testModels())
|
||||
var got patterns
|
||||
a.Register(&got)
|
||||
|
||||
table := map[string]bool{}
|
||||
for _, r := range Routes {
|
||||
key := r.Method + " " + r.Path
|
||||
if table[key] {
|
||||
t.Errorf("%s is in Routes twice", key)
|
||||
}
|
||||
table[key] = true
|
||||
}
|
||||
served := map[string]bool{}
|
||||
for _, p := range got {
|
||||
served[p] = true
|
||||
if !table[p] {
|
||||
t.Errorf("%s is registered and not in Routes: describe it there", p)
|
||||
}
|
||||
}
|
||||
for key := range table {
|
||||
if !served[key] {
|
||||
t.Errorf("%s is in Routes and not registered", key)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestEveryRouteSaysWhatItAnswers(t *testing.T) {
|
||||
for _, r := range Routes {
|
||||
if r.Summary == "" || r.Response == nil {
|
||||
t.Errorf("%s %s needs a summary and a response type", r.Method, r.Path)
|
||||
}
|
||||
if r.Request != nil && (r.Method == "GET" || r.Method == "HEAD") {
|
||||
t.Errorf("%s %s reads a body on a GET", r.Method, r.Path)
|
||||
}
|
||||
for _, seg := range strings.Split(strings.Trim(r.Path, "/"), "/") {
|
||||
if !strings.HasPrefix(seg, "{") {
|
||||
continue
|
||||
}
|
||||
found := false
|
||||
for k := range PathParams {
|
||||
if strings.HasSuffix(k, "/"+seg) && strings.Contains(r.Path, k) {
|
||||
found = true
|
||||
}
|
||||
}
|
||||
if !found {
|
||||
t.Errorf("%s %s: %s is not described in PathParams", r.Method, r.Path, seg)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestTheAPIServesItsOwnDescription(t *testing.T) {
|
||||
a, _ := setup(t, testModels())
|
||||
var doc struct {
|
||||
OpenAPI string `json:"openapi"`
|
||||
Paths map[string]map[string]any `json:"paths"`
|
||||
}
|
||||
if code := call(t, a, "GET", "/api/v1/openapi.json", "", &doc); code != 200 {
|
||||
t.Fatalf("status %d", code)
|
||||
}
|
||||
if doc.OpenAPI != "3.1.0" {
|
||||
t.Errorf("openapi %q", doc.OpenAPI)
|
||||
}
|
||||
// What is built in is the document generated when it was last committed;
|
||||
// internal/docgen's test is what fails when that is stale. This checks the
|
||||
// two ends meet: every route the table has is in what is served.
|
||||
for _, r := range Routes {
|
||||
if _, ok := doc.Paths[r.Path][strings.ToLower(r.Method)]; !ok {
|
||||
t.Errorf("the served document has no %s %s", r.Method, r.Path)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestOneModelsDefinitionIsReadByItsNameAlone(t *testing.T) {
|
||||
a, _ := setup(t, testModels())
|
||||
var m catalog.Model
|
||||
if code := call(t, a, "GET", "/api/v1/models/llama", "", &m); code != 200 {
|
||||
t.Fatalf("status %d", code)
|
||||
}
|
||||
if m.Name != "llama" || m.Source != "/m" || len(m.Profiles) != 1 || m.Profiles[0].TP != 8 {
|
||||
t.Errorf("got %+v", m)
|
||||
}
|
||||
if m.Scaling.Min != 2 || m.Scaling.Max != 4 {
|
||||
t.Errorf("scaling %+v", m.Scaling)
|
||||
}
|
||||
if !slices.Equal(m.Aliases, []string{"l"}) {
|
||||
t.Errorf("aliases %v", m.Aliases)
|
||||
}
|
||||
// An alias answering would let a tool that manages "l" believe it exists
|
||||
// when what it found is llama.
|
||||
if code := call(t, a, "GET", "/api/v1/models/l", "", nil); code != http.StatusNotFound {
|
||||
t.Errorf("an alias answered %d", code)
|
||||
}
|
||||
if code := call(t, a, "GET", "/api/v1/models/nothing", "", nil); code != http.StatusNotFound {
|
||||
t.Errorf("a missing model answered %d", code)
|
||||
}
|
||||
}
|
||||
@@ -65,6 +65,20 @@ func (a *API) listOrphans(w http.ResponseWriter, _ *http.Request) {
|
||||
writeJSON(w, http.StatusOK, a.Orphans())
|
||||
}
|
||||
|
||||
// CollectRequest limits a sweep to one node. Empty means every node, which
|
||||
// is the common case after removing a model from the catalog.
|
||||
type CollectRequest struct {
|
||||
Node string `json:"node,omitempty"`
|
||||
}
|
||||
|
||||
// CollectResult is what was deleted on one node, or why nothing was.
|
||||
type CollectResult struct {
|
||||
Node string `json:"node"`
|
||||
Files int `json:"files"`
|
||||
Bytes int64 `json:"bytes"`
|
||||
Error string `json:"error,omitempty"`
|
||||
}
|
||||
|
||||
// collectWeights deletes them.
|
||||
//
|
||||
// A proposal, not an instruction: each node checks every path again before
|
||||
@@ -79,26 +93,16 @@ func (a *API) collectWeights(w http.ResponseWriter, r *http.Request) {
|
||||
return
|
||||
}
|
||||
|
||||
var body struct {
|
||||
// Node limits it to one node. Empty means every node, which is the
|
||||
// common case after removing a model from the catalog.
|
||||
Node string `json:"node,omitempty"`
|
||||
}
|
||||
var body CollectRequest
|
||||
// An empty body is the "all nodes" case and must not be an error.
|
||||
_ = json.NewDecoder(r.Body).Decode(&body)
|
||||
|
||||
type result struct {
|
||||
Node string `json:"node"`
|
||||
Files int `json:"files"`
|
||||
Bytes int64 `json:"bytes"`
|
||||
Error string `json:"error,omitempty"`
|
||||
}
|
||||
out := make([]result, 0)
|
||||
out := make([]CollectResult, 0)
|
||||
for _, o := range a.Orphans() {
|
||||
if body.Node != "" && o.Node != body.Node {
|
||||
continue
|
||||
}
|
||||
res := result{Node: o.Node, Files: len(o.Paths), Bytes: o.Bytes}
|
||||
res := CollectResult{Node: o.Node, Files: len(o.Paths), Bytes: o.Bytes}
|
||||
// A node that has gone since the list was built is reported rather than
|
||||
// failing the whole sweep: the other nodes' space is still worth
|
||||
// freeing, and this one will be offered again next time.
|
||||
|
||||
Reference in new issue
Block a user