Sign in

v57

latestOpenAPI 3.1.0Apache-2.0raw.githubusercontent.com2026-08-012143051018.3 KB
Instance

Update Instance

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.

patch/v2/org/{org}/nico/instance/{instanceId}

Request body

namestring nullable

Updated name for the Instance

descriptionstring nullable

Updated description of the Instance

triggerRebootboolean nullable

Trigger power cycle for Instance

rebootWithCustomIpxeboolean nullable

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 nullable

When specified, pending Instance updates such as DPU reprovisioning are applied on reboot

operatingSystemIdstring nullable

The UUID of the desired operating system.

ipxeScriptstring nullable

The iPXE script content to be used for booting.

sshKeyGroupIdsstring[]

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 nullable

ID of the Network Security Group to attach to the Instance

userDatastring nullable

Any user-data to be sent to the booting OS. For example, cloud-init data.

alwaysBootWithCustomIpxeboolean nullable

Whether the custom iPXE data should be used for every boot.

phoneHomeEnabledboolean nullable

Indicates whether the Phone Home service should be enabled or disabled for the Instance

labelsLabels
secondaryVpcIdsstring[]

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.

autoNetworkboolean nullable

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.

Example request

{
  "name": "spark-monitor-1",
  "description": "Spark Monitor Node 1",
  "alwaysBootWithCustomIpxe": true,
  "sshKeyGroupIds": [
    "a7bf2f9c-12f0-4673-be47-12be6d9e16c8"
  ],
  "operatingSystemId": "eaeb86ee-c435-444e-9e01-8346f67f194b",
  "ipxeScript": "#!ipxe\nkernel http://archive.ubuntu.com/ubuntu/dists/xenial/main/installer-amd64/current/images/netboot/ubuntu-installer/amd64/linux initrd=initrd.gz\ninitrd http://archive.ubuntu.com/ubuntu/dists/xenial/main/installer-amd64/current/images/netboot/ubuntu-installer/amd64/initrd.gz\nboot || imgfree\n shell",
  "userData": "#cloud-config\nautoinstall:\n  apt:\n    geoip: true\n    preserve_sources_list: false\n    primary:\n    - arches: [amd64, i386]\n      uri: http://archive.ubuntu.com/ubuntu\n    - arches: [default]\n      uri: http://ports.ubuntu.com/ubuntu-ports\nphone_home:\n  url: http://169.254.169.254:7777/latest/meta-data/phone_home\n  post: all",
  "labels": {
    "region": "portland",
    "env": "staging"
  },
  "interfaces": [
    {
      "subnetId": "1f492faa-2963-4f21-aab5-9f00b2e40119",
      "isPhysical": true
    }
  ],
  "infinibandInterfaces": [
    {
      "partitionId": "550e8400-e29b-41d4-a716-446655440000",
      "device": "MT2910 Family [ConnectX-7]",
      "deviceInstance": 0,
      "isPhysical": true,
      "virtualFunctionId": null
    },
    {
      "partitionId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "device": "MT2910 Family [ConnectX-7]",
      "deviceInstance": 1,
      "isPhysical": false,
      "virtualFunctionId": null
    },
    {
      "partitionId": "8b05d5c3-8de4-48c8-8d1c-399a8abc3ab8",
      "device": "MT2910 Family [ConnectX-7]",
      "deviceInstance": 2,
      "isPhysical": false,
      "virtualFunctionId": null
    }
  ],
  "dpuExtensionServiceDeployments": [
    {
      "dpuExtensionServiceId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "version": "V1-T1761856992374052"
    }
  ],
  "nvLinkInterfaces": [
    {
      "nvLinkLogicalPartitionId": "2f8676fd-d228-4db5-ac76-1cfc74f48a23",
      "deviceInstance": 0
    },
    {
      "nvLinkLogicalPartitionId": "2f8676fd-d228-4db5-ac76-1cfc74f48a23",
      "deviceInstance": 1
    },
    {
      "nvLinkLogicalPartitionId": "2f8676fd-d228-4db5-ac76-1cfc74f48a23",
      "deviceInstance": 2
    },
    {
      "nvLinkLogicalPartitionId": "2f8676fd-d228-4db5-ac76-1cfc74f48a23",
      "deviceInstance": 3
    }
  ]
}

Response

OK

idstring uuid

Unique identifier for the Instance

namestring

Name for the Instance

descriptionstring nullable

Description for the Instance

tenantIdstring uuid

ID of the Tenant the Instance belongs to

infrastructureProviderIdstring uuid

ID of the Infrastructure Provider that owns the Site where the Instance is located

siteIdstring uuid

ID of the Site where the Instance is located

instanceTypeIdstring uuid nullable

ID of the Instance Type

vpcIdstring uuid

ID of the VPC

secondaryVpcIdsstring[]

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

machineIdstring nullable

ID of the Machine

operatingSystemIdstring uuid nullable

ID of the Operating System

networkSecurityGroupIdstring nullable

ID of the attached Network Security Group, if any

networkSecurityGroupInheritedboolean

Indicates if the Network Security Group is inherited from VPC

controllerInstanceIdstring uuid nullable

ID of the Instance in Site Controller

ipxeScriptstring nullable

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 nullable

UserData is inherited from Operating System or specified by user if allowed

labelsLabels
isUpdatePendingboolean

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

serialConsoleUrlstring nullable

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.

sshKeyGroupIdsstring[]

IDs of SSH Key Groups associated with this Instance

tpmEkCertificatestring nullable

base64 encoded TPM EK Certificate associated with this Instance

status'Pending' | 'Provisioning' | 'Configuring' | 'Ready' | 'Updating' | 'Repairing' | 'Rebooting' | 'Terminating' | 'Error'

Status values for Instance objects

createdstring date-time

Date/time when the Instance was created

updatedstring date-time

Date/time when the Instance was last updated

Example response

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "spark-monitor-1",
  "description": "Node for monitoring Spark",
  "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
  "infrastructureProviderId": "e94bcfda-f6cb-42e4-80ec-516811e5abbf",
  "siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
  "instanceTypeId": "41e36058-8403-4086-a9b8-39cb5bc9cb98",
  "vpcId": "5e28ad7c-5fb7-46d6-a28a-fc0ba6fdc4a3",
  "machineId": "fm100ht4v4mce2qstjnl8970nnj3ie6ecek4mtjn27pea4kre5gsa49jg0g",
  "operatingSystemId": "eaeb86ee-c435-444e-9e01-8346f67f194b",
  "controllerInstanceId": null,
  "ipxeScript": null,
  "alwaysBootWithCustomIpxe": false,
  "networkSecurityGroupId": "c602eb90-3039-11f0-997a-b38d4fc8389e",
  "networkSecurityGroupPropagationDetails": {
    "objectId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "detailedStatus": "Partial",
    "status": "Synchronizing",
    "details": "",
    "unpropagatedInstanceIds": [
      "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    ],
    "relatedInstanceIds": [
      "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    ]
  },
  "networkSecurityGroupInherited": false,
  "userData": null,
  "labels": {
    "region": "portland",
    "env": "staging"
  },
  "isUpdatePending": false,
  "serialConsoleUrl": "ssh://user@nico.acme.com",
  "interfaces": [
    {
      "id": "64d2028c-ae87-4069-a624-66089d957ef9",
      "instanceId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "subnetId": "1f232bf0-7b90-456e-b9b0-38d9fea4171a",
      "isPhysical": true,
      "virtualFunctionId": null,
      "macAddress": null,
      "ipAddresses": [],
      "status": "Pending",
      "created": "2019-08-24T14:15:22Z",
      "updated": "2019-08-24T14:15:22Z"
    }
  ],
  "infinibandInterfaces": [
    {
      "id": "c518a0e8-3f49-4a1a-8935-a6d3dee6911e",
      "instanceId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "partitionId": "05ef7e84-1d4e-4e4d-980d-38589479a0fe",
      "device": "MT2910 Family [ConnectX-7]",
      "deviceInstance": 0,
      "isPhysical": true,
      "virtualFunctionId": null,
      "guid": "946dae0300339498",
      "status": "Ready",
      "created": "2019-08-24T14:15:22Z",
      "updated": "2019-08-24T14:15:22Z"
    }
  ],
  "nvLinkInterfaces": [
    {
      "id": "fc19ab3f-1e52-4846-91bd-98743ff2752c",
      "instanceId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "nvLinkLogicalPartitionId": "2f8676fd-d228-4db5-ac76-1cfc74f48a23",
      "nvLinkDomainId": "59202b81-65fb-45ec-b3b8-91ab0ad3f34a",
      "deviceInstance": 0,
      "status": "Ready",
      "created": "2019-08-24T14:15:22Z",
      "updated": "2019-08-24T14:15:22Z"
    },
    {
      "id": "fc19ab3f-1e52-4846-91bd-98743ff2752c",
      "instanceId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "nvLinkLogicalPartitionId": "2f8676fd-d228-4db5-ac76-1cfc74f48a23",
      "nvLinkDomainId": "59202b81-65fb-45ec-b3b8-91ab0ad3f34a",
      "deviceInstance": 1,
      "status": "Ready",
      "created": "2019-08-24T14:15:22Z",
      "updated": "2019-08-24T14:15:22Z"
    },
    {
      "id": "fc19ab3f-1e52-4846-91bd-98743ff2752c",
      "instanceId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "nvLinkLogicalPartitionId": "2f8676fd-d228-4db5-ac76-1cfc74f48a23",
      "nvLinkDomainId": "59202b81-65fb-45ec-b3b8-91ab0ad3f34a",
      "deviceInstance": 2,
      "status": "Ready",
      "created": "2019-08-24T14:15:22Z",
      "updated": "2019-08-24T14:15:22Z"
    },
    {
      "id": "fc19ab3f-1e52-4846-91bd-98743ff2752c",
      "instanceId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "nvLinkLogicalPartitionId": "2f8676fd-d228-4db5-ac76-1cfc74f48a23",
      "nvLinkDomainId": "59202b81-65fb-45ec-b3b8-91ab0ad3f34a",
      "deviceInstance": 3,
      "status": "Ready",
      "created": "2019-08-24T14:15:22Z",
      "updated": "2019-08-24T14:15:22Z"
    }
  ],
  "dpuExtensionServiceDeployments": [],
  "sshKeyGroupIds": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "sshKeyGroups": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "reno-integration-sre",
      "description": "SRE access SSH keys for Reno Integration",
      "version": "fbc692b61ffef6fbfc38a3833f6b7e7ae508da75",
      "status": "Syncing",
      "created": "2019-08-24T14:15:22Z",
      "updated": "2019-08-24T14:15:22Z"
    }
  ],
  "tpmEkCertificate": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUMxVENDQWJ5Z0F3SUJBZ0lVTEE1ZHFPK1E5OXZQM3VYRTRKcjBncVRtOW93d0RRWUpLb1pJaHZjTkFRRUwKQlFBd0xqRUxNQWtHQTFVRUJoTUNWVk14RXpBUkJnTlZCQW9NQ2s1MmFXUnBZU0JEYjNKNw==",
  "status": "Pending",
  "statusHistory": [
    {
      "status": "Pending",
      "message": "Request received, pending processing",
      "created": "2019-08-24T14:15:22Z",
      "updated": "2019-08-24T14:15:22Z"
    }
  ],
  "created": "2019-08-24T14:15:22Z",
  "updated": "2019-08-24T14:15:22Z"
}