API of Hardware Introspection for Bare Metal

API versions

Concepts

In order to bring new features to users over time, the Ironic Inspector API supports versioning. There are two kinds of versions:

  • major versions, which have dedicated urls.

  • microversions, which can be requested through the use of the X-OpenStack-Ironic-Inspector-API-Version header.

The Version APIs work differently from other APIs as they do not require authentication.

All API requests support the X-OpenStack-Ironic-Inspector-API-Version header. This header SHOULD be supplied with every request; in the absence of this header, server will default to current supported version in all responses.

GET
/

List API versions

This fetches all the information about all known major API versions in the deployment. Links to more specific information will be provided for each major API version, as well as information about supported min and max microversions.

Normal response codes: 200

Request

Response Example

Name

In

Type

Description

versions

body

array

Array of information about currently supported versions.

id

body

string

API microversion, eg, “1.12”.

links

body

array

A list of relative links. Includes the self and bookmark links.

status

body

string

The status of this API version. This can be one of:

  • CURRENT This version is up to date recent and should be prioritized over all others.

  • SUPPORTED This version is available and may not be updated in future.

  • DEPRECATED This version is still available but may be removed in future.

  • EXPERIMENTAL This version is under development and may be changed in future.

x-openstack-ironic-api-min-version

header

string

Minimum API microversion supported by this endpoint, eg. “1.1”

x-openstack-ironic-api-max-version

header

string

Maximum API microversion supported by this endpoint, eg. “1.10”

{
  "versions": [
    {
      "id": "1.12",
      "links": [
        {
          "href": "http://127.0.0.1:5050/v1",
          "rel": "self"
        }
      ],
      "status": "CURRENT"
    }
  ]
}
GET
/v1/

Show v1 API

Show all the resources within the Ironic Inspector v1 API.

Normal response codes: 200

Request

Response Example

Name

In

Type

Description

resources

body

array

A list of available API resources.

links

body

array

A list of relative links. Includes the self and bookmark links.

href

body

string

A bookmark link to resource object.

rel

body

string

The relationship between the version and the href.

name

body

string

Resource name, like introspection, rules.

x-openstack-ironic-api-min-version

header

string

Minimum API microversion supported by this endpoint, eg. “1.1”

x-openstack-ironic-api-max-version

header

string

Maximum API microversion supported by this endpoint, eg. “1.10”

{
  "resources": [
    {
      "links": [
        {
          "href": "http://127.0.0.1:5050/v1/introspection",
          "rel": "self"
        }
      ],
      "name": "introspection"
    },
    {
      "links": [
        {
          "href": "http://127.0.0.1:5050/v1/continue",
          "rel": "self"
        }
      ],
      "name": "continue"
    },
    {
      "links": [
        {
          "href": "http://127.0.0.1:5050/v1/rules",
          "rel": "self"
        }
      ],
      "name": "rules"
    }
  ]
}

Node Introspection (introspection)

Start introspection, get introspection status are done through the /v1/introspection resource. There are also several sub-resources, which allow further actions to be performed on introspection.

POST
/v1/introspection/{node_id}

Start Introspection

Initiate hardware introspection for node {node_id} . All power management configuration for this node needs to be done prior to calling the endpoint.

In the case of missing or invalid authentication, the response code will be 401 and 403 respectively. If Inspector doesn’t find node {node_id}, it will return 404.

Normal response codes: 202

Error codes: 400, 401, 403, 404

Request

Name

In

Type

Description

node_id

path

string

The UUID of the Ironic node.

manage_boot (Optional)

query

string

Whether the current installation of ironic-inspector can manage PXE booting of nodes.

GET
/v1/introspection/

List All Introspection statuses

Returned status list is sorted by the started_at, uuid attribute pair, newer items first.

In case missing or invalid authentication response code will be 401 and 403.

Normal response codes: 200

Error codes: 400, 401, 403

Request

Status list may be paginated with these query string fields:

Name

In

Type

Description

marker (Optional)

query

string

The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent request.

limit (Optional)

query

integer

Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request. This value cannot be larger than the api_max_limit option in the configuration. If it is higher than api_max_limit, return 400 Bad Request.

Response

The response will contain a list of status objects:

Name

In

Type

Description

error

body

string

Error description string or null; Canceled by operator in case introspection was aborted.

finished

body

boolean

Whether introspection has finished for this node.

finished_at

body

string

UTC ISO8601 timestamp of introspection finished or null.

links

body

array

A list of relative links. Includes the self and bookmark links.

started_at

body

string

UTC ISO8601 timestamp of introspection start.

state

body

string

Current state of the introspection, possible values: enrolling, error, finished, processing, reapplying, starting, waiting. For detail information about states see Inspector states.

uuid

path

string

The UUID of the Ironic node.

Example JSON representation of an introspection:

{
  "introspection": [
    {
      "error": null,
      "finished": true,
      "finished_at": "2017-08-17T11:36:16",
      "links": [
        {
          "href": "http://127.0.0.1:5050/v1/introspection/05ccda19-581b-49bf-8f5a-6ded99701d87",
          "rel": "self"
        }
      ],
      "started_at": "2017-08-17T11:33:43",
      "state": "finished",
      "uuid": "05ccda19-581b-49bf-8f5a-6ded99701d87"
    },
    {
      "error": null,
      "finished": true,
      "finished_at": "2017-08-16T12:24:30",
      "links": [
        {
          "href": "http://127.0.0.1:5050/v1/introspection/c244557e-899f-46fa-a1ff-5b2c6718616b",
          "rel": "self"
        }
      ],
      "started_at": "2017-08-16T12:22:01",
      "state": "finished",
      "uuid": "c244557e-899f-46fa-a1ff-5b2c6718616b"
    }
  ]
}
GET
/v1/introspection/{node_id}

Show Introspection status

Show node introspection status.

In case missing or invalid authentication response code will be 401 and 403. If Inspector don’t find node {node_id}, it will return 404.

Normal response codes: 200

Error codes: 400, 401, 403, 404

Request

Name

In

Type

Description

node_id

path

string

The UUID of the Ironic node.

Response

The response will contain the complete introspection info, like start, finish time, introspection state, errors if any.

Name

In

Type

Description

error

body

string

Error description string or null; Canceled by operator in case introspection was aborted.

finished

body

boolean

Whether introspection has finished for this node.

finished_at

body

string

UTC ISO8601 timestamp of introspection finished or null.

links

body

array

A list of relative links. Includes the self and bookmark links.

started_at

body

string

UTC ISO8601 timestamp of introspection start.

state

body

string

Current state of the introspection, possible values: enrolling, error, finished, processing, reapplying, starting, waiting. For detail information about states see Inspector states.

uuid

path

string

The UUID of the Ironic node.

Example JSON representation of an introspection:

{
  "error": null,
  "finished": true,
  "finished_at": "2017-08-16T12:24:30",
  "links": [
    {
      "href": "http://127.0.0.1:5050/v1/introspection/c244557e-899f-46fa-a1ff-5b2c6718616b",
      "rel": "self"
    }
  ],
  "started_at": "2017-08-16T12:22:01",
  "state": "finished",
  "uuid": "c244557e-899f-46fa-a1ff-5b2c6718616b"
}

Introspection Management (introspection)

Abort introspection, get introspection data and reapply introspection can be done through introspection sub-resources.

POST
/v1/introspection/{node_id}/abort

Abort Introspection

Abort running introspection.

Normal response codes: 202

Error codes:

  • 400 - bad request

  • 401, 403 - missing or invalid authentication

  • 404 - node cannot be found

  • 409 - inspector has locked this node for processing

Request

Name

In

Type

Description

node_id

path

string

The UUID of the Ironic node.

GET
/v1/introspection/{node_id}/data

Get Introspection data

Return stored data from successful introspection.

Note

We do not provide any backward compatibility guarantees regarding the format and contents of the stored data. Notably, it depends on the ramdisk used and plugins enabled both in the ramdisk and in inspector itself.

Normal response codes: 200

Error codes:

  • 400 - bad request

  • 401, 403 - missing or invalid authentication

  • 404 - data cannot be found or data storage not configured

Request

Name

In

Type

Description

node_id

path

string

The UUID of the Ironic node.

Response

The response will contain introspection data in the form of json string.

Example JSON representation of an introspection data:

{
   "cpu_arch":"x86_64",
   "macs":[
      "52:54:00:4e:3d:30"
   ],
   "root_disk":{
      "rotational":true,
      "vendor":"0x1af4",
      "name":"/dev/vda",
      "hctl":null,
      "wwn_vendor_extension":null,
      "wwn_with_extension":null,
      "model":"",
      "wwn":null,
      "serial":null,
      "size":13958643712
   },
   "interfaces":{
      "eth0":{
         "ip":"172.24.42.100",
         "mac":"52:54:00:4e:3d:30",
         "pxe":true,
         "client_id":null
      }
   },
   "cpus":2,
   "boot_interface":"52:54:00:4e:3d:30",
   "memory_mb":2048,
   "ipmi_address":"192.167.2.134",
   "inventory":{
      "bmc_address":"192.167.2.134",
      "interfaces":[
         {
            "lldp":null,
            "product":"0x0001",
            "vendor":"0x1af4",
            "name":"eth1",
            "has_carrier":true,
            "ipv4_address":"172.24.42.101",
            "client_id":null,
            "mac_address":"52:54:00:47:20:4d"
         },
         {
            "lldp":null,
            "product":"0x0001",
            "vendor":"0x1af4",
            "name":"eth0",
            "has_carrier":true,
            "ipv4_address":"172.24.42.100",
            "client_id":null,
            "mac_address":"52:54:00:4e:3d:30"
         }
      ],
      "disks":[
         {
            "rotational":true,
            "vendor":"0x1af4",
            "name":"/dev/vda",
            "hctl":null,
            "wwn_vendor_extension":null,
            "wwn_with_extension":null,
            "model":"",
            "wwn":null,
            "serial":null,
            "size":13958643712
         }
      ],
      "boot":{
         "current_boot_mode":"bios",
         "pxe_interface":"52:54:00:4e:3d:30"
      },
      "system_vendor":{
         "serial_number":"Not Specified",
         "product_name":"Bochs",
         "manufacturer":"Bochs"
      },
      "memory":{
         "physical_mb":2048,
         "total":2105864192
      },
      "cpu":{
         "count":2,
         "frequency":"2100.084",
      "flags": [
        "fpu",
        "mmx",
        "fxsr",
        "sse",
        "sse2"
        ],
         "architecture":"x86_64"
      }
   },
   "error":null,
   "local_gb":12,
   "all_interfaces":{
      "eth1":{
         "ip":"172.24.42.101",
         "mac":"52:54:00:47:20:4d",
         "pxe":false,
         "client_id":null
      },
      "eth0":{
         "ip":"172.24.42.100",
         "mac":"52:54:00:4e:3d:30",
         "pxe":true,
         "client_id":null
      }
   }
}
POST
/v1/introspection/{node_id}/data/unprocessed

Reapply Introspection on data

This method triggers introspection on either stored introspection data or raw introspection data provided in the request. If the introspection data is provided in the request body, it should be a valid JSON with content similar to ramdisk callback request.

New in version 1.15: Unprocessed introspection data can be sent via request body.

Note

Reapplying introspection on stored data is only possible when a storage backend is enabled via [processing]store_data.

Normal response codes: 202

Error codes:

  • 400 - bad request, store not configured or malformed data in request body

  • 401, 403 - missing or invalid authentication

  • 404 - node not found for Node ID

  • 409 - inspector locked node for processing

Request

Name

In

Type

Description

node_id

path

string

The UUID of the Ironic node.

Process introspection data

After the ramdisk collects the required information from the bare metal node, it should post it back to Inspector via POST /v1/continue API.

Warning

Operators are reminded not to expose the Ironic Inspector API to unsecured and untrusted networks. API below is available to unauthenticated clients because ironic-python-agent ramdisk does not have access to keystone credentials.

POST
/v1/continue

Ramdisk Callback

It is the API for the ramdisk to post back all discovered data. This should not be used for clients other than the ramdisk.

Full list of hardware inventory keys may be found in ironic-python-agent documentation: hardware inventory.

Normal response codes: 201

Error codes: 400

Request

List of mandatory hardware keys:

Name

In

Type

Description

inventory

body

object

Dictionary with hardware inventory keys.

memory

body

string

Memory information containing at least physical_mb key, memory size is reported by dmidecod.

cpu

body

string

CPU information containing at least keys count (CPU count) and architecture (CPU architecture, e.g. x86_64),

bmc_address (Optional)

body

string

IP address of the node’s BMC

interfaces

body

array

List of dictionaries with interfaces info, contains following keys: name, ipv4_address, mac_address, client_id.

disks

body

array

List of disk block devices containing at least name and size keys. In case disks are not provided ironic-inspector assumes that this is a disk-less node.

root_disk

body

string

Default deployment root disk as calculated by the ironic-python-agent algorithm.

boot_interface (Optional)

body

string

MAC address of the NIC that the machine PXE booted from

Example node introspection continue request:

{
  "root_disk": {
    "rotational": true,
    "vendor": "0x1af4",
    "name": "/dev/vda",
    "hctl": null,
    "wwn_vendor_extension": null,
    "wwn_with_extension": null,
    "model": "",
    "wwn": null,
    "serial": null,
    "size": 13958643712
  },
  "boot_interface": "52:54:00:4e:3d:30",
  "inventory": {
    "bmc_address": "192.167.2.134",
    "interfaces": [
      {
        "lldp": null,
        "product": "0x0001",
        "vendor": "0x1af4",
        "name": "eth1",
        "has_carrier": true,
        "ipv4_address": "172.24.42.101",
        "client_id": null,
        "mac_address": "52:54:00:47:20:4d"
      },
      {
        "lldp": null,
        "product": "0x0001",
        "vendor": "0x1af4",
        "name": "eth0",
        "has_carrier": true,
        "ipv4_address": "172.24.42.100",
        "client_id": null,
        "mac_address": "52:54:00:4e:3d:30"
      }
    ],
    "disks": [
      {
        "rotational": true,
        "vendor": "0x1af4",
        "name": "/dev/vda",
        "hctl": null,
        "wwn_vendor_extension": null,
        "wwn_with_extension": null,
        "model": "",
        "wwn": null,
        "serial": null,
        "size": 13958643712
      }
    ],
    "memory": {
      "physical_mb": 2048,
      "total": 2105864192
    },
    "cpu": {
      "count": 2,
      "frequency": "2100.084",
      "flags": [
        "fpu",
        "mmx",
        "fxsr",
        "sse",
        "sse2",
        ],
      "architecture": "x86_64"
    }
  },
  "logs": "<hidden>"
}

Response

The response will contain Ironic node uuid record.

Name

In

Type

Description

uuid

body

string

Ironic node UUID.

Example JSON representation:

{
  "uuid": "c244557e-899f-46fa-a1ff-5b2c6718616b"
}

Introspection Rules

Simple JSON-based DSL to define rules, which run during introspection. See https://docs.openstack.org/ironic-inspector/latest/user/usage.html#introspection-rules for more information on rules.

POST
/v1/rules

Create Introspection Rule

Create a new introspection rule.

Normal response codes:

  • 200 - OK for API version < 1.6

  • 201 - OK for API version 1.6 and higher

Error codes:

  • 400 - wrong rule format

Request

Name

In

Type

Description

uuid

path

string

The UUID of the Ironic Inspector rule.

conditions (Optional)

body

array

List of a logic statementd or operations in rules, that can be evaluated as True or False.

actions

body

array

List of operations that will be performed if conditions of this rule are fulfilled.

description (Optional)

body

string

Rule human-readable description.

Example creating rule request:

{
   "uuid":"7459bf7c-9ff9-43a8-ba9f-48542ecda66c",
   "description":"Set deploy info if not already set on node",
   "actions":[
      {
         "action":"set-attribute",
         "path":"driver_info/deploy_kernel",
         "value":"8fd65-c97b-4d00-aa8b-7ed166a60971"
      },
      {
         "action":"set-attribute",
         "path":"driver_info/deploy_ramdisk",
         "value":"09e5420c-6932-4199-996e-9485c56b3394"
      }
   ],
   "conditions":[
      {
         "op":"is-empty",
         "field":"node://driver_info.deploy_ramdisk"
      },
      {
         "op":"is-empty",
         "field":"node://driver_info.deploy_kernel"
      }
   ]
}

Response

The response will contain full rule object, also condition section may contain additional default fields, like invert, multiple and field, see ` Conditions https://docs.openstack.org/ironic-inspector/latest/user/usage.html#conditions>`_

Name

In

Type

Description

uuid

path

string

The UUID of the Ironic Inspector rule.

conditions (Optional)

body

array

List of a logic statementd or operations in rules, that can be evaluated as True or False.

actions

body

array

List of operations that will be performed if conditions of this rule are fulfilled.

description (Optional)

body

string

Rule human-readable description.

Example JSON representation:

{
  "actions": [
    {
      "action": "set-attribute",
      "path": "driver_info/deploy_kernel",
      "value": "8fd65-c97b-4d00-aa8b-7ed166a60971"
    },
    {
      "action": "set-attribute",
      "path": "driver_info/deploy_ramdisk",
      "value": "09e5420c-6932-4199-996e-9485c56b3394"
    }
  ],
  "conditions": [
    {
      "field": "node://driver_info.deploy_ramdisk",
      "invert": false,
      "multiple": "any",
      "op": "is-empty"
    },
    {
      "field": "node://driver_info.deploy_kernel",
      "invert": false,
      "multiple": "any",
      "op": "is-empty"
    }
  ],
  "description": "Set deploy info if not already set on node",
  "links": [
    {
      "href": "/v1/rules/7459bf7c-9ff9-43a8-ba9f-48542ecda66c",
      "rel": "self"
    }
  ],
  "uuid": "7459bf7c-9ff9-43a8-ba9f-48542ecda66c"
}
GET
/v1/rules

Get Introspection Rules

List all introspection rules

Normal response codes: 200

Response

Name

In

Type

Description

uuid

path

string

The UUID of the Ironic Inspector rule.

description (Optional)

body

string

Rule human-readable description.

links

body

array

A list of relative links. Includes the self and bookmark links.

Example JSON representation:

{
  "rules": [
    {
      "description": "Set deploy info if not already set on node",
      "links": [
        {
          "href": "/v1/rules/7459bf7c-9ff9-43a8-ba9f-48542ecda66c",
          "rel": "self"
        }
      ],
      "uuid": "7459bf7c-9ff9-43a8-ba9f-48542ecda66c"
    },
    {
      "description": "Set IPMI driver_info if no credentials",
      "links": [
        {
          "href": "/v1/rules/b0ea6361-03cd-467c-859c-7230547dcb9a",
          "rel": "self"
        }
      ],
      "uuid": "b0ea6361-03cd-467c-859c-7230547dcb9a"
    }
  ]
}
GET
/v1/rules/{uuid}

Get Introspection Rule

Get one introspection rule by its uuid

Normal response codes: 200

Error codes:

  • 404 - rule not found

Request

Name

In

Type

Description

uuid

path

string

The UUID of the Ironic Inspector rule.

Response

The response will contain full rule object:

Name

In

Type

Description

uuid

path

string

The UUID of the Ironic Inspector rule.

conditions (Optional)

body

array

List of a logic statementd or operations in rules, that can be evaluated as True or False.

actions

body

array

List of operations that will be performed if conditions of this rule are fulfilled.

description (Optional)

body

string

Rule human-readable description.

Example JSON representation:

{
  "actions": [
    {
      "action": "set-attribute",
      "path": "driver",
      "value": "agent_ipmitool"
    },
    {
      "action": "set-attribute",
      "path": "driver_info/ipmi_username",
      "value": "username"
    },
    {
      "action": "set-attribute",
      "path": "driver_info/ipmi_password",
      "value": "password"
    }
  ],
  "conditions": [
    {
      "field": "node://driver_info.ipmi_password",
      "invert": false,
      "multiple": "any",
      "op": "is-empty"
    },
    {
      "field": "node://driver_info.ipmi_username",
      "invert": false,
      "multiple": "any",
      "op": "is-empty"
    }
  ],
  "description": "Set IPMI driver_info if no credentials",
  "links": [
    {
      "href": "/v1/rules/b0ea6361-03cd-467c-859c-7230547dcb9a",
      "rel": "self"
    }
  ],
  "uuid": "b0ea6361-03cd-467c-859c-7230547dcb9a"
}
DELETE
/v1/rules

Delete Introspection Rules

Delete all introspection rules

Normal response codes: 204

DELETE
/v1/rules/{uuid}

Delete Introspection Rule

Delete introspection rule by uuid.

Normal response codes: 204

Error codes:

  • 404 - rule not found

Request

Name

In

Type

Description

uuid

path

string

The UUID of the Ironic Inspector rule.