Skip to navigation
API ReferenceInstance

Create an Instance

View as Markdown

Create an Instance for Tenant.

Org must have a Tenant entity. User must have authorization role with TENANT_ADMIN suffix.

A request targeting an already assigned machineId returns HTTP 409. A Ready response does not reserve the Machine: another request can assign it before creation is processed. allowUnhealthyMachine does not bypass the assignment check. Honor the retryable classification below before retrying, or select another available Machine.

Machine-unavailable errors are retryable only when a unique current Instance belongs to this Tenant and is Terminating. Other current occupants are not retryable. Missing or ambiguous associations remain unclassified. No retry delay is estimated for release-pending errors.

Uncertain create outcomes return retryable: false and recovery instructions in message. Check the identified Instance and Site in REST. If the Instance is absent or its outcome is unclear, ask the Site operator to verify the Core allocation and workflow before creating again. An empty REST result does not rule out a Site allocation. Follow the same checks after a lost HTTP response.

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

Request

This endpoint expects an object.
namestringRequired2-256 characters
Name of the Instance
tenantIdstringRequiredformat: "uuid"
ID of the Tenant creating the Instance
vpcIdstringRequiredformat: "uuid"
ID of the primary VPC the Instance belongs to. It must be owned by the Instance Tenant.
descriptionstring or nullOptional<=1024 characters
Description of the Instance, optional
instanceTypeIdstring or nullOptionalformat: "uuid"
ID of the Instance Type to use for Instance
machineIdstring or nullOptional
ID of of specific Machine to use for Instance. Requires Targeted Instance Creation capability enabled for Tenant
machineLabelSelectormap from strings to stringsOptional

Optional exact-match selector applied to Machine labels during placement. Property names are arbitrary Machine label keys rather than predefined selector fields. Every supplied key/value pair must match (AND semantics). An omitted or empty object does not restrict placement.

A non-empty object requires the Tenant to have effective targetedInstanceCreation capability for the selected Site; otherwise the request is rejected with 403. When instanceTypeId is supplied, NICo selects from Ready, unassigned Machines of that Instance Type that match the selector. When machineId is supplied, the specified Machine must match the selector or the request is rejected with 400. The selector constrains placement only; it is not persisted on the created Instance.

secondaryVpcIdslist of stringsOptional

IDs of additional VPCs the Instance should attach to through non-primary Interfaces. With effective crossTenantInterfaceCreation, these may include same-Site FNN VPC IDs owned by another Tenant, obtained out of band; the capability does not expose them through VPC discovery. This field may only be specified when every entry in interfaces uses vpcPrefixId or vpcId. IDs must be unique, valid UUIDs, and must not include the primary vpcId.

userDatastring or nullOptional

Can only be specified if allowOverride is set to true in Operating System. 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.

operatingSystemIdstring or nullOptionalformat: "uuid"
Must be specified if iPXE Script field is empty
powerProfilestring or nullOptional>=1 character

Power profile to apply to the Instance. A non-empty value requires the Site’s dpsPowerManagement capability to be true.

networkSecurityGroupIdstring or nullOptional

ID of the desired Network Security Group to attach to the Instance. Instance-level policy takes precedence over VPC-level policy on every Interface, including Interfaces attached to another Tenant’s VPC.

ipxeScriptstring or nullOptional
Override iPXE script specified in OS, must be specified if Operating System is not specified
alwaysBootWithCustomIpxebooleanOptional
When set to true, the iPXE script specified by OS or overridden here will always be run when rebooting the Instance. OS must be of iPXE type.
phoneHomeEnabledbooleanOptional
When set to true, the Instance will be enabled with the Phone Home service.
labelsmap from strings to stringsOptional

User-defined key-value labels

interfaceslist of objectsOptional

At least one interface must be specified unless autoNetwork is true. 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. A non-primary VPC-backed Interface may select a same-Site Ready FNN VPC or VPC Prefix owned by another Tenant only with effective crossTenantInterfaceCreation; cross-Tenant Subnets are never supported. The primary physical Interface must select the Instance Tenant-owned primary VPC. Only one network can be attached over a physical interface. If only one Subnet is specified, it will be attached over a physical interface regardless of isPhysical. Mutually exclusive with autoNetwork: when autoNetwork is true this list MUST be empty.

autoNetworkbooleanOptional

When true, asks NICo to auto-resolve the Instance’s network interfaces from the host’s underlay (HostInband) network segments. Intended for instances on zero-DPU hosts (or hosts with their DPU in NIC mode). When true: (1) the target VPC’s networkVirtualizationType MUST be FLAT, (2) interfaces MUST be empty or omitted, and (3) secondaryVpcIds MUST be empty or omitted. Resolved interfaces surface on the Instance’s read response.

infinibandInterfaceslist of objectsOptional
Associate one or more Partitions with this Instance
spectrumXAttachmentslist of objectsOptional

Associate one or more SpectrumX Partitions with this Instance. Each device and deviceInstance pair may appear only once, irrespective of virtualFunctionId. A nonempty list is validated against the individual Machine capabilities persisted by inventory reconciliation, not Instance Type capability summaries. The selected Machine must satisfy every attachment; Instance Type placement considers only compatible Machines. Invalid explicit-machine selectors return 400. If available Instance Type candidates are all incompatible, the 400 response identifies SpectrumX capabilities as the reason. Final allocation remains authoritative because persisted inventory can lag behind the Site.

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

Define Interfaces to associate Instance GPUs with NVLink Logical Partitions. A subset of GPUs may be specified (it is not required to include all GPUs). Each item references one GPU index (deviceInstance) and one NVLink Logical Partition. Different interfaces may reference different NVLink Logical Partitions.

sshKeyGroupIdslist of stringsOptional
Specify list of SSH Key Group IDs that will provide Serial over LAN access
allowUnhealthyMachinebooleanOptional
Set to true in order to target Machines are in maintenance or have health alerts preventing regular provision flow. Requires Targeted Instance Creation capability enabled for Tenant

Response

Created
networkSecurityGroupPropagationDetailsobject or null
Network Security Group propagation details. Null when no details are available, including when no Network Security Group is attached or inherited.
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.
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
SSH Key Groups associated with this Instance, in summary form
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
409
Conflict Error
412
Precondition Failed Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error
504
Gateway Timeout Error