Skip to navigation
API ReferenceMachineInventory

Update Machine

View as Markdown

Update a Machine

Instance Type attribute updates, maintenance attribute updates and labels updates must be specified in separate requests. They cannot be processed at the same time.

Some attributes can only be updated by Provider, while others can be updated by Provider or a privileged Tenant.

For Infrastructure Providers: Org must have an Infrastructure Provider entity and own the Site that the Machine belongs to. User must have authorization role with PROVIDER_ADMIN suffix.

For Tenants: Org must have a Tenant with TargetedInstanceCreation capability enabled and Tenant Account with Machine’s Provider. User must have authorization role with TENANT_ADMIN suffix.

Authentication

AuthorizationBearer
export JWT_BEARER_TOKEN="<jwt-bearer-token>"

# Example org name: "acme-inc
export ORG_NAME=<org-name>

# Use the JWT bearer token in your API request auth header:
curl -v -X GET -H "Content-Type: application/json" -H "Authorization: Bearer $JWT_BEARER_TOKEN" https://nico-rest-api.nico.svc.cluster.local/v2/org/$ORG_NAME/nico/user/current

Path parameters

orgstringRequired
Name of the Org
machineIdstringRequired
ID of the Machine

Request

This endpoint expects an object.
instanceTypeIdstring or nullOptionalformat: "uuid"2-256 characters
Update the Instance Type of the Machine. Cannot be specified when clearing Instance Type. Can only be updated by Provider.
clearInstanceTypeboolean or nullOptional
Set to true to clear the existing Instance Type. Cannot be specified if Instance Type ID is specified. Can only be set by Provider.
setMaintenanceModeboolean or nullOptional

Set to true to enable maintenance mode and to false to disable maintenance mode. Can be set by Provider or privileged Tenant.

maintenanceMessagestring or nullOptionalformat: "[^ \t\n\f\r]"5-256 characters

Describes the reason for moving Machine into maintenance mode. Required when setMaintenanceMode is true. Omit or set to null when setMaintenanceMode is omitted, null, or false; a non-null message is rejected in those cases. Can be updated by Provider or privileged Tenant.

labelsmap from strings to stringsOptional
Machine labels will be overwritten, include existing labels to preserve them. Can be updated by Provider or privileged Tenant.
onlineRepairobjectOptional

Request to enter/exit online repair

healthIssueobjectOptional

Required when onlineRepair.enabled is true. Must not be set when exiting online repair (onlineRepair.enabled false).

Response

OK
idstringOptionalRead-only
Unique ID of Machine
infrastructureProviderIdstringOptionalRead-onlyformat: "uuid"
ID of the Provider that owns the Machine
siteIdstringOptionalformat: "uuid"
ID of the Site the Machine belongs to
instanceTypeIdstring or nullOptionalformat: "uuid"
ID of the Instance Type, if assigned
instanceIdstring or nullOptionalformat: "uuid"

ID of the associated Instance, or null when unassigned. The association remains during termination until Instance inventory confirms deletion. A non-null value precludes Ready status.

tenantIdstring or nullOptionalformat: "uuid"
ID of the Tenant that owns the Instance if the Machine is assigned to one
controllerMachineIdstringOptional
ID of the Machine at Site, now same as the primary ID
controllerMachineTypestring or nullOptional

Denotes architecture (x86 vs ARM) of the Machine

hwSkuDeviceTypestring or nullOptional
SKU derived device type of the machine, e.g. cpu, gpu, cache, storage, etc.
vendorstring or nullOptional
Name of the vendor of the Machine
productNamestring or nullOptional
Product name of the Machine
serialNumberstring or nullOptional
Serial number of the Machine, only visible to Provider
machineCapabilitieslist of objectsOptional
List of capabilities of the machine
machineInterfaceslist of objectsOptional
List of admin interfaces of the machine
associatedDpuMachineIdslist of stringsOptionalRead-only
IDs of the DPU Machines attached to this host Machine
placementInRackobjectOptional
Physical placement of the Machine within its Rack, when known
maintenanceMessagestring or nullOptional
If the Machine is in maintenance mode, this message will typically describe the reason and how long it is expected to be in maintenance
scoutVersionstring or nullOptionalRead-only
Scout version reported by the Machine, if known
healthobjectOptional
Health information about the machine
metadataobjectOptional

Only available to Providers. Returned if the includeMetadata query parameter is specified. Otherwise attribute is omitted from response.

labelsmap from strings to stringsOptional

User-specified Machine labels

statusenumOptional

Machine status combines the observed Core lifecycle with REST Instance assignment. A Ready Machine becomes InUse when REST assigns it, and remains InUse if Core reports Ready while the REST assignment still exists. Error, Maintenance, Initializing, and other non-Ready states retain precedence. When Instance deletion clears the assignment, InUse returns to Ready only if the retained Core snapshot reports Ready; otherwise fresh Machine inventory establishes the next status. Ready is not a reservation and does not guarantee that a subsequent Instance creation will succeed.

isUsableByTenantbooleanOptionalRead-only
Indicates whether the machine is usable by or currently in use by a tenant. It does not indicate that a Machine is available for Instance creation.
statusHistorylist of objectsOptional
Chronological status history for the Machine
createddatetimeOptionalRead-only

Date/time when the Machine was created

updateddatetimeOptionalRead-only

Date/time when the Machine was last updated

Errors

400
Bad Request Error
403
Forbidden Error