Skip to content
Nodus
Blog

Retire reserved host access and drain lending

POST
/apis/nodus.dev/v1/namespaces/{namespace}/reservedhosts/{name}/release-capacity
 
curl --request POST \
  --url https://example.com/apis/nodus.dev/v1/namespaces/example/reservedhosts/example/release-capacity \
  --header 'Content-Type: application/json' \
  --data '{ "agreed": true, "epoch": 1 }'

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “ Path Parameters ”
namespace
required
string

The project.

name
required
string

The object’s name.

Query Parameters

Section titled “ Query Parameters ”
dryRun
string
fieldValidation
string
fieldManager
string

Header Parameters

Section titled “ Header Parameters ”
Idempotency-Key
string
If-Match
string

Request Bodyrequired

Section titled “ Request Bodyrequired ”
Media type application/json

ReservedHostReleaseRequest confirms irreversible retirement under the reviewed reservation epoch.

object
agreed
required

Agreed confirms access retirement without shortening the supplier’s reservation term.

boolean
epoch
required

Epoch identifies the reservation assignment reviewed before retirement.

integer format: int64
Example generated 
{
  "agreed": true,
  "epoch": 1
}

Responses

Section titled “ Responses ”

200

Section titled “ 200 ”

OK

Media type application/json

ReservedHost is a project-scoped physical server assignment (Beta). Operators assign the entire machine; customer connections never create or replace capacity.

object
apiVersion
string
kind
string
metadata
object
annotations
object
key
additional properties
string
creationTimestamp
string
deletionGracePeriodSeconds
integer format: int64
deletionTimestamp
string
finalizers
Array<string>
nullable
generateName
string
generation
integer format: int64
labels
object
key
additional properties
string
managedFields
Array<object>
nullable
object
apiVersion
string
fieldsType
string
fieldsV1
object
key
additional properties
manager
string
operation
string
subresource
string
time
string
name
string
namespace
string
ownerReferences
Array<object>
nullable
object
apiVersion
required
string
blockOwnerDeletion
boolean
controller
boolean
kind
required
string
name
required
string
uid
required
string
resourceVersion
string
selfLink
string
uid
string
status
required

ReservedHostStatus is the customer-safe view of a physical host assignment.

object
conditions

Conditions reports host connectivity and reservation eligibility.

Array<object>
nullable
object
lastTransitionTime
required
string
message
required
string
observedGeneration
integer format: int64
reason
required
string
status
required
string
type
required
string
connect

ReservedHostConnect describes access to the physical operating system through Nodus.

object
command
required

Command sets up SSH and opens a shell on this host.

string
host
required

Host is the stable SSH alias installed by the Nodus CLI.

string
hostKey
required

HostKey is the public SSH host key used for strict host verification.

string
loginUser
required

LoginUser is the operator-configured operating-system account.

string
inventory
required

NodeInventory is the host’s hardware and software.

object
cpu
required

CPU is the host’s CPU count.

integer format: int32
diskGiB
required

DiskGiB is the host’s free disk in GiB.

integer format: int64
gpus

GPUs are the host’s GPUs.

Array<object>
nullable

NodeGPU is one device on the host.

object
driver

Driver is the GPU driver version.

string
memoryMiB
required

MemoryMiB is the GPU’s memory in MiB.

integer format: int64
type
required

Accelerator model, “h100-sxm-80g”

string
memoryMiB
required

MemoryMiB is the host’s memory in MiB.

integer format: int64
nodusdVersion

NodusdVersion is the nodusd release on the host.

string
os

OS is the host’s operating system.

string
lastHeartbeatTime

LastHeartbeatTime is the latest host heartbeat.

string
pool

Pool is the enrolled capacity group used for this host’s lending agreement.

string
release

ReservedHostReleaseStatus reports execution drainage, never early contract cancellation or disk sanitization.

object
drainedAt

DrainedAt is when current-agent evidence confirmed that owner and borrower execution had ended.

string
requestedAt
required

RequestedAt is when the owner requested retirement of access and execution.

string
reservation
required

HostReservation is the customer-safe projection of the physical server’s assignment (Beta).

object
endsAt
required

EndsAt is the exclusive end of the reservation term.

string
epoch
required

Epoch fences connections after access changes.

integer format: int64
loginUser
required

LoginUser is the fixed operating-system account.

string
project
required

Project identifies the customer project authorized to connect.

string
startsAt
required

StartsAt is the beginning of the reservation term.

string
state
required

State controls access, never hardware availability to other workloads.

string
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"
  },
  "status": {
    "conditions": [
      {
        "lastTransitionTime": "example",
        "message": "example",
        "observedGeneration": 1,
        "reason": "example",
        "status": "example",
        "type": "example"
      }
    ],
    "connect": {
      "command": "example",
      "host": "example",
      "hostKey": "example",
      "loginUser": "example"
    },
    "inventory": {
      "cpu": 1,
      "diskGiB": 1,
      "gpus": [
        {
          "driver": "example",
          "memoryMiB": 1,
          "type": "example"
        }
      ],
      "memoryMiB": 1,
      "nodusdVersion": "example",
      "os": "example"
    },
    "lastHeartbeatTime": "example",
    "pool": "example",
    "release": {
      "drainedAt": "example",
      "requestedAt": "example"
    },
    "reservation": {
      "endsAt": "example",
      "epoch": 1,
      "loginUser": "example",
      "project": "example",
      "startsAt": "example",
      "state": "example"
    }
  }
}

default

Section titled “ default ”

An error: a metav1.Status whose reason is a registered code.

Media type application/json

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
apiVersion
string
code
integer format: int32
details
object
causes
Array<object>
nullable
object
field
string
message
string
reason
string
group
string
kind
string
name
string
retryAfterSeconds
integer format: int32
uid
string
docs

Docs is the URL of the code’s docs page.

string
fix

Fix says what to do next, for example a CLI command or the field to change.

string
kind
string
message
string
metadata
object
continue
string
remainingItemCount
integer format: int64
resourceVersion
string
selfLink
string
shardInfo
object
selector
required
string
reason
string
requestId

RequestID identifies the request in logs and support tickets.

string
status
string
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"
}