Object model
The objects Wingsmith manages, grouped into supply, demand, binding and machinery, and how they relate.
Wingsmith’s objects fall into four groups. Most of the design is in the seams between them. Each object has its own page under Concepts; this page shows the whole and how the parts connect.
The four groups
| Group | Holds | Objects | Mostly |
|---|---|---|---|
| Supply | What capacity exists | Cluster, Node, Device, TopologyDomain, Pool | Observed |
| Demand | What should be running | Artifact, Workload, Deployment, Replica, Endpoint | Declared |
| Binding | Where they meet, and the rules when they cannot | Tenant, Project, Quota, PriorityClass, Policy, Allocation | Declared |
| Machinery | What makes it operable | Component, Operation, Event, CacheEntry | Mixed |
Three kinds of object
- Declared. The plane writes it and the cluster obeys. It syncs down.
- Observed. The cluster writes it and the plane reads it. It syncs up and is copied into Postgres. Each observed object has one writer.
- Operation. Imperative, long-running and able to fail. It is neither of the above.
Operations are the kind that gets skipped. Drain is not a field on a node. It is cordon, evict, wait for in-flight requests, confirm, and possibly time out and force. It has a lifecycle, an actor, a reason and a failure mode, and a draining status flag cannot answer “why is this stuck” or “who did this”. One Operation object with a typed payload covers drain, scale, cordon, reboot and the other long-running acts. See Operations.
Supply: what capacity exists
You do not create GPUs. You enrol clusters, and the operator in each reports what it finds.
| Object | Kind | What it is |
|---|---|---|
| Cluster | Declared entry, observed state | One enrolled Kubernetes cluster. It authenticates with a per-cluster enrolment token (prefix hgro1.). See Clusters. |
| Node | Observed | A machine in a cluster, with conditions, versions and cordon state. |
| Device | Observed | One accelerator, identified by UUID, with health, memory and current allocation. The vendor string maps to a Wingsmith device class such as h100-80gb-sxm. See Devices. |
| TopologyDomain | Observed | Devices sharing an NVLink or NVSwitch fabric, a PCIe root or a NUMA node. |
| Pool | Declared | A provisioning spec: device class, node shape, min and max, labels and taints. |
The unit of capacity is the device, not the node. A node count cannot say that seven of eight GPUs are healthy, or which one is throttling. Topology is an object for the same reason: eight GPUs in one NVLink domain and eight spread across four machines perform very differently for tensor parallelism. Placement uses topology to choose only clusters where a workload that requires one domain fits.
Pool is declared because Wingsmith assumes you own and provision your clusters. If it managed clusters it did not provision, a pool with a min and max would not be a promise it could keep.
Demand: what should be running
| Object | Kind | What it is |
|---|---|---|
| Artifact | Declared | Immutable, content-addressed weights: a base model, fine-tune, quantized derivative or LoRA adapter. It has one digest and one or more storage locations. |
| Workload | Declared, plane-only | What you asked to run, globally: an artifact plus a complete serving configuration, total scale bounds, priority and placement constraints. |
| Deployment | Declared, sent to one cluster | One workload on one cluster, carrying that cluster’s share of the scale. The unit the operator reconciles. |
| Replica | Observed | One running instance of a deployment on named devices, with readiness and engine version. |
| Endpoint | Declared, plane-only | The stable public model name clients call. It resolves to one or more deployments with weights or failover order. |
See Artifacts and workloads, Deployments and Endpoints.
A few rules shape how these fit together:
- A workload is global and a deployment is per cluster. Run a model in Asia and in Europe is one workload and two deployments with one replica each. A workload never goes on the wire. Placement expands it into deployments, and the operator sees only its own cluster’s share.
- Serving configuration belongs to the workload. Engine, quantization, parallelism and context length are hashed into a
serving_digest. The same weights at FP8, TP2 and 32k context and at BF16, TP4 and 128k context need different hardware, so they are two workloads over one artifact. - Only
serviceworkloads are accepted. Thetaskandgangkinds are reserved. - A Wingsmith deployment is not a Kubernetes Deployment. The operator renders each one into one NVIDIA Dynamo
DynamoGraphDeployment. - Endpoint and deployment are separate. An endpoint is a contract clients depend on, and a deployment lives only as long as its workload is placed on that cluster. Separate objects make weighted, canary and blue-green routing a matter of editing endpoint targets.
- Authority is explicit. A deployment is
observed(record and verify, touch nothing) ormanaged(render and converge). That is how an existing workload is tracked without a restart and then adopted.
Binding: tenants, quotas, policy
| Object | Kind | What it is |
|---|---|---|
| Tenant | Declared | An organisation using the installation’s models. It owns endpoints, API keys and the host name its requests arrive on. |
| Project | Declared | A unit inside a tenant. Workloads and quotas attach to projects. |
| Quota | Declared | A device ceiling per project and device class, in one cluster or fleet-wide. |
| PriorityClass | Declared | A named priority with a preemptible flag. Recorded, not yet acted on. |
| Policy | Declared | Placement constraints such as region, residency, device class, cost ceiling and allowed or denied clusters. It attaches to a tenant, endpoint, workload or cluster. |
| Allocation | Observed | The devices currently committed to a replica. |
Placement refuses a deployment that would take a project past its device quota for that class. Quota also records a guaranteed floor and an over-quota weight that nothing acts on yet. See Tenants and projects and Quotas and placement; planned work is on the roadmap.
Machinery: what makes it operable
| Object | Kind | What it is |
|---|---|---|
| Operation | Operation | An imperative, long-running act such as drain, cordon, scale, pause or benchmark. It carries target, requester, reason, phase and result. |
| Component | Declared, observed rollout | Something installed in a cluster and versioned on its own: the operator, agent, exporters. |
| Event | Observed | A fact such as node joined, device degraded or load failed. |
| CacheEntry | Observed | Whether an artifact’s weights are resident on a cluster or node, against the declared warm set. |
The weight cache and the KV or prefix cache are unrelated. Weights are files on disk, declared per cluster as a warm set, with residency observed. KV and prefix cache are attention state kept by the engine, and they are configured on the workload.
How the objects relate
- A Policy attaches to a tenant, endpoint, workload or cluster, and a PriorityClass is referenced by workloads.
- An Operation targets a node, device, workload, deployment or cluster.
- A Component is declared per cluster, and an Event can be about any object.
- A CacheEntry is per artifact and cluster, optionally per node.
From workload to traffic
Submit
You create a workload from the console or hgr. The plane checks that the artifact and project exist and that the serving configuration is valid.
Place
Placement reads observed capacity and declared quota and policy, picks one or more clusters, and derives each cluster’s share of the scale.
Create deployments
The plane creates one deployment per cluster with authority: managed, and the hub pushes each to the operator in that cluster.
Reconcile
The operator stores the deployment in a SyncedResource custom resource, so desired state survives operator restarts and plane outages. It renders a DynamoGraphDeployment and waits for it to come up.
Report
The operator reports replicas. The plane copies them into Postgres so the console shows them without asking each cluster.
Route
If an endpoint targets the deployment, the plane updates the routing table. The gateway picks it up on its next refresh, and requests for that model name reach the new cluster.
IDs
Every id is a type prefix followed by a lowercase Crockford base32 ULID. Declared ids are minted by the plane. The cluster mints the ids of the nodes, devices and topology domains it discovers.
| Prefix | Object | Prefix | Object |
|---|---|---|---|
clu_ | Cluster | ten_ | Tenant |
nod_ | Node | prj_ | Project |
dev_ | Device | qta_ | Quota |
tpd_ | TopologyDomain | prc_ | PriorityClass |
pol_ | Pool | plc_ | Policy |
art_ | Artifact | alc_ | Allocation |
wkl_ | Workload | opr_ | Operation |
dep_ | Deployment | cmp_ | Component |
rep_ | Replica | evt_ | Event |
end_ | Endpoint |
The serving digest is not an id of this kind. It is svg_ followed by a SHA-256 hex digest of the serving configuration.