Replace a Function
const url = 'https://example.com/apis/nodus.dev/v1/namespaces/example/functions/example';const options = { method: 'PUT', headers: {'Content-Type': 'application/json'}, body: '{"apiVersion":"example","kind":"example","metadata":{"annotations":{"additionalProperty":"example"},"creationTimestamp":"example","deletionGracePeriodSeconds":1,"deletionTimestamp":"example","finalizers":["example"],"generateName":"example","generation":1,"labels":{"additionalProperty":"example"},"managedFields":[{"apiVersion":"example","fieldsType":"example","fieldsV1":{"additionalProperty":"example"},"manager":"example","operation":"example","subresource":"example","time":"example"}],"name":"example","namespace":"example","ownerReferences":[{"apiVersion":"example","blockOwnerDeletion":true,"controller":true,"kind":"example","name":"example","uid":"example"}],"resourceVersion":"example","selfLink":"example","uid":"example"},"spec":{"args":["example"],"cluster":{"launcher":"example","network":"example","size":1,"transport":"example"},"code":{"blob":"example","cls":{"methods":["example"],"name":"example"},"module":"example","qualname":"example"},"command":["example"],"connections":["example"],"env":[{"name":"example","value":"example","valueFrom":{"secretKeyRef":{"key":"example","name":"example"}}}],"image":"example","imagePullSecrets":["example"],"imageRef":"example","initCommand":{"command":["example"],"timeout":"example"},"maxCostUSD":"example","network":{"egress":{"allow":["example"],"policy":"example","presets":["example"]}},"placement":{"dedicated":true,"interruptible":"example","maxRateUSDPerHour":"example","offerings":["example"],"pool":"example","profile":"example","queueTimeout":"example","regions":["example"]},"python":"example","recovery":{"checkpoint":{"format":"example","integration":"example","interval":"example","maxSize":"example","paths":["example"],"retainAfterFinish":"example"},"continuity":"example","maxAttempts":1,"minProgressDuration":"example","onInterruption":"example"},"resources":{"cpu":"example","disk":"example","gpu":{"count":1,"exact":true,"interconnect":"example","minMemory":"example","type":["example"]},"memory":"example","nodes":1},"retries":{"backoffCoefficient":1,"initialDelay":"example","maxDelay":"example","maxRetries":1},"scaling":{"maxWorkers":1,"minWorkers":1,"scaledownWindow":"example","targetConcurrency":1},"secrets":[{"name":"example","version":1}],"serviceAccountName":"example","sidecars":[{"command":["example"],"env":[{"name":"example","value":"example","valueFrom":{"secretKeyRef":{"key":"example","name":"example"}}}],"image":"example","name":"example","startupTimeout":"example"}],"state":"example","timeout":"example","volumes":[{"mountPath":"example","readOnly":true,"revision":1,"volume":"example"}],"workingDir":"example"},"status":{"appVersion":1,"conditions":[{"lastTransitionTime":"example","message":"example","observedGeneration":1,"reason":"example","status":"example","type":"example"}],"cost":{"bySegment":{"bootUSD":"example","coveredByNodus":["example"],"restoreUSD":"example","runningUSD":"example","teardownUSD":"example"},"final":true,"fundedUntilTime":"example","heldUSD":"example","limitUSD":"example","rateUSDPerHour":"example","totalUSD":"example"},"estimate":{"assemblyBoundUSD":"example","blockingReasons":[{"code":"example","fix":"example","message":"example"}],"concurrentHoldUSD":"example","costUSD":{"p50":"example","p90":"example"},"gangHoldUSD":"example","holdUSD":"example","minimumChargeUSD":"example","overheadUSD":{"p50":"example","p90":"example"},"placementPreview":{"explain":"example","interruptible":true,"offering":"example","regionClass":"example","warmReuse":true},"pricebookVersion":"example","rateUSDPerHour":"example","startup":{"cold":{"p50":"example","p90":"example"},"warm":{"p50":"example","p90":"example"}},"topology":"example","validUntil":"example","warnings":[{"code":"example","message":"example"}]},"handledRequests":{"additionalProperty":"example"},"image":{"digest":"example","reference":"example","user":"example"},"message":"example","observedGeneration":1,"phase":"example","queue":{"queued":1,"running":1},"reason":"example","workers":{"busy":1,"draining":1,"idle":1,"ready":1,"starting":1}}}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request PUT \ --url https://example.com/apis/nodus.dev/v1/namespaces/example/functions/example \ --header 'Content-Type: application/json' \ --data '{ "apiVersion": "example", "kind": "example", "metadata": { "annotations": { "additionalProperty": "example" }, "creationTimestamp": "example", "deletionGracePeriodSeconds": 1, "deletionTimestamp": "example", "finalizers": [ "example" ], "generateName": "example", "generation": 1, "labels": { "additionalProperty": "example" }, "managedFields": [ { "apiVersion": "example", "fieldsType": "example", "fieldsV1": { "additionalProperty": "example" }, "manager": "example", "operation": "example", "subresource": "example", "time": "example" } ], "name": "example", "namespace": "example", "ownerReferences": [ { "apiVersion": "example", "blockOwnerDeletion": true, "controller": true, "kind": "example", "name": "example", "uid": "example" } ], "resourceVersion": "example", "selfLink": "example", "uid": "example" }, "spec": { "args": [ "example" ], "cluster": { "launcher": "example", "network": "example", "size": 1, "transport": "example" }, "code": { "blob": "example", "cls": { "methods": [ "example" ], "name": "example" }, "module": "example", "qualname": "example" }, "command": [ "example" ], "connections": [ "example" ], "env": [ { "name": "example", "value": "example", "valueFrom": { "secretKeyRef": { "key": "example", "name": "example" } } } ], "image": "example", "imagePullSecrets": [ "example" ], "imageRef": "example", "initCommand": { "command": [ "example" ], "timeout": "example" }, "maxCostUSD": "example", "network": { "egress": { "allow": [ "example" ], "policy": "example", "presets": [ "example" ] } }, "placement": { "dedicated": true, "interruptible": "example", "maxRateUSDPerHour": "example", "offerings": [ "example" ], "pool": "example", "profile": "example", "queueTimeout": "example", "regions": [ "example" ] }, "python": "example", "recovery": { "checkpoint": { "format": "example", "integration": "example", "interval": "example", "maxSize": "example", "paths": [ "example" ], "retainAfterFinish": "example" }, "continuity": "example", "maxAttempts": 1, "minProgressDuration": "example", "onInterruption": "example" }, "resources": { "cpu": "example", "disk": "example", "gpu": { "count": 1, "exact": true, "interconnect": "example", "minMemory": "example", "type": [ "example" ] }, "memory": "example", "nodes": 1 }, "retries": { "backoffCoefficient": 1, "initialDelay": "example", "maxDelay": "example", "maxRetries": 1 }, "scaling": { "maxWorkers": 1, "minWorkers": 1, "scaledownWindow": "example", "targetConcurrency": 1 }, "secrets": [ { "name": "example", "version": 1 } ], "serviceAccountName": "example", "sidecars": [ { "command": [ "example" ], "env": [ { "name": "example", "value": "example", "valueFrom": { "secretKeyRef": { "key": "example", "name": "example" } } } ], "image": "example", "name": "example", "startupTimeout": "example" } ], "state": "example", "timeout": "example", "volumes": [ { "mountPath": "example", "readOnly": true, "revision": 1, "volume": "example" } ], "workingDir": "example" }, "status": { "appVersion": 1, "conditions": [ { "lastTransitionTime": "example", "message": "example", "observedGeneration": 1, "reason": "example", "status": "example", "type": "example" } ], "cost": { "bySegment": { "bootUSD": "example", "coveredByNodus": [ "example" ], "restoreUSD": "example", "runningUSD": "example", "teardownUSD": "example" }, "final": true, "fundedUntilTime": "example", "heldUSD": "example", "limitUSD": "example", "rateUSDPerHour": "example", "totalUSD": "example" }, "estimate": { "assemblyBoundUSD": "example", "blockingReasons": [ { "code": "example", "fix": "example", "message": "example" } ], "concurrentHoldUSD": "example", "costUSD": { "p50": "example", "p90": "example" }, "gangHoldUSD": "example", "holdUSD": "example", "minimumChargeUSD": "example", "overheadUSD": { "p50": "example", "p90": "example" }, "placementPreview": { "explain": "example", "interruptible": true, "offering": "example", "regionClass": "example", "warmReuse": true }, "pricebookVersion": "example", "rateUSDPerHour": "example", "startup": { "cold": { "p50": "example", "p90": "example" }, "warm": { "p50": "example", "p90": "example" } }, "topology": "example", "validUntil": "example", "warnings": [ { "code": "example", "message": "example" } ] }, "handledRequests": { "additionalProperty": "example" }, "image": { "digest": "example", "reference": "example", "user": "example" }, "message": "example", "observedGeneration": 1, "phase": "example", "queue": { "queued": 1, "running": 1 }, "reason": "example", "workers": { "busy": 1, "draining": 1, "idle": 1, "ready": 1, "starting": 1 } } }'Parameters
Section titled “ Parameters ”Path Parameters
Section titled “ Path Parameters ”The project.
The object’s name.
Query Parameters
Section titled “ Query Parameters ”Header Parameters
Section titled “ Header Parameters ”Request Bodyrequired
Section titled “ Request Bodyrequired ”Function is a deployed Python function served by a pool of warm workers. .remote(), .spawn() and .map() create FunctionCalls, and the shared worker pool sizes the worker attempts between scaling.minWorkers and scaling.maxWorkers.
object
object
object
object
object
object
object
FunctionSpec describes a Function. Every field is mutable: a change to code, image or resources rolls the workers, and in-flight calls finish on the old ones. maxCostUSD can only be raised.
object
FunctionCluster is spec.cluster (Beta).
object
Launcher is Plain for @nodus.clustered.
Network is the gang network placement.
Size is the number of nodes of the gang.
Transport is the gang transport.
FunctionCode locates the function the worker runs.
object
Blob is the content-addressed code archive shared by the App’s members.
FunctionClass describes an @app.cls class.
object
Methods are the @nodus.method() names a call may name (at most 128).
Name is the class name.
Module is the importable module path.
Qualname is the qualified name of the function or class in the module.
EnvVar is one environment variable: a literal value or a Secret key.
object
Name matches ^[A-Za-z_][A-Za-z0-9_]*$.
Value is the literal value.
EnvVarSource names where an env value comes from.
object
SecretKeySelector selects one key of a Secret.
object
Key is the key within it.
Name is the Secret.
InitCommand is a preflight run before the command.
object
Command is the argv.
Timeout is at most 30m.
MaxCostUSD caps what the Function’s workers may spend in total. It can only be raised.
Network sets egress for the container.
object
Egress is the outbound network policy.
object
Allow lists DNS names or *.suffix patterns (AllowList only; at most 128).
Policy is Deny, AllowList or Open.
Presets add curated host lists such as python-packages or huggingface.
Placement constrains where work may run.
object
Dedicated is reserved; only true is accepted.
Interruptible is Never, Allow (the scheduler decides by expected cost) or Prefer.
MaxRateUSDPerHour filters out offerings above this customer rate.
Offerings restricts placement to these Offerings.
Pool is a BYOC Pool in the project.
Profile is Balanced, Cost or Speed.
QueueTimeout is how long the Job may wait for capacity before failing with CapacityUnavailable (default 24h; 0s waits forever).
Regions are region classes (us, eu, …); empty means any.
Python is the interpreter minor version of the image, 3.10 to 3.13. A caller on another minor gets Invalid.
Recovery says how progress survives lost capacity.
object
CheckpointPolicy configures checkpoints.
object
Format is Snapshot, or Dcp for torch.distributed.checkpoint (the default for distributed Jobs).
Integration is Auto, None or HFTrainer.
Interval is auto or a duration from 1m to 6h.
MaxSize is checked before upload (default 1Ti, at most 2Ti).
Paths are saved together in one checkpoint (at most 64; default /nodus/state).
RetainAfterFinish keeps checkpoints this long after the Job finishes (default 168h).
Continuity is Checkpointed (restore the latest checkpoint), Restartable (progress cursor) or Ephemeral.
MaxAttempts is how many infrastructure replacements each index may use (1–32; gangs count restarts).
MinProgressDuration is the run time that counts as progress (default 2m).
OnInterruption is Resume, or Fail to fail instead of recovering or suspending.
Resources are capacity floors. For GPU work the offering’s host shape applies if larger.
object
CPU is the vCPU floor.
Disk is the ephemeral disk floor.
GPURequest asks for accelerators. A family (H100) matches any of its variants and never another family.
object
Count is the GPUs per node: 1, 2, 4 or 8.
Exact pins the exact variant instead of matching the family.
Interconnect is Any or NVLink.
MinMemory is the per-GPU memory floor.
Type lists 1–8 accelerator ids or families from the catalog.
Memory is the host memory floor.
Nodes above 1 is shorthand for spec.distributed.nodes and is stored in that form.
FunctionRetries is spec.retries.
object
BackoffCoefficient multiplies the delay after each retry, 1 to 10 (default 2.0).
InitialDelay is the wait before the first retry (default 1s).
MaxDelay caps the delay (default 60s).
MaxRetries is how many times a call that raised is retried, 0 to 10.
FunctionScaling is spec.scaling.
object
MaxWorkers bounds the pool, 1 to 1000 (default 10).
MinWorkers stay warm even when idle, 0 to maxWorkers; an idle one is billed as warm capacity.
ScaledownWindow is how long an idle worker above minWorkers stays, 0s to 20m (default 60s).
TargetConcurrency is the calls one worker runs at once, 1 to 1000 (default 1).
SecretMount mounts one Secret, optionally pinned to a version. The bare name is accepted on write.
object
Name is the Secret.
Version pins a version; unset pins the latest at admission.
Sidecar is a helper container with native-sidecar semantics.
object
Command is the sidecar’s argv.
Env adds environment variables.
EnvVar is one environment variable: a literal value or a Secret key.
object
Name matches ^[A-Za-z_][A-Za-z0-9_]*$.
Value is the literal value.
EnvVarSource names where an env value comes from.
object
SecretKeySelector selects one key of a Secret.
object
Key is the key within it.
Name is the Secret.
Image defaults to the Job’s image.
Name is unique within the Job.
StartupTimeout bounds how long the sidecar may take to become ready.
State is the desired state: Running (the default) or Stopped, which drains the workers to zero while new calls queue.
Timeout is the limit of one call, 1s to 24h (default 300s).
VolumeMount mounts a Volume.
object
MountPath is the absolute mount point; system paths are refused.
ReadOnly mounts it read-only.
Revision pins a revision; only with readOnly.
Volume names the Volume.
FunctionStatus is what Nodus observed about a Function.
object
AppVersion is the App version that last deployed this Function.
Conditions are Ready (WorkersReady) and Funded.
object
Cost is status.cost on every kind that spends money. It is a display copy of the ledger: amounts are decimal USD strings, and nothing is charged from these fields.
object
CostSegments splits a charge by billing segment.
object
BootUSD is the charge from the start of billing until the program started.
CoveredByNodus lists the segments (Boot, Running, Restore, Teardown) with time Nodus paid for instead of charging it, such as the start and teardown of a run that failed because of Nodus.
RestoreUSD is the charge for bringing a replacement up after capacity was lost.
RunningUSD is the charge while the program ran.
TeardownUSD is the charge from stop until deletion was confirmed, with the billing increment.
Final is true once the final charge has posted.
FundedUntilTime is when the current holds stop paying for the object.
HeldUSD is what is currently held for it.
LimitUSD is the object’s maxCostUSD, if it has one.
RateUSDPerHour is the sum of the hourly rates of its capacity that is still billing.
TotalUSD is what has been charged for this object so far.
Estimate is returned in status.estimate by a dry-run (?dryRun=All) and on create for every compute kind (ADR-031). Amounts are decimal USD strings; the ETag of the dry-run response binds a later create to it.
object
AssemblyBoundUSD is the most a multi-node Job can cost if its members never assemble.
BlockingReasons say why a real create would fail now, with the amounts and a fix.
BlockingReason says why a create would fail now.
object
Code is the error code the create would return, for example InsufficientCredits.
Fix says what to do.
Message states the reason with the amounts involved.
ConcurrentHoldUSD is the total of the holds for every slot that starts at once.
USDBand is a median and a 90th-percentile amount in USD.
object
P50 is the median amount.
P90 is the 90th-percentile amount.
GangHoldUSD is the total of the member holds of a multi-node Job.
HoldUSD is the first hold that must fit your balance, every matching Budget and the object’s own cap.
MinimumChargeUSD is the billing increment rounding charged once per allocation.
USDBand is a median and a 90th-percentile amount in USD.
object
P50 is the median amount.
P90 is the 90th-percentile amount.
PlacementPreview is the customer-safe description of the capacity a create would use.
object
Explain is the scheduler’s explanation, the same shape as Attempt status.placement.explain.
Interruptible reports whether the capacity can be reclaimed.
Offering is the offering id, for example h100-sxm-80g-x8-us.
RegionClass is the region class of the offering.
WarmReuse reports whether warm capacity would be reused.
PricebookVersion is the price book the estimate used.
RateUSDPerHour is the hourly rate of the chosen capacity.
StartupEstimate is the expected time to start.
object
DurationBand is a median and a 90th-percentile duration, as Go duration strings.
object
P50 is the median duration.
P90 is the 90th-percentile duration.
DurationBand is a median and a 90th-percentile duration, as Go duration strings.
object
P50 is the median duration.
P90 is the 90th-percentile duration.
Topology is the resolved multi-node topology of a gang Job.
ValidUntil is when the prices this estimate used stop being current. A create bound by If-Match is admitted after it too, and never placed above rateUSDPerHour plus 10 %.
Warnings are non-blocking notes, for example ColdStart or InterruptibleSelected.
EstimateWarning is a non-blocking note on an estimate.
object
Code is the CamelCase warning code.
Message explains the warning.
HandledRequests records the restart requests the controller acted on.
object
ImageStatus is the pinned image.
object
Digest is the pinned digest.
Reference is the image as written.
User is the user the image’s config runs its process as (root when it names none). Only an image that runs as root is placed on offerings that start the Nodus node agent inside the image itself.
Message explains the phase in a sentence.
ObservedGeneration is the spec generation this status reflects.
Phase is the lifecycle phase, from the long-running vocabulary.
FunctionQueue is status.queue.
object
Queued calls wait for a worker.
Running calls are on a worker.
Reason is the machine-readable reason for the phase.
FunctionWorkers is status.workers.
object
Busy workers run at least one call.
Draining workers finish their calls and stop.
Idle workers run none.
Ready workers are claiming calls.
Starting workers are placed but not claiming yet.
Example generated
{ "apiVersion": "example", "kind": "example", "metadata": { "annotations": { "additionalProperty": "example" }, "creationTimestamp": "example", "deletionGracePeriodSeconds": 1, "deletionTimestamp": "example", "finalizers": [ "example" ], "generateName": "example", "generation": 1, "labels": { "additionalProperty": "example" }, "managedFields": [ { "apiVersion": "example", "fieldsType": "example", "fieldsV1": { "additionalProperty": "example" }, "manager": "example", "operation": "example", "subresource": "example", "time": "example" } ], "name": "example", "namespace": "example", "ownerReferences": [ { "apiVersion": "example", "blockOwnerDeletion": true, "controller": true, "kind": "example", "name": "example", "uid": "example" } ], "resourceVersion": "example", "selfLink": "example", "uid": "example" }, "spec": { "args": [ "example" ], "cluster": { "launcher": "example", "network": "example", "size": 1, "transport": "example" }, "code": { "blob": "example", "cls": { "methods": [ "example" ], "name": "example" }, "module": "example", "qualname": "example" }, "command": [ "example" ], "connections": [ "example" ], "env": [ { "name": "example", "value": "example", "valueFrom": { "secretKeyRef": { "key": "example", "name": "example" } } } ], "image": "example", "imagePullSecrets": [ "example" ], "imageRef": "example", "initCommand": { "command": [ "example" ], "timeout": "example" }, "maxCostUSD": "example", "network": { "egress": { "allow": [ "example" ], "policy": "example", "presets": [ "example" ] } }, "placement": { "dedicated": true, "interruptible": "example", "maxRateUSDPerHour": "example", "offerings": [ "example" ], "pool": "example", "profile": "example", "queueTimeout": "example", "regions": [ "example" ] }, "python": "example", "recovery": { "checkpoint": { "format": "example", "integration": "example", "interval": "example", "maxSize": "example", "paths": [ "example" ], "retainAfterFinish": "example" }, "continuity": "example", "maxAttempts": 1, "minProgressDuration": "example", "onInterruption": "example" }, "resources": { "cpu": "example", "disk": "example", "gpu": { "count": 1, "exact": true, "interconnect": "example", "minMemory": "example", "type": [ "example" ] }, "memory": "example", "nodes": 1 }, "retries": { "backoffCoefficient": 1, "initialDelay": "example", "maxDelay": "example", "maxRetries": 1 }, "scaling": { "maxWorkers": 1, "minWorkers": 1, "scaledownWindow": "example", "targetConcurrency": 1 }, "secrets": [ { "name": "example", "version": 1 } ], "serviceAccountName": "example", "sidecars": [ { "command": [ "example" ], "env": [ { "name": "example", "value": "example", "valueFrom": { "secretKeyRef": { "key": "example", "name": "example" } } } ], "image": "example", "name": "example", "startupTimeout": "example" } ], "state": "example", "timeout": "example", "volumes": [ { "mountPath": "example", "readOnly": true, "revision": 1, "volume": "example" } ], "workingDir": "example" }, "status": { "appVersion": 1, "conditions": [ { "lastTransitionTime": "example", "message": "example", "observedGeneration": 1, "reason": "example", "status": "example", "type": "example" } ], "cost": { "bySegment": { "bootUSD": "example", "coveredByNodus": [ "example" ], "restoreUSD": "example", "runningUSD": "example", "teardownUSD": "example" }, "final": true, "fundedUntilTime": "example", "heldUSD": "example", "limitUSD": "example", "rateUSDPerHour": "example", "totalUSD": "example" }, "estimate": { "assemblyBoundUSD": "example", "blockingReasons": [ { "code": "example", "fix": "example", "message": "example" } ], "concurrentHoldUSD": "example", "costUSD": { "p50": "example", "p90": "example" }, "gangHoldUSD": "example", "holdUSD": "example", "minimumChargeUSD": "example", "overheadUSD": { "p50": "example", "p90": "example" }, "placementPreview": { "explain": "example", "interruptible": true, "offering": "example", "regionClass": "example", "warmReuse": true }, "pricebookVersion": "example", "rateUSDPerHour": "example", "startup": { "cold": { "p50": "example", "p90": "example" }, "warm": { "p50": "example", "p90": "example" } }, "topology": "example", "validUntil": "example", "warnings": [ { "code": "example", "message": "example" } ] }, "handledRequests": { "additionalProperty": "example" }, "image": { "digest": "example", "reference": "example", "user": "example" }, "message": "example", "observedGeneration": 1, "phase": "example", "queue": { "queued": 1, "running": 1 }, "reason": "example", "workers": { "busy": 1, "draining": 1, "idle": 1, "ready": 1, "starting": 1 } }}Responses
Section titled “ Responses ”OK
Function is a deployed Python function served by a pool of warm workers. .remote(), .spawn() and .map() create FunctionCalls, and the shared worker pool sizes the worker attempts between scaling.minWorkers and scaling.maxWorkers.
object
object
object
object
object
object
object
FunctionSpec describes a Function. Every field is mutable: a change to code, image or resources rolls the workers, and in-flight calls finish on the old ones. maxCostUSD can only be raised.
object
FunctionCluster is spec.cluster (Beta).
object
Launcher is Plain for @nodus.clustered.
Network is the gang network placement.
Size is the number of nodes of the gang.
Transport is the gang transport.
FunctionCode locates the function the worker runs.
object
Blob is the content-addressed code archive shared by the App’s members.
FunctionClass describes an @app.cls class.
object
Methods are the @nodus.method() names a call may name (at most 128).
Name is the class name.
Module is the importable module path.
Qualname is the qualified name of the function or class in the module.
EnvVar is one environment variable: a literal value or a Secret key.
object
Name matches ^[A-Za-z_][A-Za-z0-9_]*$.
Value is the literal value.
EnvVarSource names where an env value comes from.
object
SecretKeySelector selects one key of a Secret.
object
Key is the key within it.
Name is the Secret.
InitCommand is a preflight run before the command.
object
Command is the argv.
Timeout is at most 30m.
MaxCostUSD caps what the Function’s workers may spend in total. It can only be raised.
Network sets egress for the container.
object
Egress is the outbound network policy.
object
Allow lists DNS names or *.suffix patterns (AllowList only; at most 128).
Policy is Deny, AllowList or Open.
Presets add curated host lists such as python-packages or huggingface.
Placement constrains where work may run.
object
Dedicated is reserved; only true is accepted.
Interruptible is Never, Allow (the scheduler decides by expected cost) or Prefer.
MaxRateUSDPerHour filters out offerings above this customer rate.
Offerings restricts placement to these Offerings.
Pool is a BYOC Pool in the project.
Profile is Balanced, Cost or Speed.
QueueTimeout is how long the Job may wait for capacity before failing with CapacityUnavailable (default 24h; 0s waits forever).
Regions are region classes (us, eu, …); empty means any.
Python is the interpreter minor version of the image, 3.10 to 3.13. A caller on another minor gets Invalid.
Recovery says how progress survives lost capacity.
object
CheckpointPolicy configures checkpoints.
object
Format is Snapshot, or Dcp for torch.distributed.checkpoint (the default for distributed Jobs).
Integration is Auto, None or HFTrainer.
Interval is auto or a duration from 1m to 6h.
MaxSize is checked before upload (default 1Ti, at most 2Ti).
Paths are saved together in one checkpoint (at most 64; default /nodus/state).
RetainAfterFinish keeps checkpoints this long after the Job finishes (default 168h).
Continuity is Checkpointed (restore the latest checkpoint), Restartable (progress cursor) or Ephemeral.
MaxAttempts is how many infrastructure replacements each index may use (1–32; gangs count restarts).
MinProgressDuration is the run time that counts as progress (default 2m).
OnInterruption is Resume, or Fail to fail instead of recovering or suspending.
Resources are capacity floors. For GPU work the offering’s host shape applies if larger.
object
CPU is the vCPU floor.
Disk is the ephemeral disk floor.
GPURequest asks for accelerators. A family (H100) matches any of its variants and never another family.
object
Count is the GPUs per node: 1, 2, 4 or 8.
Exact pins the exact variant instead of matching the family.
Interconnect is Any or NVLink.
MinMemory is the per-GPU memory floor.
Type lists 1–8 accelerator ids or families from the catalog.
Memory is the host memory floor.
Nodes above 1 is shorthand for spec.distributed.nodes and is stored in that form.
FunctionRetries is spec.retries.
object
BackoffCoefficient multiplies the delay after each retry, 1 to 10 (default 2.0).
InitialDelay is the wait before the first retry (default 1s).
MaxDelay caps the delay (default 60s).
MaxRetries is how many times a call that raised is retried, 0 to 10.
FunctionScaling is spec.scaling.
object
MaxWorkers bounds the pool, 1 to 1000 (default 10).
MinWorkers stay warm even when idle, 0 to maxWorkers; an idle one is billed as warm capacity.
ScaledownWindow is how long an idle worker above minWorkers stays, 0s to 20m (default 60s).
TargetConcurrency is the calls one worker runs at once, 1 to 1000 (default 1).
SecretMount mounts one Secret, optionally pinned to a version. The bare name is accepted on write.
object
Name is the Secret.
Version pins a version; unset pins the latest at admission.
Sidecar is a helper container with native-sidecar semantics.
object
Command is the sidecar’s argv.
Env adds environment variables.
EnvVar is one environment variable: a literal value or a Secret key.
object
Name matches ^[A-Za-z_][A-Za-z0-9_]*$.
Value is the literal value.
EnvVarSource names where an env value comes from.
object
SecretKeySelector selects one key of a Secret.
object
Key is the key within it.
Name is the Secret.
Image defaults to the Job’s image.
Name is unique within the Job.
StartupTimeout bounds how long the sidecar may take to become ready.
State is the desired state: Running (the default) or Stopped, which drains the workers to zero while new calls queue.
Timeout is the limit of one call, 1s to 24h (default 300s).
VolumeMount mounts a Volume.
object
MountPath is the absolute mount point; system paths are refused.
ReadOnly mounts it read-only.
Revision pins a revision; only with readOnly.
Volume names the Volume.
FunctionStatus is what Nodus observed about a Function.
object
AppVersion is the App version that last deployed this Function.
Conditions are Ready (WorkersReady) and Funded.
object
Cost is status.cost on every kind that spends money. It is a display copy of the ledger: amounts are decimal USD strings, and nothing is charged from these fields.
object
CostSegments splits a charge by billing segment.
object
BootUSD is the charge from the start of billing until the program started.
CoveredByNodus lists the segments (Boot, Running, Restore, Teardown) with time Nodus paid for instead of charging it, such as the start and teardown of a run that failed because of Nodus.
RestoreUSD is the charge for bringing a replacement up after capacity was lost.
RunningUSD is the charge while the program ran.
TeardownUSD is the charge from stop until deletion was confirmed, with the billing increment.
Final is true once the final charge has posted.
FundedUntilTime is when the current holds stop paying for the object.
HeldUSD is what is currently held for it.
LimitUSD is the object’s maxCostUSD, if it has one.
RateUSDPerHour is the sum of the hourly rates of its capacity that is still billing.
TotalUSD is what has been charged for this object so far.
Estimate is returned in status.estimate by a dry-run (?dryRun=All) and on create for every compute kind (ADR-031). Amounts are decimal USD strings; the ETag of the dry-run response binds a later create to it.
object
AssemblyBoundUSD is the most a multi-node Job can cost if its members never assemble.
BlockingReasons say why a real create would fail now, with the amounts and a fix.
BlockingReason says why a create would fail now.
object
Code is the error code the create would return, for example InsufficientCredits.
Fix says what to do.
Message states the reason with the amounts involved.
ConcurrentHoldUSD is the total of the holds for every slot that starts at once.
USDBand is a median and a 90th-percentile amount in USD.
object
P50 is the median amount.
P90 is the 90th-percentile amount.
GangHoldUSD is the total of the member holds of a multi-node Job.
HoldUSD is the first hold that must fit your balance, every matching Budget and the object’s own cap.
MinimumChargeUSD is the billing increment rounding charged once per allocation.
USDBand is a median and a 90th-percentile amount in USD.
object
P50 is the median amount.
P90 is the 90th-percentile amount.
PlacementPreview is the customer-safe description of the capacity a create would use.
object
Explain is the scheduler’s explanation, the same shape as Attempt status.placement.explain.
Interruptible reports whether the capacity can be reclaimed.
Offering is the offering id, for example h100-sxm-80g-x8-us.
RegionClass is the region class of the offering.
WarmReuse reports whether warm capacity would be reused.
PricebookVersion is the price book the estimate used.
RateUSDPerHour is the hourly rate of the chosen capacity.
StartupEstimate is the expected time to start.
object
DurationBand is a median and a 90th-percentile duration, as Go duration strings.
object
P50 is the median duration.
P90 is the 90th-percentile duration.
DurationBand is a median and a 90th-percentile duration, as Go duration strings.
object
P50 is the median duration.
P90 is the 90th-percentile duration.
Topology is the resolved multi-node topology of a gang Job.
ValidUntil is when the prices this estimate used stop being current. A create bound by If-Match is admitted after it too, and never placed above rateUSDPerHour plus 10 %.
Warnings are non-blocking notes, for example ColdStart or InterruptibleSelected.
EstimateWarning is a non-blocking note on an estimate.
object
Code is the CamelCase warning code.
Message explains the warning.
HandledRequests records the restart requests the controller acted on.
object
ImageStatus is the pinned image.
object
Digest is the pinned digest.
Reference is the image as written.
User is the user the image’s config runs its process as (root when it names none). Only an image that runs as root is placed on offerings that start the Nodus node agent inside the image itself.
Message explains the phase in a sentence.
ObservedGeneration is the spec generation this status reflects.
Phase is the lifecycle phase, from the long-running vocabulary.
FunctionQueue is status.queue.
object
Queued calls wait for a worker.
Running calls are on a worker.
Reason is the machine-readable reason for the phase.
FunctionWorkers is status.workers.
object
Busy workers run at least one call.
Draining workers finish their calls and stop.
Idle workers run none.
Ready workers are claiming calls.
Starting workers are placed but not claiming yet.
Example generated
{ "apiVersion": "example", "kind": "example", "metadata": { "annotations": { "additionalProperty": "example" }, "creationTimestamp": "example", "deletionGracePeriodSeconds": 1, "deletionTimestamp": "example", "finalizers": [ "example" ], "generateName": "example", "generation": 1, "labels": { "additionalProperty": "example" }, "managedFields": [ { "apiVersion": "example", "fieldsType": "example", "fieldsV1": { "additionalProperty": "example" }, "manager": "example", "operation": "example", "subresource": "example", "time": "example" } ], "name": "example", "namespace": "example", "ownerReferences": [ { "apiVersion": "example", "blockOwnerDeletion": true, "controller": true, "kind": "example", "name": "example", "uid": "example" } ], "resourceVersion": "example", "selfLink": "example", "uid": "example" }, "spec": { "args": [ "example" ], "cluster": { "launcher": "example", "network": "example", "size": 1, "transport": "example" }, "code": { "blob": "example", "cls": { "methods": [ "example" ], "name": "example" }, "module": "example", "qualname": "example" }, "command": [ "example" ], "connections": [ "example" ], "env": [ { "name": "example", "value": "example", "valueFrom": { "secretKeyRef": { "key": "example", "name": "example" } } } ], "image": "example", "imagePullSecrets": [ "example" ], "imageRef": "example", "initCommand": { "command": [ "example" ], "timeout": "example" }, "maxCostUSD": "example", "network": { "egress": { "allow": [ "example" ], "policy": "example", "presets": [ "example" ] } }, "placement": { "dedicated": true, "interruptible": "example", "maxRateUSDPerHour": "example", "offerings": [ "example" ], "pool": "example", "profile": "example", "queueTimeout": "example", "regions": [ "example" ] }, "python": "example", "recovery": { "checkpoint": { "format": "example", "integration": "example", "interval": "example", "maxSize": "example", "paths": [ "example" ], "retainAfterFinish": "example" }, "continuity": "example", "maxAttempts": 1, "minProgressDuration": "example", "onInterruption": "example" }, "resources": { "cpu": "example", "disk": "example", "gpu": { "count": 1, "exact": true, "interconnect": "example", "minMemory": "example", "type": [ "example" ] }, "memory": "example", "nodes": 1 }, "retries": { "backoffCoefficient": 1, "initialDelay": "example", "maxDelay": "example", "maxRetries": 1 }, "scaling": { "maxWorkers": 1, "minWorkers": 1, "scaledownWindow": "example", "targetConcurrency": 1 }, "secrets": [ { "name": "example", "version": 1 } ], "serviceAccountName": "example", "sidecars": [ { "command": [ "example" ], "env": [ { "name": "example", "value": "example", "valueFrom": { "secretKeyRef": { "key": "example", "name": "example" } } } ], "image": "example", "name": "example", "startupTimeout": "example" } ], "state": "example", "timeout": "example", "volumes": [ { "mountPath": "example", "readOnly": true, "revision": 1, "volume": "example" } ], "workingDir": "example" }, "status": { "appVersion": 1, "conditions": [ { "lastTransitionTime": "example", "message": "example", "observedGeneration": 1, "reason": "example", "status": "example", "type": "example" } ], "cost": { "bySegment": { "bootUSD": "example", "coveredByNodus": [ "example" ], "restoreUSD": "example", "runningUSD": "example", "teardownUSD": "example" }, "final": true, "fundedUntilTime": "example", "heldUSD": "example", "limitUSD": "example", "rateUSDPerHour": "example", "totalUSD": "example" }, "estimate": { "assemblyBoundUSD": "example", "blockingReasons": [ { "code": "example", "fix": "example", "message": "example" } ], "concurrentHoldUSD": "example", "costUSD": { "p50": "example", "p90": "example" }, "gangHoldUSD": "example", "holdUSD": "example", "minimumChargeUSD": "example", "overheadUSD": { "p50": "example", "p90": "example" }, "placementPreview": { "explain": "example", "interruptible": true, "offering": "example", "regionClass": "example", "warmReuse": true }, "pricebookVersion": "example", "rateUSDPerHour": "example", "startup": { "cold": { "p50": "example", "p90": "example" }, "warm": { "p50": "example", "p90": "example" } }, "topology": "example", "validUntil": "example", "warnings": [ { "code": "example", "message": "example" } ] }, "handledRequests": { "additionalProperty": "example" }, "image": { "digest": "example", "reference": "example", "user": "example" }, "message": "example", "observedGeneration": 1, "phase": "example", "queue": { "queued": 1, "running": 1 }, "reason": "example", "workers": { "busy": 1, "draining": 1, "idle": 1, "ready": 1, "starting": 1 } }}default
Section titled “ default ”An error: a metav1.Status whose reason is a registered code.
Status is the error body of every API response: a Kubernetes metav1.Status (so kubectl and client-go understand it) plus three top-level extensions that those clients ignore (ADR-028).
object
object
object
Docs is the URL of the code’s docs page.
Fix says what to do next, for example a CLI command or the field to change.
object
object
RequestID identifies the request in logs and support tickets.
Example generated
{ "apiVersion": "example", "code": 1, "details": { "causes": [ { "field": "example", "message": "example", "reason": "example" } ], "group": "example", "kind": "example", "name": "example", "retryAfterSeconds": 1, "uid": "example" }, "docs": "example", "fix": "example", "kind": "example", "message": "example", "metadata": { "continue": "example", "remainingItemCount": 1, "resourceVersion": "example", "selfLink": "example", "shardInfo": { "selector": "example" } }, "reason": "example", "requestId": "example", "status": "example"}