Create VPC

POST

https://nico-rest-api.nico.svc.cluster.local/v2/org/:org/nico/vpc

POST

/v2/org/:org/nico/vpc

curl -X POST https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/vpc \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "name": "spark-vpc",
  "siteId": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "description": "Virtual network for machines executing Spark jobs",
  "networkVirtualizationType": "ETHERNET_VIRTUALIZER",
  "slaacEnabled": false,
  "vni": 12001,
  "nvLinkLogicalPartitionId": "dd887330-dbd3-45ce-b400-c42fc8e47315",
  "labels": {
    "env": "dev",
    "region": "us-west-1"
  }
}'

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "spark-vpc",
  "description": "Virtual network for machines executing Spark jobs",
  "org": "xskkpgqpeakn",
  "tenantId": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  "siteId": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
  "controllerVpcId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "networkVirtualizationType": "ETHERNET_VIRTUALIZER",
  "slaacEnabled": false,
  "requestedVni": 12001,
  "vni": 12001,
  "nvLinkLogicalPartitionId": "dd887330-dbd3-45ce-b400-c42fc8e47315",
  "labels": {
    "env": "dev",
    "region": "us-west-1"
  },
  "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"
}

Create a VPC for the org.

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

When slaacEnabled is true, REST reads vpcSlaac from the latest successfully stored configuration inventory for the selected Site before persisting the VPC. Periodic Site inventory reports whether Core supports this feature, so the stored value can lag a Core rollout. False or missing vpcSlaac returns 412 before REST persistence or workflow dispatch. This flag reports Core support only; it does not verify DPU agent versions. When a new API server release is deployed, DPU agents roll forward, and instance network configuration may fail transiently until eligible agents converge. Core can also return 412 after dispatch for another create prerequisite. Failure to resolve the Site client or persist the VPC returns 500, rolls back the REST transaction, and does not request a remote create. An error returned while starting the workflow also returns 500 and may leave remote acceptance unknown. After the start request, an unavailable result returns 503, while a workflow wait timeout returns 500 and triggers an attempted workflow termination. Errors while starting or waiting for the workflow roll back the REST transaction, but do not guarantee that Core did not create the VPC; a later inventory reconciliation may recreate the REST record.

Safe recovery from an ambiguous create result requires supplying a stable id in the original request. After an ambiguous error while starting the workflow or after dispatch, callers should allow inventory reconciliation time, then retrieve that id. If the VPC is found, do not retry. If no record is found, reuse the same id for any retry; reusing the ID prevents a second Core VPC record, but the retry itself is not guaranteed to succeed and can return 409 if reconciliation completes concurrently.

Create a VPC for the org. Org must have a Tenant entity. User must have authorization role with `TENANT_ADMIN` suffix. When `slaacEnabled` is true, REST reads `vpcSlaac` from the latest successfully stored configuration inventory for the selected Site before persisting the VPC. Periodic Site inventory reports whether Core supports this feature, so the stored value can lag a Core rollout. False or missing `vpcSlaac` returns 412 before REST persistence or workflow dispatch. This flag reports Core support only; it does not verify DPU agent versions. When a new API server release is deployed, DPU agents roll forward, and instance network configuration may fail transiently until eligible agents converge. Core can also return 412 after dispatch for another create prerequisite. Failure to resolve the Site client or persist the VPC returns 500, rolls back the REST transaction, and does not request a remote create. An error returned while starting the workflow also returns 500 and may leave remote acceptance unknown. After the start request, an unavailable result returns 503, while a workflow wait timeout returns 500 and triggers an attempted workflow termination. Errors while starting or waiting for the workflow roll back the REST transaction, but do not guarantee that Core did not create the VPC; a later inventory reconciliation may recreate the REST record. Safe recovery from an ambiguous create result requires supplying a stable `id` in the original request. After an ambiguous error while starting the workflow or after dispatch, callers should allow inventory reconciliation time, then retrieve that `id`. If the VPC is found, do not retry. If no record is found, reuse the same `id` for any retry; reusing the ID prevents a second Core VPC record, but the retry itself is not guaranteed to succeed and can return 409 if reconciliation completes concurrently.

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

``` 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

namestringRequired2-256 characters

Name of the VPC

siteIdstringRequiredformat: "uuid"

ID of the Site where the VPC should be created

idstringOptionalformat: "uuid"

Optional user-specified UUID for the VPC

descriptionstring or nullOptional

Optional description for the VPC

networkVirtualizationTypeenumOptional

Network virtualization type of the VPC. If no value is specified, then defaults to FNN if Site has native networking enabled, or ETHERNET_VIRTUALIZER if native networking is disabled. Flat VPCs hold instances on zero-DPU hosts (or hosts with their DPU in NIC mode) and are never auto-selected — FLAT must be specified explicitly.

slaacEnabledbooleanOptionalDefaults to false

When true, Core allocates a /64 to each instance interface that includes IPv6 and retains the prefix without assigning a concrete IPv6 host address. It is supported only for FNN VPCs and fixed during creation. False or omission disables SLAAC. Before persistence, REST requires vpcSlaac in the latest successfully stored configuration inventory for the selected Site. Periodic Site inventory reports whether Core supports this feature, so the stored value can lag a Core rollout. False or missing vpcSlaac returns 412 before REST persistence or workflow dispatch. This flag does not verify DPU agent versions. When a new API server release is deployed, DPU agents roll forward, and instance network configuration may fail transiently until eligible agents converge. NICo does not yet configure router advertisements (RAs); that support is tracked by https://github.com/NVIDIA/infra-controller/issues/2398.

routingProfilestring or nullOptional3-64 characters

Specify a Site-configured routing profile returned by GET /tenant/current/routing-profile for the VPC. Only supported when networkVirtualizationType is set to FNN, or when networkVirtualizationType is omitted and Site has Native Networking enabled. Requires Tenant to have elevated privilege.

routingProfileOverridesobject or nullOptional

Routing-profile properties to overlay on the resolved named profile. Only supported for FNN VPCs and requires TargetedInstanceCreation to be effective for the Tenant at the VPC’s Site. routingProfile may be omitted when the Site and Tenant configuration select a named profile.

powerResourceGroupstring or nullOptional>=1 character

Power resource group to associate with the VPC. A non-empty value requires the Site’s dpsPowerManagement capability to be true.

networkSecurityGroupIdstring or nullOptional

ID of the Network Security Group to attach to the VPC

vniinteger or nullOptional1-65535

Explicitly requested VNI for the VPC

nvLinkLogicalPartitionIdstring or nullOptionalformat: "uuid"

ID of the default NVLink Logical Partition that GPUs for all Instances in the VPC will attach to

labelsmap from strings to stringsOptional

String key-value pairs describing VPC labels. Up to 10 key-value pairs can be specified

Response

Created

idstringOptionalRead-onlyformat: "uuid"

ID of the VPC

namestringOptional2-256 characters

Name of the VPC

descriptionstring or nullOptional

Description of the VPC, can be empty

orgstringOptionalRead-only

Organization the VPC belongs to

tenantIdstringOptionalRead-onlyformat: "uuid"

ID of the Tenant the VPC belongs to

siteIdstringOptionalformat: "uuid"

ID of the Site the VPC belongs to

controllerVpcIdstring or nullOptionalformat: "uuid"

Legacy attribute, contains the same value as ID

networkVirtualizationTypeenumOptional

Network virtualization type of the VPC. Flat VPCs hold instances on zero-DPU hosts (or hosts with their DPU in NIC mode); their interfaces are bound to underlay (HostInband) network segments and NICo does not drive their data plane.

slaacEnabledbooleanOptionalRead-only

Whether this VPC uses SLAAC allocation mode for instance IPv6 interfaces. When true, Core allocates a /64 to each interface that includes IPv6 and retains the prefix without assigning a concrete IPv6 host address. This value is fixed when the VPC is created. NICo does not yet configure router advertisements (RAs); that support is tracked by https://github.com/NVIDIA/infra-controller/issues/2398.

routingProfilestring or nullOptional1-64 characters

Routing profile type for the VPC. Populated when Site has Native Networking enabled and network virtualization type is FNN.

powerResourceGroupstring or nullOptional

External power provisioning resource group associated with the VPC.

routingProfileOverridesobject or nullOptional

Routing-profile properties set directly on the VPC. Unset properties inherit from the named routing profile.

effectiveRoutingProfileobjectOptional

Fully resolved routing profile last reported by Core for the VPC. This property is included only when the requesting Tenant has effective TargetedInstanceCreation permission for the VPC's Site.

requestedVniinteger or nullOptionalRead-only1-65535

Explicitly requested VNI for the VPC if one was requested at creation time

vniinteger or nullOptionalRead-only1-16777215

Active VNI assigned to the VPC

networkSecurityGroupIdstring or nullOptional

ID of the Network Security Group attached to the VPC

networkSecurityGroupPropagationDetailsobjectOptional

Propagation details for the attached Network Security Group

nvLinkLogicalPartitionIdstring or nullOptionalformat: "uuid"

ID of the default NVLink Logical Partition that GPUs for all Instances in the VPC will attach to

labelsmap from strings to stringsOptional

String key-value pairs describing VPC labels

statusenumOptional

Status of the VPC

statusHistorylist of objectsOptionalRead-only

History of status changes for the VPC

createddatetimeOptionalRead-only

Date/time when VPC was created

updateddatetimeOptionalRead-only

Date/time when VPC was last updated

Errors

400

Bad Request Error

403

Forbidden Error

409

Conflict Error

412

Precondition Failed Error

500

Internal Server Error

503

Service Unavailable Error