Instance

Create an Instance

Changed on

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.

post/v2/org/{org}/nico/instance

Request

  • Base URL
    https://nico-rest-api.nico.svc.cluster.local
  • URL
    https://nico-rest-api.nico.svc.cluster.local/v2/org/{org}/nico/instance
  • Auth
    HTTP bearer

Request body

namestring required

Name of the Instance

descriptionstring nullable

Description of the Instance, optional

tenantIdstring uuid required

ID of the Tenant creating the Instance

instanceTypeIdstring uuid nullable

ID of the Instance Type to use for Instance

machineIdstring nullable

ID of of specific Machine to use for Instance. Requires Targeted Instance Creation capability enabled for Tenant

machineLabelSelectorMachineLabelSelector

Property names are arbitrary Machine label keys supplied by the caller; there is no predefined set of selector fields. Every property must have a string value; an empty string is allowed, but JSON null is not. Keys must not be empty or whitespace-only. Keys and values may contain at most 255 characters and must not contain the Unicode NUL character (U+0000).

vpcIdstring uuid required

ID of the VPC the Instance should belong to

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.

userDatastring nullable

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 uuid nullable

Must be specified if iPXE Script field is empty

powerProfilestring nullable

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

networkSecurityGroupIdstring nullable

ID of the desired Network Security Group to attach to the Instance

ipxeScriptstring nullable

Override iPXE script specified in OS, must be specified if Operating System is not specified

alwaysBootWithCustomIpxeboolean

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.

phoneHomeEnabledboolean

When set to true, the Instance will be enabled with the Phone Home service.

labelsLabels

Label keys must not be empty or whitespace-only. Keys and values may contain at most 255 characters and must not contain the Unicode NUL character (U+0000). Empty values are allowed.

autoNetworkboolean

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.

sshKeyGroupIdsstring[]

Specify list of SSH Key Group IDs that will provide Serial over LAN access

allowUnhealthyMachineboolean

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

Example request

{
  "name": "spark-monitor-1",
  "description": "Node for monitoring Spark",
  "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
  "instanceTypeId": "41e36058-8403-4086-a9b8-39cb5bc9cb98",
  "vpcId": "5e28ad7c-5fb7-46d6-a28a-fc0ba6fdc4a3",
  "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",
  "alwaysBootWithCustomIpxe": true,
  "phoneHomeEnabled": true,
  "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/latest/meta-data/phone_home\n  post: all",
  "labels": {
    "region": "portland",
    "env": "staging"
  },
  "machineLabelSelector": {
    "custom-machine-label": "required-value"
  },
  "interfaces": [
    {
      "subnetId": "1f232bf0-7b90-456e-b9b0-38d9fea4171a",
      "isPhysical": false
    },
    {
      "subnetId": "31074c90-3061-4d90-bc62-eaf479989b97",
      "isPhysical": true
    }
  ],
  "infinibandInterfaces": [
    {
      "partitionId": "4f4decba-7d7f-46b9-9e5f-e5d71c2e0666",
      "device": "MT2910 Family [ConnectX-7]",
      "deviceInstance": 0,
      "isPhysical": true,
      "virtualFunctionId": null
    }
  ],
  "spectrumXAttachments": [
    {
      "spectrumXPartitionId": "8e6f2a1c-9b3d-4e5f-a6b7-c8d9e0f1a2b3",
      "device": "NVIDIA BlueField-3 B3140L E-Series FHHL SuperNIC",
      "deviceInstance": 0,
      "attachmentType": "Physical",
      "virtualFunctionId": null
    }
  ],
  "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
    }
  ],
  "sshKeyGroupIds": [
    "a7bf2f9c-12f0-4673-be47-12be6d9e16c8"
  ]
}

Response

Created

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

powerProfilestring nullable

External power provisioning profile associated with the Instance.

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

Label keys must not be empty or whitespace-only. Keys and values may contain at most 255 characters and must not contain the Unicode NUL character (U+0000). Empty values are allowed.

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' | 'Unknown'

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"
}

Changes

  • 3a9ac4059293Revision changes
    • breaking

      added subschema #2 to the response property oneOf list for the response status

    • breaking

      the response's property type changed from object to no type for status

    • warning

      removed the optional property / from the response with the status

    • warning

      removed the optional property / from the response with the status

    • warning

      removed the optional property / from the response with the status

    • warning

      removed the optional property / from the response with the status

    • warning

      removed the optional property / from the response with the status

    • warning

      removed the optional property / from the response with the status

    • warning

      removed the optional property / from the response with the status

    • info

      the response property became required for the status

  • 273aadbf1c41Revision changes
    • warning

      removed the optional property // from the response with the status

    • warning

      removed the optional property // from the response with the status

    • warning

      removed the optional property // from the response with the status

    • warning

      removed the optional property // from the response with the status

    • warning

      removed the optional property // from the response with the status

    • warning

      added the new Unknown enum value to the response property for the response status

    • info

      the response optional property // became read-only for the status

    • info

      the response optional property // became read-only for the status

    • info

      the response optional property // became read-only for the status

    • info

      the response optional property // became read-only for the status

    • info

      the response property // became required for the status

    • info

      the response property // became required for the status

    • info

      the response property // became required for the status

    • info

      the response property // became required for the status

    • info

      the response property // became required for the status