---
title: "Create an Instance"
method: POST
path: "/v2/org/{org}/nico/instance"
tags: ["Instance"]
---

# Create an Instance

`POST /v2/org/{org}/nico/instance`

Create an Instance for Tenant.

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

## Request body

- InstanceCreateRequest — Request data to create Instance
  - `name` string, required — Name of the Instance
  - `description` string, nullable — Description of the Instance, optional
  - `tenantId` string, uuid, required — ID of the Tenant creating the Instance
  - `instanceTypeId` string, uuid, nullable — ID of the Instance Type to use for Instance
  - `machineId` string, nullable — ID of of specific Machine to use for Instance. Requires Targeted Instance Creation capability enabled for Tenant
  - `vpcId` string, uuid, required — ID of the VPC the Instance should belong to
  - `secondaryVpcIds` string[] — 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`.
  - `userData` string, nullable — Can only be specified if allowOverride is set to true in Operating System
  - `operatingSystemId` string, uuid, nullable — Must be specified if iPXE Script field is empty
  - `networkSecurityGroupId` string, nullable — ID of the desired Network Security Group to attach to the Instance
  - `ipxeScript` string, nullable — Override iPXE script specified in OS, must be specified if Operating System is not specified
  - `alwaysBootWithCustomIpxe` boolean — 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.
  - `phoneHomeEnabled` boolean — When set to true, the Instance will be enabled with the Phone Home service.
  - `labels` Labels
  - `interfaces` InterfaceCreateRequest[] — 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`. 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.
    - union — Request data to create an Interface for an Instance by associating it with a Subnet, an explicit VPC Prefix, or a VPC from which the Controller selects a prefix. Exactly one of `subnetId`, `vpcPrefixId`, or `vpcId` must be specified. If the VPC specified in the request has FNN virtualization type, all interfaces must specify either `vpcPrefixId` or `vpcId`. If the VPC has Ethernet network virtualization type then all interfaces must specify Subnet.
      - object
        - `subnetId` string, uuid, required — ID of the Subnet to attach to the Interface
        - `vpcPrefixId` string, uuid — ID of the VPC Prefix to attach to the Interface
        - `vpcId` string, uuid — ID of the VPC from which the Controller should select a prefix. `ipFamilies` must also be specified, and `ipAddress` cannot be specified.
        - `ipFamilies` string[] — Address families requested for Controller prefix selection. Required with `vpcId` and prohibited otherwise. Only `IPv4` is currently accepted.
        - `ipAddress` string, nullable — Explicitly requested IP address for the interface. It can only be specified with an explicit `vpcPrefixId`. The least-significant host bit must be 1.
        - `inlineRoutingProfile` InterfaceInlineRoutingProfile — Interface-local routing profile options that narrow the owning VPC's routing profile.
          - `allowedAnycastPrefixes` string[] — CIDR prefixes this interface is allowed to announce as anycast routes.
        - `isPhysical` boolean — Specifies whether this network should be attached to the Instance over a physical interface.
        - `device` string — Name of the device to use
        - `deviceInstance` integer — Index of the device, used to identify which interface card to attache the Partition to
        - `virtualFunctionId` integer, nullable — Index of the virtual function to use, must be specified if isPhysical is false
      - object
        - `subnetId` string, uuid — ID of the Subnet to attach to the Interface
        - `vpcPrefixId` string, uuid, required — ID of the VPC Prefix to attach to the Interface
        - `vpcId` string, uuid — ID of the VPC from which the Controller should select a prefix. `ipFamilies` must also be specified, and `ipAddress` cannot be specified.
        - `ipFamilies` string[] — Address families requested for Controller prefix selection. Required with `vpcId` and prohibited otherwise. Only `IPv4` is currently accepted.
        - `ipAddress` string, nullable — Explicitly requested IP address for the interface. It can only be specified with an explicit `vpcPrefixId`. The least-significant host bit must be 1.
        - `inlineRoutingProfile` InterfaceInlineRoutingProfile — Interface-local routing profile options that narrow the owning VPC's routing profile.
          - `allowedAnycastPrefixes` string[] — CIDR prefixes this interface is allowed to announce as anycast routes.
        - `isPhysical` boolean — Specifies whether this network should be attached to the Instance over a physical interface.
        - `device` string — Name of the device to use
        - `deviceInstance` integer — Index of the device, used to identify which interface card to attache the Partition to
        - `virtualFunctionId` integer, nullable — Index of the virtual function to use, must be specified if isPhysical is false
      - object
        - `subnetId` string, uuid — ID of the Subnet to attach to the Interface
        - `vpcPrefixId` string, uuid — ID of the VPC Prefix to attach to the Interface
        - `vpcId` string, uuid, required — ID of the VPC from which the Controller should select a prefix. `ipFamilies` must also be specified, and `ipAddress` cannot be specified.
        - `ipFamilies` string[] — Address families requested for Controller prefix selection. Required with `vpcId` and prohibited otherwise. Only `IPv4` is currently accepted.
        - `ipAddress` string, nullable — Explicitly requested IP address for the interface. It can only be specified with an explicit `vpcPrefixId`. The least-significant host bit must be 1.
        - `inlineRoutingProfile` InterfaceInlineRoutingProfile — Interface-local routing profile options that narrow the owning VPC's routing profile.
          - `allowedAnycastPrefixes` string[] — CIDR prefixes this interface is allowed to announce as anycast routes.
        - `isPhysical` boolean — Specifies whether this network should be attached to the Instance over a physical interface.
        - `device` string — Name of the device to use
        - `deviceInstance` integer — Index of the device, used to identify which interface card to attache the Partition to
        - `virtualFunctionId` integer, nullable — Index of the virtual function to use, must be specified if isPhysical is false
  - `autoNetwork` boolean — 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.
  - `infinibandInterfaces` InfiniBandInterfaceCreateRequest[] — Associate one or more Partitions with this Instance
    - `partitionId` string, uuid — ID of the Partition the Interface should attach to
    - `device` string — Name of the InfiniBand device to use
    - `vendor` string, nullable — Name of the InfiniBand device vendor, optional
    - `deviceInstance` integer — Index of the device, used to identify which interface card to attache the Partition to
    - `isPhysical` boolean — Specifies whether this Partition should be attached to the Instance over physical interface
    - `virtualFunctionId` integer, nullable — Must be specified if isPhysical is false
  - `dpuExtensionServiceDeployments` DpuExtensionServiceDeploymentRequest[] — DPU Extension Services to deploy to the DPUs of this Instance
    - `dpuExtensionServiceId` string, uuid — ID of the DPU Extension Service to deploy
    - `version` string — Version of the DPU Extension Service to deploy
  - `nvLinkInterfaces` NVLinkInterfaceCreateOrUpdateRequest[] — 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.
    - `nvLinkLogicalPartitionId` string, uuid — ID of the NVLink Logical Partition the Interface should attach to
    - `deviceInstance` integer — GPU index for this NVLink interface. Must be non-negative, unique within the request, and within the GPU count exposed by the selected Machine or Instance Type.
  - `sshKeyGroupIds` string[] — Specify list of SSH Key Group IDs that will provide Serial over LAN access
  - `allowUnhealthyMachine` boolean — 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 `201`

Created

- Instance — Instance is a baremetal Machine that has been provisioned for a Tenant
  - `id` string, uuid — Unique identifier for the Instance
  - `name` string — Name for the Instance
  - `description` string, nullable — Description for the Instance
  - `tenantId` string, uuid — ID of the Tenant the Instance belongs to
  - `infrastructureProviderId` string, uuid — ID of the Infrastructure Provider that owns the Site where the Instance is located
  - `siteId` string, uuid — ID of the Site where the Instance is located
  - `instanceTypeId` string, uuid, nullable — ID of the Instance Type
  - `vpcId` string, uuid — ID of the VPC
  - `secondaryVpcIds` string[] — IDs of VPCs attached to the Instance through non-primary interfaces
  - `machineId` string, nullable — ID of the Machine
  - `operatingSystemId` string, uuid, nullable — ID of the Operating System
  - `networkSecurityGroupId` string, nullable — ID of the attached Network Security Group, if any
  - `networkSecurityGroupPropagationDetails` NetworkSecurityGroupPropagationDetails — The Network Security Group propagation details for a VPC or Instance
    - `objectId` string, uuid — The ID of the object (VPC/Instance etc.)
    - `detailedStatus` 'None' | 'Partial' | 'Full' | 'Unknown' | 'Error' — The detailed propagation status that was actually returned from NICo
    - `status` 'Synchronizing' | 'Synchronized' | 'Error' — Status values for Network Security Group propagation
    - `details` string, nullable — Additional details for the status
    - `unpropagatedInstanceIds` string[] — IDs of Instances associated with the object that have not yet updated their Network Security Group rules
    - `relatedInstanceIds` string[] — IDs of the instances involved in determining the propagation status
    - `deprecations` Deprecation[] — Deprecations active for this resource. Returned only if there are active deprecations.
      - `attribute` string, nullable — Name of the attribute that is deprecated. Omitted if queryParam or endpoint is being deprecated.
      - `queryParam` string, nullable — Query parameter that is deprecated. Omitted if attribute or endpoint is being deprecated.
      - `endpoint` string, nullable — API endpoint that is deprecated. Omitted if attribute or queryParam is being deprecated.
      - `replacedBy` string, nullable — Name of the attribute, query parameter, or endpoint that replaces the deprecated item. Omitted if no replacement is available.
      - `takeActionBy` string, date-time — Date/time by which clients should migrate away from the deprecated API surface
      - `notice` string — Message describing the deprecation
  - `networkSecurityGroupInherited` boolean — Indicates if the Network Security Group is inherited from VPC
  - `controllerInstanceId` string, uuid, nullable — ID of the Instance in Site Controller
  - `ipxeScript` string, nullable — Attribute which is inherited from Operating System
  - `alwaysBootWithCustomIpxe` boolean — Indicates whether the Instance should always execute custom iPXE script when rebooting
  - `phoneHomeEnabled` boolean — Indicates whether the Phone Home service should be enabled or disabled for the Instance
  - `userData` string, nullable — UserData is inherited from Operating System or specified by user if allowed
  - `labels` Labels
  - `isUpdatePending` boolean — Indicates whether an update is available for the Instance. Updates can be applied on reboot
  - `serialConsoleUrl` string, nullable — Serial Console URL for the Instance. Format: ssh://<id>@siteSerialConsoleHostname
  - `autoNetwork` boolean — 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`.
  - `interfaces` Interface[] — Interfaces are list of the subnet associated with the Instance
    - `id` string, uuid — Unique UUID v4 identifier for the Interface
    - `instanceId` string, uuid — ID of the associated Instance
    - `subnetId` string, uuid, nullable — ID of the associated Subnet
    - `vpcPrefixId` string, uuid, nullable — ID of the VPC Prefix explicitly selected by the caller
    - `vpcId` string, uuid — ID of the VPC from which the Controller selects a prefix
    - `ipFamilies` IPFamily[] — Address families requested for Controller prefix selection
    - `isPhysical` boolean — Indicates whether the network is bound on a physical Interface
    - `device` string, nullable — Name of the device to use
    - `deviceInstance` integer, nullable — Index of the device, used to identify which interface card to attache the Partition to
    - `virtualFunctionId` integer, nullable — Must be specified if isPhysical is false
    - `macAddress` string, nullable — MAC address of the Interface
    - `ipAddresses` string[] — A list of IPv4 or IPv6 addresses
    - `requestedIpAddress` string, nullable — Explicitly requested IP address for the interface. This is only used with an explicit `vpcPrefixId` and is not valid with `subnetId` or VPC-selected interfaces. The least-significant host bit must be 1.
    - `inlineRoutingProfile` InterfaceInlineRoutingProfile — Interface-local routing profile options that narrow the owning VPC's routing profile.
      - `allowedAnycastPrefixes` string[] — CIDR prefixes this interface is allowed to announce as anycast routes.
    - `status` 'Pending' | 'Provisioning' | 'Ready' | 'Deleting' | 'Error' — Status values for Interface objects
    - `created` string, date-time — Date/time when the Interface was created
    - `updated` string, date-time — Date/time when the Interface was last updated
  - `infinibandInterfaces` InfiniBandInterface[] — InfiniBandInterfaces are list of the InfiniBandInterface associated with the Instance
    - `id` string, uuid — Unique UUID v4 identifier for the InfiniBandInterface
    - `instanceId` string, uuid — ID of the associated Instance
    - `partitionId` string, uuid — ID of the InfiniBand Partition associated with this interface
    - `device` string — Name of the InfiniBand device associated with this interface
    - `vendor` string, nullable — Name of the InfiniBand device vendor associated with this interface
    - `deviceInstance` integer — Index of the device where partition attach to
    - `isPhysical` boolean — Indicates whether this is a physical interface
    - `virtualFunctionId` integer, nullable — Must be specified if isPhysical is false
    - `guid` string, nullable — Must be specified if isPhysical is false
    - `status` 'Pending' | 'Provisioning' | 'Ready' | 'Deleting' | 'Error' — Status values for InfiniBand Interface objects
    - `created` string, date-time — Date/time when the InfiniBandInterface was created
    - `updated` string, date-time — Date/time when the InfiniBandInterface was last updated
  - `nvLinkInterfaces` NVLinkInterface[] — NVLinkInterfaces are list of the NVLinkInterface associated with the Instance
    - `id` string, uuid — Unique UUID v4 identifier for the NVLinkInterface
    - `instanceId` string, uuid — ID of the associated Instance
    - `nvLinkLogicalPartitionId` string, uuid — ID of the NVLink Logical Partition associated with this interface
    - `nvLinkDomainId` string, uuid, nullable — ID of the NVLink Domain associated with this Interface
    - `deviceInstance` integer — Index of the device, used to identify the GPU associated with this Interface
    - `gpuGuid` string, nullable — Unique ID of the GPU
    - `status` 'Pending' | 'Provisioning' | 'Ready' | 'Deleting' | 'Error' — Status values for NVLink Interface objects
    - `created` string, date-time — Date/time when the NVLinkInterface was created
    - `updated` string, date-time — Date/time when the NVLinkInterface was last updated
    - `deprecations` Deprecation[] — Deprecations active for this resource. Returned only if there are active deprecations.
      - `attribute` string, nullable — Name of the attribute that is deprecated. Omitted if queryParam or endpoint is being deprecated.
      - `queryParam` string, nullable — Query parameter that is deprecated. Omitted if attribute or endpoint is being deprecated.
      - `endpoint` string, nullable — API endpoint that is deprecated. Omitted if attribute or queryParam is being deprecated.
      - `replacedBy` string, nullable — Name of the attribute, query parameter, or endpoint that replaces the deprecated item. Omitted if no replacement is available.
      - `takeActionBy` string, date-time — Date/time by which clients should migrate away from the deprecated API surface
      - `notice` string — Message describing the deprecation
  - `dpuExtensionServiceDeployments` DpuExtensionServiceDeployment[] — DPU Extension Services deployed on DPUs of this Instance
    - `id` string, uuid — Unique identifier for the DPU Extension Service Deployment
    - `dpuExtensionService` DpuExtensionServiceSummary — DPU Extension Service allows user defined services to run on DPUs of their Instances
      - `id` string, uuid — Unique identifier for the DPU Extension Service
      - `name` string — Name for the DPU Extension Service. Must be unique for a given Tenant
      - `serviceType` 'KubernetesPod' — Type of the DPU Extension Service
      - `latestVersion` string, nullable — Latest version of the DPU Extension Service
      - `status` 'Pending' | 'Ready' | 'Error' | 'Deleting' — Status values for DPU Extension Service objects
    - `version` string — Deployed version of the DPU Extension Service
    - `status` 'Pending' | 'Running' | 'Error' | 'Failed' | 'Terminating' — Status values for DPU Extension Service Deployment objects
    - `created` string, date-time — Date/time when this version of the DPU Extension Service Deployment was created
    - `updated` string, date-time — Date/time when this version of the DPU Extension Service Deployment was updated
  - `sshKeyGroupIds` string[] — IDs of SSH Key Groups associated with this Instance
  - `sshKeyGroups` SshKeyGroup[] — IDs of SSH Key Groups associated with this Instance
    - `id` string, uuid — Unique identifier for the SSH Key Group
    - `name` string — Name of the SSH Key Group
    - `description` string, nullable — Description for the SSH Key Group, optional
    - `org` string — Organization this SSH Key Group belongs to
    - `tenantId` string, uuid — ID of the Tenane the SSH Key Group belongs to
    - `version` string, nullable — Version of the SSH Key Group
    - `sshKeys` SshKey[] — SSH Keys associated with this SSH Key Group
      - `id` string, uuid — Unique identifier for the key
      - `name` string — Name of the SSHKey
      - `org` string — Organization the SSHKey belongs to
      - `tenantId` string, uuid — ID of the Tenant
      - `fingerprint` string — SHA256 fingerprint of the public key
      - `created` string, date-time — Date/time when the SSH key was created
      - `updated` string, date-time — Date/time when the SSH key was last updated
    - `siteAssociations` SshKeyGroupSiteAssociation[] — Sites the SSH Key Group is synced to
      - `site` SiteSummary — SiteSummary contains a subset of data for Site object, used when nesting in other objects
        - `id` string, uuid — Unique UUID v4 identifier for the Site
        - `name` string — Name of the Site
        - `infrastructureProviderId` string, uuid — ID of the Infrastructure Provider that owns the Site
        - `isSerialConsoleEnabled` boolean — Indicates if Serial Console is enabled for the Site by the Provider
        - `isOnline` boolean — Indicates if the Site is currently reachable from Cloud
        - `capabilities` SiteCapabilities — Boolean flags to indicate features supported by a Site
          - `nativeNetworking` boolean — Whether the Site supports native networking
          - `networkSecurityGroup` boolean — Whether the Site supports Network Security Groups
          - `nvLinkPartition` boolean — Whether the Site supports NVLink partitioning
          - `flow` boolean — Whether the Site supports Flow-based operations
          - `imageBasedOperatingSystem` boolean — Whether the Site supports image-based operating system provisioning
        - `status` 'Pending' | 'Registered' | 'Error' — Status values for Site objects
      - `status` 'Syncing' | 'Synced' | 'Pending' | 'Error' | 'Deleting' — Status values for SSH Key Group Site Association objects
      - `version` string, nullable — Version of the Key Group on Site
      - `created` string, date-time — Date/time when the Site was created
      - `updated` string, date-time — Date/time when the Site was last updated
    - `status` 'Syncing' | 'Synced' | 'Error' | 'Deleting' — Status values for SSH Key Group objects
    - `statusHistory` StatusDetail[] — History of the SSH Key Group states
      - `status` string — State of the associated entity at a particular time
      - `message` string, nullable — Description of the state and cause/remedy in case of error
      - `created` string, date-time — Date/time when the associated entity assumed the status
      - `updated` string, date-time — Date/time when the associated entity was last observed with this status
    - `created` string, date-time — Date/time when the SSH key was created
    - `updated` string, date-time — Date/time when the SSH key was last updated
  - `tpmEkCertificate` string, 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
  - `statusHistory` StatusDetail[] — Chronological status history for the Instance
    - `status` string — State of the associated entity at a particular time
    - `message` string, nullable — Description of the state and cause/remedy in case of error
    - `created` string, date-time — Date/time when the associated entity assumed the status
    - `updated` string, date-time — Date/time when the associated entity was last observed with this status
  - `deprecations` Deprecation[] — Deprecations active for this resource. Returned only if there are active deprecations.
    - `attribute` string, nullable — Name of the attribute that is deprecated. Omitted if queryParam or endpoint is being deprecated.
    - `queryParam` string, nullable — Query parameter that is deprecated. Omitted if attribute or endpoint is being deprecated.
    - `endpoint` string, nullable — API endpoint that is deprecated. Omitted if attribute or queryParam is being deprecated.
    - `replacedBy` string, nullable — Name of the attribute, query parameter, or endpoint that replaces the deprecated item. Omitted if no replacement is available.
    - `takeActionBy` string, date-time — Date/time by which clients should migrate away from the deprecated API surface
    - `notice` string — Message describing the deprecation
  - `created` string, date-time — Date/time when the Instance was created
  - `updated` string, date-time — Date/time when the Instance was last updated

## Other responses

- `400` — Error response when request data cannot be validated
- `403` — Error response when user is not authorized to call an endpoint or retrieve/modify objects
- `429` — Error response when the Controller cannot allocate a requested resource because capacity is exhausted

---

[API](https://skmtc.net/nvidia/apis/nvidia-infra-controller-rest-api.md) · [All operations](https://skmtc.net/nvidia/apis/nvidia-infra-controller-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/nvidia/nvidia-infra-controller-rest-api/versions/69e00804e732/schema)