ironic/doc/source/contributor/webapi-version-history.rst

REST API Version History

1.94 (Epoxy)

Add support to create ports passing in either the node name or UUID.

1.92 (Dalmatian)

Adds runbooks, a predefined list of steps that can be run on nodes associated via traits and used in place of an explicit list of steps for manual cleaning or servicing, to enable self-service of maintenance items by project members.

• Adds a new REST API endpoint /v1/runbooks/ with basic CRUD support.
• Extends the /v1/nodes/<node>/states/provision API to accept a runbook identifier (name or UUID) instead of clean_steps or service_steps for servicing or manual cleaning.
• Implements RBAC-aware lifecycle management for runbooks, allowing projects to limit who can CRUD and use a runbook.

1.91 (Dalmatian)

Removes special treatment of .json for API objects

• /v1/nodes/test.json will now only mean node with the name "test.json"
• /v1/nodes/test.json.json will mean a node with the name "test.json.json" and,
• /v1/nodes/test will mean a node with the name "test".

So /v1/nodes/test.json will no longer default to "test" and will HTTP 404 unless a node with the name "test" actually exists.

This also removes the backward compatibility with the guess_content_type_from_ext feature

1.90 (Caracal)

API supports ovn vtep switches as a valid schema for port.local_link_connection. Ovn vtep switches are represented as the following:

{
  "port_id": "exampleportid",
  "vtep-logical-switch": "examplelogicalswitch",
  "vtep-physical-switch": "examplephysicalswitch"
}

1.89 (Caracal)

Adds support to attaching or detaching images from a node's virtual media using the /v1/nodes/{node_ident}/vmedia endpoint. A POST request containing device_type, image_url, and image_download_source will attach the requested image to the node's virtual media. A later DELETE request to the same endpoint will detach it.

1.88 (Bobcat)

Added the name field to the port API. It should be unique when set, and can be used to identify a port resource.

1.87 (Bobcat)

Adds the service provision state verb to allow modifications via the "steps" interface to occur with a baremetal node. With this functionality comes a service_step field on the /v1/nodes based resources, which indicates the current step.

1.86 (Bobcat)

Adds a firmware_interface field to the /v1/nodes resources.

1.85 (Bobcat, 22.1)

This version adds a new provision state change verb called unhold to be utilized with the new provision_state values clean hold and deploy hold. The verb instructs Ironic to remove the node from it's present hold and to resume it's prior cleaning or deployment process.

1.84 (Bobcat, 22.1)

Add callback endpoint for in-band inspection /v1/continue_inspection. This endpoint is not designed to be used by regular users.

1.83 (Bobcat, 22.0)

This version adds a concept of child nodes through the use of a parent_node field which can be set on a node.

Under normal conditions, child nodes are not visible in the normal node list, as they are more for nested resources and not machines which can be freely used outside of an integrated context of the parent node. Think of a "child node" as a node with it's own BMC embedded inside of an existing node.

Additionally:

• Adds GET /v1/nodes/{node_ident}/children to return a list of node UUIDs which represent children, which can acted upon individually.
• Adds GET /v1/nodes/?include_children=True to return a list of all parent nodes and children.
• Adds GET /v1/nodes?parent_node={node_ident} to explicitly request a detailed list of nodes by parent relationship.

1.82 (Antelope, 21.4)

This version signifies the addition of node sharding endpoints.

• Adds support for get, set, and delete of shard key on Node object.
• Adds support for GET /v1/shards which returns a list of all shards and the count of nodes assigned to each.

1.81 (Antelope, 21.3)

Add endpoint to retrieve introspection data for nodes via the REST API.

• GET /v1/nodes/{node_ident}/inventory/

1.80 (Zed, 21.1)

This version is a signifier of additional RBAC functionality allowing a project scoped admin to create or delete nodes in Ironic.

1.79 (Zed, 21.0)

A node with the same name as the allocation name is moved to the start of the derived candidate list.

1.78 (Xena, 18.2)

Add endpoints to allow history events for nodes to be retrieved via the REST API.

• GET /v1/nodes/{node_ident}/history/
• GET /v1/nodes/{node_ident}/history/{event_uuid}

1.77 (Xena, 18.2)

Add a fields selector to the the Drivers list: * GET /v1/drivers?fields= Also add a fields selector to the the Driver detail: * GET /v1/drivers/{driver_name}?fields=

1.76 (Xena, 18.2)

Add endpoints for changing boot mode and secure boot state of node asynchronously:

• PUT /v1/nodes/{node_ident}/states/boot_mode
• PUT /v1/nodes/{node_ident}/states/secure_boot

1.75 (Xena, 18.1)

Add boot_mode and secure_boot to node object and expose their state at:

• /v1/nodes/{node_ident}/states

1.74 (Xena, 18.0)

Add support for BIOS registry fields which include details about the BIOS setting. Included in the /v1/nodes/{node_ident}/bios/{setting} response.

Add a new selector to include the fields in the BIOS settings list:

• /v1/nodes/{node_ident}/bios/?detail=

Also add a fields selector to the the BIOS settings list:

• /v1/nodes/{node_ident}/bios/?fields=

1.73 (Xena, 18.0)

Add a new deploy verb as an alias to active and undeploy verb as an alias to deleted.

1.72 (Wallaby, 17.0)

Add support for agent_status and agent_status_message to /v1/heartbeat. These fields are used for external installation tools, such as Anaconda, to report back status.

1.71 (Wallaby, 17.0)

Signifier of the API supporting keystone system scoped roles and access controls. This is an informational flag for clients to be aware of the server's capability.

1.70 (Wallaby, 17.0)

Add support for disable_ramdisk parameter to provisioning endpoint /v1/nodes/{node_ident}/states/provision.

1.69 (Wallaby, 16.2)

Add support for deploy_steps parameter to provisioning endpoint /v1/nodes/{node_ident}/states/provision. Available and optional when target is 'active' or 'rebuild'.

1.68 (Victoria, 16.0)

Added the agent_verify_ca parameter to the ramdisk heartbeat API.

1.67 (Victoria, 15.1)

Add support for the mutually exclusive port_uuid and portgroup_uuid fields by having the node vif_attach API accept those values within vif_info. If one is specified, then Ironic will attempt to attach a VIF to the relative port or portgroup.

1.66 (Victoria, 15.1)

Add network_data field to the node object, that will be used by stand-alone ironic to pass L3 network configuration information to ramdisk.

1.65 (Ussuri, 15.0)

Added lessee field to the node object. The field should match the project_id of the intended lessee. If an allocation has an owner, then the allocation process will only match the allocation with a node that has the same owner or lessee.

1.64 (Ussuri, 15.0)

Added the network_type to the port objects local_link_connection field. The network_type can be set to either managed or unmanaged. When the type is unmanaged other fields are not required. Use unmanaged when the neutron network_interface is required, but the network is in fact a flat network where no actual switch management is done.

1.63 (Ussuri, 15.0)

Added the following new endpoints for indicator management:

• GET /v1/nodes/<node_ident>/management/indicators to list all available indicators names for each of the hardware component. Currently known components are: chassis, system, disk, power and nic.
• GET /v1/nodes/<node_ident>/management/indicators/<component>/<indicator_ident> to retrieve all indicators and their states for the hardware component.
• PUT /v1/nodes/<node_ident>/management/indicators/<component>/<indicator_ident> change state of the desired indicators of the component.

1.62 (Ussuri, 15.0)

This version of the API is to signify capability of an ironic deployment to support the agent token functionality with the ironic-python-agent.

1.61 (Ussuri, 14.0)

Added retired field to the node object to mark nodes for retirement. If set, this flag will move nodes to manageable upon automatic cleaning. manageable nodes which have this flag set cannot be moved to available. Also added retired_reason to specify the retirement reason.

1.60 (Ussuri, 14.0)

Added owner field to the allocation object. The field should match the project_id of the intended owner. If the owner field is set, the allocation process will only match the allocation with a node that has the same owner field set.

1.59 (Ussuri, 14.0)

Added the ability to specify a vendor_data dictionary field in the configdrive parameter submitted with the deployment of a node. The value is a dictionary which is served as vendor_data2.json in the config drive.

1.58 (Train, 12.2.0)

Added the ability to backfill allocations for already deployed nodes by creating an allocation with node set.

1.57 (Train, 12.2.0)

Added the following new endpoint for allocation:

• PATCH /v1/allocations/<allocation_ident> that allows updating name and extra fields for an existing allocation.

1.56 (Stein, 12.1.0)

Added the ability for the configdrive parameter submitted with the deployment of a node, to include a meta_data, network_data and user_data dictionary fields. Ironic will now use the supplied data to create a configuration drive for the user. Prior uses of the configdrive field are unaffected.

1.55 (Stein, 12.1.0)

Added the following new endpoints for deploy templates:

• GET /v1/deploy_templates to list all deploy templates.
• GET /v1/deploy_templates/<deploy template identifier> to retrieve details of a deploy template.
• POST /v1/deploy_templates to create a deploy template.
• PATCH /v1/deploy_templates/<deploy template identifier> to update a deploy template.
• DELETE /v1/deploy_templates/<deploy template identifier> to delete a deploy template.

1.54 (Stein, 12.1.0)

Added new endpoints for external events:

• POST /v1/events for creating events. (This endpoint is only intended for internal consumption.)

1.53 (Stein, 12.1.0)

Added is_smartnic field to the port object to enable Smart NIC port creation in addition to local link connection attributes port_id and hostname.

1.52 (Stein, 12.1.0)

Added allocation API, allowing reserving a node for deployment based on resource class and traits. The new endpoints are:

• POST /v1/allocations to request an allocation.
• GET /v1/allocations to list all allocations.
• GET /v1/allocations/<ID or name> to retrieve the allocation details.
• GET /v1/nodes/<ID or name>/allocation to retrieve an allocation associated with the node.
• DELETE /v1/allocations/<ID or name> to remove the allocation.
• DELETE /v1/nodes/<ID or name>/allocation to remove an allocation associated with the node.

Also added a new field allocation_uuid to the node resource.

1.51 (Stein, 12.1.0)

Added description field to the node object to enable operators to store any information relates to the node. The field is limited to 4096 characters.

1.50 (Stein, 12.1.0)

Added owner field to the node object to enable operators to store information in relation to the owner of a node. The field is up to 255 characters and MAY be used in a later point in time to allow designation and deligation of permissions.

1.49 (Stein, 12.0.0)

Added new endpoints for retrieving conductors information, and added a conductor field to node object.

1.48 (Stein, 12.0.0)

Added protected field to the node object to allow protecting deployed nodes from undeploying, rebuilding or deletion. Also added protected_reason to specify the reason of making the node protected.

1.47 (Stein, 12.0.0)

Added automated_clean field to the node object, enabling cleaning per node.

1.46 (Rocky, 11.1.0)

Added conductor_group field to the node and the node response, as well as support to the API to return results by matching the parameter.

1.45 (Rocky, 11.1.0)

Added reset_interfaces parameter to node's PATCH request, to specify whether to reset hardware interfaces to their defaults on driver's update.

1.44 (Rocky, 11.1.0)

Added deploy_step to the node object, to indicate the current deploy step (if any) being performed on the node.

1.43 (Rocky, 11.0.0)

Added ?detail= boolean query to the API list endpoints to provide a more RESTful alternative to the existing /nodes/detail and similar endpoints.

1.42 (Rocky, 11.0.0)

Added fault to the node object, to indicate currently detected fault on the node.

1.41 (Rocky, 11.0.0)

Added support to abort inspection of a node in the inspect wait state.

1.40 (Rocky, 11.0.0)

Added BIOS properties as sub resources of nodes:

• GET /v1/nodes/<node_ident>/bios
• GET /v1/nodes/<node_ident>/bios/<setting_name>

Added bios_interface field to the node object to allow getting and setting the interface.

1.39 (Rocky, 11.0.0)

Added inspect wait to available provision states. A node is shown as inspect wait instead of inspecting during asynchronous inspection.

1.38 (Queens, 10.1.0)

Added provision_state verbs rescue and unrescue along with the following states: rescue, rescue failed, rescue wait, rescuing, unrescue failed, and unrescuing. After rescuing a node, it will be left in the rescue state running a rescue ramdisk, configured with the rescue_password, and listening with ssh on the specified network interfaces. Unrescuing a node will return it to active.

Added rescue_interface to the node object, to allow setting the rescue interface for a dynamic driver.

1.37 (Queens, 10.1.0)

Adds support for node traits, with the following new endpoints.

• GET /v1/nodes/<node identifier>/traits lists the traits for a node.
• PUT /v1/nodes/<node identifier>/traits sets all traits for a node.
• PUT /v1/nodes/<node identifier>/traits/<trait> adds a trait to a node.
• DELETE /v1/nodes/<node identifier>/traits removes all traits from a node.
• DELETE /v1/nodes/<node identifier>/traits/<trait> removes a trait from a node.

A node's traits are also included the following node query and list responses:

• GET /v1/nodes/<node identifier>
• GET /v1/nodes/detail
• GET /v1/nodes?fields=traits

Traits cannot be specified on node creation, nor can they be updated via a PATCH request on the node.

1.36 (Queens, 10.0.0)

Added agent_version parameter to deploy heartbeat request for version negotiation with Ironic Python Agent features.

1.35 (Queens, 9.2.0)

Added ability to provide configdrive when node is updated to rebuild provision state.

1.34 (Pike, 9.0.0)

Adds a physical_network field to the port object. All ports in a portgroup must have the same value in their physical_network field.

1.33 (Pike, 9.0.0)

Added storage_interface field to the node object to allow getting and setting the interface.

Added default_storage_interface and enabled_storage_interfaces fields to the driver object to show the information.

1.32 (Pike, 9.0.0)

Added new endpoints for remote volume configuration:

• GET /v1/volume as a root for volume resources
• GET /v1/volume/connectors for listing volume connectors
• POST /v1/volume/connectors for creating a volume connector
• GET /v1/volume/connectors/<UUID> for showing a volume connector
• PATCH /v1/volume/connectors/<UUID> for updating a volume connector
• DELETE /v1/volume/connectors/<UUID> for deleting a volume connector
• GET /v1/volume/targets for listing volume targets
• POST /v1/volume/targets for creating a volume target
• GET /v1/volume/targets/<UUID> for showing a volume target
• PATCH /v1/volume/targets/<UUID> for updating a volume target
• DELETE /v1/volume/targets/<UUID> for deleting a volume target

Volume resources also can be listed as sub resources of nodes:

• GET /v1/nodes/<node identifier>/volume
• GET /v1/nodes/<node identifier>/volume/connectors
• GET /v1/nodes/<node identifier>/volume/targets

1.31 (Ocata, 7.0.0)

Added the following fields to the node object, to allow getting and setting interfaces for a dynamic driver:

• boot_interface
• console_interface
• deploy_interface
• inspect_interface
• management_interface
• power_interface
• raid_interface
• vendor_interface

1.30 (Ocata, 7.0.0)

Added dynamic driver APIs:

• GET /v1/drivers now accepts a type parameter (optional, one of classic or dynamic), to limit the result to only classic drivers or dynamic drivers (hardware types). Without this parameter, both classic and dynamic drivers are returned.
• GET /v1/drivers now accepts a detail parameter (optional, one of True or False), to show all fields for a driver. Defaults to False.
• GET /v1/drivers now returns an additional type field to show if the driver is classic or dynamic.
• GET /v1/drivers/<name> now returns an additional type field to show if the driver is classic or dynamic.
• GET /v1/drivers/<name> now returns additional fields that are null for classic drivers, and set as following for dynamic drivers:
  • The value of the default<interface-type>_interface is the entrypoint name of the calculated default interface for that type:
    • default_boot_interface
    • default_console_interface
    • default_deploy_interface
    • default_inspect_interface
    • default_management_interface
    • default_network_interface
    • default_power_interface
    • default_raid_interface
    • default_vendor_interface
  • The value of the enabled<interface-type>_interfaces is a list of entrypoint names of the enabled interfaces for that type:
    • enabled_boot_interfaces
    • enabled_console_interfaces
    • enabled_deploy_interfaces
    • enabled_inspect_interfaces
    • enabled_management_interfaces
    • enabled_network_interfaces
    • enabled_power_interfaces
    • enabled_raid_interfaces
    • enabled_vendor_interfaces

1.29 (Ocata, 7.0.0)

Add a new management API to support inject NMI, 'PUT /v1/nodes/(node_ident)/management/inject_nmi'.

1.28 (Ocata, 7.0.0)

Add '/v1/nodes/<node identifier>/vifs' endpoint for attach, detach and list of VIFs.

1.27 (Ocata, 7.0.0)

Add soft rebooting and soft power off as possible values for the target field of the power state change payload, and also add timeout field to it.

1.26 (Ocata, 7.0.0)

Add portgroup mode and properties fields.

1.25 (Ocata, 7.0.0)

Add possibility to unset chassis_uuid from a node.

1.24 (Ocata, 7.0.0)

Added new endpoints '/v1/nodes/<node>/portgroups' and '/v1/portgroups/<portgroup>/ports'. Added new field port.portgroup_uuid.

1.23 (Ocata, 7.0.0)

Added '/v1/portgroups/ endpoint.

1.22 (Newton, 6.1.0)

Added endpoints for deployment ramdisks.

1.21 (Newton, 6.1.0)

Add node resource_class field.

1.20 (Newton, 6.1.0)

Add node network_interface field.

1.19 (Newton, 6.1.0)

Add local_link_connection and pxe_enabled fields to the port object.

1.18 (Newton, 6.1.0)

Add internal_info readonly field to the port object, that will be used by ironic to store internal port-related information.

1.17 (Newton, 6.0.0)

Addition of provision_state verb adopt which allows an operator to move a node from manageable state to active state without performing a deployment operation on the node. This is intended for nodes that have already been deployed by external means.

1.16 (Mitaka, 5.0.0)

Add ability to filter nodes by driver.

1.15 (Mitaka, 5.0.0)

Add ability to do manual cleaning when a node is in the manageable provision state via PUT v1/nodes/<identifier>/states/provision, target:clean, clean_steps:[...].

1.14 (Liberty, 4.2.0)

Make the following endpoints discoverable via Ironic API:

• '/v1/nodes/<UUID or logical name>/states'
• '/v1/drivers/<driver name>/properties'

1.13 (Liberty, 4.2.0)

Add a new verb abort to the API used to abort nodes in CLEANWAIT state.

1.12 (Liberty, 4.2.0)

This API version adds the following abilities:

• Get/set node.target_raid_config and to get node.raid_config.
• Retrieve the logical disk properties for the driver.

1.11 (Liberty, 4.0.0, breaking change)

Newly registered nodes begin in the enroll provision state by default, instead of available. To get them to the available state, the manage action must first be run to verify basic hardware control. On success the node moves to manageable provision state. Then the provide action must be run. Automated cleaning of the node is done and the node is made available.

1.10 (Liberty, 4.0.0)

Logical node names support all RFC 3986 unreserved characters. Previously only valid fully qualified domain names could be used.

1.9 (Liberty, 4.0.0)

Add ability to filter nodes by provision state.

1.8 (Liberty, 4.0.0)

Add ability to return a subset of resource fields.

1.7 (Liberty, 4.0.0)

Add node clean_step field.

1.6 (Kilo)

Add inspection </admin/inspection> process: introduce inspecting and inspectfail provision states, and inspect action that can be used when a node is in manageable provision state.

1.5 (Kilo)

Add logical node names that can be used to address a node in addition to the node UUID. Name is expected to be a valid fully qualified domain name in this version of API.

1.4 (Kilo)

Add manageable state and manage transition, which can be used to move a node to manageable state from available. The node cannot be deployed in manageable state. This change is mostly a preparation for future inspection work and introduction of enroll provision state.

1.3 (Kilo)

Add node driver_internal_info field.

1.2 (Kilo, breaking change)

Renamed NOSTATE (None in Python, null in JSON) node state to available. This is needed to reduce confusion around None state, especially when future additions to the state machine land.

1.1 (Kilo)

This was the initial version when API versioning was introduced. Includes the following changes from Kilo release cycle:

• Add node maintenance_reason field and an API endpoint to set/unset the node maintenance mode.
• Add sync and async support for vendor passthru methods.
• Vendor passthru endpoints support different HTTP methods, not only POST.
• Make vendor methods discoverable via the Ironic API.
• Add logic to store the config drive passed by Nova.

This has been the minimum supported version since versioning was introduced.

1.0 (Juno)

This version denotes Juno API and was never explicitly supported, as API versioning was not implemented in Juno, and 1.1 became the minimum supported version in Kilo.