Replace a Pool

PUT

/apis/nodus.dev/v1/namespaces/{namespace}/pools/{name}

const url = 'https://example.com/apis/nodus.dev/v1/namespaces/example/pools/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":{"act":{"mode":"example","paused":true,"policies":[{"action":"example","duration":"example","idleFor":"example","maxGPUs":1,"maxRateUSDPerHour":"example","maxWaitTimeout":"example","minWaitTimeout":"example","schedule":"example"}]},"predict":{"enabled":true,"horizon":"example"},"routing":{"burstToMarket":"example","mode":"example","waitPolicy":"example","waitTimeout":"example"},"sandboxCapable":true},"status":{"act":{"lastActionTime":"example","pending":1},"capacity":{"gpus":{"additionalProperty":{"free":1,"total":1}},"nodes":1,"readyNodes":1},"conditions":[{"lastTransitionTime":"example","message":"example","observedGeneration":1,"reason":"example","status":"example","type":"example"}],"forecast":{"generatedTime":"example","horizon":"example","peakDemandGPUs":{"p50":1,"p90":1},"shortfallTime":"example"},"phase":"example","predict":{"enabledTime":"example"},"routing":{"burstPending":1,"consent":{"rateUSD":"example","time":"example"},"waiting":1},"utilization":{"deviceHours":"example","gpuPercent":1,"window":"example"}}}'
};

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/pools/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": { "act": { "mode": "example", "paused": true, "policies": [ { "action": "example", "duration": "example", "idleFor": "example", "maxGPUs": 1, "maxRateUSDPerHour": "example", "maxWaitTimeout": "example", "minWaitTimeout": "example", "schedule": "example" } ] }, "predict": { "enabled": true, "horizon": "example" }, "routing": { "burstToMarket": "example", "mode": "example", "waitPolicy": "example", "waitTimeout": "example" }, "sandboxCapable": true }, "status": { "act": { "lastActionTime": "example", "pending": 1 }, "capacity": { "gpus": { "additionalProperty": { "free": 1, "total": 1 } }, "nodes": 1, "readyNodes": 1 }, "conditions": [ { "lastTransitionTime": "example", "message": "example", "observedGeneration": 1, "reason": "example", "status": "example", "type": "example" } ], "forecast": { "generatedTime": "example", "horizon": "example", "peakDemandGPUs": { "p50": 1, "p90": 1 }, "shortfallTime": "example" }, "phase": "example", "predict": { "enabledTime": "example" }, "routing": { "burstPending": 1, "consent": { "rateUSD": "example", "time": "example" }, "waiting": 1 }, "utilization": { "deviceHours": "example", "gpuPercent": 1, "window": "example" } } }'

Parameters

Path Parameters

namespace

required

string

The project.

name

required

string

The object’s name.

Query Parameters

dryRun

string

fieldValidation

string

fieldManager

string

Header Parameters

Idempotency-Key

string

If-Match

string

Request Body^required

application/json

Pool is a set of the customer’s own hosts that Nodus measures, routes work onto, forecasts and manages.

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

spec

required

PoolSpec is the desired behavior of a Pool.

object

act

PoolAct configures the Act tier.

object

mode

Mode is Off, Shadow, Propose or Auto. Default Off.

string

paused

Paused is the kill switch: running actions stop at their next safe point and pending ones are canceled.

boolean

policies

Policies are the actions Act may take, at most 16.

Array<object>

nullable

PoolActPolicy is one automated action and its bounds.

object

action

required

Action is IdleReclaim, Drain, Defragment, WaitTuning or Burst.

string

duration

Duration is the length of a Drain window.

string

idleFor

IdleFor is how long a host must be idle before IdleReclaim returns it.

string

maxGPUs

MaxGPUs caps the GPUs a Burst policy pre-approves.

integer format: int32

maxRateUSDPerHour

MaxRateUSDPerHour caps the market rate a Burst policy pre-approves, as a decimal string.

string

maxWaitTimeout

MaxWaitTimeout bounds the wait timeout a Job may ask for in this Pool.

string

minWaitTimeout

MinWaitTimeout and MaxWaitTimeout bound WaitTuning.

string

schedule

Schedule is the cron expression that opens a Drain window.

string

predict

PoolPredict configures the Predict tier.

object

enabled

Enabled turns forecasts and recommendations on; enabling needs billing:write and rate consent.

boolean

horizon

Horizon is how far forecasts look ahead, from 24h to 720h. Default 168h.

string

routing

PoolRouting is the Pool’s placement policy for pool-routed work.

object

burstToMarket

BurstToMarket is Allow, Approve or Deny. Default Approve.

string

mode

Mode is Prefer (Pool first, then the market per burstToMarket) or Only (never the market). Default Prefer.

string

waitPolicy

WaitPolicy is Never, Cheaper or Timeout. Default Timeout.

string

waitTimeout

WaitTimeout bounds the wait for Pool capacity under waitPolicy Timeout, from 1m to 24h. Default 30m.

string

sandboxCapable

SandboxCapable lets the Pool’s hosts also run CPU Sandboxes under gVisor.

boolean

status

PoolStatus is the observed state of a Pool.

object

act

PoolActStatus counts open actions.

object

lastActionTime

LastActionTime is when the latest PoolAction was created.

string

pending

required

Pending counts PoolActions waiting for a decision.

integer format: int32

capacity

PoolCapacity is the Pool’s inventory.

object

gpus

GPUs counts devices per accelerator model.

object

key

additional properties

DeviceCounts counts one device model’s devices.

object

free

required

Free is the number of devices with no work.

integer format: int32

total

required

Total is the number of devices.

integer format: int32

nodes

required

Nodes is the number of enrolled hosts.

integer format: int32

readyNodes

required

ReadyNodes is the number of hosts that are Ready.

integer format: int32

conditions

Conditions carries the Pool’s conditions.

Array<object>

nullable

object

lastTransitionTime

required

string

message

required

string

observedGeneration

integer format: int64

reason

required

string

status

required

string

type

required

string

forecast

PoolForecastSummary is the headline of the latest forecast.

object

generatedTime

required

GeneratedTime is when the forecast was made.

string

horizon

required

Horizon is how far ahead the forecast looks.

string

peakDemandGPUs

required

Band is a forecast’s median and 90th percentile.

object

p50

required

P50 is the median.

number format: double

p90

required

P90 is the 90th percentile.

number format: double

shortfallTime

ShortfallTime is the first hour the p90 demand exceeds the Pool’s devices, when inside the horizon.

string

phase

Phase is the Pool’s lifecycle phase.

string

predict

PoolPredictStatus is Predict’s billing anchor.

object

enabledTime

required

EnabledTime is when Predict was enabled; the Predict fee is billed from it.

string

routing

PoolRoutingStatus counts pool-routed objects that are not placed yet.

object

burstPending

required

BurstPending counts burst decisions waiting for approval.

integer format: int32

consent

PriceConsent records the platform price a caller agreed to and when.

object

rateUSD

required

RateUSD is the agreed rate in US dollars, as a decimal string.

string

time

required

Time is when the caller agreed.

string

waiting

required

Waiting counts pool-routed objects waiting for capacity.

integer format: int32

utilization

PoolUtilization summarizes a window of utilization.

object

deviceHours

Decimal device-hours of Nodus-scheduled work

string

gpuPercent

required

GPUPercent is the GPU busy share over the window, in percent.

integer format: int32

window

Window is the window the summary covers.

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"
  },
  "spec": {
    "act": {
      "mode": "example",
      "paused": true,
      "policies": [
        {
          "action": "example",
          "duration": "example",
          "idleFor": "example",
          "maxGPUs": 1,
          "maxRateUSDPerHour": "example",
          "maxWaitTimeout": "example",
          "minWaitTimeout": "example",
          "schedule": "example"
        }
      ]
    },
    "predict": {
      "enabled": true,
      "horizon": "example"
    },
    "routing": {
      "burstToMarket": "example",
      "mode": "example",
      "waitPolicy": "example",
      "waitTimeout": "example"
    },
    "sandboxCapable": true
  },
  "status": {
    "act": {
      "lastActionTime": "example",
      "pending": 1
    },
    "capacity": {
      "gpus": {
        "additionalProperty": {
          "free": 1,
          "total": 1
        }
      },
      "nodes": 1,
      "readyNodes": 1
    },
    "conditions": [
      {
        "lastTransitionTime": "example",
        "message": "example",
        "observedGeneration": 1,
        "reason": "example",
        "status": "example",
        "type": "example"
      }
    ],
    "forecast": {
      "generatedTime": "example",
      "horizon": "example",
      "peakDemandGPUs": {
        "p50": 1,
        "p90": 1
      },
      "shortfallTime": "example"
    },
    "phase": "example",
    "predict": {
      "enabledTime": "example"
    },
    "routing": {
      "burstPending": 1,
      "consent": {
        "rateUSD": "example",
        "time": "example"
      },
      "waiting": 1
    },
    "utilization": {
      "deviceHours": "example",
      "gpuPercent": 1,
      "window": "example"
    }
  }
}

Responses

200

application/json

Pool is a set of the customer’s own hosts that Nodus measures, routes work onto, forecasts and manages.

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

spec

required

PoolSpec is the desired behavior of a Pool.

object

act

PoolAct configures the Act tier.

object

mode

Mode is Off, Shadow, Propose or Auto. Default Off.

string

paused

Paused is the kill switch: running actions stop at their next safe point and pending ones are canceled.

boolean

policies

Policies are the actions Act may take, at most 16.

Array<object>

nullable

PoolActPolicy is one automated action and its bounds.

object

action

required

Action is IdleReclaim, Drain, Defragment, WaitTuning or Burst.

string

duration

Duration is the length of a Drain window.

string

idleFor

IdleFor is how long a host must be idle before IdleReclaim returns it.

string

maxGPUs

MaxGPUs caps the GPUs a Burst policy pre-approves.

integer format: int32

maxRateUSDPerHour

MaxRateUSDPerHour caps the market rate a Burst policy pre-approves, as a decimal string.

string

maxWaitTimeout

MaxWaitTimeout bounds the wait timeout a Job may ask for in this Pool.

string

minWaitTimeout

MinWaitTimeout and MaxWaitTimeout bound WaitTuning.

string

schedule

Schedule is the cron expression that opens a Drain window.

string

predict

PoolPredict configures the Predict tier.

object

enabled

Enabled turns forecasts and recommendations on; enabling needs billing:write and rate consent.

boolean

horizon

Horizon is how far forecasts look ahead, from 24h to 720h. Default 168h.

string

routing

PoolRouting is the Pool’s placement policy for pool-routed work.

object

burstToMarket

BurstToMarket is Allow, Approve or Deny. Default Approve.

string

mode

Mode is Prefer (Pool first, then the market per burstToMarket) or Only (never the market). Default Prefer.

string

waitPolicy

WaitPolicy is Never, Cheaper or Timeout. Default Timeout.

string

waitTimeout

WaitTimeout bounds the wait for Pool capacity under waitPolicy Timeout, from 1m to 24h. Default 30m.

string

sandboxCapable

SandboxCapable lets the Pool’s hosts also run CPU Sandboxes under gVisor.

boolean

status

PoolStatus is the observed state of a Pool.

object

act

PoolActStatus counts open actions.

object

lastActionTime

LastActionTime is when the latest PoolAction was created.

string

pending

required

Pending counts PoolActions waiting for a decision.

integer format: int32

capacity

PoolCapacity is the Pool’s inventory.

object

gpus

GPUs counts devices per accelerator model.

object

key

additional properties

DeviceCounts counts one device model’s devices.

object

free

required

Free is the number of devices with no work.

integer format: int32

total

required

Total is the number of devices.

integer format: int32

nodes

required

Nodes is the number of enrolled hosts.

integer format: int32

readyNodes

required

ReadyNodes is the number of hosts that are Ready.

integer format: int32

conditions

Conditions carries the Pool’s conditions.

Array<object>

nullable

object

lastTransitionTime

required

string

message

required

string

observedGeneration

integer format: int64

reason

required

string

status

required

string

type

required

string

forecast

PoolForecastSummary is the headline of the latest forecast.

object

generatedTime

required

GeneratedTime is when the forecast was made.

string

horizon

required

Horizon is how far ahead the forecast looks.

string

peakDemandGPUs

required

Band is a forecast’s median and 90th percentile.

object

p50

required

P50 is the median.

number format: double

p90

required

P90 is the 90th percentile.

number format: double

shortfallTime

ShortfallTime is the first hour the p90 demand exceeds the Pool’s devices, when inside the horizon.

string

phase

Phase is the Pool’s lifecycle phase.

string

predict

PoolPredictStatus is Predict’s billing anchor.

object

enabledTime

required

EnabledTime is when Predict was enabled; the Predict fee is billed from it.

string

routing

PoolRoutingStatus counts pool-routed objects that are not placed yet.

object

burstPending

required

BurstPending counts burst decisions waiting for approval.

integer format: int32

consent

PriceConsent records the platform price a caller agreed to and when.

object

rateUSD

required

RateUSD is the agreed rate in US dollars, as a decimal string.

string

time

required

Time is when the caller agreed.

string

waiting

required

Waiting counts pool-routed objects waiting for capacity.

integer format: int32

utilization

PoolUtilization summarizes a window of utilization.

object

deviceHours

Decimal device-hours of Nodus-scheduled work

string

gpuPercent

required

GPUPercent is the GPU busy share over the window, in percent.

integer format: int32

window

Window is the window the summary covers.

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"
  },
  "spec": {
    "act": {
      "mode": "example",
      "paused": true,
      "policies": [
        {
          "action": "example",
          "duration": "example",
          "idleFor": "example",
          "maxGPUs": 1,
          "maxRateUSDPerHour": "example",
          "maxWaitTimeout": "example",
          "minWaitTimeout": "example",
          "schedule": "example"
        }
      ]
    },
    "predict": {
      "enabled": true,
      "horizon": "example"
    },
    "routing": {
      "burstToMarket": "example",
      "mode": "example",
      "waitPolicy": "example",
      "waitTimeout": "example"
    },
    "sandboxCapable": true
  },
  "status": {
    "act": {
      "lastActionTime": "example",
      "pending": 1
    },
    "capacity": {
      "gpus": {
        "additionalProperty": {
          "free": 1,
          "total": 1
        }
      },
      "nodes": 1,
      "readyNodes": 1
    },
    "conditions": [
      {
        "lastTransitionTime": "example",
        "message": "example",
        "observedGeneration": 1,
        "reason": "example",
        "status": "example",
        "type": "example"
      }
    ],
    "forecast": {
      "generatedTime": "example",
      "horizon": "example",
      "peakDemandGPUs": {
        "p50": 1,
        "p90": 1
      },
      "shortfallTime": "example"
    },
    "phase": "example",
    "predict": {
      "enabledTime": "example"
    },
    "routing": {
      "burstPending": 1,
      "consent": {
        "rateUSD": "example",
        "time": "example"
      },
      "waiting": 1
    },
    "utilization": {
      "deviceHours": "example",
      "gpuPercent": 1,
      "window": "example"
    }
  }
}

default

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

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

Replace a Pool

Parameters

Path Parameters

Query Parameters

Header Parameters

Request Bodyrequired

Example generated

Responses

200

Example generated

default

Example generated

Request Body^required

Example ^generated

Example ^generated

Example ^generated