Retrieve a Machine

GET

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

GET

/v2/org/:org/nico/machine/:machineId

curl https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/machine/machineId \
     -H "Authorization: Bearer <token>"

{
  "id": "fm100ht4v4mce2qstjnl8970nnj3ie6ecek4mtjn27pea4kre5gsa49jg0g",
  "infrastructureProviderId": "e94bcfda-f6cb-42e4-80ec-516811e5abbf",
  "siteId": "60189e9c-7d12-438c-b9ca-6998d9c364b1",
  "instanceTypeId": "2e016c02-2c67-48aa-b289-5d3ca6320c52",
  "instanceId": "59bdaaff-3998-4fd9-a140-8749beeb605e",
  "tenantId": "99819e6e-4017-4021-9edd-ea1bdf4dbd59",
  "controllerMachineId": "fm100ht4v4mce2qstjnl8970nnj3ie6ecek4mtjn27pea4kre5gsa49jg0g",
  "controllerMachineType": "x86_64",
  "hwSkuDeviceType": "cpu",
  "vendor": "Lenovo",
  "productName": "ThinkSystem SR670 V2",
  "serialNumber": "J1060ACR.D3KS2CS001G",
  "machineCapabilities": [
    {
      "type": "CPU",
      "name": "Intel(R) Xeon(R) Gold 6354 CPU @ 3.00GHz",
      "frequency": "3.0GHz",
      "cores": 18,
      "threads": 36,
      "count": 2
    },
    {
      "type": "Memory",
      "name": "Corsair Vengeance LPX",
      "capacity": "32GB",
      "count": 4
    },
    {
      "type": "Network",
      "name": "MT42822 BlueField-2 integrated ConnectX-6 Dx network controller",
      "count": 2,
      "deviceType": "DPU"
    },
    {
      "type": "Storage",
      "name": "Dell Ent NVMe CM6 RI 1.92TB",
      "capacity": "1.92TB",
      "count": 2
    },
    {
      "type": "GPU",
      "name": "NVIDIA A100 PCIe",
      "capacity": "80GB",
      "count": 2
    },
    {
      "type": "InfiniBand",
      "name": "MT28908 Family [ConnectX-6]",
      "vendor": "Mellanox Technologies",
      "count": 2
    }
  ],
  "machineInterfaces": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "machineId": "fm100ht4v4mce2qstjnl8970nnj3ie6ecek4mtjn27pea4kre5gsa49jg0g",
      "controllerInterfaceId": "ad3dac49-741d-4c1f-815c-c020127c532f",
      "controllerSegmentId": "f2207a3c-1847-42e5-bf2c-cd015f87a2bc",
      "attachedDpuMachineID": "fm100dsg4ekcb4sdi6hkqn0iojhj18okrr8vct64luh8957lfe8e69vme20,",
      "subnetId": "1f232bf0-7b90-456e-b9b0-38d9fea4171a",
      "hostname": "example.com",
      "isPrimary": true,
      "macAddress": "00:00:5e:00:53:af",
      "ipAddresses": [
        "192.156.7.23",
        "202.88.37.112"
      ],
      "created": "2019-08-24T14:15:22Z",
      "updated": "2019-08-24T14:15:22Z"
    }
  ],
  "maintenanceMessage": null,
  "health": {
    "source": "aggregate-host-health",
    "observedAt": null,
    "successes": [
      {
        "id": "BgpDaemonEnabled",
        "target": null
      },
      {
        "id": "BgpStats",
        "target": null
      },
      {
        "id": "DhcpServer",
        "target": null
      },
      {
        "id": "DpuDiskUtilizationCheck",
        "target": null
      },
      {
        "id": "FanSpeed",
        "target": "System Board Fan1A"
      },
      {
        "id": "PowerSupply",
        "target": "PS1 Status"
      },
      {
        "id": "Temperature",
        "target": "CPU1 Temp"
      },
      {
        "id": "Temperature",
        "target": "System Board Exhaust Temp"
      },
      {
        "id": "Voltage",
        "target": "CPU1 1P8 PG"
      }
    ],
    "alerts": []
  },
  "labels": {
    "RackIdentifier": "GVX11F01C02",
    "ServerName": "SITE1-C03-Server-02"
  },
  "status": "InUse",
  "isUsableByTenant": true,
  "statusHistory": [
    {
      "status": "InUse",
      "message": "Machine is assigned to an Instance",
      "created": "2019-08-24T14:15:22Z",
      "updated": "2019-08-24T14:15:22Z"
    }
  ],
  "created": "2019-08-24T14:15:22Z",
  "updated": "2019-08-24T14:15:22Z"
}

Org must have either an Infrastructure Provider entity or a Tenant entity.

If org has an Infrastructure Provider entity, then a user with PROVIDER_ADMIN role can request details for any Machine on any Site owned by the Provider.

If org has a Tenant entity, then a user with TENANT_ADMIN role can request details for any Machine associated with Tenant’s active Instances.

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

Path parameters

orgstringRequired

Name of the Org

machineIdstringRequired

ID of the Machine

Query parameters

includeRelationenumOptional

Related entity to expand

Allowed values:

includeMetadatabooleanOptional

Include Machine metadata e.g. BMC, DPU, GPU and Interface data. Can only be requested by Provider.

Response

idstringOptionalRead-only

Unique ID of Machine

infrastructureProviderIdstringOptionalRead-onlyformat: "uuid"

ID of the Provider that owns the Machine

siteIdstringOptionalformat: "uuid"

ID of the Site the Machine belongs to

instanceTypeIdstring or nullOptionalformat: "uuid"

ID of the Instance Type, if assigned

instanceIdstring or nullOptionalformat: "uuid"

ID of the associated Instance, or null when unassigned. The association remains during termination until Instance inventory confirms deletion. A non-null value precludes Ready status.

tenantIdstring or nullOptionalformat: "uuid"

ID of the Tenant that owns the Instance if the Machine is assigned to one

controllerMachineIdstringOptional

ID of the Machine at Site, now same as the primary ID

controllerMachineTypestring or nullOptional

Denotes architecture (x86 vs ARM) of the Machine

hwSkuDeviceTypestring or nullOptional

SKU derived device type of the machine, e.g. cpu, gpu, cache, storage, etc.

vendorstring or nullOptional

Name of the vendor of the Machine

productNamestring or nullOptional

Product name of the Machine

serialNumberstring or nullOptional

Serial number of the Machine, only visible to Provider

machineCapabilitieslist of objectsOptional

List of capabilities of the machine

machineInterfaceslist of objectsOptional

List of admin interfaces of the machine

associatedDpuMachineIdslist of stringsOptionalRead-only

IDs of the DPU Machines attached to this host Machine

placementInRackobjectOptional

Physical placement of the Machine within its Rack, when known

maintenanceMessagestring or nullOptional

If the Machine is in maintenance mode, this message will typically describe the reason and how long it is expected to be in maintenance

scoutVersionstring or nullOptionalRead-only

Scout version reported by the Machine, if known

healthobjectOptional

Health information about the machine

metadataobjectOptional

Only available to Providers. Returned if the includeMetadata query parameter is specified. Otherwise attribute is omitted from response.

labelsmap from strings to stringsOptional

User-specified Machine labels

statusenumOptional

Machine status combines the observed Core lifecycle with REST Instance assignment. A Ready Machine becomes InUse when REST assigns it, and remains InUse if Core reports Ready while the REST assignment still exists. Error, Maintenance, Initializing, and other non-Ready states retain precedence. When Instance deletion clears the assignment, InUse returns to Ready only if the retained Core snapshot reports Ready; otherwise fresh Machine inventory establishes the next status. Ready is not a reservation and does not guarantee that a subsequent Instance creation will succeed.

isUsableByTenantbooleanOptionalRead-only

Indicates whether the machine is usable by or currently in use by a tenant. It does not indicate that a Machine is available for Instance creation.

statusHistorylist of objectsOptional

Chronological status history for the Machine

createddatetimeOptionalRead-only

Date/time when the Machine was created

updateddatetimeOptionalRead-only

Date/time when the Machine was last updated

Errors

403

Forbidden Error

404

Not Found Error