Machine

Retrieve all Machines

Changed on

Get all Machines visible to the caller.

Infrastructure Provider callers receive Machines owned by their Provider. Tenant Admin callers receive Machines only from Sites where TargetedInstanceCreation is effective. The siteId query parameter is optional and further restricts either result set.

get/v2/org/{org}/nico/machine

Request

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

Query parameters

siteIdstring

Filter Machines by Site ID

idstring

Filter Machines by ID. Can be specified multiple times to filter on more than one ID.

hasInstanceTypeboolean

Filter Machines that have been assigned an Instance Type.

instanceTypeIdstring

Filter Machines by Instance Type ID. Can be specified multiple times to filter on more than one Instance Type ID.

tenantIdstring

Filter Machines by ID of tenant of assigned instance. Can be specified multiple times to filter on more than one Tenant ID.

hasInstanceboolean

Filter Machines that are assigned to an Instance. siteId must be specified when using this param.

isMissingOnSiteboolean

Filter Machines that are missing on Site.

includeMetadataboolean

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

statusstring

Filter Machines by Status. Can be specified multiple times to filter on more than one Status.

capabilityTypestring

Filter Machines by Capability Type

capabilityNamestring

Filter Machines by Capability Name. Can be specified multiple times to filter on more than one Capability Name.

hwSkuDeviceTypestring

Filter Machines by hardware SKU Device Type. Example values: "gpu", "cpu", "storage", "cache"

querystring

Provide query to search for matches. Input will be matched against Machine ID, vendor, product name, hostname and status

includeRelation'InfrastructureProvider' | 'Site' | 'InstanceType'

Related entity to expand

pageNumberinteger

One-indexed page number.

Page number for pagination query

pageSizeinteger
Example:20

Page size for pagination query

orderBy'STATUS_ASC' | 'STATUS_DESC' | 'CREATED_ASC' | 'CREATED_DESC' | 'UPDATED_ASC' | 'UPDATED_DESC' | 'ID_ASC' | 'ID_DESC'

Ordering for pagination query

Response

OK

idstring

Unique ID of Machine

infrastructureProviderIdstring uuid

ID of the Provider that owns the Machine

siteIdstring uuid

ID of the Site the Machine belongs to

instanceTypeIdstring uuid nullable

ID of the Instance Type, if assigned

instanceIdstring uuid nullable

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

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

controllerMachineIdstring

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

controllerMachineTypestring nullable

Denotes architecture (x86 vs ARM) of the Machine

hwSkuDeviceTypestring nullable

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

vendorstring nullable

Name of the vendor of the Machine

productNamestring nullable

Product name of the Machine

serialNumberstring nullable

Serial number of the Machine, only visible to Provider

associatedDpuMachineIdsstring[]

IDs of the DPU Machines attached to this host Machine

maintenanceMessagestring nullable

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 nullable

Scout version reported by the Machine, if known

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.

status'Initializing' | 'Ready' | 'Reset' | 'Maintenance' | 'InUse' | 'Error' | 'Decommissioning' | 'Decommissioned' | 'Unknown'

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.

isUsableByTenantboolean

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.

createdstring date-time

Date/time when the Machine was created

updatedstring date-time

Date/time when the Machine was last updated

Example response

[
  {
    "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
      }
    ],
    "machineInterfaces": [
      {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "machineId": "fm100ht4v4mce2qstjnl8970nnj3ie6ecek4mtjn27pea4kre5gsa49jg0g",
        "controllerInterfaceId": "ad3dac49-741d-4c1f-815c-c020127c532f",
        "controllerSegmentId": "f2207a3c-1847-42e5-bf2c-cd015f87a2bc",
        "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,
    "scoutVersion": "2.6.1",
    "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": [
        {
          "id": "FailedValidationTest",
          "target": "DcgmFullShort",
          "inAlertSince": null,
          "message": "Failed validation test:\nName:DcgmFullShort\nCommand:dcgmi\nArgs:diag -r 2",
          "tenantMessage": null,
          "classifications": [
            "PreventAllocations"
          ]
        }
      ]
    },
    "labels": {
      "RackIdentifier": "GVX11F01C02",
      "ServerName": "SITE1-C03-Server-02"
    },
    "status": "Error",
    "isUsableByTenant": false,
    "statusHistory": [
      {
        "status": "Error",
        "message": "Machine has one or more health probe alerts that prevents allocation",
        "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

  • b0c3be6c8504Revision changes
    • breaking

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

    • 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

    • 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

    • 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

    • 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

    • info

      the response property // became required for the status

  • 293dc126ab73Revision changes
    • info

      removed the nico enum value from the response property for the response status