Create an Instance

POST

https://carbide-rest-api.carbide.svc.cluster.local/v2/org/:org/carbide/instance

POST

/v2/org/:org/carbide/instance

1 curl -X POST https://carbide-rest-api.carbide.svc.cluster.local/v2/org/org/carbide/instance \
2      -H "Authorization: Bearer <token>" \
3      -H "Content-Type: application/json" \
4      -d '{
5   "name": "spark-monitor-1",
6   "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
7   "vpcId": "5e28ad7c-5fb7-46d6-a28a-fc0ba6fdc4a3",
8   "interfaces": [
9     {
10       "subnetId": "1f232bf0-7b90-456e-b9b0-38d9fea4171a",
11       "isPhysical": true
12     }
13   ],
14   "description": "Node for monitoring Spark",
15   "instanceTypeId": "41e36058-8403-4086-a9b8-39cb5bc9cb98",
16   "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",
17   "operatingSystemId": "eaeb86ee-c435-444e-9e01-8346f67f194b",
18   "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\nshell",
19   "alwaysBootWithCustomIpxe": true,
20   "labels": {
21     "region": "portland",
22     "env": "staging"
23   },
24   "infinibandInterfaces": [
25     {
26       "partitionId": "4f4decba-7d7f-46b9-9e5f-e5d71c2e0666",
27       "device": "MT2910 Family [ConnectX-7]",
28       "deviceInstance": 0,
29       "isPhysical": true,
30       "virtualFunctionId": null
31     }
32   ],
33   "nvLinkInterfaces": [
34     {
35       "deviceInstance": 0,
36       "nvLinkLogicalPartitionId": "2f8676fd-d228-4db5-ac76-1cfc74f48a23"
37     },
38     {
39       "deviceInstance": 1,
40       "nvLinkLogicalPartitionId": "2f8676fd-d228-4db5-ac76-1cfc74f48a23"
41     },
42     {
43       "deviceInstance": 2,
44       "nvLinkLogicalPartitionId": "2f8676fd-d228-4db5-ac76-1cfc74f48a23"
45     },
46     {
47       "deviceInstance": 3,
48       "nvLinkLogicalPartitionId": "2f8676fd-d228-4db5-ac76-1cfc74f48a23"
49     }
50   ],
51   "sshKeyGroupIds": [
52     "497f6eca-6276-4993-bfeb-53cbbbba6f08"
53   ]
54 }'

1 {
2   "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
3   "name": "spark-monitor-1",
4   "description": "Node for monitoring Spark",
5   "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
6   "infrastructureProviderId": "e94bcfda-f6cb-42e4-80ec-516811e5abbf",
7   "siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
8   "instanceTypeId": "41e36058-8403-4086-a9b8-39cb5bc9cb98",
9   "vpcId": "5e28ad7c-5fb7-46d6-a28a-fc0ba6fdc4a3",
10   "machineId": "fm100ht4v4mce2qstjnl8970nnj3ie6ecek4mtjn27pea4kre5gsa49jg0g",
11   "operatingSystemId": "eaeb86ee-c435-444e-9e01-8346f67f194b",
12   "controllerInstanceId": null,
13   "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\nshell",
14   "alwaysBootWithCustomIpxe": true,
15   "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",
16   "labels": {
17     "region": "portland",
18     "env": "staging"
19   },
20   "isUpdatePending": false,
21   "serialConsoleUrl": "ssh://user@carbide.acme.com",
22   "interfaces": [
23     {
24       "id": "64d2028c-ae87-4069-a624-66089d957ef9",
25       "instanceId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
26       "subnetId": "1f232bf0-7b90-456e-b9b0-38d9fea4171a",
27       "isPhysical": true,
28       "virtualFunctionId": null,
29       "macAddress": null,
30       "ipAddresses": [],
31       "status": "Pending",
32       "created": "2019-08-24T14:15:22Z",
33       "updated": "2019-08-24T14:15:22Z"
34     }
35   ],
36   "infinibandInterfaces": [
37     {
38       "id": "c518a0e8-3f49-4a1a-8935-a6d3dee6911e",
39       "instanceId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
40       "partitionId": "05ef7e84-1d4e-4e4d-980d-38589479a0fe",
41       "device": "MT2910 Family [ConnectX-7]",
42       "deviceInstance": 0,
43       "isPhysical": true,
44       "virtualFunctionId": null,
45       "guid": "946dae0300339498",
46       "status": "Pending",
47       "created": "2019-08-24T14:15:22Z",
48       "updated": "2019-08-24T14:15:22Z"
49     }
50   ],
51   "nvLinkInterfaces": [
52     {
53       "id": "fc19ab3f-1e52-4846-91bd-98743ff2752c",
54       "instanceId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
55       "nvLinkLogicalPartitionId": "2f8676fd-d228-4db5-ac76-1cfc74f48a23",
56       "nvLinkDomainId": "59202b81-65fb-45ec-b3b8-91ab0ad3f34a",
57       "deviceInstance": 0,
58       "status": "Ready",
59       "created": "2019-08-24T14:15:22Z",
60       "updated": "2019-08-24T14:15:22Z"
61     }
62   ],
63   "dpuExtensionServiceDeployments": [],
64   "sshKeyGroupIds": [
65     "497f6eca-6276-4993-bfeb-53cbbbba6f08"
66   ],
67   "sshKeyGroups": [
68     {
69       "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
70       "name": "reno-integration-sre",
71       "description": "SRE access SSH keys for Reno Integration",
72       "version": "fbc692b61ffef6fbfc38a3833f6b7e7ae508da75",
73       "status": "Syncing",
74       "created": "2019-08-24T14:15:22Z",
75       "updated": "2019-08-24T14:15:22Z"
76     }
77   ],
78   "status": "Pending",
79   "statusHistory": [
80     {
81       "status": "Pending",
82       "message": "Request received, pending processing",
83       "created": "2019-08-24T14:15:22Z",
84       "updated": "2019-08-24T14:15:22Z"
85     }
86   ],
87   "deprecations": [
88     {
89       "attribute": "sshkeygroups",
90       "replacedBy": "sshKeyGroups",
91       "takeActionBy": "2025-09-04T00:00:00Z",
92       "notice": "'sshkeygroups' is being deprecated in favor of 'sshKeyGroups'. Please take action prior to the specified date."
93     }
94   ],
95   "created": "2019-08-24T14:15:22Z",
96   "updated": "2019-08-24T14:15:22Z"
97 }

Create an Instance for Tenant.

Org must have a Tenant entity. User must have FORGE_TENANT_ADMIN authorization role.

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://carbide-rest-api.carbide.svc.cluster.local/v2/org/$ORG_NAME/carbide/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://carbide-rest-api.carbide.svc.cluster.local/v2/org/$ORG_NAME/carbide/user/current ```

Path parameters

orgstringRequired

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

interfaceslist of objectsRequired

At least one interface must be specified. 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

descriptionstring or nullOptional<=1024 characters

Description of the Instance, optional

instanceTypeIdstringOptionalformat: "uuid"

ID of the Instance Type to use for Instance

machineIdstringOptional

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

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

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

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

instanceTypeIdstringformat: "uuid"

vpcIdstringformat: "uuid"

secondaryVpcIdslist of strings

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

machineIdstring or null

operatingSystemIdstringformat: "uuid"

networkSecurityGroupIdstring or null

networkSecurityGroupPropagationDetailsobject

Propagation details for the attached Network Security Group

networkSecurityGroupInheritedboolean

Indicates if the Network Security Group is inherited from VPC

controllerInstanceIdstring or nullformat: "uuid"

ipxeScriptstring or null

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 Instance

userDatastring or null

labelsmap from strings to strings

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

interfaceslist of objects

infinibandInterfaceslist of objects

nvLinkInterfaceslist of objects

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 values for Instance objects

statusHistorylist of objects

deprecationslist of objects

createddatetimeRead-only

updateddatetimeRead-only

Errors

400

Bad Request Error

403

Forbidden Error