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.

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 VPC the Instance should belong to
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
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. IDs must be unique, must be 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
operatingSystemIdstring or nullOptionalformat: "uuid"
Must be specified if iPXE Script field is empty
networkSecurityGroupIdstring or nullOptional
ID of the desired Network Security Group to attach to the Instance
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. Either Subnet or VPC Prefix interfaces allowed. Only one of the Subnets or VPC Prefixes can be attached over Physical interface. If only one Subnet is specified, then it will be attached over physical interface regardless of the value of isPhysical. In case of VPC Prefix, isPhysical will always be true. 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
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
idstringRead-onlyformat: "uuid"
Unique identifier for the Instance
namestring2-256 characters
Name for the Instance
descriptionstring or null
Description for the Instance
tenantIdstringformat: "uuid"
ID of the Tenant the Instance belongs to
infrastructureProviderIdstringformat: "uuid"
ID of the Infrastructure Provider that owns the Site where the Instance is located
siteIdstringformat: "uuid"
ID of the Site where the Instance is located
instanceTypeIdstring or nullformat: "uuid"
ID of the Instance Type
vpcIdstringformat: "uuid"
ID of the VPC
secondaryVpcIdslist of strings

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

machineIdstring or null
ID of the Machine
operatingSystemIdstring or nullformat: "uuid"
ID of the Operating System
networkSecurityGroupIdstring or null
ID of the attached Network Security Group, if any
networkSecurityGroupPropagationDetailsobject
Propagation details for the attached Network Security Group
networkSecurityGroupInheritedboolean
Indicates if the Network Security Group is inherited from VPC
controllerInstanceIdstring or nullformat: "uuid"
ID of the Instance in Site Controller
ipxeScriptstring or null
Attribute which is inherited from Operating System
alwaysBootWithCustomIpxeboolean
Indicates whether the Instance should always execute custom iPXE script when rebooting
phoneHomeEnabledboolean
Indicates whether the Phone Home service should be enabled or disabled for the Instance
userDatastring or null
UserData is inherited from Operating System or specified by user if allowed
labelsmap from strings to strings

User-specified Instance labels

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

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

autoNetworkboolean

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 objects
Interfaces are list of the subnet associated with the Instance
infinibandInterfaceslist of objects
InfiniBandInterfaces are list of the InfiniBandInterface associated with the Instance
nvLinkInterfaceslist of objects
NVLinkInterfaces are list of the NVLinkInterface associated with the Instance
dpuExtensionServiceDeploymentslist of objects
DPU Extension Services deployed on DPUs of this Instance
sshKeyGroupIdslist of strings
IDs of SSH Key Groups associated with this Instance
sshKeyGroupslist of objects
IDs of SSH Key Groups associated with this Instance
tpmEkCertificatestring or null
base64 encoded TPM EK Certificate associated with this Instance
statusenum
Status of the Instance
statusHistorylist of objects
Chronological status history for the Instance
deprecationslist of objects
Deprecation notices for fields returned by this resource
createddatetimeRead-only

Date/time when the Instance was created

updateddatetimeRead-only

Date/time when the Instance was last updated

Errors

400
Bad Request Error
403
Forbidden Error