API ReferenceInstance

Update Instance

View as Markdown
Update an Instance by ID Org must have a Tenant entity. Instance must belong to Tenant. User must have authorization role with `TENANT_ADMIN` suffix. A non-empty `powerProfile` requires the Site's `dpsPowerManagement` capability to be `true`; otherwise the request returns 412. Omission or `null` preserves the current profile, while an empty string clears it even when DPS power management is disabled.

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
instanceIdstringRequiredformat: "uuid"
ID of the Instance

Request

namestring or nullOptional2-256 characters
Updated name for the Instance
descriptionstring or nullOptional<=1024 characters
Updated description of the Instance
triggerRebootboolean or nullOptional
Trigger power cycle for Instance
rebootWithCustomIpxeboolean or nullOptional
When specified along with triggerReboot, the Instance will boot using the custom iPXE specified by OS. If Instance has alwaysBootWithCustomIpxe flag set then this value will be ignored.
applyUpdatesOnRebootboolean or nullOptional
When specified, pending Instance updates such as DPU reprovisioning are applied on reboot
operatingSystemIdstring or nullOptional
The UUID of the desired operating system.
ipxeScriptstring or nullOptional
The iPXE script content to be used for booting.
sshKeyGroupIdslist of stringsOptional
Specify a new list of SSH Key Group IDs that will provide Serial over LAN and SSH access. This will overwrite an existing list.
networkSecurityGroupIdstring or nullOptional
ID of the Network Security Group to attach to the Instance
powerProfilestring or nullOptional

Power profile to apply to the Instance. A non-empty value requires the Site’s dpsPowerManagement capability to be true. Omission or null preserves the current profile; an empty string clears it when DPS power management is disabled.

userDatastring or nullOptional

Any user-data to be sent to the booting OS. For example, cloud-init data. Limited to 32768 bytes (32 KiB), measured on the effective value NICo stores rather than the text submitted. Operating System defaults are inherited first, and when phone-home is configured the document is re-serialized with a phone_home block added. Re-serialization normalizes indentation and can grow the document, so a request just under the limit may still be rejected.

alwaysBootWithCustomIpxeboolean or nullOptional
Whether the custom iPXE data should be used for every boot.
phoneHomeEnabledboolean or nullOptional
Indicates whether the Phone Home service should be enabled or disabled for the Instance
labelsmap from strings to stringsOptional
Update labels of the Instance. The labels will be replaced with the labels sent in the request. Any labels not included in the request will be removed. To retain existing labels, fetch them first and include them in this request.
secondaryVpcIdslist of stringsOptional

IDs of additional VPCs the Instance should attach to through non-primary interfaces. This field may only be specified when every entry in interfaces uses vpcPrefixId or vpcId. IDs must be unique, must be valid UUIDs, and must not include the primary vpcId.

interfaceslist of anyOptional

Complete updated Interface configuration for the Instance. Interfaces must all be Subnet-backed or all be VPC-backed; VPC-backed interfaces may use an explicit vpcPrefixId or ask the Controller to select a prefix using vpcId and ipFamilies. Mutually exclusive with autoNetwork: when autoNetwork is true this list MUST be empty.

autoNetworkboolean or nullOptional

When set, asks NICo to auto-resolve the Instance’s network interfaces from the host’s underlay (HostInband) segments. null leaves the value unchanged; true (re-)resolves; false returns to explicit interface configuration. When true, the Instance’s VPC MUST already have networkVirtualizationType: FLAT, interfaces MUST be empty or omitted, and secondaryVpcIds MUST be empty or omitted.

infinibandInterfaceslist of objectsOptional
Update InfiniBand Interfaces of the Instance
spectrumXAttachmentslist of objectsOptional

Update SpectrumX Partition attachments of the Instance. Omitting this field leaves the Instance’s SpectrumX attachments unchanged; an explicit (possibly empty) list replaces them entirely. Each device and deviceInstance pair may appear only once, irrespective of virtualFunctionId.

nvLinkInterfaceslist of objectsOptional

Update NVLink Interfaces of the Instance. A subset of GPUs may be specified. Each item references a GPU index (deviceInstance) and an NVLink Logical Partition. Different interfaces may reference different NVLink Logical Partitions. Partial updates are not allowed; specified interfaces will delete or replace existing Interfaces. Updating is not allowed if the Instance’s VPC has the nvLinkLogicalPartitionId attribute set.

dpuExtensionServiceDeploymentslist of objectsOptional
Updated set of DPU Extension Services to deploy to the DPUs of this Instance

Response

OK
idstringOptionalRead-onlyformat: "uuid"
Unique identifier for the Instance
namestringOptional2-256 characters
Name for the Instance
descriptionstring or nullOptional
Description for the Instance
tenantIdstringOptionalformat: "uuid"
ID of the Tenant the Instance belongs to
infrastructureProviderIdstringOptionalformat: "uuid"
ID of the Infrastructure Provider that owns the Site where the Instance is located
siteIdstringOptionalformat: "uuid"
ID of the Site where the Instance is located
instanceTypeIdstring or nullOptionalformat: "uuid"
ID of the Instance Type
vpcIdstringOptionalformat: "uuid"
ID of the VPC
secondaryVpcIdslist of stringsOptional

IDs of VPCs attached to the Instance through non-primary interfaces

machineIdstring or nullOptional
ID of the Machine
operatingSystemIdstring or nullOptionalformat: "uuid"
ID of the Operating System
networkSecurityGroupIdstring or nullOptional
ID of the attached Network Security Group, if any
powerProfilestring or nullOptional
External power provisioning profile associated with the Instance.
networkSecurityGroupPropagationDetailsobjectOptional
Propagation details for the attached Network Security Group
networkSecurityGroupInheritedbooleanOptional
Indicates if the Network Security Group is inherited from VPC
controllerInstanceIdstring or nullOptionalformat: "uuid"
ID of the Instance in Site Controller
ipxeScriptstring or nullOptional
Attribute which is inherited from Operating System
alwaysBootWithCustomIpxebooleanOptional
Indicates whether the Instance should always execute custom iPXE script when rebooting
phoneHomeEnabledbooleanOptional
Indicates whether the Phone Home service should be enabled or disabled for the Instance
userDatastring or nullOptional
UserData is inherited from Operating System or specified by user if allowed
labelsmap from strings to stringsOptional

User-specified Instance labels

isUpdatePendingbooleanOptional
Indicates whether an update is available for the Instance. Updates can be applied on reboot
serialConsoleUrlstring or nullOptional

Serial Console URL for the Instance. Format: ssh://<id>@siteSerialConsoleHostname

autoNetworkbooleanOptional

True when this Instance uses NICo auto-resolved networking from the host’s underlay (HostInband) network segments. When true, the caller’s request interfaces list was empty, this interfaces field remains empty on readback, and the resolved per-interface details surface under status.network.interfaces.

interfaceslist of objectsOptional
Interfaces are list of the subnet associated with the Instance
infinibandInterfaceslist of objectsOptional
InfiniBandInterfaces are list of the InfiniBandInterface associated with the Instance
spectrumXAttachmentslist of objectsOptional
SpectrumXAttachments are list of the SpectrumXAttachment associated with the Instance
nvLinkInterfaceslist of objectsOptional
NVLinkInterfaces are list of the NVLinkInterface associated with the Instance
dpuExtensionServiceDeploymentslist of objectsOptional
DPU Extension Services deployed on DPUs of this Instance
sshKeyGroupIdslist of stringsOptional
IDs of SSH Key Groups associated with this Instance
sshKeyGroupslist of objectsOptional
IDs of SSH Key Groups associated with this Instance
tpmEkCertificatestring or nullOptional
base64 encoded TPM EK Certificate associated with this Instance
statusenumOptional
Status of the Instance
statusHistorylist of objectsOptional
Chronological status history for the Instance
deprecationslist of objectsOptional
Deprecations active for this resource. Returned only if there are active deprecations.
createddatetimeOptionalRead-only

Date/time when the Instance was created

updateddatetimeOptionalRead-only

Date/time when the Instance was last updated

Errors

400
Bad Request Error
403
Forbidden Error
412
Precondition Failed Error
429
Too Many Requests Error