Trigger proactive guest memory reclaim

client.resources.reclaimMemory(, ?): MemoryReclaimResponse { actions, applied_reclaim_bytes, host_available_bytes, 4 more }

post/resources/memory/reclaim

Requests runtime balloon inflation across reclaim-eligible guests. The same planner used by host-pressure reclaim is applied, including protected floors and per-VM step limits.

ParametersExpand Collapse

body: ResourceReclaimMemoryParams { reclaim_bytes, dry_run, hold_for, reason }

reclaim_bytes: number

Total bytes of guest memory to reclaim across eligible VMs.

formatint64

minimum0

dry_run?: boolean

Calculate a reclaim plan without applying balloon changes or creating a hold.

hold_for?: string

How long to keep the reclaim hold active (Go duration string). Defaults to 5m when omitted.

reason?: string

Optional operator-provided reason attached to logs and traces.

maxLength256

ReturnsExpand Collapse

MemoryReclaimResponse { actions, applied_reclaim_bytes, host_available_bytes, 4 more }

actions: Array<MemoryReclaimAction { applied_reclaim_bytes, assigned_memory_bytes, hypervisor, 8 more } >

applied_reclaim_bytes: number

formatint64

assigned_memory_bytes: number

formatint64

hypervisor: "cloud-hypervisor" | "firecracker" | "qemu" | "vz"

Accepts one of the following:

"cloud-hypervisor"

"firecracker"

"qemu"

"vz"

instance_id: string

instance_name: string

planned_target_guest_memory_bytes: number

formatint64

previous_target_guest_memory_bytes: number

formatint64

protected_floor_bytes: number

formatint64

status: string

Result of this VM's reclaim step.

target_guest_memory_bytes: number

formatint64

error?: string

Error message when status is error or unsupported.

applied_reclaim_bytes: number

formatint64

host_available_bytes: number

formatint64

host_pressure_state: "healthy" | "pressure"

Accepts one of the following:

"healthy"

"pressure"

planned_reclaim_bytes: number

formatint64

requested_reclaim_bytes: number

formatint64

hold_until?: string

When the current manual reclaim hold expires.

formatdate-time

Trigger proactive guest memory reclaim

import Hypeman from '@onkernel/hypeman';

const client = new Hypeman({
  apiKey: 'My API Key',
});

const memoryReclaimResponse = await client.resources.reclaimMemory({ reclaim_bytes: 536870912 });

console.log(memoryReclaimResponse.actions);

{
  "actions": [
    {
      "applied_reclaim_bytes": 0,
      "assigned_memory_bytes": 0,
      "hypervisor": "cloud-hypervisor",
      "instance_id": "instance_id",
      "instance_name": "instance_name",
      "planned_target_guest_memory_bytes": 0,
      "previous_target_guest_memory_bytes": 0,
      "protected_floor_bytes": 0,
      "status": "applied",
      "target_guest_memory_bytes": 0,
      "error": "error"
    }
  ],
  "applied_reclaim_bytes": 0,
  "host_available_bytes": 0,
  "host_pressure_state": "healthy",
  "planned_reclaim_bytes": 0,
  "requested_reclaim_bytes": 0,
  "hold_until": "2019-12-27T18:11:19.117Z"
}

Returns Examples

{
  "actions": [
    {
      "applied_reclaim_bytes": 0,
      "assigned_memory_bytes": 0,
      "hypervisor": "cloud-hypervisor",
      "instance_id": "instance_id",
      "instance_name": "instance_name",
      "planned_target_guest_memory_bytes": 0,
      "previous_target_guest_memory_bytes": 0,
      "protected_floor_bytes": 0,
      "status": "applied",
      "target_guest_memory_bytes": 0,
      "error": "error"
    }
  ],
  "applied_reclaim_bytes": 0,
  "host_available_bytes": 0,
  "host_pressure_state": "healthy",
  "planned_reclaim_bytes": 0,
  "requested_reclaim_bytes": 0,
  "hold_until": "2019-12-27T18:11:19.117Z"
}